MOOSE: A Python repository from n7k-dobri

MOOSE 2.0 🦌- Leaner. Meaner. Stronger 💪

Unveiling a new dimension in 3D medical image segmentation: MOOSE 2.0 🚀

Crafted meticulously from the core principles of data-centric AI, MOOSE 2.0 is our response to the demands of both preclinical and clinical imaging.

✨ It's Leaner: We've hacked away the fluff and made MOOSE 2.0 leaner than ever before. This bad boy doesn't need heavy-duty computing. With less than 32GB of RAM, compatibility across OS, and the flexibility to work with or without NVIDIA GPUs, MOOSE 2.0 fits right into any environment. 🔬

💥 It's Meaner: The QIMPies have poured their hearts and souls into building this beast from scratch. With the speed clocking 5x faster than its predecessor, MOOSE 2.0 cuts through the noise and gets down to business instantly. It serves up a range of segmentation models designed for both clinical and preclinical settings. No more waiting, no more compromises. It's Mean Machine time! ⚡

🔥 It's Stronger: MOOSE 2.0 is powered by the sheer strength of Data-centric AI principles. With a whopping 1.5k whole-body PET/CT datasets, that's ~40x times more data than our first model, we're packing a punch. MOOSE 2.0 comes with the strength and knowledge gained from an array of data that's simply unparalleled. The result? Better precision, improved outcomes, and a tool you can trust. 💼

🔔 📢 💥 And now, it's even more versatile, with MOOSE 2.0, you now have the flexibility to use it as a powerful command-line tool for batch processing, or as a library package for individual processing in your Python projects. The choice is yours! 😎

Accommodating an array of modalities including PET, CT, and MRI, MOOSE 2.0 stands at the cusp of a paradigm shift. It’s not just an upgrade; it’s our commitment to making MOOSE 2.0 your go-to for segmentation tasks.

Join us as we embark on this journey.

Shows an illustrated MOOSE story board adopted to different themes

Available Segmentation Models 🧬

MOOSE 2.0 offers a wide range of segmentation models catering to various clinical and preclinical needs. Here are the models currently available:

Clinical 👫🏽

Preclinical 🐁

Each model is designed to provide high-quality segmentation with MOOSE 2.0's optimized algorithms and data-centric AI principles.

Star History 🤩

Citations ❤️

Shiyam Sundar, L. K., Yu, J., Muzik, O., Kulterer, O., Fueger, B. J., Kifjak, D., Nakuz, T., Shin, H. M., Sima, A. K., Kitzmantl, D., Badawi, R. D., Nardo, L., Cherry, S. R., Spencer, B. A., Hacker, M., & Beyer, T. (2022). Fully-automated, semantic segmentation of whole-body ¹⁸F-FDG PET/CT images based on data-centric artificial intelligence. Journal of Nuclear Medicine. https://doi.org/10.2967/jnumed.122.264063
Isensee, F., Jaeger, P.F., Kohl, S.A.A. et al. nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nat Methods 18, 203–211 (2021). https://doi.org/10.1038/s41592-020-01008-z

Requirements ✅

Before you dive into the incredible world of MOOSE 2.0, here are a few things you need to ensure for an optimal experience:

Operating System: We've got you covered whether you're on Windows, Mac, or Linux. MOOSE 2.0 has been tested across these platforms to ensure seamless operation.
Memory: MOOSE 2.0 has quite an appetite! Make sure you have at least 32GB of RAM for the smooth running of all tasks.
GPU: If speed is your game, an NVIDIA GPU is the name! MOOSE 2.0 leverages GPU acceleration to deliver results fast. Don't worry if you don't have one, though - it will still work, just at a slower pace.
Python: Ensure that you have Python 3.10 installed on your system. MOOSE 2.0 likes to keep up with the latest, after all!

So, that's it! Make sure you're geared up with these specifications, and you're all set to explore everything MOOSE 2.0 has to offer. 🚀🌐

Installation Guide 🛠️

Available on Windows, Linux, and MacOS, the installation is as simple as it gets. Follow our step-by-step guide below and set sail on your journey with MOOSE 2.0.

For Linux and MacOS 🐧🍏

First, create a Python environment. You can name it to your liking; for example, 'moose-env'.
```
python3 -m venv moose-env
```

Activate your newly created environment.

source moose-env/bin/activate  # for Linux
source moose-env/bin/activate  # for MacOS

Install MOOSE 2.0.
```
pip install moosez
```

Voila! You're all set to explore with MOOSE 2.0.

For Windows 🪟

Create a Python environment. You could name it 'moose-env', or as you wish.
```
python -m venv moose-env
```
Activate your newly created environment.
```
.\moose-env\Scripts\activate
```
Go to the PyTorch website and install the appropriate PyTorch version for your system. !DO NOT SKIP THIS!
Finally, install MOOSE 2.0.
```
pip install moosez
```

There you have it! You're ready to venture into the world of 3D medical image segmentation with MOOSE 2.0.

Happy exploring! 🚀🔬

Usage Guide 📚

Command-line tool for batch processing 💻

Embarking on your journey with MOOSE 2.0 is straightforward and easy. Our command-line tool for batch processing requires only two arguments: the directory path where your subject images are stored, and the segmentation model name you wish to use. Here's how you can get started:

moosez -d <path_to_image_dir> -m <model_name>

Here <path_to_image_dir> refers to the directory containing your subject images and <model_name> is the name of the segmentation model you intend to utilize.

For instance, to perform clinical CT organ segmentation, the command would be:

moosez -d <path_to_image_dir> -m clin_ct_organs

In this example, 'clin_ct_organs' is the segmentation model name for clinical CT organ segmentation.

And that's it! With just one command, you're all set to explore the new horizons of 3D medical image segmentation with MOOSE 2.0.

Need assistance along the way? Don't worry, we've got you covered. Simply type:

moosez -h

This command will provide you with all the help and the information about the available models and the regions it segments.

Using MOOSE 2.0 as a Library 📚

MOOSE 2.0 can also be imported and used as a library in your own Python projects. Here's how you can do it:

First, import the moose function from the moosez package in your python script:

from moosez import moose

Then, call the moose function to run predictions. The moose function takes four arguments:

model_name: The name of the model to use for the predictions.
input_dir: The directory containing the images (in nifti, either .nii or .nii.gz) to process.
output_dir: The directory where the output will be saved.
accelerator: The type of accelerator to use (e.g., "cpu", "cuda").

Here's an example of how to call the moose function:

model_name = 'clin_ct_organs'
input_dir = '/home/Documents/your_project/data/input'
output_dir = '/home/Documents/your_project/data/output'
accelerator = 'cuda'
moose(model_name, input_dir, output_dir, accelerator)

Remember to replace model_name, input_dir, output_dir, and accelerator with the actual values you want to use.

That's it! MOOSE 2.0 will now process the images in the input directory and save the output in the output directory. Enjoy using MOOSE 2.0 as a library in your Python projects!

Directory Structure and Naming Conventions for MOOSE 📂🏷️

Applicable only for batch mode ⚠️

Using MOOSE 2.0 optimally requires your data to be structured according to specific conventions. MOOSE 2.0 supports both DICOM and NIFTI formats. For DICOM files, MOOSE infers the modality from the DICOM tags and checks if the given modality is suitable for the chosen segmentation model. However, for NIFTI files, users need to ensure that the files are named with the correct modality as a suffix.

Required Directory Structure 🌳

Please structure your dataset as follows:

MOOSEv2_data/
├── S1
│   ├── AC-CT
│   │   ├── WBACCTiDose2_2001_CT001.dcm
│   │   ├── WBACCTiDose2_2001_CT002.dcm
│   │   ├── .
│   │   ├── .
│   │   ├── .
│   │   └── WBACCTiDose2_2001_CT532.dcm
│   └── AC-PT
│       ├── DetailWB_CTACWBPT001_PT001.dcm
│       ├── DetailWB_CTACWBPT001_PT002.dcm
│       ├── .
│       ├── .
│       ├── .
│       └── DetailWB_CTACWBPT001_PT532.dcm
├── S2
│   └── CT_S2.nii
├── S3
│   └── CT_S3.nii
├── S4
│   └── S4_ULD_FDG_60m_Dynamic_Patlak_HeadNeckThoAbd_20211025075852_2.nii
└── S5
    └── CT_S5.nii

Note: If the necessary naming conventions are not followed, MOOSE 2.0 will skip the subjects.

Naming Conventions for NIFTI files 📝

When using NIFTI files, you should name the file with the appropriate modality as a suffix.

For instance, if you have chosen the model_name as clin_ct_organs, the CT scan for subject 'S2' in NIFTI format, should have the modality tag 'CT_' attached to the file name, e.g. CT_S2.nii. In the directory shown above, every subject will be processed by moosez except S4.

Remember: Adhering to these file naming and directory structure conventions ensures smooth and efficient processing with MOOSE 2.0. Happy segmenting! 🚀

🎉 Add and contribute Your Own nnUNetv2 Models to MooseZ 🚀

Want to power-up your medical image segmentation tasks? ⚡ Join the MooseZ community and contribute your own nnUNetv2 models! 🥇:

By adding your custom models to MooseZ, you can enjoy:

⏩ Increased Speed - MooseZ is optimized for fast performance. Use it to get your results faster!
💾 Reduced Memory - MooseZ is designed to be efficient and lean, so it uses less memory!

So why wait? Make your models fly with MooseZ ✈️

How to Contribute Your Model 🛠️

Prepare Your Model 📁

Train your model using nnUNetv2 and get it ready for the big leagues!
Update AVAILABLE_MODELS List ✏️

Include your model's unique identifier to the AVAILABLE_MODELS list in the resources.py file. The model name should follow a specific syntax: 'clin' or 'preclin' (indicating Clinical or Preclinical), modality tag (like 'ct', 'pt', 'mr'), and then the tissue of interest.
Update MODELS Dictionary 📋

Add a new entry to the MODELS dictionary in the resources.py file. Fill in the corresponding details (like URL, filename, directory, trainer type, voxel spacing, and multilabel prefix).
Update expected_modality Function 📝

Update the expected_modality function in the resources.py file to return the imaging technique, modality, and tissue of interest for your model.
Update map_model_name_to_task_number Function 🗺️

Modify the map_model_name_to_task_number function in the resources.py file to return the task number associated with your model.
Update ORGAN_INDICES in constants.py 🧠

Append the ORGAN_INDICES dictionary in the constants.py with your label intensity to region mapping. This is particularly important if you would like to have your stats from the PET images based on your CT masks.

That's it! You've successfully contributed your own model to the MooseZ community! 🎊

With your contribution 🙋, MooseZ becomes a stronger and more robust tool for medical image segmentation! 💪

A Note on QIMP Python Packages: The 'Z' Factor 📚🚀

All of our Python packages here at QIMP carry a special signature – a distinctive 'Z' at the end of their names. The 'Z' is more than just a letter to us; it's a symbol of our forward-thinking approach and commitment to continuous innovation.

Our MOOSE package, for example, is named as 'moosez', pronounced "moose-see". So, why 'Z'?

Well, in the world of mathematics and science, 'Z' often represents the unknown, the variable that's yet to be discovered, or the final destination in a series. We at QIMP believe in always pushing boundaries, venturing into uncharted territories, and staying on the cutting edge of technology. The 'Z' embodies this philosophy. It represents our constant quest to uncover what lies beyond the known, to explore the undiscovered, and to bring you the future of medical imaging.

Each time you see a 'Z' in one of our package names, be reminded of the spirit of exploration and discovery that drives our work. With QIMP, you're not just installing a package; you're joining us on a journey to the frontiers of medical image processing. Here's to exploring the 'Z' dimension together! 🚀