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.5checkpoint_callback
has been deprecated in v1.5 and will be removed in v1.7. Please consider usingenable_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, andgradient_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 passTQDMProgressBar
withprocess_position
directly to the Trainer’scallbacks
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 tocallbacks
. Default: None, means a suitable value will be chosen based on the environment (terminal, Google COLAB, etc.). .. deprecated:: v1.5progress_bar_refresh_rate
has been deprecated in v1.5 and will be removed in v1.7. Please passTQDMProgressBar
withrefresh_rate
directly to the Trainer’scallbacks
argument instead. To disable the progress bar, passenable_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 toTrue
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, setmax_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 todatetime.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 thestrategy
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, passenable_model_summary = False
to the Trainer. To customize the summary, passModelSummary
directly to the Trainer’scallbacks
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 toTrainer.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 usereload_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 andshuffle=False
for val/test sampler. If you want to customize it, you can setreplace_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 passStochasticWeightAveraging
directly to the Trainer’scallbacks
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 usedetect_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 tocallbacks
. Default: None, means a suitable value will be chosen based on the environment (terminal, Google COLAB, etc.). .. deprecated:: v1.5progress_bar_refresh_rate
has been deprecated in v1.5 and will be removed in v1.7. Please passTQDMProgressBar
withrefresh_rate
directly to the Trainer’scallbacks
argument instead. To disable the progress bar, passenable_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 thestrategy
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 tocallbacks
. Default: None, means a suitable value will be chosen based on the environment (terminal, Google COLAB, etc.). .. deprecated:: v1.5progress_bar_refresh_rate
has been deprecated in v1.5 and will be removed in v1.7. Please passTQDMProgressBar
withrefresh_rate
directly to the Trainer’scallbacks
argument instead. To disable the progress bar, passenable_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 thestrategy
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