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.