Usage

To use tiramisu-brulee in a project:

import tiramisu_brulee

Import the 2D or 3D Tiramisu CNN version with:

from tiramisu_brulee.model import Tiramisu2d, Tiramisu3d

Command-line interfaces

Tutorial

To use the command-line interfaces (CLIs), install tiramisu-brulee with the [lesionseg] extras.

Training

To train a network, create one or more CSV files with headers like “t1”, “flair”, “t2”, “pd”, etc. These columns will be interpreted as the input images. Also include a column called “label” which will be the target image. You should also create a separate CSV file or files for validation. The validation CSVs should contain the same columns as the training but with paths to images not included in the training CSVs.

Here is an example training CSV file.

Now you should create a configuration file for training with:

lesion-train --print_config > train_config.yaml

Alternatively, you can create a configuration file for training with help comments running, e.g.:

lesion-train --print_config=comments > train_config.yaml

You’ll need to add the training CSV files in the train_csv argument and all of the the validation CSV files in the valid_csv argument. Make sure they are in correspondence.

You’ll also need to modify the num_input argument to match the number of non-label columns in the csv files.

Make sure to set the gpus argument to some number greater than or equal to 1 (assuming you want to train on one of more GPUs). If you use multiple GPUs, you should also change accelerator to ddp and sync_batchnorm to true.

You should also consider using a 2.5D or pseudo-3d network. The state-of-the-art in MS lesion segmentation uses such a methodology. Basically, a 2.5D network is uses 2D operations instead of 3D and the input to the network is a stack of adjacent slices, concatenated on the channel row.

To use a 2.5D/pseudo-3D network, determine which axis you want to stack the slices on. Set pseudo3d_dim to that axis (e.g., 2). Then change the patch size to something like:

- 128
- 128

and set pseudo3d_size to something small and odd like 3. Also set the pseudo3d_dim to some value between 0 and 2. If you have set num_input to N and the pseudo3d_size to M, then this will result in a 2D network with N * M input channels and trained/validated on 128x128 images (if you set the patch size as above).

Note that you can set the pseudo3d_dim per each set of train/valid CSVs, e.g., if you have two train/valid CSVs, then you can set pseudo3d_dim to:

- 1
- 2

which will set the network on corresponding to the first train/valid CSV pair to have pseudo3d_dim == 1 and the second CSV pair to have psuedo3d_dim == 2 (pseudo3d_size will correspond to both). This can be useful to replicate the training/prediction scheme used in the original Tiramisu 2.5D paper.

Now you can use your config file to train a set of lesion segmentation Tiramisu neural networks with:

lesion-train --config train_config.yaml

This will create a directory called lesion_tiramisu_experiment in the directory in which you run the above command (assuming you haven’t changed the default_root_dir field in the config file). The more times you run the above command, the more lesion_tiramisu_experiment/version_* directories will be created. So the current run is usually in the last version_* directory. Note that if you provide T train_csv files, T version_* will be created for each run, e.g., if lesion_tiramisu_experiment contains version_12 and you start training with 3 CSV files, then lesion-train will create version_13, version_14 and version_15.

You can montior your experiment with tensorboard by running, e.g.,:

tensorboard --logdir=lesion_tiramisu_experiment/version_13/tensorboard

(where the version number is changed appropriately based on your experiment.)

You can change the experiment name from lesion_tiramisu_experiment by setting experiment_name in the config file. Similarly, you can set a more descriptive trial name than version_* by setting trial_name.

Prediction

Once training is completed, a prediction config file will automatically be generated. A predict_config.yaml file will be generated in every lesion_tiramisu_experiment/version_* directory. The model_path will contain the best model path already filled in according to the (approximate) ISBI 15 score on the validation data.

Copy one of those config files and modify it to use the your prediction CSV file (i.e., a CSV with the same columns as the training minus the label column and with the addition of an out column which contains the paths to save the image).

Here is an example prediction CSV file.

You can either use patches for prediction (by setting patch_size) or predict the whole image volume at once. If you predict with patches, you’ll need to tune the batch size. If you predict the whole volume at once, leave batch_size at 1 because, even though it crops the image based on estimates foreground values and inputs the only the foreground image into the network, it is still memory-intensive.

If you set pseudo3d_dim for training, an option to make prediction faster is to set patch_size to use the full image dimensions along the non-pseudo3d_dim axis. To do so, you can set patch_size to:

- null
- null

Note that pseudo3d_size must be the same as used in training If the image to predict on has shape H x W x D, then the input to the network will be H x W x (M * N) where N is the num_input set in training and M is the pseudo3d_size. This will speed up prediction because some redundant prediction is skipped due to predicting non-overlapped patches. In general, you should leave patch_overlap as null, regardless, because the correct patch_overlap will be automatically determined based on patch_size such that there are no missing predictions.

If you are using multiple networks for prediction (by providing multiple model paths) and those networks are pseudo3d networks, then you should set pseudo3d_dim to either 1 number to be used across all models, e.g.,:

pseudo3d_dim:
- 1

Or, if each model doesn’t use the same pseudo3d_dim, then use, e.g.,:

pseudo3d_dim:
- 1
- 2

where each number corresponds to a model path.

If you run out of memory, try it on a machine with more memory or use patch-based prediction. And/or try setting the precision to 16.

Use lesion-predict --config predict_config.yaml to run prediction.

Alternatively, use the lesion-predict-image script for single time-point prediction. Note that this interface doesn’t accept a config file. Note that you input the image using the same name used for the header in training, e.g.:

lesion-predict-image --t1 /path/to/t1.nii --flair /path/to/flair.nii \
     --out path/to/prediction.nii ...

where --out is the output prediction and --label is excluded.

lesion-train

Train a Tiramisu CNN to segment lesions

usage: lesion-train [-h] [--config CONFIG] [-sd SEED] [-v] [-uri TRACKING_URI]
                    [-md MODEL_DIR] [-en EXPERIMENT_NAME] [-tn TRIAL_NAME]
                    [-stk SAVE_TOP_K] [-ni NUM_INPUT] [-nc NUM_CLASSES]
                    [-dr DROPOUT_RATE]
                    [-it {normal,xavier_normal,he_normal,he_uniform,orthogonal}]
                    [-ig INIT_GAIN] [-db DOWN_BLOCKS [DOWN_BLOCKS ...]]
                    [-ub UP_BLOCKS [UP_BLOCKS ...]] [-bl BOTTLENECK_LAYERS]
                    [-gr GROWTH_RATE] [-fcoc FIRST_CONV_OUT_CHANNELS]
                    [-rm {crop,interpolate}] [-th THRESHOLD] [-bt BETAS BETAS]
                    [-cen CHECKPOINT_EVERY_N_EPOCHS] [-pw POS_WEIGHT]
                    [-fg FOCAL_GAMMA] [-cw COMBO_WEIGHT] [-da DECAY_AFTER]
                    [-lr LEARNING_RATE] [-lf {combo,l1,mse}] [-ne N_EPOCHS]
                    [-rp] [-wd WEIGHT_DECAY] [-sl]
                    [-tm {dice,isbi15_score,loss,ppv}] --train-csv TRAIN_CSV
                    [TRAIN_CSV ...] --valid-csv VALID_CSV [VALID_CSV ...]
                    [-ps PATCH_SIZE [PATCH_SIZE ...]] [-ql QUEUE_LENGTH]
                    [-spv SAMPLES_PER_VOLUME] [-ls] [-sa]
                    [-psw POS_SAMPLING_WEIGHT] [--random-validation-patches]
                    [-bs BATCH_SIZE] [-nw NUM_WORKERS] [-rtc]
                    [-p3d {0,1,2,all} [{0,1,2,all} ...]] [-p3s PSEUDO3D_SIZE]
                    [-nsa] [-cd] [--use-memory-saving-dataset] [-mu]
                    [-ma MIXUP_ALPHA]
                    [--checkpoint_callback [CHECKPOINT_CALLBACK]]
                    [--default_root_dir DEFAULT_ROOT_DIR]
                    [--gradient_clip_val GRADIENT_CLIP_VAL]
                    [--gradient_clip_algorithm GRADIENT_CLIP_ALGORITHM]
                    [--process_position PROCESS_POSITION]
                    [--num_nodes NUM_NODES] [--num_processes NUM_PROCESSES]
                    [--devices DEVICES] [--gpus GPUS]
                    [--auto_select_gpus [AUTO_SELECT_GPUS]]
                    [--tpu_cores TPU_CORES] [--ipus IPUS]
                    [--log_gpu_memory LOG_GPU_MEMORY]
                    [--progress_bar_refresh_rate PROGRESS_BAR_REFRESH_RATE]
                    [--enable_progress_bar [ENABLE_PROGRESS_BAR]]
                    [--overfit_batches OVERFIT_BATCHES]
                    [--track_grad_norm TRACK_GRAD_NORM]
                    [--check_val_every_n_epoch CHECK_VAL_EVERY_N_EPOCH]
                    [--fast_dev_run [FAST_DEV_RUN]]
                    [--accumulate_grad_batches ACCUMULATE_GRAD_BATCHES]
                    [--max_epochs MAX_EPOCHS] [--min_epochs MIN_EPOCHS]
                    [--max_time MAX_TIME]
                    [--limit_train_batches LIMIT_TRAIN_BATCHES]
                    [--limit_val_batches LIMIT_VAL_BATCHES]
                    [--limit_test_batches LIMIT_TEST_BATCHES]
                    [--limit_predict_batches LIMIT_PREDICT_BATCHES]
                    [--val_check_interval VAL_CHECK_INTERVAL]
                    [--flush_logs_every_n_steps FLUSH_LOGS_EVERY_N_STEPS]
                    [--log_every_n_steps LOG_EVERY_N_STEPS]
                    [--accelerator ACCELERATOR] [--strategy STRATEGY]
                    [--sync_batchnorm [SYNC_BATCHNORM]]
                    [--precision PRECISION]
                    [--enable_model_summary [ENABLE_MODEL_SUMMARY]]
                    [--weights_summary WEIGHTS_SUMMARY]
                    [--num_sanity_val_steps NUM_SANITY_VAL_STEPS]
                    [--resume_from_checkpoint RESUME_FROM_CHECKPOINT]
                    [--profiler PROFILER] [--benchmark [BENCHMARK]]
                    [--deterministic [DETERMINISTIC]]
                    [--reload_dataloaders_every_n_epochs RELOAD_DATALOADERS_EVERY_N_EPOCHS]
                    [--reload_dataloaders_every_epoch [RELOAD_DATALOADERS_EVERY_EPOCH]]
                    [--auto_lr_find [AUTO_LR_FIND]]
                    [--replace_sampler_ddp [REPLACE_SAMPLER_DDP]]
                    [--detect_anomaly [DETECT_ANOMALY]]
                    [--auto_scale_batch_size [AUTO_SCALE_BATCH_SIZE]]
                    [--prepare_data_per_node [PREPARE_DATA_PER_NODE]]
                    [--plugins PLUGINS] [--amp_backend AMP_BACKEND]
                    [--amp_level AMP_LEVEL]
                    [--move_metrics_to_cpu [MOVE_METRICS_TO_CPU]]
                    [--multiple_trainloader_mode MULTIPLE_TRAINLOADER_MODE]
                    [--stochastic_weight_avg [STOCHASTIC_WEIGHT_AVG]]
                    [--terminate_on_nan [TERMINATE_ON_NAN]]

Named Arguments

--config

path to a configuration file in json or yaml format

Experiment

-sd, --seed

set seed for reproducibility

Default: 0

-v, --verbosity

increase output verbosity (e.g., -vv is more than -v)

Default: 0

-uri, --tracking-uri

use this URI for tracking metrics and artifacts with an MLFlow server

-md, --model-dir

save models to this directory if provided, otherwise save in default_root_dir

-en, --experiment-name

name of the experiment/output directory

Default: “lesion_tiramisu_experiment”

-tn, --trial-name

name of the trial/output version directory

-stk, --save-top-k

save the top k models in checkpoints

Default: 3

I/O

-ni, --num-input

number of input images (should match the number of non-label/other fields in the input csv)

Default: 1

-nc, --num-classes

number of classes to segment (1 for binary segmentation)

Default: 1

Model

-dr, --dropout-rate

dropout rate/probability

Default: 0.2

-it, --init-type

Possible choices: normal, xavier_normal, he_normal, he_uniform, orthogonal

use this type of initialization for the network

Default: “he_uniform”

-ig, --init-gain

use this initialization gain for initialization

Default: 0.2

-db, --down-blocks

tiramisu down-sample path specification

Default: [4, 4, 4, 4, 4]

-ub, --up-blocks

tiramisu up-sample path specification

Default: [4, 4, 4, 4, 4]

-bl, --bottleneck-layers

tiramisu bottleneck specification

Default: 4

-gr, --growth-rate

tiramisu growth rate (number of channels added between each layer in a dense block)

Default: 12

-fcoc, --first-conv-out-channels

number of output channels in first conv

Default: 48

-rm, --resize-method

Possible choices: crop, interpolate

use transpose conv and crop or normal conv and interpolate to correct size in upsample branch

Default: “crop”

Other

-th, --threshold

probability threshold for segmentation

Default: 0.5

Training

-bt, --betas

AdamW momentum parameters (for RMSprop, momentum and alpha)

Default: [0.9, 0.99]

-cen, --checkpoint-every-n-epochs

save model weights (checkpoint) every n epochs

Default: 1

-pw, --pos-weight

weight of positive class in focal/bce loss component of combo loss function (None -> equal, which is equivalent to setting this to 1.0)

-fg, --focal-gamma

gamma parameter for focal loss component of combo loss (0.0 -> BCE)

Default: 0.0

-cw, --combo-weight

weight of focal loss component in combo loss

Default: 0.6

-da, --decay-after

decay learning rate after this number of epochs

Default: 8

-lr, --learning-rate

learning rate for the optimizer

Default: 0.0003

-lf, --loss-function

Possible choices: combo, l1, mse

loss function to train the network

Default: “combo”

-ne, --n-epochs

number of epochs

Default: 64

-rp, --rmsprop

use rmsprop instead of adam

Default: False

-wd, --weight-decay

weight decay parameter for adamw

Default: 1e-05

-sl, --soft-labels

use soft labels (i.e., non-binary labels) for training

Default: False

-tm, --track-metric

Possible choices: dice, isbi15_score, loss, ppv

pick the best network based on this metric; metric is the mean over a validation epoch.

Default: “isbi15_score”

Data

--train-csv

path(s) to CSV(s) with training images

Default: [‘SET ME!’]

--valid-csv

path(s) to CSV(s) with validation images

Default: [‘SET ME!’]

-ps, --patch-size

training/validation patch size extracted from image

Default: [96, 96, 96]

-ql, --queue-length

queue length for torchio sampler

Default: 200

-spv, --samples-per-volume

samples per volume for torchio sampler

Default: 10

-ls, --label-sampler

use label sampler instead of uniform

Default: False

-sa, --spatial-augmentation

use spatial (affine and elastic) data augmentation

Default: False

-psw, --pos-sampling-weight

sample positive voxels with this weight/negative voxels with 1.0-this

Default: 1.0

--random-validation-patches

randomly sample patches in the validation set

Default: False

-bs, --batch-size

training/validation batch size

Default: 1

-nw, --num-workers

number of CPUs to use for loading data

Default: 16

-rtc, --reorient-to-canonical

reorient inputs images to canonical orientation (useful when using data from heterogeneous sources or using pseudo3d_dim == all; otherwise, e.g., the axis corresponding to left-right in one image might be anterior-posterior in another.)

Default: False

-p3d, --pseudo3d-dim

Possible choices: 0, 1, 2, all

dim on which to concatenate the images for input to a 2D network. If provided, either provide 1 valueto be used for each CSV or provide N values corresponding to the N CSVs. If not provided, use 3D network.

-p3s, --pseudo3d-size

size of the pseudo3d dimension (if -p3d provided)

-nsa, --non-strict-affine

if images have different affine matrices, resample the images to be consistent; avoid usingthis by coregistering your images within a subject.

Default: True

-cd, --check-dicom

check DICOM images to see if they have uniform spacing between slices; warn the user if not.

Default: False

--use-memory-saving-dataset

default dataset can leak memory when num_workers > 1, use this if you encounter non-GPU OOM errors

Default: False

Mixup

-mu, --mixup

use mixup during training

Default: False

-ma, --mixup-alpha

mixup alpha parameter for beta distribution

Default: 0.4

pl.Trainer

--checkpoint_callback

If True, enable checkpointing. .. deprecated:: v1.5 checkpoint_callback has been deprecated in v1.5 and will be removed in v1.7. Please consider using enable_checkpointing instead.

--default_root_dir

Default path for logs and weights when no logger/ckpt_callback passed. Default: os.getcwd(). Can be remote file paths such as s3://mybucket/path or ‘hdfs://path/’

--gradient_clip_val

The value at which to clip gradients. Passing gradient_clip_val=None disables gradient clipping. If using Automatic Mixed Precision (AMP), the gradients will be unscaled before.

--gradient_clip_algorithm

The gradient clipping algorithm to use. Pass gradient_clip_algorithm="value" to clip by value, and gradient_clip_algorithm="norm" to clip by norm. By default it will be set to "norm".

--process_position

Orders the progress bar when running multiple models on same machine. .. deprecated:: v1.5 process_position has been deprecated in v1.5 and will be removed in v1.7. Please pass TQDMProgressBar with process_position directly to the Trainer’s callbacks argument instead.

Default: 0

--num_nodes

Number of GPU nodes for distributed training.

Default: 1

--num_processes

Number of processes for distributed training with accelerator="cpu".

Default: 1

--devices

Will be mapped to either gpus, tpu_cores, num_processes or ipus, based on the accelerator type.

--gpus

Number of GPUs to train on (int) or which GPUs to train on (list or str) applied per node

--auto_select_gpus

If enabled and gpus is an integer, pick available gpus automatically. This is especially useful when GPUs are configured to be in “exclusive mode”, such that only one process at a time can access them.

Default: False

--tpu_cores

How many TPU cores to train on (1 or 8) / Single TPU to train on [1]

--ipus

How many IPUs to train on.

--log_gpu_memory

None, ‘min_max’, ‘all’. Might slow performance. .. deprecated:: v1.5 Deprecated in v1.5.0 and will be removed in v1.7.0 Please use the DeviceStatsMonitor callback directly instead.

--progress_bar_refresh_rate

How often to refresh progress bar (in steps). Value 0 disables progress bar. Ignored when a custom progress bar is passed to callbacks. Default: None, means a suitable value will be chosen based on the environment (terminal, Google COLAB, etc.). .. deprecated:: v1.5 progress_bar_refresh_rate has been deprecated in v1.5 and will be removed in v1.7. Please pass TQDMProgressBar with refresh_rate directly to the Trainer’s callbacks argument instead. To disable the progress bar, pass enable_progress_bar = False to the Trainer.

--enable_progress_bar

Whether to enable to progress bar by default.

Default: True

--overfit_batches

Overfit a fraction of training data (float) or a set number of batches (int).

Default: 0.0

--track_grad_norm

-1 no tracking. Otherwise tracks that p-norm. May be set to ‘inf’ infinity-norm. If using Automatic Mixed Precision (AMP), the gradients will be unscaled before logging them.

Default: -1

--check_val_every_n_epoch

Check val every n train epochs.

Default: 1

--fast_dev_run

Runs n if set to n (int) else 1 if set to True batch(es) of train, val and test to find any bugs (ie: a sort of unit test).

Default: False

--accumulate_grad_batches

Accumulates grads every k batches or as set up in the dict.

--max_epochs

Stop training once this number of epochs is reached. Disabled by default (None). If both max_epochs and max_steps are not specified, defaults to max_epochs = 1000. To enable infinite training, set max_epochs = -1.

--min_epochs

Force training for at least these many epochs. Disabled by default (None). If both min_epochs and min_steps are not specified, defaults to min_epochs = 1.

--max_time

Stop training after this amount of time has passed. Disabled by default (None). The time duration can be specified in the format DD:HH:MM:SS (days, hours, minutes seconds), as a datetime.timedelta, or a dictionary with keys that will be passed to datetime.timedelta.

--limit_train_batches

How much of training dataset to check (float = fraction, int = num_batches).

Default: 1.0

--limit_val_batches

How much of validation dataset to check (float = fraction, int = num_batches).

Default: 1.0

--limit_test_batches

How much of test dataset to check (float = fraction, int = num_batches).

Default: 1.0

--limit_predict_batches

How much of prediction dataset to check (float = fraction, int = num_batches).

Default: 1.0

--val_check_interval

How often to check the validation set. Use float to check within a training epoch, use int to check every n steps (batches).

Default: 1.0

--flush_logs_every_n_steps

How often to flush logs to disk (defaults to every 100 steps). .. deprecated:: v1.5 flush_logs_every_n_steps has been deprecated in v1.5 and will be removed in v1.7. Please configure flushing directly in the logger instead.

--log_every_n_steps

How often to log within steps (defaults to every 50 steps).

Default: 50

--accelerator

Supports passing different accelerator types (“cpu”, “gpu”, “tpu”, “ipu”, “auto”) as well as custom accelerator instances. .. deprecated:: v1.5 Passing training strategies (e.g., ‘ddp’) to accelerator has been deprecated in v1.5.0 and will be removed in v1.7.0. Please use the strategy argument instead.

--strategy

Supports different training strategies with aliases as well custom training type plugins.

--sync_batchnorm

Synchronize batch norm layers between process groups/whole world.

Default: False

--precision

Double precision (64), full precision (32), half precision (16) or bfloat16 precision (bf16). Can be used on CPU, GPU or TPUs.

Default: 32

--enable_model_summary

Whether to enable model summarization by default.

Default: True

--weights_summary

Prints a summary of the weights when training begins. .. deprecated:: v1.5 weights_summary has been deprecated in v1.5 and will be removed in v1.7. To disable the summary, pass enable_model_summary = False to the Trainer. To customize the summary, pass ModelSummary directly to the Trainer’s callbacks argument.

Default: “top”

--num_sanity_val_steps

Sanity check runs n validation batches before starting the training routine. Set it to -1 to run all batches in all validation dataloaders.

Default: 2

--resume_from_checkpoint

Path/URL of the checkpoint from which training is resumed. If there is no checkpoint file at the path, an exception is raised. If resuming from mid-epoch checkpoint, training will start from the beginning of the next epoch. .. deprecated:: v1.5 resume_from_checkpoint is deprecated in v1.5 and will be removed in v1.7. Please pass the path to Trainer.fit(..., ckpt_path=...) instead.

--profiler

To profile individual steps during training and assist in identifying bottlenecks.

--benchmark

If true enables cudnn.benchmark.

Default: False

--deterministic

If True, sets whether PyTorch operations must use deterministic algorithms. Default: False.

Default: False

--reload_dataloaders_every_n_epochs

Set to a non-negative integer to reload dataloaders every n epochs.

Default: 0

--reload_dataloaders_every_epoch

Set to True to reload dataloaders every epoch. .. deprecated:: v1.4 reload_dataloaders_every_epoch has been deprecated in v1.4 and will be removed in v1.6. Please use reload_dataloaders_every_n_epochs.

Default: False

--auto_lr_find

If set to True, will make trainer.tune() run a learning rate finder, trying to optimize initial learning for faster convergence. trainer.tune() method will set the suggested learning rate in self.lr or self.learning_rate in the LightningModule. To use a different key set a string instead of True with the key name.

Default: False

--replace_sampler_ddp

Explicitly enables or disables sampler replacement. If not specified this will toggled automatically when DDP is used. By default it will add shuffle=True for train sampler and shuffle=False for val/test sampler. If you want to customize it, you can set replace_sampler_ddp=False and add your own distributed sampler.

Default: True

--detect_anomaly

Enable anomaly detection for the autograd engine.

Default: False

--auto_scale_batch_size

If set to True, will initially run a batch size finder trying to find the largest batch size that fits into memory. The result will be stored in self.batch_size in the LightningModule. Additionally, can be set to either power that estimates the batch size through a power search or binsearch that estimates the batch size through a binary search.

Default: False

--prepare_data_per_node

If True, each LOCAL_RANK=0 will call prepare data. Otherwise only NODE_RANK=0, LOCAL_RANK=0 will prepare data .. deprecated:: v1.5 Deprecated in v1.5.0 and will be removed in v1.7.0 Please set prepare_data_per_node in LightningDataModule or LightningModule directly instead.

--plugins

Plugins allow modification of core behavior like ddp and amp, and enable custom lightning plugins.

--amp_backend

The mixed precision backend to use (“native” or “apex”).

Default: “native”

--amp_level

The optimization level to use (O1, O2, etc…). By default it will be set to “O2” if amp_backend is set to “apex”.

--move_metrics_to_cpu

Whether to force internal logged metrics to be moved to cpu. This can save some gpu memory, but can make training slower. Use with attention.

Default: False

--multiple_trainloader_mode

How to loop over the datasets when there are multiple train loaders. In ‘max_size_cycle’ mode, the trainer ends one epoch when the largest dataset is traversed, and smaller datasets reload when running out of their data. In ‘min_size’ mode, all the datasets reload when reaching the minimum length of datasets.

Default: “max_size_cycle”

--stochastic_weight_avg

Whether to use Stochastic Weight Averaging (SWA). .. deprecated:: v1.5 stochastic_weight_avg has been deprecated in v1.5 and will be removed in v1.7. Please pass StochasticWeightAveraging directly to the Trainer’s callbacks argument instead.

Default: False

--terminate_on_nan

If set to True, will terminate training (by raising a ValueError) at the end of each training batch, if any of the parameters or the loss are NaN or +/-inf. .. deprecated:: v1.5 Trainer argument terminate_on_nan was deprecated in v1.5 and will be removed in 1.7. Please use detect_anomaly instead.

lesion-predict

Use a Tiramisu CNN to segment lesions

usage: lesion-predict [-h] [--config CONFIG] -mp MODEL_PATH [MODEL_PATH ...]
                      [-sd SEED] [-oa] [-at {mean,vote,union}] [-v]
                      [-th THRESHOLD] [-mls MIN_LESION_SIZE] [-fh] [-pp]
                      --predict-csv PREDICT_CSV
                      [-ps PATCH_SIZE [PATCH_SIZE ...]]
                      [-po PATCH_OVERLAP PATCH_OVERLAP PATCH_OVERLAP]
                      [-bs BATCH_SIZE] [-nw NUM_WORKERS] [-rtc]
                      [-p3d {0,1,2,all} [{0,1,2,all} ...]]
                      [-p3s PSEUDO3D_SIZE] [-nsa] [-cd]
                      [--use-memory-saving-dataset] [--devices DEVICES]
                      [--gpus GPUS]
                      [--progress_bar_refresh_rate PROGRESS_BAR_REFRESH_RATE]
                      [--enable_progress_bar [ENABLE_PROGRESS_BAR]]
                      [--accelerator ACCELERATOR] [--strategy STRATEGY]
                      [--precision PRECISION] [--benchmark [BENCHMARK]]

Named Arguments

--config

path to a configuration file in json or yaml format

Experiment

-mp, --model-path

path to output the trained model

Default: [‘SET ME!’]

-sd, --seed

set seed for reproducibility

Default: 0

-oa, --only-aggregate

only aggregate results (useful to test different thresholds)

Default: False

-at, --aggregation-type

Possible choices: mean, vote, union

aggregate results with this method

Default: “mean”

-v, --verbosity

increase output verbosity (e.g., -vv is more than -v)

Default: 0

Other

-th, --threshold

probability threshold for segmentation

Default: 0.5

Testing

-mls, --min-lesion-size

in testing, remove lesions smaller in voxels than this

Default: 3

-fh, --fill-holes

in testing, preform binary hole filling

Default: False

-pp, --predict-probability

in testing, store the probability instead of the binary prediction

Default: False

Data

--predict-csv

path to csv of prediction images

Default: SET ME!

-ps, --patch-size

shape of patches (None -> crop image to foreground)

-po, --patch-overlap

patches will overlap by this much (None -> patch-size // 2)

-bs, --batch-size

training/validation batch size

Default: 1

-nw, --num-workers

number of CPUs to use for loading data

Default: 16

-rtc, --reorient-to-canonical

reorient inputs images to canonical orientation (useful when using data from heterogeneous sources or using pseudo3d_dim == all; otherwise, e.g., the axis corresponding to left-right in one image might be anterior-posterior in another.)

Default: False

-p3d, --pseudo3d-dim

Possible choices: 0, 1, 2, all

dim on which to concatenate the images for input to a 2D network. If provided, either provide 1 valueto be used for each CSV or provide N values corresponding to the N CSVs. If not provided, use 3D network.

-p3s, --pseudo3d-size

size of the pseudo3d dimension (if -p3d provided)

-nsa, --non-strict-affine

if images have different affine matrices, resample the images to be consistent; avoid usingthis by coregistering your images within a subject.

Default: True

-cd, --check-dicom

check DICOM images to see if they have uniform spacing between slices; warn the user if not.

Default: False

--use-memory-saving-dataset

default dataset can leak memory when num_workers > 1, use this if you encounter non-GPU OOM errors

Default: False

pl.Trainer

--devices

Will be mapped to either gpus, tpu_cores, num_processes or ipus, based on the accelerator type.

--gpus

Number of GPUs to train on (int) or which GPUs to train on (list or str) applied per node

--progress_bar_refresh_rate

How often to refresh progress bar (in steps). Value 0 disables progress bar. Ignored when a custom progress bar is passed to callbacks. Default: None, means a suitable value will be chosen based on the environment (terminal, Google COLAB, etc.). .. deprecated:: v1.5 progress_bar_refresh_rate has been deprecated in v1.5 and will be removed in v1.7. Please pass TQDMProgressBar with refresh_rate directly to the Trainer’s callbacks argument instead. To disable the progress bar, pass enable_progress_bar = False to the Trainer.

--enable_progress_bar

Whether to enable to progress bar by default.

Default: True

--accelerator

Supports passing different accelerator types (“cpu”, “gpu”, “tpu”, “ipu”, “auto”) as well as custom accelerator instances. .. deprecated:: v1.5 Passing training strategies (e.g., ‘ddp’) to accelerator has been deprecated in v1.5.0 and will be removed in v1.7.0. Please use the strategy argument instead.

--strategy

Supports different training strategies with aliases as well custom training type plugins.

--precision

Double precision (64), full precision (32), half precision (16) or bfloat16 precision (bf16). Can be used on CPU, GPU or TPUs.

Default: 32

--benchmark

If true enables cudnn.benchmark.

Default: False

lesion-predict-image

Use a Tiramisu CNN to segment lesions for a single time-point prediction

usage: lesion-predict-image [-h] -mp MODEL_PATH [MODEL_PATH ...] [-sd SEED]
                            [-oa] [-at {mean,vote,union}] [-v] [-th THRESHOLD]
                            [-mls MIN_LESION_SIZE] [-fh] [-pp]
                            [-ps PATCH_SIZE [PATCH_SIZE ...]]
                            [-po PATCH_OVERLAP PATCH_OVERLAP PATCH_OVERLAP]
                            [-bs BATCH_SIZE] [-nw NUM_WORKERS] [-rtc]
                            [-p3d {0,1,2,all} [{0,1,2,all} ...]]
                            [-p3s PSEUDO3D_SIZE] [-nsa] [-cd]
                            [--use-memory-saving-dataset] [--devices DEVICES]
                            [--gpus GPUS]
                            [--progress_bar_refresh_rate PROGRESS_BAR_REFRESH_RATE]
                            [--enable_progress_bar [ENABLE_PROGRESS_BAR]]
                            [--accelerator ACCELERATOR] [--strategy STRATEGY]
                            [--precision PRECISION] [--benchmark [BENCHMARK]]

Experiment

-mp, --model-path

path to output the trained model

Default: [‘SET ME!’]

-sd, --seed

set seed for reproducibility

Default: 0

-oa, --only-aggregate

only aggregate results (useful to test different thresholds)

Default: False

-at, --aggregation-type

Possible choices: mean, vote, union

aggregate results with this method

Default: “mean”

-v, --verbosity

increase output verbosity (e.g., -vv is more than -v)

Default: 0

Other

-th, --threshold

probability threshold for segmentation

Default: 0.5

Testing

-mls, --min-lesion-size

in testing, remove lesions smaller in voxels than this

Default: 3

-fh, --fill-holes

in testing, preform binary hole filling

Default: False

-pp, --predict-probability

in testing, store the probability instead of the binary prediction

Default: False

Data

-ps, --patch-size

shape of patches (None -> crop image to foreground)

-po, --patch-overlap

patches will overlap by this much (None -> patch-size // 2)

-bs, --batch-size

training/validation batch size

Default: 1

-nw, --num-workers

number of CPUs to use for loading data

Default: 16

-rtc, --reorient-to-canonical

reorient inputs images to canonical orientation (useful when using data from heterogeneous sources or using pseudo3d_dim == all; otherwise, e.g., the axis corresponding to left-right in one image might be anterior-posterior in another.)

Default: False

-p3d, --pseudo3d-dim

Possible choices: 0, 1, 2, all

dim on which to concatenate the images for input to a 2D network. If provided, either provide 1 valueto be used for each CSV or provide N values corresponding to the N CSVs. If not provided, use 3D network.

-p3s, --pseudo3d-size

size of the pseudo3d dimension (if -p3d provided)

-nsa, --non-strict-affine

if images have different affine matrices, resample the images to be consistent; avoid usingthis by coregistering your images within a subject.

Default: True

-cd, --check-dicom

check DICOM images to see if they have uniform spacing between slices; warn the user if not.

Default: False

--use-memory-saving-dataset

default dataset can leak memory when num_workers > 1, use this if you encounter non-GPU OOM errors

Default: False

pl.Trainer

--devices

Will be mapped to either gpus, tpu_cores, num_processes or ipus, based on the accelerator type.

--gpus

Number of GPUs to train on (int) or which GPUs to train on (list or str) applied per node

--progress_bar_refresh_rate

How often to refresh progress bar (in steps). Value 0 disables progress bar. Ignored when a custom progress bar is passed to callbacks. Default: None, means a suitable value will be chosen based on the environment (terminal, Google COLAB, etc.). .. deprecated:: v1.5 progress_bar_refresh_rate has been deprecated in v1.5 and will be removed in v1.7. Please pass TQDMProgressBar with refresh_rate directly to the Trainer’s callbacks argument instead. To disable the progress bar, pass enable_progress_bar = False to the Trainer.

--enable_progress_bar

Whether to enable to progress bar by default.

Default: True

--accelerator

Supports passing different accelerator types (“cpu”, “gpu”, “tpu”, “ipu”, “auto”) as well as custom accelerator instances. .. deprecated:: v1.5 Passing training strategies (e.g., ‘ddp’) to accelerator has been deprecated in v1.5.0 and will be removed in v1.7.0. Please use the strategy argument instead.

--strategy

Supports different training strategies with aliases as well custom training type plugins.

--precision

Double precision (64), full precision (32), half precision (16) or bfloat16 precision (bf16). Can be used on CPU, GPU or TPUs.

Default: 32

--benchmark

If true enables cudnn.benchmark.

Default: False