Merge pull request #2 from axondeepseg/ac/update_readme

Update README according to new template

README.md

@@ -1,9 +1,53 @@
 # model_seg_rat_axon-myelin_bf
+---
+## Model overview
+
+<figure>
+
+![bf model preview image](bf_model_preview.png)
+
+<figcaption><p align="center"><b><i>Image courtesy of Gregory Borschel and Simeon Daeschler.</i></b></p></figcaption>
+
+</figure>
+
 Default Bright-Field (BF) optical microscopy model that works at a resolution of 0.1 micrometer per pixel.
 
-# Steps to train this model
-1. Get `ivadomed` version: [[83f11d4]](https://github.com/ivadomed/ivadomed/pull/980/commits/83f11d4433f8a8679d11bb7667a4e1d9e02c56b1)
-2. Get the data: `data_axondeepseg_bf_training` (duke/projects/axondeepseg/20211105_bf_datasets/data_axondeepseg_bf_training)
-3. Copy the "model_seg_rat_axon-myelin_bf_training.json" and "split_dataset.joblib" files, and update the following fields: `fname_split`, `path_output`, `path_data` and `gpu_ids`.
-4. Run ivadomed: `ivadomed -c path/to/the/config/file`
-5. The trained model file will be saved under the `path_output` directory.
+## Segment (ADS)
+To segment an image using this model, use the following command in an `axondeepseg` virtual environment:
+```
+axondeepseg -t BF -i <IMG_PATH> -s <PIXEL_SIZE>
+```
+The `-m` option can be omitted in this case because this is a default built-in model.
+
+## Train and test (ivadomed)
+This model was trained and tested with [ivadomed](https://ivadomed.org). We recommend you install ivadomed in a virtual environment to reproduce the original training steps. The specific revision hash of the version used for training is documented in the *version_info.log* file.
+
+### Clone this repository
+You will need the *model_seg_rat_axon-myelin_bf.json* configuration file located in this repo.
+```
+git clone https://github.com/axondeepseg/default-BF-model
+```
+
+### Get the data
+The dataset used to train this model is hosted on git-annex at `data.neuro.polymtl.ca:datasets/data_axondeepseg_bf_training`. The dataset revision hash used for training is `f833b905c2cb221d45b2ef5ac2fad1100e70b410`.
+
+### Train this model
+To train the model, please first update the following fields in the aforementioned JSON configuration file:
+- `gpu_ids`: specific to your hardware
+- `path_output`: where the model will be saved
+- `loader_parameters:path_data`: path to training data
+- `loader_parameters:bids_config`: path to the custom bids config located in `ivadomed/config/config_bids.json`
+- `split_dataset:fname_split`: path to the split_dataset.joblib file
+
+Then, you can train the model with
+```
+ivadomed --train -c path/to/model_seg_rat_axon-myelin_bf.json
+```
+The trained model file will be saved under the `path_output` directory. For more information about training models in `ivadomed`, please refer to the following [tutorial](https://ivadomed.org/tutorials/two_class_microscopy_seg_2d_unet.html).
+
+### Evaluate this model
+To test the performance of this model, use
+```
+ivadomed --test -c path/to/model_seg_rat_axon-myelin_bf.json
+```
+The evaluation results will be saved in `"path_output"/results_eval/evaluation_3Dmetrics.csv`

version_info.log

@@ -0,0 +1,36 @@
+IVADOMED TOOLBOX
+----------------
+(git-mhb/979-filter-patch-346ca0c4de8e8ec670d808011b999f42ec11775d*)
+
+
+DATASET VERSION
+---------------
+The following BIDS dataset(s) were used for training.
+1. /home/GRAMES.POLYMTL.CA/maboudb/data_extrassd_maboudb/20211013_optim_om/data_axondeepseg_bf_source/ - Dataset is not Annexed.
+
+
+SYSTEM INFO
+-------------
+OS: linux (Linux-5.4.0-90-generic-x86_64-with-glibc2.27)
+CPU cores: Available: 40
+
+
+
+
+CONFIG INPUTS
+-------------
+command: segment
+gpu_ids: [6]
+path_output: ../data_extrassd_maboudb/20211013_optim_om/20211112_log_bf_base512_full_filter_medium_da
+model_name: model_seg_rat_axon-myelin_bf
+debugging: True
+log_file: log
+object_detection_params: {'object_detection_path': None, 'safety_factor': [1.0, 1.0, 1.0]}
+loader_parameters: {'path_data': ['/home/GRAMES.POLYMTL.CA/maboudb/data_extrassd_maboudb/20211013_optim_om/data_axondeepseg_bf_source/'], 'subject_selection': {'n': [], 'metadata': [], 'value': []}, 'target_suffix': ['_seg-axon-manual', '_seg-myelin-manual'], 'extensions': ['.png'], 'roi_params': {'suffix': None, 'slice_filter_roi': None}, 'contrast_params': {'training_validation': ['BF'], 'testing': ['BF'], 'balance': {}}, 'slice_filter_params': {'filter_empty_mask': False, 'filter_empty_input': False, 'filter_empty_mask_patch': True}, 'slice_axis': 'axial', 'multichannel': False, 'soft_gt': False, 'is_input_dropout': False, 'bids_config': 'ivadomed/config/config_bids.json'}
+split_dataset: {'fname_split': '../data_extrassd_maboudb/20211013_optim_om/config/split_datasets.joblib', 'random_seed': 6, 'split_method': 'participant_id', 'data_testing': {'data_type': None, 'data_value': []}, 'balance': None, 'train_fraction': 0.7, 'test_fraction': 0.1}
+training_parameters: {'batch_size': 4, 'loss': {'name': 'DiceLoss'}, 'training_time': {'num_epochs': 150, 'early_stopping_patience': 50, 'early_stopping_epsilon': 0.001}, 'scheduler': {'initial_lr': 0.005, 'lr_scheduler': {'name': 'CosineAnnealingLR', 'base_lr': 1e-05, 'max_lr': 0.01}}, 'balance_samples': {'applied': False, 'type': 'gt'}, 'mixup_alpha': None, 'transfer_learning': {'retrain_model': None, 'retrain_fraction': 1.0, 'reset': True}}
+default_model: {'name': 'Unet', 'dropout_rate': 0.2, 'bn_momentum': 0.1, 'depth': 4, 'is_2d': True, 'final_activation': 'sigmoid', 'length_2D': [512, 512], 'stride_2D': [500, 500]}
+uncertainty: {'epistemic': False, 'aleatoric': False, 'n_it': 0}
+postprocessing: {'binarize_maxpooling': {}}
+evaluation_parameters: {}
+transformation: {'Resample': {'wspace': 0.0001, 'hspace': 0.0001}, 'RandomAffine': {'degrees': 2.5, 'scale': [0.05, 0.05], 'translate': [0.015, 0.015], 'applied_to': ['im', 'gt'], 'dataset_type': ['training']}, 'ElasticTransform': {'alpha_range': [28.0, 30.0], 'sigma_range': [3.5, 4.5], 'p': 0.1, 'applied_to': ['im', 'gt'], 'dataset_type': ['training']}, 'NormalizeInstance': {'applied_to': ['im']}}