Repository navigation
Hello! 🌸 It's been a while since the last release...during my PhD I was focused on getting my own analyses done and let the codebase accumulate changes across several branches. This release catches everything up: all of that work has now been consolidated onto main, tested, and documented. It includes some breaking API changes (see below), so please check the changelog before upgrading. Thank you!
Breaking changes
If you use prepare_fusion_data and train_and_save_models to run your experiments, most of this doesn't affect
you. The changes below are in the lower-level classes that those functions call internally.
data_dimsand datasourcesare now dictionaries (e.g.{"mod1_dim": ..., "mod2_dim": ...}) instead of lists, to support a variable number of tabular modalities.prepare_fusion_data's owndata_pathsargument was already a dictionary before and after this change. This only matters if your code constructsLoadDatasets,TrainTestDataModule,KFoldDataModule, or a fusion model class directly with the old list format (for example, if you followed the "creating your own fusion model" template) - that code will need updating to the dictionary format.- Fusion model
forward()methods now take modalities as separate tensor arguments and return a single tensor, instead of taking/returning lists.forward()is called internally during training and validation, so this only matters if you call a model'.forward()ormodel(x)directly yourself, e.g. for custom inference or a custom fusion model. - The binary classification final layer no longer applies
Sigmoidinternally, and the loss function now usesBCEWithLogitsLosson raw logits directly (more numerically stable). The built-in evaluation classes (RealsVsPreds,ConfusionMatrix,ModelComparison) already account for this and don't need any changes. But if you use thelogitsreturned from a trained model yourself - for your own metrics, manual thresholding, or feeding into another library like SHAP - be aware they're no longer bounded between 0 and 1 the way they used to be. Thresholding at 0.5 or treating them as probabilities directly will now give wrong results; usesigmoid(logits)first if you need a probability.
New features
- Three-tabular-modality support: most tabular-tabular fusion methods (
TabularDecision,ConcatTabularData,ConcatTabularFeatureMaps,TabularChannelWiseMultiAttention,TabularCrossmodalMultiheadAttention,ActivationFusion,AttentionAndSelfActivation) now accept a third tabular modality via atabular3data source.
Attention-based methods gained a configurablemain_modality/attention_modalityfor choosing which modality gets special treatment. - Image transforms:
prepare_fusion_dataaccepts atransformsargument (torchio.transforms-style) for image augmentation/preprocessing, for 2D and 3D images. - GPU/device configuration: a
training_modificationsargument (accelerator, number of devices) is now supported onprepare_fusion_dataandtrain_and_save_models; metric calculations follow the data's device. - MCVAE early-stopping patience and tolerance are now configurable via the layer modifications dictionary.
Robustness fixes
- Fixed the binary classification activation function (see "Breaking changes" above) - models were previously double-squashing predictions through a
Sigmoid. - Fixed a bug where MCVAE's early-stopping patience attribute was misnamed internally.
- Fixed the custom early-stopping callback.
- Image-based methods no longer error out when the image is too small for the default network architecture - they now require
layer_modsto fix the architecture instead of crashing outright. - The attention reduction ratio for channel-attention methods now auto-corrects to a working value instead of raising when it doesn't evenly divide the modality's feature dimension.
torch.loadcalls updated for current PyTorch versions (weights_only).
Output / logging improvements
- Training and validation logits are now recorded on trained models, in addition to reals and predictions.
ModelComparisonnow also returns the underlying reals/preds for further analysis.- Multiclass dimensions and image downsample size can now be passed to more of the
from_new_dataevaluation functions. - WandB's local log directory is now configurable via an environment variable.
- Loading CSVs with a stray
Unnamed: 0index column now raises a clear warning instead of silently including it.
Documentation and packaging
- Documented the three-tabular-modality feature,
main_modality/attention_modalityselection, and image transforms (previously undocumented). - Fixed a broken link and a class-name typo in the docs.
- Bumped a vulnerable
urllib3dependency pin. - Fixed CI so the vendored
mcvaegit submodule is actually fetched during test runs - this had been silently giving the MCVAE fusion model 0% test coverage. - Fixed a ReadTheDocs build timeout caused by an earlier docs cleanup accidentally discarding the sphinx-gallery example cache.
- General branch cleanup and consolidation; test coverage raised from 89% to 93% (304/304 tests passing).