SimNorth

Contrastive self-supervised representation learning for ultrasound frames.

SimNorth maps frames onto the unit hypersphere with three objectives:

  1. Alignment — two augmented views of the same frame are pulled together.
  2. Uniformity — randomly paired views are pushed apart with a rank-based weighting, so the most-similar (likely true-negative) random pairs are penalized the most.
  3. North / light house — a set of fixed anchor points ("light houses") on the sphere attract their nearest embeddings, organizing the learned manifold around well-separated anchors.

Built on PyTorch Lightning 2.x with MLflow experiment tracking.

Install

pip install -e .
# or
pip install -r requirements.txt

Data format

A CSV or Parquet table with one row per frame and a column of image paths (default img_path), resolved relative to --mount_point. Frames are read with SimpleITK; single-channel frames are promoted to 3 channels.

Usage

Optionally pre-compute well-separated light house anchors:

python pretrain_lighthouse.py --n_lights 64 --emb_dim 128 --out lights.pkl

Train:

python train.py \
    --csv_train train.parquet --csv_valid valid.parquet --csv_test test.parquet \
    --mount_point /data/frames \
    --base_encoder efficientnet_b0 --emb_dim 128 --hidden_dim 64 --n_lights 64 \
    --batch_size 256 --epochs 200 --lr 1e-4 \
    --lights lights.pkl \
    --tracking_uri file:./mlruns --experiment_name SimNorth --run_name effnet_b0

If --lights is omitted, anchors are initialized uniformly at random.

Inspect runs:

mlflow ui --backend-store-uri ./mlruns

Package layout

simnorth/
├── nets/
│   ├── simnorth.py    # SimNorth, ProjectionHead, GaussianNoise
│   └── lighthouse.py  # LightHouse anchor optimizer
├── data/
│   ├── dataset.py     # USDataset, USDataModule
│   └── transforms.py  # paired augmentation transforms
└── callbacks/
    └── image_logger.py  # logs augmented-view grids to MLflow
train.py                  # training entrypoint (MLflow)
pretrain_lighthouse.py    # optional anchor pre-optimization

Provenance

Extracted and modernized from the us-famli-pl research codebase (nets/contrastive.py, contrastive_learning.py). Compared to the original:

  • Upgraded from pytorch_lightning to the lightning 2.x API.
  • Switched experiment logging from Neptune to MLflow.
  • SimNorth takes explicit hyperparameters instead of an args namespace.
  • Fixed a copy-paste bug in the north loss where the second view's nearest index was taken from the first view (z_1_n now uses the z_1 index).

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jprieto from gravatar.com jprieto

License

MIT

Requires

Python >=3.9

Provides Extra

dev

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

simnorth-0.1.0.tar.gz (9.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

simnorth-0.1.0-py3-none-any.whl (10.7 kB view details)

Uploaded Python 3

File details

Details for the file simnorth-0.1.0.tar.gz.

File metadata

  • Download URL: simnorth-0.1.0.tar.gz
  • Upload date:
  • Size: 9.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for simnorth-0.1.0.tar.gz
Algorithm Hash digest
SHA256 083b3cf48978b3f509f7e833f6718da322bdf24fac736fe83ad3b5bd0476dd71
MD5 9e13c09f97774864d31f9492ab627a33
BLAKE2b-256 c49a8b46a316cccad810e5ff640f23406d9ea2f1e1e2f16efc6d9d94e701dd07

See more details on using hashes here.

Provenance

The following attestation bundles were made for simnorth-0.1.0.tar.gz:

Publisher: python-publish.yml on ImageMindAnalytics/SimNorth

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file simnorth-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: simnorth-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 10.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for simnorth-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9b40fbb3875fc2c4f0e0356ff9c9a06ccccb0f5e7c17ddb1df765db57bdd45a2
MD5 50476539d0f2fb040b8ba55c547c52f4
BLAKE2b-256 6ab0665cf7f451c2a636cab4e75c357fb705a263b2cc425419ded3d73e1f8341

See more details on using hashes here.

Provenance

The following attestation bundles were made for simnorth-0.1.0-py3-none-any.whl:

Publisher: python-publish.yml on ImageMindAnalytics/SimNorth

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page