[LRabuzin]

What does this change?

GRASS-MIL 1.1.0 turns the 1.0.0 paper companion into a package with one default path: BGRL pretraining, then finetune with an automatically fitted probe head, then nested CV, per-cell extraction and niche analysis. See CHANGELOG.md for the full list.

Breaking: commands, configuration keys and file formats changed. Graphs and checkpoints from 1.0.0 must be rebuilt.

• Regimes renamed, with finetune as the default: linear_ftall → finetune, linear_ftall_reg → finetune_reg, linear_probehead → attention_only, mil → mlp_head, mil_frozen → mlp_head_frozen, pretrain_a3 → pretrain. The probe head is now fitted automatically, so grass-mil-probe is gone.

• grass-mil-niches reports the primary results:

  • niches in the attention space;
  • their composition, association and attention-weighted margins, with patient-bootstrap intervals;
  • per-niche Moran's I, neighbourhood enrichment, cross-L and contacts;
  • optional survival analysis.

  grass-mil-metaclusters and grass-mil-spatial-stats are optional.

• Removed:

  • commands: grass-mil-report, -eval, -loocv, -scores and -probe;
  • mean pooling and the GCN/GAT/SAGE/GIN encoders;
  • the 1.0.0 checkpoint import and the unused presets.

• Configuration:

  • one data.input block for CSV, TSV, h5ad and SCE;
  • data.unit (region, tile or polygon);
  • labels attached at load time, so one set of graphs serves every task and fold;
  • task (classification, regression or survival), each with its own selection metric.

• Fixes:

  • Training:
    • Gradient clipping now acts on unscaled gradients under AMP.
    • CV refits no longer evaluate on the held-out fold, and they keep the inner learning-rate schedule.
    • Survival training optimises over several units per step.
    • The Cox loss handles tied times (Breslow), and the c-index handles ties correctly.
    • Outer folds must keep each patient together.
  • Statistics:
    • Margin intervals resample patients.
    • Cross-L is measured relative to random labelling.
    • Moran's I uses exact randomisation moments.
  • Data and prediction:
    • grass-mil-predict reports AUROC, works without regime=, and refuses cohorts preprocessed differently from training.
    • The PCA reducer works.
    • Numeric sample ids work.
    • Stale graphs are detected.

• Docs:

  • a README with a step-by-step "Your first cohort";
  • four guides (data preparation, training and evaluation, niche analysis, configuration);
  • three re-executed vignettes on squidpy.datasets.mibitof().