transform documentation enhancements

Is your feature request related to a problem? Please describe.

Until now we are using MONAI for our training pipeline and torchio for data augmentations (offline preprocessed). The data augmentations torchio provides are very medically relevant. Their documentation, naming of the augmentations and the visual examples are very helpful.

Original	Random blur
Random flip	Random noise
Random affine transformation	Random elastic transformation
Random bias field artifact	Random motion artifact
Random spike artifact	Random ghosting artifact
Random Anisotropy	Random Swap

We struggled finding equivalent methods in MONAI and even when we did, we were not certain that these are actually the same methods. We therefore never bothered using MONAI for data augmentations. We would like to replace torchio with MONAI to further reduce our dependencies.

Describe the solution you’d like

1. We wish that MONAI would provide the same transformations as torchio does.
2. We also wish that MONAI provides a equally good documentation and uses medical terms for naming for these transforms.
3. MONAI should add visual examples for these transforms (in the form of GIFs if possible)

While this issue is meant as a feature request, I see that it has a wide scope. It is also a question in that I might just not see the equivalents. Let’s see were MONAI currently is. I will to try find the equivalent transforms of both packages.

torchio	MONAI
RandomAnisotropy	Downsampling + Upsampling with Spacing
RandomBlur	RandGaussianSmooth
RandomFlip	RandFlip
RandomNoise	RandGaussianNoise
RandomAffine	RandAffine
RandomElasticDeformation	Rand3DElastic
RandomBiasField	RandBiasField
RandomMotion	?
RandomSpike	RandKSpaceSpikeNoise
RandomGhosting	?
RandomGamma	RandAdjustContrast
RandomSwap	?

Having visual examples in the documentation of the transforms would really help.

Other open issues on data augmentations I could find:

• https://github.com/Project-MONAI/MONAI/issues/1847
• https://github.com/Project-MONAI/MONAI/issues/2186
• https://github.com/Project-MONAI/MONAI/issues/2707
• https://github.com/Project-MONAI/MONAI/issues/2701
• https://github.com/Project-MONAI/MONAI/issues/2691
• https://github.com/Project-MONAI/MONAI/issues/2245
• https://github.com/Project-MONAI/MONAI/issues/1993

I would like to collect all task which are needed for MONAI to match torchio on its documentation and transforms.

The following tasks will be necessary to match torchio:

• Implement RandAnisotropy similar to RandomAnisotropy. This should be implemented with a sequential down and up sampling via Spacing.
• Implement a RandMotion similar to RandomMotion. See also MRI k-Space Motion Artefact Augmentation: Model Robustness and Task-Specific Uncertainty.
• Implement a RandPatchSwap similar to RandomSwap. Coordinate with https://github.com/Project-MONAI/MONAI/issues/2701 where a RandPatchShuffle is proposed.
• Implement a RandGhosting similar to . See also Ghost Artifacts - Why do motion artifacts often form into discrete ghosts?
• Add example images to documentation of transforms (especially the augmentation transforms). If possible create GIFs like it is done in torchio (see above).

[Spenhouet]

Hi @fepegar, first of I would like to thank you for your great library. As I already wrote above I really value the documentation and that it is highly medically relevant. Sorry that I did not tag you on this issue. No bad intention.

I’m not sure it’s necessary to spend resources in implementing more and more transforms. TorchIO and MONAI can be mixed more or less easily

Having MONAI transform wrappers around torch.io transforms would be an option but this would add torch.io as dependency to MONAI and that is a decision I have no say in but doubt that it is likely. For us, as a medtech software company, reducing dependencies is crucial. For each SOUP (software of unknown provenance) we have to perform validations, risk assessments, … and then again on updates. This is a lot of work for a Startup.

I agree that this seemingly binds “unnecessary” resources but having a single framework instead of multiple is way better for us (and probably many more). Currently there are way to many individual projects on the same topics and combining resources would be the best. But it is how it is. We did see the most potential for our use case in MONAI and therefore went with it. But MONAI doesn’t yet provide the same data augmentations as torch.io does why we are still dependent on torch.io. Therefore my wish to close this gap.

[aylward]

MONAI isn’t even version 1.0 yet and your are already stopping change for backwards compatibility? I feel like this library needs to undergo a lot of change until it reaches v1. Personally I would prioritize refactoring to a good initial v1 instead of directly starting with a legacy product.

Agreed. Maybe now is a good time to start introducing @deprecated usage and policies. This was a huge point of discussion with ITK. You can see opinions from various folks here: https://itk.org/Wiki/ITK/Backward_Compatibility_Open_Discussion

Your comments on the importance of naming (to reduce learning curve) and suggestion for maintaining backward compatibility is perfect (if deprecation notifications are also provided).