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] [-co] [-csv WRITE_CSV] [--disable-cuda]
[-e {nii,tif,png,jpg}] [-mp] [-fr] [-l {mse,mae,cp,bce}] [-mg]
[-n N_JOBS] [-ocf OUT_CONFIG_FILE]
[-ps PATCH_SIZE [PATCH_SIZE ...]] [-pm] [-pl PLOT_LOSS] [-pr]
[-sa SAMPLE_AXIS] [-spt SAMPLE_PCT SAMPLE_PCT] [-sd SEED]
[-tb] [-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,nsgd,nsgdw,adagrad,amsgrad,rmsprop}]
[-wd WEIGHT_DECAY] [-cm {triangular,triangular2,exp_range}]
[-df DIV_FACTOR] [-lrs {cyclic,cosinerestarts}]
[-mr MOMENTUM_RANGE MOMENTUM_RANGE] [-nc NUM_CYCLES]
[-pst PCT_START] [-rp RESTART_PERIOD] [-tm T_MULT]
[-ac {relu,lrelu,prelu,elu,celu,selu,tanh,sigmoid,swish}]
[-af] [-dm {1,2,3}] [-dp DROPOUT_PROB] [-eb]
[-in {normal,xavier,kaiming,orthogonal}] [-ing INIT_GAIN]
[-ks KERNEL_SIZE [KERNEL_SIZE ...]] [-lr LEARNING_RATE]
[-ne N_EPOCHS] [-nl N_LAYERS]
[-na {unet,nconv,vae,densenet,ordnet,hotnet,burnnet,burn2net,burn2netp12,burn2netp21,unburnnet,unburn2net,lavanet,lava2net,lautonet,ocnet1,ocnet2}]
[-nm {instance,batch,layer,weight,spectral,none}]
[-oac {linear,relu,lrelu,prelu,elu,celu,selu,tanh,sigmoid}]
[-acv] [-at {channel,self}] [-cbp CHANNEL_BASE_POWER]
[-s3 SEMI_3D] [-ic] [-im {nearest,bilinear,trilinear}] [-ns]
[-nz NOISE_LVL] [-rb] [-sp] [-sx] [-b1 BETA] [-tp TEMPERATURE]
[-ord ORD_PARAMS ORD_PARAMS ORD_PARAMS]
[-id IMG_DIM [IMG_DIM ...]] [-ls LATENT_SIZE]
[-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] | |
-co, --color | input and output images are color (ie, 3 channels) [Default=False] Default: False |
-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 |
-fr, --freeze | freeze network in predefined way, e.g., U-Net is all but final 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, 2 numbers if 2d, 3 numbers if 3d [Default=None, i.e., whole slice or whole image] | |
-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] | |
-pr, --preload | preload data to memory in dataloader [Default=False] Default: False |
-sa, --sample-axis | |
axis on which to sample for 2d (None for random orientation when NIfTI images given) [Default=2] Default: 2 | |
-spt, --sample-pct | |
percent of image along defined axis on which to sample for 3d patches, e.g., used to exclude neck and above head region in brain images [Default=(0,1)] Default: (0.0, 1.0) | |
-sd, --seed | set seed for reproducibility [Default=0] Default: 0 |
-tb, --tensorboard | |
use tensorboard Default: False | |
-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, nsgd, nsgdw, 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: “triangular” | |
-df, --div-factor | |
divide LR by this amount for minimum LR [Default=25] Default: 25 | |
-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 | |
-pst, --pct-start | |
percent of cycle dedicated to raising LR for cyclic [Default=0.3] Default: 0.3 | |
-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, swish type of activation to use throughout network except output [Default=relu] Default: “relu” | |
-af, --affine | use affine transform on normalization routines [Default=True] Default: True |
-dm, --dim | Possible choices: 1, 2, 3 create a dim dimension network [Default=2] Default: 2 |
-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,3) or (3,3,3) depending on –is-3d] 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 | |
-na, --nn-arch | Possible choices: unet, nconv, vae, densenet, ordnet, hotnet, burnnet, burn2net, burn2netp12, burn2netp21, unburnnet, unburn2net, lavanet, lava2net, lautonet, ocnet1, ocnet2 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¶
-acv, --all-conv | |
only use conv layers in unet (max pooling -> strided, upsamp -> shuffle) [Default=False] Default: False | |
-at, --attention | |
Possible choices: channel, self use attention gates in up conv layers in unet [Default=None] | |
-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 | |
-s3, --semi-3d | if using 3d with oblong kernel, use an isotropic 3d conv layer in network at beginning when =1, at beginning and end =2 [Default=False] Default: 0 |
-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 | |
-rb, --resblock | |
use residual (addition) connections in unet blocks (all_conv must equal true to use) [Default=False] Default: False | |
-sp, --separable | |
use separable convolutions instead of full convolutions [Default=False] Default: False | |
-sx, --softmax | use softmax before last layer [Default=False] Default: False |
OrdNet/HotNet Options¶
-b1, --beta | scale variance [Default=1.] Default: 1.0 |
-tp, --temperature | |
temperature parameter [Default=1.] Default: 1.0 | |
-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 |
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=0] Default: 0 | |
-sc, --scale | max scale (1-scale,1+scale) [Default=0] Default: 0 |
-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=0] Default: 0 |
-gn, --gain | gain (1-gain,1+gain) for (gain * x ** gamma) [Default=0] Default: 0 |
-blk, --block | insert random blocks of this size range [Default=None] |
-th, --threshold | |
threshold for foreground for blocks and 2d crop, 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.