October 22, 2022: MOOSE version 0.1.4: If your previous MOOSE installation suddenly stopped working or if you downloaded MOOSE recently (Oct 1-22, 2022) and it doesn't work, reinstall MOOSE with the latest version (MOOSE v0.1.4). Please reach us out on discord (click the discord label link above), if the error persists, we will be happy to help.
MOOSE (Multi-organ objective segmentation) a data-centric AI solution that generates multilabel organ segmentations to facilitate systemic TB whole-person research. The pipeline is based on nn-UNet and has the capability to segment 120 unique tissue classes from a whole-body 18F-FDG PET/CT image. The input can be an 18F-FDG PET/CT image or a CT only image (but never a PET only image) and the segmentation of the tissues is done automatically based on the provided DICOM input.
As mentioned earlier, MOOSE is built on data-centric AI principles where the state-of-the-art architecture (nnUNet in our case) is fixed and the training data is selectively augmented to ensure peak segmentation performance. The segmentation performance is continously monitored in a systemic manner using the concept of similarity space (refer manuscript). Data that causes a decrease in the performance is automatically identified and included to the initial training dataset for maintaining peak performance. ⭐️ us if you like our work!
MOOSE has been ONLY tested on Ubuntu linux OS, with the following hardware capabilities:
- Intel(R) Xeon(R) Silver 4216 CPU @ 2.10GHz
- 256 GB of RAM (Very important for total-body datasets)
- 1 x Nvidia GeForce RTX 3090 Ti (or similar) We are testing different configurations now, but the RAM (256 GB) seems to be a hard requirement if you are using whole-body CT datasets with high resolution.
We offer two flavors of installation:
- Installing in your local machine and
- Installing in your shared server (e.g. DGX) via docker.
I personally recommend the docker as you have a fully functional, ready-to-go solution. But honestly, depends on what you like!
Include sudo as shown below, in case you don't have write access. If you use sudo, make sure you type sudo su before you run moose, check usage! If you do have write access, meaning its really your personal server, feel free to ignore the sudo part
Kindly copy the code below and paste it on your ubuntu terminal, the installer should ideally take care of the rest. A fresh install would approximately take 5-10 minutes. We have also made a video of how to perform a fresh install of moose
sudo git config --global url."https://".insteadOf git://
sudo git clone https://github.com/QIMP-Team/MOOSE.git
cd MOOSE
sudo bash moose_installer.shsource ~/.bashrcYou can uninstall MOOSE by following the steps here and also there is a video which shows how to perform the uninstallation!
If you have already installed moose before. You need to uninstall moose before installing the current version. This can be easily done by using the command below.
sudo git config --global url."https://".insteadOf git://
sudo git clone https://github.com/QIMP-Team/MOOSE.git
cd MOOSE
sudo bash moose_uninstaller.shOnce these steps are done, follow the steps below to do a fresh install of moose.
sudo bash moose_installer.shsource ~/.bashrcWe have already created the docker image for you, all you need to do is load it. We assume that you have already installed docker in your system (solutions to common 'installation and image-loading' issues in docker can be found here). Make sure you replace the path_to_mount_without_the_quotes in the last command with your own local path (e.g. /home/Documents/data-to-moose) , which needs to be mounted to the container (now your mounted data will be in the container at /data). We have made a video regarding the moose docker installation, to give an overview of how it is done.
mkdir moose_dckr
cd moose_dckr
wget "https://moose-files.s3.eu-de.cloud-object-storage.appdomain.cloud/moose_16072022.tar"
docker load < moose_16072022.tar
docker run --gpus all --name moose -it --ipc=host -v 'path_to_mount_without_the_quotes':/data moose:latest /bin/bashAfter this step, a docker container with the name 'moose' will be created. In case you exited the moose container, you can start and run the container using the following commands mentioned in step 2!
docker start moose
docker attach mooseYou will now be inside the moose container after the execution of the docker attach moose command. Kindly refer the usage section for running moose on your datasets. You don't need to sudo su before you run moose, if you are using it via docker!
If you have troubles with the installation, you can reach us via discord!
MOOSE inherently performs batchwise analysis. Once you have all the patients to be analysed in a main directory, the analysis is performed sequentially. The output folders that will be created by the script itself are highlighted with the tag "Auto-generated" (refer results section). Organising the folder structure is the sole responsibility of the user. Also closely monitor the moose.log file for finding out more about the workflow of MOOSE. All the labels are stored under the 'labels' folder of each subject.
main_folder/ # The mother folder that holds all the patient folders (folder name can be anything)
├── SUB01 # Individual patient folder (folder name can be anything)
│ ├── AC_CT # Required: The CT folder name can be named anything as long as the files inside this folder is DICOM
│ └── PET_WB # Required: The PT folder name can be named anything as long as the files inside this folder is DICOM
└── SUB02
│ ├── AC_CT_1.2.752.37.47.345051852996.20220311.1441.5.430761
│ └── PET_WB_CORRECTED_1.2.752.37.47.345051852996.20220311.1441.5.430763
└── .
└── .
└── .
└── SUB0N
├── AC_CT_1.2.752.37.47.345051852996.20220311.1441.5.430761
└── PET_WB_CORRECTED_1.2.752.37.47.345051852996.20220311.1441.5.430763 For running the moose directly from the command-line terminal using the default options - please use the following command. In general, MOOSE performs the error analysis (refer paper) in similarity space and assumes that the given (if given) PET image is static.
#syntax:
moose -f path_to_main_folder
sudo su # In your terminal before you run moose, if you installed earlier with sudo in your local machine.
#example:
moose -f /home/kyloren/Documents/main_folder # input can be absolute path
or
moose -f /main_folder # or relative path
After you start the moose docker container, you can use the command below.
#example:
moose -f '/data/main_folder' # always absolute path
After the analysis the following folders would be created.
main_folder/ # The mother folder that holds all the patient folders (folder name can be anything)
├── SUB01 # Individual patient folder (folder name can be anything)
│ ├── AC_CT # Required: The CT folder name can be named anything as long as the files inside this folder is DICOM
│ ├── MOOSE-SUB01 # Auto-generated: All the files generated by MOOSE will be stored here
│ │ ├── CT # Auto-generated: The NIFTI CT file derived from the DICOM images will be stored here
│ │ ├── labels # Auto-generated: All the generated labels will be stored here
│ │ │ └── sim_space
│ │ │ └── similarity-space # Auto-generated: All the files generated during the error analysis will be stored here
│ │ ├── PT # Auto-generated: The NIFTI PT file dereived from DICOM images will be stored here
│ │ └── temp # Auto-generated: Temporary folder for house-keeping
│ └── PET_WB # Required: The PT folder name can be named anything as long as the files inside this folder is DICOM
└── SUB02
├── AC_CT_1.2.752.37.47.345051852996.20220311.1441.5.430761
├── MOOSE-SUB02
│ ├── CT
│ ├── labels
│ │ └── sim_space
│ │ └── similarity-space
│ ├── PT
│ └── temp
└── PET_WB_CORRECTED_1.2.752.37.47.345051852996.20220311.1441.5.430763The generated labels are currently in nifti format and for each subject SUB0XX, the labels will be stored in SUB0XX/MOOSE-SUB0XX/labels.
The label to region correspondence can be found here!
-
Unified labels:
MOOSE-Non-cerebral-tissues-CT-SUB0XX-XXXX.nii.gz:Multilabel non-cerebral CT segmentations from the subject's CT.MOOSE-unified-PET-CT-atlas.nii.gz:Multilabel MOOSE atlas which should ideally contain all the cerebral (from PT) and non-cerebral tissues (from CT)
-
Compartmental labels:
Bones_XXXXX.nii.gz:Multilabel bone segmentations from the subject's CT.Fat-Muscle_XXXXX.nii.gz:Multilabel fat-muscle (skeletal muscle, subcutaneous and visceral fat) segmentations from the subject's CT.Organs_XXXXX.nii.gz:Multilabel abdominal organ segmentations from the subject's CT.Psoas_XXXXX.nii.gz:Psoas muscle segmentations from the subject's CT.Brain_XXXXX.nii.gz:Multilabel hammersmith atlas segmentations from the subject's PT.
-
Individual labels: All individual labels can be found inside
SUB0XX/MOOSE-SUB0XX/labels/sim_space/similarity-space/. Each label is a binary mask with their actual region name. E.g. 'Aorta' would be named asAorta.nii.gz.
MOOSE also derives statistical measures (Mean, Median, Standard-deviation, Maximum and Minimum) based on the segmentations and they are stored in MOOSE-SUB0XX/stats as .csv files.
XXXXX-ct-hu-values.csv:Hounsfield values of the regions derived from CTXXXXX-ct-volume-stats.csv:Volume of the regions derived from CTXXXXX-SUV-values.csv:SUV values of the regions derived from PT
XXXXX-Risk-of-Segmentation-error.csv:An automatically generated report, which highlights the risk of the segmentation errors for each region with the taghighorlow. High indicates that the chance of the segmentation being erroenous is high and low indicates vice-versa.
MOOSE is built on top of some amazing open-source libraries, please consider citing them as well as a token of appreciation.
MOOSE
Shiyam Sundar LK, Yu J, Muzik O, et al. Fully-automated, semantic segmentation of whole-body 18F-FDG PET/CT images based on data-centric artificial intelligence. J Nucl Med. June 2022.
nnUNet
Isensee, F., Jaeger, P. F., Kohl, S. A., Petersen, J., & Maier-Hein, K. H. (2020). nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nature Methods, 1-9.
dcm2niix
Li X, Morgan PS, Ashburner J, Smith J, Rorden C. (2016) The first step for neuroimaging data analysis: DICOM to NIfTI conversion. J Neurosci Methods. 264:47-56.
SimpleITK
Z. Yaniv, B. C. Lowekamp, H. J. Johnson, R. Beare, “SimpleITK Image-Analysis Notebooks: a Collaborative Environment for Education and Reproducible Research”, J Digit Imaging., doi: 10.1007/s10278-017-0037-8, 31(3): 290-303, 2018.
MOOSE installation/uninstallation:
- Installation in your local workstation
- Uninstallation in your local workstation
- Installation via docker image
This research was supported by:
[1] Will MOOSE only work on whole-body 18F-FDG PET/CT datasets?
*MOOSE ideally works on whole-body (head to toe) PET/CT datasets, but also works on semi whole-body PET/CT datasets (head to pelvis). We have also tested it on abdominal CT as well as thorax/chest CT. MOOSE will ideally work, if the test datasets have sufficient quality and not too different from the training datasets.
[2] Will MOOSE only work on multimodal 18F-FDG PET/CT datasets or can it also be applied to CT only? or PET only?
MOOSE automatically infers the modality type using the DICOM header tags. MOOSE builds the entire atlas with 120 tissues if the user provides multimodal 18F-FDG PET/CT datasets. The user can also provide CT only DICOM folder, MOOSE will infer the modality type and segment only the non-cerebral tissues (36/120 tissues) and will not segment the 83 subregions of the brain. MOOSE will definitely not work if only provided with 18F-FDG PET images.
[3] Will MOOSE work on non-DICOM formats?
Unfortunately the current version accepts only DICOM formats. In the future, we will try to enable non-DICOM formats for processing as well.
MOOSEv0.1.0: July release candidate
- Create a working
moose_uninstaller.sh@LalithShiyam - Create a docker image (
moose_16072022.tar) for the current version of moose v0.1.0 @LalithShiyam
MOOSEv0.2.0: December 25 release candidate
- Enable
mooseto accept non-dicom inputs (e.g. nifti/analyze/mha)@LalithShiyam - Allow users to select the choose segmentation compartments (Organs, Bones, Fat-muscle, Brain, Psoas)@LalithShiyam
- Prune/Compress the models for faster inference: (PRs welcome)@davidiommi
- Reduce memory requirement (No more 256 GB, ideally 32 GB) for MOOSE during inference: (PRs welcome) @dhaberl@Keyn34
Above image generated by dall-e