seana-ssl 0.1.0__tar.gz

seana_ssl-0.1.0/CITATION.cff

@@ -0,0 +1,18 @@
+cff-version: 1.2.0
+message: "If you use SEANA, please cite the accompanying paper. Publication metadata will be updated for the camera-ready release."
+type: software
+title: "SEANA: Noise-Aligned View Generation for Self-Supervised Learning"
+version: 0.1.0
+authors:
+  - family-names: Patil
+    given-names: Oankar R.
+  - family-names: Wang
+    given-names: May D.
+preferred-citation:
+  type: manuscript
+  title: "Breaking Noise Shortcuts in Self-Supervised Learning via Noise-Aligned View Generation"
+  authors:
+    - family-names: Patil
+      given-names: Oankar R.
+    - family-names: Wang
+      given-names: May D.

seana_ssl-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 SEANA authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Scope: this license covers original SEANA code and documentation. Third-party
+code, dependencies, datasets and weights retain their own terms. In particular,
+cifar10/lejepa.py and denoisers/nsp.py are not covered by this MIT grant; see
+THIRD_PARTY_NOTICES.md.

seana_ssl-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+# Library source distribution: experiment repository assets are released separately.
+global-exclude *
+include pyproject.toml MANIFEST.in LICENSE CITATION.cff THIRD_PARTY_NOTICES.md
+include seana.py _seana_api.py uv.lock
+include docs/library.md
+include examples/ssl_pipeline.py
+include tests/conftest.py tests/test_library.py

seana_ssl-0.1.0/PKG-INFO

@@ -0,0 +1,313 @@
+Metadata-Version: 2.4
+Name: seana-ssl
+Version: 0.1.0
+Summary: Learned variance stabilization and noise-aligned views for self-supervised learning
+Author: Oankar R. Patil, May D. Wang
+License-Expression: MIT
+Keywords: self-supervised-learning,augmentation,denoising,pytorch
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch<3,>=2.5.1
+Provides-Extra: drunet
+Requires-Dist: deepinv==0.4.1; extra == "drunet"
+Provides-Extra: experiments
+Requires-Dist: torch==2.5.1; extra == "experiments"
+Requires-Dist: torchvision==0.20.1; extra == "experiments"
+Requires-Dist: lightly==1.5.25; extra == "experiments"
+Requires-Dist: deepinv==0.4.1; extra == "experiments"
+Requires-Dist: numpy<3,>=1.26; extra == "experiments"
+Requires-Dist: pillow<14,>=10; extra == "experiments"
+Provides-Extra: imagenet100
+Requires-Dist: datasets==4.4.1; extra == "imagenet100"
+Provides-Extra: bbbc048
+Requires-Dist: tifffile==2024.8.30; extra == "bbbc048"
+Provides-Extra: demo
+Requires-Dist: ipywidgets<9,>=8; extra == "demo"
+Requires-Dist: matplotlib<4,>=3.8; extra == "demo"
+Requires-Dist: tqdm<5,>=4.66; extra == "demo"
+Dynamic: license-file
+
+# SEANA for your SSL pipeline
+
+SEANA learns a variance-stabilizing transform (VST) around a frozen Gaussian
+denoiser and generates independently resampled views for self-supervised learning.
+The Python distribution is **`seana-ssl`**; its import is **`seana`**. The core
+implementation remains in `seana.py` at the repository root.
+
+## Install with uv
+
+Add SEANA to your uv project:
+
+```bash
+uv add seana-ssl
+# Optional pretrained DRUNet support:
+uv add 'seana-ssl[drunet]'
+```
+
+For an existing environment using uv's pip interface:
+
+```bash
+uv pip install 'seana-ssl[drunet]'
+# Standard pip works too:
+python -m pip install 'seana-ssl[drunet]'
+```
+
+For local development from a source checkout:
+
+```bash
+uv sync --extra drunet
+uv run --extra drunet python -c "from seana import SEANA; print(SEANA)"
+# Or add the checkout to a different project:
+uv add /path/to/SEANA --extra drunet
+```
+
+Only **PyTorch** is required by the core library. The `drunet` extra adds
+DeepInverse. Importing `seana` does not import DeepInverse or download weights.
+Choose the PyTorch CPU/CUDA build appropriate for your environment; the library
+does not impose a CUDA index. See [uv's PyTorch guide](https://docs.astral.sh/uv/guides/integration/pytorch/).
+Python 3.10+ is required. Research dependencies retain their Python 3.12 recipe.
+
+To reproduce this package release, pin `seana-ssl==0.1.0` (or
+`seana-ssl[drunet]==0.1.0`) in your environment.
+
+The wheel and source distribution contain the reusable core/API, without research
+datasets, comparison-model code or cluster artifacts. Experiments remain in the
+full repository checkout. The source distribution also includes this guide, a
+runnable example, library tests and the development lockfile.
+
+## Fit once, generate views
+
+```python
+import torch
+from seana import SEANA
+
+device = "cuda" if torch.cuda.is_available() else "cpu"
+seana = SEANA.from_drunet(
+    sigma_d=0.08,       # Gaussian denoiser's noise-level input
+    sigma_vst=0.1,      # Resampling standard deviation in VST space
+    channels=3,
+    device=device,
+)
+
+# train_loader yields raw floating [B,3,H,W] images, optionally followed by labels.
+# Fit on training images only, before ImageNet/encoder mean-std normalization.
+seana.fit(train_loader, steps=5000, patch_size=64, seed=0)
+
+for images, _ in train_loader:
+    source_a, source_b = seana(images.to(device))
+    # Apply independent SSL transforms to each source, as shown below.
+```
+
+These noise levels demonstrate the API; appropriate values depend on the dataset,
+fitted transform and SSL objective. The library does not automatically tune them
+against downstream labels. `sigma_d` and `sigma_vst` have different roles.
+
+Calling `seana(images)` denoises once and returns two independent noise draws
+**at the same spatial geometry**. It does not add an implicit crop or normalization
+policy. For a dataset of already-noisy images, use this order:
+
+**Original noisy image → SEANA denoising and independent resampling → independent
+SSL crops/photometric transforms → encoder normalization → SSL model.**
+
+The fitting loader and the SSL source loader should yield original noisy images,
+converted to floating tensors at the intended intensity scale, before SSL
+augmentations. Apply your single-view transforms to the two SEANA outputs:
+
+```python
+source_a, source_b = seana(images)
+view_a = torch.stack([ssl_view_a(image) for image in source_a])
+view_b = torch.stack([ssl_view_b(image) for image in source_b])
+loss = ssl_loss(encoder(view_a), encoder(view_b))
+loss.backward()
+```
+
+Here `ssl_view_a` and `ssl_view_b` are your single-view augmentation pipelines,
+including normalization as their last step. They can share a stochastic transform
+or use different branch settings, as in BYOL. Calling them per image gives
+independent transform draws across examples as well as across branches.
+
+This order lets SEANA denoise the original acquisition noise before resizing,
+blur or color operations alter it. Those operations then act on the resampled
+sources, so noise after the SSL transforms need not retain its pre-transform
+statistics. A crop without interpolation or a flip preserves retained pixel
+values, but a crop still changes the denoiser's available context.
+
+The API also permits `.augment(crop)` for an explicitly chosen alternate protocol;
+the orders are not generally equivalent. The captured ImageNet runner uses
+SEANA before SSL transforms. The captured CIFAR runner applies SEANA after its
+view transforms, and microscopy has several explicit order controls. Existing
+research recipes retain those protocols; the library example follows the
+SEANA-first workflow described here.
+
+## LightlySSL integration
+
+Use a **single-view** Lightly transform on each independently resampled source.
+Its normal final normalization can stay enabled because SEANA runs first:
+
+```python
+from lightly.transforms import SimCLRViewTransform
+
+ssl_view = SimCLRViewTransform(input_size=224)
+for images, _ in raw_train_loader:
+    source_a, source_b = seana(images.to(device))
+    view_a = torch.stack([ssl_view(image) for image in source_a])
+    view_b = torch.stack([ssl_view(image) for image in source_b])
+    loss = ssl_loss(encoder(view_a), encoder(view_b))
+    loss.backward()
+```
+
+`SimCLRViewTransform` includes crop/resize, flipping, color jitter, grayscale,
+blur and normalization. Tensor inputs require torchvision transforms v2, available
+in the tested torchvision 0.20.1 / Lightly 1.5.25 research environment.
+See the [Lightly transform API](https://docs.lightly.ai/self-supervised-learning/lightly.transforms.html#lightly.transforms.simclr_transform.SimCLRViewTransform).
+Keep the raw-image loader free of the usual two-view dataset transform and run
+SEANA in the training process, after batching. Using one SEANA noise draw as the
+shared input to a two-view `SimCLRTransform` would share that draw across both
+views, so it is not the independent-resampling path shown above.
+
+The augmenter stays in evaluation mode with frozen parameters, even when it is
+a child of a module on which `.train()` is called. Its outputs are detached
+regular tensors, so the encoder still receives parameter gradients. Do not put
+the complete SSL encoder/loss computation inside `torch.no_grad()`.
+
+A complete, download-free example is included:
+
+```bash
+uv run examples/ssl_pipeline.py
+```
+
+It uses synthetic images, a toy averaging filter and a small contrastive encoder
+to demonstrate integration, not scientific performance. To use pretrained DRUNet:
+
+```bash
+uv run --extra drunet examples/ssl_pipeline.py --drunet --device cuda
+```
+
+To exercise Lightly's actual transforms after SEANA with the research dependencies:
+
+```bash
+uv run --python 3.12 --extra experiments examples/ssl_pipeline.py --lightly \
+  --checkpoint runs/library_example/lightly_seana.pt
+```
+
+Add `--drunet --device cuda` to use pretrained DRUNet in that example. Lightly is
+optional; it is not imported by the core library.
+
+The root BBBC048 notebook provides a real-data demo in the full repository.
+
+## Supply your own denoiser
+
+```python
+seana = SEANA(my_denoiser, channels=1, sigma_vst=0.05, device="cuda")
+seana.fit(train_loader, steps=5000, patch_size=64)
+```
+
+The denoiser must be an `nn.Module` mapping floating `[B,C,H,W]` tensors to the
+same shape/device. Its forward pass must be differentiable with respect to its
+**input** during VST fitting, although its own weights and BatchNorm statistics
+stay frozen. A denoiser whose forward uses `torch.no_grad()` cannot train a VST
+through that method.
+
+SEANA owns the module by reference: it moves and freezes it. Pass a separate copy
+if another part of your application trains the same denoiser. Inputs may be CHW
+or BCHW for inference. Denoiser-specific image/patch-size constraints still apply.
+
+## Fitting options
+
+`fit()` accepts a re-iterable loader of tensors or `(images, labels)` batches.
+For dictionaries, pass `batch_key="image"`; other fields are ignored. One-shot
+generators and empty loaders are rejected. Training images must have the configured
+channel count and be at least as large as `patch_size`.
+
+By default, the first 50 training batches calibrate one dataset-level intensity
+range. To use a known range:
+
+```python
+seana = SEANA(my_denoiser, input_range=(0.0, 1.0), sigma_vst=0.1)
+seana.fit(train_loader, calibrate=False, steps=5000, patch_size=64,
+          patch_batch_size=4, stride=4, lr=0.01)
+```
+
+The default spline has 128 knots and uses the captured global fitting objective.
+Use `variant="conditional"` for the captured conditional VST, with the correct
+`channels` specified at construction. Existing low-level imports
+`GlobalNoise2VST`, `ConditionalGlobalNoise2VST` and `DeepInvDRUNetWrapper` remain
+available for research code.
+
+An optional `seed` isolates the loop's Python/PyTorch RNG state; separate loader
+generators and stochastic worker transforms remain the caller's responsibility.
+The `progress` callback receives percent completion. Repeated `fit()` calls
+continue the current VST weights; construct a new augmenter for a fresh fit.
+A failed fit remains unusable until fitting succeeds. Fitting needs autograd
+and must run outside `torch.inference_mode()`.
+
+## Denoising and reproducible resampling
+
+```python
+estimate = seana.denoise(images)  # No noise draw; does not advance the RNG.
+a, b = seana(images, sigma_vst=0.0)  # Equal views with resampling disabled.
+a, b = seana(images, sigma_vst=(0.05, 0.15))  # One scale per image, shared by the pair.
+
+generator = torch.Generator(device=device).manual_seed(123)
+a, b = seana(images, sigma_vst=0.1, generator=generator)
+```
+
+Use a generator on the augmenter's device. Recreating it with the same seed
+repeats the noise; reusing it advances the stream. Each view receives independent
+noise. Per-image strengths may be tensors shaped `[B]` or `[B,1,1,1]`. All
+strengths must be finite and nonnegative. Outputs are clamped to the fitted
+physical intensity range by default; `clamp=False` disables both input and output
+clamps. `denoise()` is an estimate, not clean ground truth.
+
+## Save and reload
+
+```python
+seana.save("weights/seana.pt")
+restored = SEANA.load("weights/seana.pt", device=device)
+```
+
+For a custom denoiser, supply the same configured module:
+
+```python
+restored = SEANA.load("weights/seana.pt", denoiser=my_reconstructed_denoiser,
+                      device=device)
+```
+
+Checkpoints store the VST, denoiser tensors, settings and fit summary. DRUNet
+reloads with `pretrained=None`, without another download. Custom denoisers are
+never dynamically imported or unpickled: the provided class/representation is
+checked and tensor states load strictly. Preserve any custom behavior not encoded
+in `state_dict()` or `extra_repr()` yourself. Loading uses a typed payload and
+`torch.load(weights_only=True)`. Saving refuses an existing file. These are
+inference artifacts, not optimizer-state resume checkpoints.
+
+## Development and research checkout
+
+```bash
+uv lock --check
+uv build
+uv sync --group dev
+uv run --group dev pytest -q tests/test_library.py
+```
+
+`uv.lock` records the development resolution. Consumer projects resolve the
+package dependency bounds in their own environment, using their own lockfile.
+
+For the complete research checkout and test suite:
+
+```bash
+uv sync --python 3.12 --extra experiments --extra imagenet100 --extra bbbc048 \
+  --extra demo --group dev --group notebooks
+uv run --no-sync pytest -q
+```
+
+Legacy `requirements*.txt` files retain the research/Colab installation paths.
+Run experiment scripts from the full checkout; installing the core into another
+project does not install those scripts or datasets.
+
+Original SEANA code is MIT licensed. Dependencies, pretrained weights and the
+repository's comparison methods/datasets retain their own terms. Please cite
+*Breaking Noise Shortcuts in Self-Supervised Learning via Noise-Aligned View
+Generation*, Oankar R. Patil and May D. Wang; the repository's `CITATION.cff`
+tracks publication details.

seana_ssl-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,88 @@
+# Third-party components
+
+The original SEANA code is MIT licensed. The following components retain separate
+terms. This repository has not yet been published.
+
+The `seana-ssl` library wheel contains only the original SEANA core and its
+practitioner API, under MIT. Comparison implementations, datasets and pretrained
+weights are excluded from the library distributions. The following comparison
+and dataset notices apply to their files in the full research repository.
+
+## LeJEPA / SIGReg
+
+`cifar10/lejepa.py` is adapted from the project's microscopy implementation,
+which identifies its Epps–Pulley and slicing routines as ports of
+[galilai-group/lejepa](https://github.com/galilai-group/lejepa), by Randall
+Balestriero and Yann LeCun. The upstream code is licensed under
+[CC BY-NC 4.0](https://github.com/galilai-group/lejepa/blob/main/LICENSE).
+The full license is retained in [third_party/lejepa-LICENSE.txt](third_party/lejepa-LICENSE.txt).
+It is excluded from the MIT grant for original SEANA code.
+
+The release adaptation runs on one process, uses two views at the selected dataset's size, and
+exposes the upstream `(1-lambda)*invariance + lambda*SIGReg` weighting and the
+captured project's `invariance + lambda*SIGReg` weighting as separate settings.
+The upstream weighting is the default. Source reference:
+[minimal example](https://github.com/galilai-group/lejepa/blob/main/MINIMAL.md).
+
+## Next-Scale Prediction (NSP)
+
+`denoisers/nsp.py` is the project's adaptation of
+[XLearning-SCU/2026-CVPR-NSP](https://github.com/XLearning-SCU/2026-CVPR-NSP),
+by Yiwen Shan, Haiyu Zhao, Peng Hu, Xi Peng and Yuanbiao Gou.
+Its DBSNl architecture also references Wu et al., *Unpaired Learning of Deep
+Image Denoising* (ECCV 2020).
+
+No license file was present in the inspected NSP repository on 2026-11-06.
+This local preparation preserves the user's existing adaptation; it does not
+assert redistribution permission. **Resolve upstream redistribution terms before
+publishing this file.** The root MIT license does not cover it. Adaptations
+include `tds=4` for 32x32 images, a shorter fit schedule, functional masked
+convolution, vectorized pair sampling and averaged sub-image inference.
+The new ImageNet-100 recipe uses 160x160 fitting patches and tds=5.
+The BBBC048 and fetal ultrasound recipes retain 64x64 fitting patches and tds=4.
+
+## Neighbor2Neighbor (N2N)
+
+`denoisers/n2n.py` preserves the project's own SmallUNet and loss. It is inspired
+by Tao Huang, Songjiang Li, Xu Jia, Huchuan Lu and Jianzhuang Liu,
+*Neighbor2Neighbor: Self-Supervised Denoising from Single Noisy Images* (CVPR 2021).
+The [official implementation](https://github.com/TaoHuang2018/Neighbor2Neighbor)
+uses a different sampling/regularization scheme. No official implementation is
+vendored here; [protocol.md](docs/protocol.md) states the project's exact loss.
+
+## Dependencies, data and pretrained weights
+
+PyTorch is the library's required dependency. DeepInverse is an optional extra;
+torchvision, Lightly, Hugging Face Datasets and tifffile support the research workflows.
+Their source code is not bundled into this repository. Model heads and standard
+losses use Lightly. The SEANA experiment uses DeepInverse's pretrained DRUNet;
+its weights are obtained separately and retain their applicable terms.
+
+CIFAR-10 data are obtained through torchvision or supplied by the user and are
+not distributed here. ImageNet-100 is obtained separately through
+[clane9/imagenet-100](https://huggingface.co/datasets/clane9/imagenet-100), whose
+dataset card provides its terms. ImageNet images are not redistributed.
+BBBC048's original pre-merged images and ground-truth list are included in the
+single-file [dataset archive](fluorescence_imaging_bbbc048/dataset/bbbc048_merged_v1.zip).
+The [dataset page](https://bbbc.broadinstitute.org/BBBC048) identifies Andrew Filby
+as the licensor under **CC BY-NC-SA 3.0**. The archive retains that license and
+attribution to the Flow Cytometry Core Facility, Newcastle University, with
+citations to Eulenberg et al. (2017) and Ljosa et al. (2012). See
+[the dataset notice](fluorescence_imaging_bbbc048/dataset/NOTICE.md) and
+[full license](fluorescence_imaging_bbbc048/dataset/LICENSE.txt).
+BBBC048 images are redistributed without pixel changes; SEANA adds the manifest,
+hashes and reproducible split assignments.
+
+FETAL_PLANES_DB's prepared native-resolution regions are included as the single
+[fetal dataset file](fetal_ultrasound/dataset/fetal_planes_native192_v1.zip).
+[Burgos-Artizzu et al.'s dataset v1](https://doi.org/10.5281/zenodo.3904280) is
+licensed under **CC BY 4.0**. The file preserves the original metadata and adds
+192x192 grayscale crops, provenance hashes and patient partitions. Cropping
+matches the experiment loader without interpolation; the full source frames
+are not bundled. See [attribution and modification notice](fetal_ultrasound/dataset/NOTICE.md)
+and [full license](fetal_ultrasound/dataset/LICENSE.txt). The GitHub dataset file
+uses Git LFS and is excluded from Python package distributions.
+
+Experiment CSVs are the author's measurements.
+The repository's MIT license does not grant rights to
+datasets or pretrained weights.