Skip to content

2.0.0

Latest
Latest

Choose a tag to compare

View all tags
@clemsgrs clemsgrs released this 16 Oct 06:22
· 5 commits to main since this release
2.0.0
92a5889

Soma 2.0 is a full redesign of the library around a small set of public verbs (extract, fit, predict, evaluate), the nouns they pass between them (Cohort, sources, Learner, Predictions, Evaluation), and a declarative ExperimentConfig that mirrors that API. Every component kind is now a registry, the benchmark side lives in its own explicitly imported package, and every recorded benchmark row was re-recorded on the 2.0 code. This is a breaking release. The 1.x dataset, training, configuration and import surfaces are removed without aliases, and every feature cache key changes, so existing caches have to be re-extracted.

Breaking changes

  • Data layer. soma.data replaces Dataset, TileDataset, the task manifests, load_manifest and Splits. Samples are SampleRecords (identity and targets, no paths) held in a validated Cohort with folds and one sampling unit. Features and targets come from typed sources (SetSource, GridSource, TargetSource), and heads read supervision from a bound source instead of opening files. (#583)
  • Training. The old trainer is replaced by a subclass-first Learner (MILLearner, DenseLearner) driven by a generic Trainer with callbacks (Checkpoint, EarlyStopping, History, Progress), plus soma.fit. (#584)
  • Inference and scoring. soma.predict and soma.evaluate are public verbs, with Predictions (parquet, head-declared columns) and a frozen Evaluation between them. compare and Baseline support side-by-side results. The HTML run report is removed. (#585)
  • Dense shape. Segmentation and detection are heads on one grid shape: GridBatch, DenseModel (replacing SegmentationModel and LiveSegmentationModel), DenseLearner and a live encoder stage. Pixel classifiers are removed. (#589)
  • Pipeline. soma.pipeline is now a package built from the public verbs in one canonical fold order, with a single persisted model format (the bundle) and a parity test that guards it. (#596)
  • Configuration. soma.ExperimentConfig replaces the old config. It has seven sections that each hold one public callable's keywords, and every component is a {name, params} leaf. A run resolves the config to a soma.Plan before reading any data. There is no defaults YAML and no translation layer, so 1.x YAML files do not load. (#608)
  • Extraction config. Soma no longer mirrors slide2vec and hs2p settings. It holds their PreprocessingConfig, ExecutionOptions and DenseOptions dataclasses as given, next to its own FeaturesConfig. Every cache key and experiment id changes, so 1.x caches are not reused. (#606)
  • Feature entry point. soma.extract (with Cohort.derived) is the single way features enter. FeatureExtractor, FeatureExtractionResult, attach_source, Pipeline.dataset / Pipeline.splits and the whole legacy bridge are removed. (#611)
  • Package layout. The core moves into soma.data, soma.extract, soma.models, soma.learn, soma.evaluation and soma.pipeline. The root namespace only exposes the verbs and nouns. (#612)
  • Benchmarks. Benchmark code moves into soma.benchmark, with one subpackage per protocol (eva, hest, ocelot, midog, monkey, croma). import soma no longer imports it: import soma.benchmark explicitly. soma.benchmarks, soma.curation, soma.leaderboard and soma.robustness are gone. import-linter enforces the boundary. (#613)
  • ROI sampling default. When no filter is set, annotation ROI sampling no longer drops small annotated regions: hs2p's contour-area filter defaults to a_t: 0. Before, small regions were dropped from slide-manifest segmentation datasets without a warning. (#607)
  • Dependencies. Requires slide2vec[fm]>=7.1.2, hs2p>=6.1.0, torchvision>=0.23 and croma>=1.0.0. Runs started under slide2vec 7.1.0 may refuse to resume with a features drift unless the config states the same GPU and worker counts. (#606, #619, #627)
  • Repository content. scripts/, examples/eva/, examples/ocelot/ and examples/make_beetle_manifest.py are removed. Use soma reproduce for the benchmark configs. (#626)

Added

  • Registries everywhere. Every component kind (aggregators, augmentations, benchmarks, callbacks, decoders, encoders, heads, learners, optimizers, samplers, schedulers, presets) is a Registry. Components declare their params at registration, and soma.components() lists them all. New samplers: uniform, class_conditioned, event_balanced. (#601)
  • Presets, soma run and soma init. Five presets (mil_classification, tile_classification, survival, segmentation, detection) each return a complete ExperimentConfig. soma init writes one to disk and soma run runs it. (#610, #620)
  • Getting-started notebook. One executed notebook on a synthetic cohort replaces the six walkthroughs. soma.testing.synthetic_cohort and a fake encoder let you try the whole flow on CPU, with no weights and no network. (#620)
  • Live detection augmentation. SegmentationAugment now moves Points targets together with the pixels, so live detection runs can be augmented. (#627)
  • Attention-map detection decoder. The attention_map decoder scores the encoder's CLS attention as a detection heatmap without training. It runs as an ordinary soma run. (#631)
  • soma.predict(..., device=...). Predict takes an explicit device, and a model without parameters now runs on the GPU when one is available. (#633)
  • MONKEY ranking and gate. MONKEY ranks by the inflammatory-cell FROC (the Track-1 leaderboard metric) and reports the per-class FROCs. It also has a local gate row (virchow2, 0.275). (#595, #630)

Fixed

  • soma reproduce detection/midog and detection/monkey now score their own runs instead of failing with FileNotFoundError. (#629)
  • run_benchmark_spec frees each seed's pipeline before the next seed, so live segmentation seeds no longer pile up GPU memory. (#590)
  • Same-second runs get separate output directories, and the core names used by the benchmark package are now public. (#619)

Benchmarks and docs

  • The HEST, CRoMa, EVA and OCELOT rows were re-recorded on the 2.0 code with slide2vec 7.1.1, and all are in band. The CRoMa reference panel is pinned to croma 1.0.1, which republished DINOv2-B under Meta's evaluation recipe. (#622, #623, #624, #625)
  • The benchmark pages (EVA, OCELOT, HEST, CRoMa) are rewritten by hand around data, protocol, results and reproduction. Only the results tables are generated. (#632, #634, #635)
  • The reader-path docs are curated for 2.0, extending.rst is rewritten around the extension points, and a test checks that every Python snippet in the docs compiles and uses only public names. (#621)
  • The test suite mirrors the package and is limited to the public API. (#614)
  • New page on the detection annotation-efficiency protocol and MIDOG curation. The recorded-OCELOT ranking report driver is removed. (#587, #588)
Assets 2
Loading