ivadomed is an integrated framework for medical image analysis with deep learning.

Following #209, some refactoring in the transforms:

• im and seg transforms run separetely, see comment here.
• Only use numpy operations (i.e. no PIL)
• Be robust to both "sample" and "list of sample"
• Split file between different small files, using #212
• Implement test functions

Checklist

GitHub

• [x] I've given this PR a concise, self-descriptive, and meaningful title
• [x] I've linked relevant issues in the PR body
• [x] I've applied the relevant labels to this PR
• [ ] I've assigned a reviewer

PR contents

• [x] I've consulted ivadomed's internal developer documentation to ensure my contribution is in line with any relevant design decisions
• [x] I've added relevant tests for my contribution
• [ ] I've updated the relevant documentation for my changes, including argparse descriptions, docstrings, and ReadTheDocs tutorial pages

Description

In this pull, we aim to reformulate the semantic intervertebral disc labeling using the pose estimation technique. To this end, we utilize the stacked hourglass network. The proposed deep model takes into account the strength of semantic segmentation and pose estimation technique to handle the missing and falsely additional disc areas.

Linked issues

resolves #539 resolves #766

Run Demo:

1. Download Spine Generic Public Database (Multi-Subject) dataset
2. Run (update path to proper location):

   python prepare_dataset_vertebral_labeling.py --path ~/data-multi-subject/ -s _T2w
   

After running the above command, it will generate the mid files. While running it will print the list of subjects that the mid file is generating for them. For example:

3- Run ivadomed --train -c config_pose.json --gif 2

This PR aims at improving the documentation as a few section needs to be modified.

fix #473. fix #475

to visualize: https://ivadomed.org/en/lr-fixing_documentation/

Motivation for the feature

7T researchers cannot use SCT's segmentation models as is because features of the data are too different than 3T data used to train the model. Moreover, it would be desired to have a multi-class model (SC + GM) instead of two separate models.

Description of the feature

Researchers from the CRMBM in Marseille (Nilser Laines, Arnaud Le Troter and Virginie Callot) trained a model which would be beneficial for SCT users. The purpose of this issue is to document for the Marseille team (and everybody else wanting to chip in) the steps involved for training such a model within the ivadomed framework. The benefits is that the model will then be compatible with SCT's sct_deepseg command.

Checklist

GitHub

• [x] I've given this PR a concise, self-descriptive, and meaningful title
• [x] I've linked relevant issues in the PR body
• [x] I've applied the relevant labels to this PR
• [x] I've assigned a reviewer

PR contents

• [x] I've consulted ivadomed's internal developer documentation to ensure my contribution is in line with any relevant design decisions
• [ ] I've added relevant tests for my contribution
• [x] I've updated the relevant documentation for my changes, including argparse descriptions, docstrings, and ReadTheDocs tutorial pages

Description

In ivadomed installlation doc (https://ivadomed.org/en/latest/installation.html), under Approach 2, the second step mentions:

pip install -r requirements.txt

However, there is no mention of cloning the repo which is where the requirement.txt exists. Though git clone is an obvious step, it can make the installation instructions complete.

Linked issues

Fixes #849

We do not provide information about the used sphinx version to built doc locally. The RTD version is fixed to 1.8.5 (for now). The different version can have different behavior so the local doc and the online doc might look different. After a discussion with @kousu we have three options:

• Add the information in the wiki
• add right sphinx version to the requirements (note: might conflict with other version and not needed for most users)
• Use setuptools https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies to create one requirement files that handle two installation (one for doc , one for the rest)
• To create a requirement.txt file under doc to specify which sphinx version we are using. (currently implemented in PR #425) which would work for the online version (but not install it by default) see https://docs.readthedocs.io/en/stable/guides/specifying-dependencies.html. It needs to be used with admin right as specified in the previous link.

Any preference ?

Context

This PR introduces a basic tutorial: training and evaluation with a basic network.

Changes include:

• New tutorial: one_class_segmentation_2d_unet.rst
• Various fixes to the documentation

➤ The built documentation for this branch is available here

DONE

• add link to "compatible GPU is available" (section 'run the training') and point to info about compatible GPU, cuda config, etc.

Observed issues to fix in subsequent PRs

• Issue with doc build #347
• Pytest failing for py38 #351
• Create an ivadomed download function #346
• Add a .readthedocs.yml to configure build #349
• Create PATH_IVADOMED shell environment variable #350
• Display Starting, End, Duration for training model #353
• Save log of terminal printout during training #354
• Move log_directory from config_file to ivadomed flag #355

Checklist

GitHub

• [x] I've given this PR a concise, self-descriptive, and meaningful title
• [x] I've linked relevant issues in the PR body
• [x] I've applied the relevant labels to this PR
• [x] I've assigned a reviewer

PR contents

• [ ] I've consulted ivadomed's internal developer documentation to ensure my contribution is in line with any relevant design decisions
• [ ] I've added relevant tests for my contribution
• [x] I've updated the relevant documentation for my changes, including argparse descriptions, docstrings, and ReadTheDocs tutorial pages

Description

~Use the newish --extra-index that torch put up at https://download.pytorch.org/whl in preference to --find-links. This means a lot of the installation gymnastics can be streamlined.~

Streamline the installation by moving all dependencies back into setup.py. This essentially redoes #1000 but without the disallowed direct .whl links or the pip install ivadomed[cpu] / pip install ivadomed[gpu] extras.

Effects:

• Each requirements_x.txt becomes an “extra”, giving a consistent installation process no matter whether people are installing from git, from pypi, or as a dependency of another package. There's no fumbling with pip install -r requirements_dev.txt or pip install -r requirements_gpu.txt

• Drops requirements_gpu.txt entirely, declaring our dependency on torch/torchvision in setup.py directly.

  Doing this fixes #1130 and #861, making sure downstream packages (like SCT) can safely depend on ivadomed. This even resolves #996.

• torch is loosened to torch~=1.8.1 (meaning 1.8.1, 1.8.2, 1.8.3, …), which enables --extra-index-url https://download.pytorch.org/whl/.... for a wider set of platforms (see below)

• CUDA 11 is no longer mandatory -- it never really was.

Dropping requirements_gpu.txt is, IMO, the biggest change here. Instead of trying to second-guess torch, we will conform to their decision to put CPU-only Windows/Mac builds, but CUDA 10.* GPU Linux builds on PyPI.

The CUDA 10 GPU builds are a waste of space for the majority of Linux users (e.g.), while for a minority (i.e. us, when working on romane.neuro.polymtl.ca) they are broken because those users need CUDA 11 instead; on the other hand, the CPU builds mean Windows users can't train models if that's something they want to try to help out with.

But @kanishk16 noticed that torch provides an escape hatch to cover all these cases now, one that's better than us trying to handle it in our setup.py (i.e. #1000's experiment with pip install ivadomed[cpu] / pip install ivadomed[gpu]): torch hosts custom pip repos people can use like

pip install --extra-index-url https://download.pytorch.org/whl/cpu ivadomed # e.g. for linux users without GPUs

pip install --extra-index-url https://download.pytorch.org/whl/cu102 ivadomed # e.g. for Windows users with GPUs

pip install --extra-index-url https://download.pytorch.org/whl/cu113 ivadomed # e.g. for Linux users with very new GPUs

This PR clears the way for people to use those by getting ivadomed out of the business of assuming what hardware people have. torch's default (=PyPI) builds work for 99% of systems; people on the bleeding edge (notably: our romane.neuro.polymtl.ca system, or people who want to do deep learning natively on Windows) can adapt their pip.conf to it; but that's not and shouldn't be in ivadomed's scope. We will document "some amount" of this in followup that's already started: https://github.com/ivadomed/ivadomed/pull/1125 but, again, mostly we should stick close to torch's decisions to avoid the friction.

(please ignore the branch name; it was a naive name from the first version of this branch, something like 'torch-install' would have been better)

Linked issues

Resolves #996, Fixes https://github.com/ivadomed/ivadomed/issues/1130 as well as fixes #861 which is part of fixing https://github.com/spinalcordtoolbox/spinalcordtoolbox/pull/3790.

To be followed by https://github.com/ivadomed/ivadomed/pull/1125.

After doing the steps of the "installing" part, I tried to start the training using the ivadomed command: "ivadomed configs/config.json". I got the following error message in the terminal: "-bash: ivadomed: command not found". How could I solve it?

We are facing a severe class-imbalance issue since the introduction of the MS lesion segmentation task. This PR allows the use of new loss functions:

• focal loss: https://arxiv.org/abs/1708.02002
• generalised Dice loss: https://arxiv.org/abs/1707.03237
• mixed loss: inspired by: https://arxiv.org/pdf/1809.00076.pdf

Done:

• Implement Focal Loss for binary segmentation: details
• Display Dice Loss results while using a new loss --> as reference / safety check: details
• Add Focal loss gamma param in the config files: details
• Implement Generalised Dice Loss for binary segmentation: details
• Implement MixedLoss: details
• Re-implement dice_score to be robust to "both empty" issue: Fixes #52.
• Re-implement the Dice loss to make it compatible with mixup experiments: details

Hi,

So I am training a segmentation model of axon and myelin from microscopy images using axondeepseg. The whole process up to creating the trained model worked just fine. However when I am trying to test the trained model, it kept on producing this error: AttributeError: 'NoneType' object has no attribute 'lower'. I was wondering if you could point out where I went wrong (the full output is shown below).

Many thanks, Leroy

2022-05-30 13:48:44.003 | INFO | ivadomed.utils:init_ivadomed:421 - ivadomed (2.9.5)

2022-05-30 13:48:44.008 | INFO | ivadomed.utils:get_path_output:373 - CLI flag --path-output not used to specify output directory. Will check config file for directory... 2022-05-30 13:48:44.008 | INFO | ivadomed.utils:get_path_data:385 - CLI flag --path-data not used to specify BIDS data directory. Will check config file for directory... 2022-05-30 13:48:44.009 | INFO | ivadomed.main:set_output_path:207 - Output path already exists: drive/MyDrive/ADS22/model 2022-05-30 13:48:44.107 | INFO | ivadomed.utils:define_device:137 - Using GPU ID 0 2022-05-30 13:48:44.109 | INFO | ivadomed.utils:display_selected_model_spec:147 - Selected architecture: Unet, with the following parameters: 2022-05-30 13:48:44.109 | INFO | ivadomed.utils:display_selected_model_spec:150 - dropout_rate: 0.2 2022-05-30 13:48:44.109 | INFO | ivadomed.utils:display_selected_model_spec:150 - bn_momentum: 0.1 2022-05-30 13:48:44.109 | INFO | ivadomed.utils:display_selected_model_spec:150 - depth: 2 2022-05-30 13:48:44.110 | INFO | ivadomed.utils:display_selected_model_spec:150 - is_2d: True 2022-05-30 13:48:44.110 | INFO | ivadomed.utils:display_selected_model_spec:150 - final_activation: sigmoid 2022-05-30 13:48:44.110 | INFO | ivadomed.utils:display_selected_model_spec:150 - length_2D: [256, 256] 2022-05-30 13:48:44.111 | INFO | ivadomed.utils:display_selected_model_spec:150 - stride_2D: [244, 244] 2022-05-30 13:48:44.111 | INFO | ivadomed.utils:display_selected_model_spec:150 - folder_name: model_NewEllipse_22 2022-05-30 13:48:44.111 | INFO | ivadomed.utils:display_selected_model_spec:150 - in_channel: 1 2022-05-30 13:48:44.111 | INFO | ivadomed.utils:display_selected_model_spec:150 - out_channel: 3 2022-05-30 13:48:44.700 | INFO | ivadomed.loader.bids_dataframe:save:322 - Dataframe has been saved in drive/MyDrive/ADS22/model/bids_dataframe.csv. 2022-05-30 13:48:44.704 | WARNING | ivadomed.loader.utils:split_dataset:102 - After splitting: train, validation and test fractions are respectively 0.571, 0.286 and 0.143 of sample_id. 2022-05-30 13:48:44.786 | INFO | ivadomed.utils:display_selected_transfoms:160 - Selected transformations for the ['testing'] dataset: 2022-05-30 13:48:44.786 | INFO | ivadomed.utils:display_selected_transfoms:162 - Resample: {'hspace': 0.0001, 'wspace': 0.0001} 2022-05-30 13:48:44.787 | INFO | ivadomed.utils:display_selected_transfoms:162 - NormalizeInstance: {'applied_to': ['im']} Loading dataset: 100% 1/1 [00:00<00:00, 449.31it/s] 2022-05-30 13:48:45.956 | INFO | ivadomed.loader.loader:load_dataset:114 - Loaded 24 axial patches of shape [256, 256] for the testing set. 2022-05-30 13:48:45.957 | INFO | ivadomed.testing:test:52 - Loading model: drive/MyDrive/ADS22/model/best_model.pt Inference - Iteration 0: 83% 10/12 [00:01<00:00, 2.42it/s]2022-05-30 13:48:52.031 | WARNING | ivadomed.testing:run_inference:249 - No color labels saved due to a temporary issue. For more details see:https://github.com/ivadomed/ivadomed/issues/720 Lossy conversion from float64 to uint8. Range [0, 1]. Convert image to uint8 prior to saving to suppress this warning. Lossy conversion from float64 to uint8. Range [0, 1]. Convert image to uint8 prior to saving to suppress this warning. Inference - Iteration 0: 100% 12/12 [00:03<00:00, 3.34it/s] 2022-05-30 13:49:13.560 | INFO | ivadomed.testing:test:88 - {'dice_score': 0.9126436879383726, 'multi_class_dice_score': 0.9166985962316472, 'precision_score': 0.8887869614675107, 'recall_score': 0.9378164590446905, 'specificity_score': 0.9369739801311445, 'intersection_over_union': 0.8393234837695477, 'accuracy_score': 0.9372683577674897, 'hausdorff_score': 0.0} 2022-05-30 13:49:13.560 | INFO | ivadomed.evaluation:evaluate:33 - Run Evaluation on drive/MyDrive/ADS22/model/pred_masks

Evaluation: 0% 0/1 [00:00<?, ?it/s] Traceback (most recent call last): File "/usr/local/bin/ivadomed", line 8, in sys.exit(run_main()) File "/usr/local/lib/python3.7/site-packages/ivadomed/main.py", line 604, in run_main resume_training=bool(args.resume_training)) File "/usr/local/lib/python3.7/site-packages/ivadomed/main.py", line 517, in run_command eval_params=context[ConfigKW.EVALUATION_PARAMETERS]) File "/usr/local/lib/python3.7/site-packages/ivadomed/evaluation.py", line 66, in evaluate fname_gt = [imed_loader_utils.update_filename_to_nifti(fname) for fname in fname_gt] File "/usr/local/lib/python3.7/site-packages/ivadomed/evaluation.py", line 66, in fname_gt = [imed_loader_utils.update_filename_to_nifti(fname) for fname in fname_gt] File "/usr/local/lib/python3.7/site-packages/ivadomed/loader/utils.py", line 423, in update_filename_to_nifti extension = get_file_extension(filename) File "/usr/local/lib/python3.7/site-packages/ivadomed/loader/utils.py", line 404, in get_file_extension extension = next((ext for ext in EXT_LST if filename.lower().endswith(ext)), None) File "/usr/local/lib/python3.7/site-packages/ivadomed/loader/utils.py", line 404, in extension = next((ext for ext in EXT_LST if filename.lower().endswith(ext)), None) AttributeError: 'NoneType' object has no attribute 'lower'

Addresses #1002

Checklist

GitHub

• [ ] I've given this PR a concise, self-descriptive, and meaningful title
• [ ] I've linked relevant issues in the PR body
• [ ] I've applied the relevant labels to this PR
• [ ] I've assigned a reviewer

PR contents

• [ ] I've consulted ivadomed's internal developer documentation to ensure my contribution is in line with any relevant design decisions
• [ ] I've added relevant tests for my contribution
• [ ] I've updated the relevant documentation for my changes, including argparse descriptions, docstrings, and ReadTheDocs tutorial pages

Description

Linked issues

Checklist

GitHub

• [x] I've given this PR a concise, self-descriptive, and meaningful title
• [x] I've linked relevant issues in the PR body
• [x] I've applied the relevant labels to this PR
• [ ] I've assigned a reviewer

PR contents

• [x] I've consulted ivadomed's internal developer documentation to ensure my contribution is in line with any relevant design decisions
• [ ] I've added relevant tests for my contribution
• [x] I've updated the relevant documentation for my changes, including argparse descriptions, docstrings, and ReadTheDocs tutorial pages

Description

Even if the config file does NOT include any wandb field, training with ivadomed can use wandb in case wandb logging was previously done. This PR bypasses the wandb.login call if the key is not defined or is empty.

Linked issues

Resolves #1252

Motivation for the feature

My config file does NOT include any wandb field, yet training with ivadomed used wandb:

2023-01-01 18:25:54.402 | INFO     | ivadomed.loader.loader:load_dataset:118 - Loaded 6958 volumes of shape [32, 32, 16] for the training set.
2023-01-01 18:25:54.402 | INFO     | ivadomed.main:create_path_model:89 - Creating model directory: /home/GRAMES.POLYMTL.CA/p101317/data_nvme_p101317/model_seg_lesion_mp2rage_20230101_182457-batch_size-8/model_seg_lesion_mp2rage
wandb: Currently logged in as: jcohenadad. Use `wandb login --relogin` to force relogin
2023-01-01 18:25:55.487 | INFO     | ivadomed.utils:initialize_wandb:56 - WandB API Authentication Successful!
wandb: wandb version 0.13.7 is available!  To upgrade, please run:
wandb:  $ pip install wandb --upgrade
wandb: Tracking run with wandb version 0.13.6
wandb: Run data is saved locally in /home/GRAMES.POLYMTL.CA/p101317/data_nvme_p101317/model_seg_lesion_mp2rage_20230101_182457-batch_size-8/wandb/run-20230101_182555-3eiodlnq
wandb: Run `wandb offline` to turn off syncing.
wandb: Syncing run run-1
wandb: ⭐️ View project at https://wandb.ai/jcohenadad/my_project
wandb: 🚀 View run at https://wandb.ai/jcohenadad/my_project/runs/3eiodlnq

This is probably because the code checks for an environment variable? Anyway, this is highly confusing and undesired. I suggest to not activate wandb if it is not mentioned in the config file.

Motivation for the feature

When using ivadomed_automate_training with wandb, the JSON config file of ivadomed specifies a single group/run, hence all runs are aggregated into the same group/run.

Note: This feature won't be necessary if https://github.com/ivadomed/ivadomed/issues/1124 is fixed.

Description of the feature

Create a specific group (or run) for each training managed by ivadomed_automate_training.

Motivation for the feature

I find this section on https://ivadomed.org/tutorials/automate_training.html#default a bit confusing.

Here is the text:

If neither all-combin nor multi-params is selected, then the hyperparameters will be combined as follows into a config_list. I am not showing the actual config_list here as it would take up too much space. The options listed below are incorporated into the base config file in config.json.

What exactly is this config_list? Something the user has to provide?

And the note (which, BTW should not be written in the first person) is also confusing. What does it mean that the "options [...] are incorporated into the base config file in config.json."? I thought that the hyperparams from the config_hyper.json file actually overwrites that from the config.json?

Checklist

GitHub

• [ ] I've given this PR a concise, self-descriptive, and meaningful title
• [ ] I've linked relevant issues in the PR body
• [ ] I've applied the relevant labels to this PR
• [ ] I've assigned a reviewer

PR contents

• [ ] I've consulted ivadomed's internal developer documentation to ensure my contribution is in line with any relevant design decisions
• [ ] I've added relevant tests for my contribution
• [ ] I've updated the relevant documentation for my changes, including argparse descriptions, docstrings, and ReadTheDocs tutorial pages

Description

Initial prototype for using Wandb sweep with ivadomed. Feedback welcome!

Linked issues

Resolves https://github.com/ivadomed/ivadomed/issues/1124