Executables¶
Neural Network Trainer¶
train a CNN for MR image synthesis
usage: nn-train [-h] -s SOURCE_DIR [SOURCE_DIR ...] -t TARGET_DIR
[TARGET_DIR ...] [-o TRAINED_MODEL] [-bs BATCH_SIZE] [-c CLIP]
[-chk CHECKPOINT] [-csv WRITE_CSV] [--disable-cuda]
[-e {nii,tif,png,jpg}] [-mp] [-l {mse,mae,cp,bce}] [-mg]
[-n N_JOBS] [-ocf OUT_CONFIG_FILE] [-ps PATCH_SIZE] [-pm]
[-pl PLOT_LOSS] [-sa SAMPLE_AXIS] [-sd SEED] [-vs VALID_SPLIT]
[-vsd VALID_SOURCE_DIR [VALID_SOURCE_DIR ...]]
[-vtd VALID_TARGET_DIR [VALID_TARGET_DIR ...]] [-v]
[-bt BETAS BETAS] [-nlo]
[-opt {adam,adamw,sgd,sgdw,nesterov,adagrad,amsgrad,rmsprop}]
[-wd WEIGHT_DECAY] [-cm {triangular,triangular2,exp_range}]
[-lrs {cyclic,cosinerestarts}]
[-mr MOMENTUM_RANGE MOMENTUM_RANGE] [-nc NUM_CYCLES]
[-rp RESTART_PERIOD] [-tm T_MULT]
[-ac {relu,lrelu,prelu,elu,celu,selu,tanh,sigmoid}]
[-dp DROPOUT_PROB] [-eb]
[-in {normal,xavier,kaiming,orthogonal}] [-ing INIT_GAIN]
[-ks KERNEL_SIZE] [-lr LEARNING_RATE] [-ne N_EPOCHS]
[-nl N_LAYERS] [-3d]
[-na {unet,nconv,vae,segae,densenet,ordnet,lrsdnet,hotnet}]
[-nm {instance,batch,layer,weight,spectral,none}]
[-oac {linear,relu,lrelu,prelu,elu,celu,selu,tanh,sigmoid}]
[-atu] [-at] [-cbp CHANNEL_BASE_POWER] [-ic]
[-im {nearest,bilinear,trilinear}] [-ns] [-nz NOISE_LVL] [-sp]
[-sx] [-lrsd LRSD_WEIGHTS LRSD_WEIGHTS] [-ed] [-lp]
[-ord ORD_PARAMS ORD_PARAMS ORD_PARAMS]
[-id IMG_DIM [IMG_DIM ...]] [-ls LATENT_SIZE] [-fl]
[-is INITIALIZE_SEG] [-nseg N_SEG]
[-li LAST_INIT [LAST_INIT ...]] [-np NORM_PENALTY]
[-op ORTHO_PENALTY] [-sm SEG_MIN] [-mse] [-mask]
[-p PROB PROB PROB PROB PROB] [-r ROTATE] [-ts TRANSLATE]
[-sc SCALE] [-hf] [-vf] [-g GAMMA] [-gn GAIN]
[-blk BLOCK BLOCK] [-th THRESHOLD] [-pwr NOISE_PWR]
[-mean MEAN [MEAN ...]] [-std STD [STD ...]] [-tx] [-ty]
Required¶
-s, --source-dir | |
path to directory with source images (multiple paths can be provided for multi-modal synthesis) | |
-t, --target-dir | |
path to directory with target images (multiple paths can be provided for multi-modal synthesis) | |
-o, --trained-model | |
path to output the trained model or (if model exists) continue training this model |
Options¶
-bs, --batch-size | |
batch size (num of images to process at once) [Default=5] Default: 5 | |
-c, --clip | gradient clipping threshold [Default=None] |
-chk, --checkpoint | |
save the model every checkpoint epochs [Default=None] | |
-csv, --write-csv | |
write the loss to a csv file of this filename [Default=None] | |
--disable-cuda | Disable CUDA regardless of availability Default: False |
-e, --ext | Possible choices: nii, tif, png, jpg extension of training/validation images [Default=None (.nii and .nii.gz)] |
-mp, --fp16 | enable mixed precision training Default: False |
-l, --loss | Possible choices: mse, mae, cp, bce Use this specified loss function [Default=None, MSE for Unet] |
-mg, --multi-gpu | |
use multiple gpus [Default=False] Default: False | |
-n, --n-jobs | number of CPU processors to use (use 0 if CUDA enabled) [Default=0] Default: 0 |
-ocf, --out-config-file | |
output a config file for the options used in this experiment (saves them as a json file with the name as input in this argument) | |
-ps, --patch-size | |
patch size extracted from image [Default=0, i.e., whole slice or whole image] Default: 0 | |
-pm, --pin-memory | |
pin memory in dataloader [Default=False] Default: False | |
-pl, --plot-loss | |
plot the loss vs epoch and save at the filename provided here [Default=None] | |
-sa, --sample-axis | |
axis on which to sample for 2d (None for random orientation when NIfTI images given) [Default=2] Default: 2 | |
-sd, --seed | set seed for reproducibility [Default=0] Default: 0 |
-vs, --valid-split | |
split the data in source_dir and target_dir into train/validation with this split percentage [Default=0.2] Default: 0.2 | |
-vsd, --valid-source-dir | |
path to directory with source images for validation, see -vs for default action if this is not provided [Default=None] | |
-vtd, --valid-target-dir | |
path to directory with target images for validation, see -vs for default action if this is not provided [Default=None] | |
-v, --verbosity | |
increase output verbosity (e.g., -vv is more than -v) Default: 0 |
Optimizer Options¶
-bt, --betas | optimizer parameters (if using SGD, then the first element will be momentum and the second ignored) [Default=(0.9,0.99)] Default: (0.9, 0.99) |
-nlo, --no-load-opt | |
if loading a trained model, do not load the optimizer [Default=False] Default: False | |
-opt, --optimizer | |
Possible choices: adam, adamw, sgd, sgdw, nesterov, adagrad, amsgrad, rmsprop Use this optimizer to train the network [Default=adam] Default: “adam” | |
-wd, --weight-decay | |
weight decay parameter for optimizer [Default=0] Default: 0 |
Scheduler Options¶
-cm, --cycle-mode | |
Possible choices: triangular, triangular2, exp_range type of cycle for cyclic lr scheduler [Default=triangular] Default: “triangluar” | |
-lrs, --lr-scheduler | |
Possible choices: cyclic, cosinerestarts use a learning rate scheduler [Default=None] | |
-mr, --momentum-range | |
range over which to inversely cycle momentum (does not work w/ all optimizers) [Default=(0.85,0.95)] Default: (0.85, 0.95) | |
-nc, --num-cycles | |
number of cycles for cyclic learning rate scheduler [Default=1] Default: 1 | |
-rp, --restart-period | |
restart period for cosine annealing with restarts [Default=None] | |
-tm, --t-mult | multiplication factor for which the next restart period will extend or shrink (for cosine annealing with restarts) [Default=None] |
Neural Network Options¶
-ac, --activation | |
Possible choices: relu, lrelu, prelu, elu, celu, selu, tanh, sigmoid type of activation to use throughout network except output [Default=relu] Default: “relu” | |
-dp, --dropout-prob | |
dropout probability per conv block [Default=0] Default: 0 | |
-eb, --enable-bias | |
enable bias calculation in upsampconv layers and final conv layer [Default=False] Default: False | |
-in, --init | Possible choices: normal, xavier, kaiming, orthogonal use this type of initialization for the network [Default=kaiming] Default: “kaiming” |
-ing, --init-gain | |
use this initialization gain for initialization [Default=0.2] Default: 0.2 | |
-ks, --kernel-size | |
convolutional kernel size (squared or cubed) [Default=3] Default: 3 | |
-lr, --learning-rate | |
learning rate for the optimizer [Default=1e-3] Default: 0.001 | |
-ne, --n-epochs | |
number of epochs [Default=100] Default: 100 | |
-nl, --n-layers | |
number of layers to use in network (different meaning per arch) [Default=3] Default: 3 | |
-3d, --is-3d | create a 3d network instead of 2d [Default=False] Default: False |
-na, --nn-arch | Possible choices: unet, nconv, vae, segae, densenet, ordnet, lrsdnet, hotnet specify neural network architecture to use Default: “unet” |
-nm, --normalization | |
Possible choices: instance, batch, layer, weight, spectral, none type of normalization layer to use in network [Default=instance] Default: “instance” | |
-oac, --out-activation | |
Possible choices: linear, relu, lrelu, prelu, elu, celu, selu, tanh, sigmoid type of activation to use in network on output [Default=linear] Default: “linear” |
UNet Options¶
-atu, --add-two-up | |
Add two to the kernel size on the upsampling in the U-Net as per Zhao, et al. 2017 [Default=False] Default: False | |
-at, --attention | |
use attention gates in up conv layers in unet[Default=False] Default: False | |
-cbp, --channel-base-power | |
2 ** channel_base_power is the number of channels in the first layer and increases in each proceeding layer such that in the n-th layer there are 2 ** (channel_base_power + n) channels [Default=5] Default: 5 | |
-ic, --input-connect | |
connect the input to the final layers via a concat skip connection [Default=False] Default: False | |
-im, --interp-mode | |
Possible choices: nearest, bilinear, trilinear use this type of interpolation for upsampling [Default=nearest] Default: “nearest” | |
-ns, --no-skip | do not use skip connections in unet [Default=False] Default: False |
-nz, --noise-lvl | |
add this level of noise to model parameters [Default=0] Default: 0 | |
-sp, --separable | |
use separable convolutions instead of full convolutions [Default=False] Default: False | |
-sx, --softmax | use softmax before last layer [Default=False] Default: False |
LRSDNet Options¶
-lrsd, --lrsd-weights | |
penalties for lrsd [Default=None] |
OrdNet/HotNet Options¶
-ed, --edge | use edge map [Default=False] Default: False |
-lp, --laplacian | |
use laplacian [Default=False] Default: False | |
-ord, --ord-params | |
ordinal regression params (start, stop, n_bins) [Default=None] |
VAE Options¶
-id, --img-dim | if using VAE, then input image dimension must be specified [Default=None] |
-ls, --latent-size | |
if using VAE, this controls latent dimension size [Default=2048] Default: 2048 |
SegAE Options¶
-fl, --freeze-last | |
freeze the last layer for training [Default=False] Default: False | |
-is, --initialize-seg | |
number of epochs to initialize segmentation layers with seed [Default=0] Default: 0 | |
-nseg, --n-seg | number of segmentation layers [Default=5] Default: 5 |
-li, --last-init | |
initial numbers for last layer [Default=None] | |
-np, --norm-penalty | |
weight for the norm penalty [Default=1] Default: 1 | |
-op, --ortho-penalty | |
weight for the orthogonality penalty [Default=1] Default: 1 | |
-sm, --seg-min | minimum prob in segmentation [Default=0] Default: 0 |
-mse, --use-mse | |
use mse instead of cosine proximity in loss function [Default=False] Default: False | |
-mask, --use-mask | |
use brain mask on segmentation and output (during training and testing) [Default=False] Default: False |
Data Augmentation Options¶
-p, --prob | probability of (Affine, Flip, Gamma, Block, Noise) [Default=None] |
-r, --rotate | max rotation angle [Default=0] Default: 0 |
-ts, --translate | |
max fractional translation [Default=None] | |
-sc, --scale | max scale (1-scale,1+scale) [Default=None] |
-hf, --hflip | horizontal flip [Default=False] Default: False |
-vf, --vflip | vertical flip [Default=False] Default: False |
-g, --gamma | gamma (1-gamma,1+gamma) for (gain * x ** gamma) [Default=None] |
-gn, --gain | gain (1-gain,1+gain) for (gain * x ** gamma) [Default=None] |
-blk, --block | insert random blocks of this size range [Default=None] |
-th, --threshold | |
threshold for foreground for blocks, if none use mean [Default=None] | |
-pwr, --noise-pwr | |
noise standard deviation/power [Default=0] Default: 0 | |
-mean, --mean | normalize input images with this mean (one entry per input directory) [Default=None] |
-std, --std | normalize input images with this std (one entry per input directory) [Default=None] |
-tx, --tfm-x | apply transforms to x (change this with config file) [Default=True] Default: True |
-ty, --tfm-y | apply transforms to y [Default=False] Default: False |
Neural Network Predictor¶
The prediction function only supports the use of a configuration file (which can be created from the use of the nn-train, see the –out-config-file option). This is due to pytorch requiring the parameters to recreate the neural network class, which can then be updated with the trained weights.
Note that you will have to change the predict_out and predict_dir fields in the .json file with where the output files should be stored and where the source images should come from, respectively.
There may be other fields that need to be altered based on your specific configuration.