convexAdam 0.2.0

Convex Adam

convexAdam

News:

• :zap: Our Journal paper extension got accepted to IEEE TMI! :tada:
• :zap: Easy installation with pip available!

:zap: Fast and accurate optimisation for registration with little learning

:star: ConvexAdam ranks first for the Learn2Reg Challenge Datasets! :star:

:floppy_disk: Installation

You can run ConvexAdam out of the box with

pip install convexAdam

:bar_chart: Self-configuring hyperparameter optimisation

To obtain an automatic estimate of the best choice of all various hyperparameter configurations, we propose a rank-based multi-metric two-stage search mechanism that leverages the fast dual optimisation employed in ConvexAdam to rapidly evaluate hundreds of settings.

We consider two scenarios: with and without available automatic semantic segmentation features using a pre-trained nnUNet. In the latter case we employ the handcraft MIND-SSC feature descriptor. For the former all infered train/test segmentations for the Learn2Reg tasks can be obtained at https://cloud.imi.uni-luebeck.de/s/cgXJfjDZNNgKRZe

Next we create a small config file for a new task that is similar to the Learn2Reg dataset.json and contains information on which training/validation pairs to use and how many (if any) labels are available for test/evaluation.

The entire self-configuring hyperparameter optimisation can usually be run in 1 hour or less and comprises two scripts that are executed after another.

convex_run_withconfig.py and adam_run_with_config.py

Each will test various settings, run online validation on the training/validation data and create a small log of all obtained scores that are ranked across those individual settings using a simplified version of Learn2Reg's evaluation (normalised per metric ranking w/o statistical significance and a geometric mean across metrics).

Finally you can use infer_convexadam.py to apply the best parameter setting to the test data and refer to https://github.com/MDL-UzL/L2R/tree/main/evaluation for the official evaluation.

:books: Citations

If you find our work helpful, please cite:

%convexAdam + Hyperparameter Optimisation TMI
@article{siebert2024convexadam,
  title={ConvexAdam: Self-Configuring Dual-Optimisation-Based 3D Multitask Medical Image Registration},
  author={Siebert, Hanna and Gro{\ss}br{\"o}hmer, Christoph and Hansen, Lasse and Heinrich, Mattias P},
  journal={IEEE Transactions on Medical Imaging},
  year={2024},
  publisher={IEEE}
}
% Original Learn2Reg2021 Submission
@inproceedings{siebert2021fast,
  title={Fast 3D registration with accurate optimisation and little learning for Learn2Reg 2021},
  author={Siebert, Hanna and Hansen, Lasse and Heinrich, Mattias P},
  booktitle={International Conference on Medical Image Computing and Computer-Assisted Intervention},
  pages={174--179},
  year={2021},
  organization={Springer}
}
% Registration with Convex Optimisation
@inproceedings{heinrich2014non,
  title={Non-parametric discrete registration with convex optimisation},
  author={Heinrich, Mattias P and Papie{\.z}, Bartlomiej W and Schnabel, Julia A and Handels, Heinz},
  booktitle={Biomedical Image Registration: 6th International Workshop, WBIR 2014, London, UK, July 7-8, 2014. Proceedings 6},
  pages={51--61},
  year={2014},
  organization={Springer}
}