-
Notifications
You must be signed in to change notification settings - Fork 102
Deploying AI models
AI models are distributed as packaged Conda environments, available upon request through MSKCC Box.
To untar the environment file, for example in Windows, open the Command Prompt and run the following with correct paths of the tar file and the destination directory:
tar -xf CT_heart_sub_structs.tar.gz -C CT_heart_sub_structs
Models are distributed as Conda environments as well as Singularity containers.
-
MATLAB or GNU-Octave
CERR's AI model deployment pipeline is compatible with Matlab as well as Octave for license-free use. -
CERR
Download CERR and add it to your MATLAB/Octave path:
addpath(genpath('/your/path/to/CERR/'));
-
CUDA
AI models can be executed in CPU-only or GPU-mode. For the latter, an NVIDIA GPU and the associated CUDA-capable driver are required. -
AI model
AI models along with dependencies are available in ready-to-use Singularity containers (Linux) or Conda archives (Windows, Mac, Linux) hosted at MSKCC. Please submit a request for access to pre-trained models.If using Singularity containers, download Singularity 3.5 or higher on your Linux machine. For Windows OS we provide instructions to set-up Singularity over Vagrant.
See documentation on currently available pre-trained models.
CERR uses JSON-format configuration files to specify pre/post processing transformations to models inputs/outputs). Configuration files for pretrained models are distributed with CERR.
Configurations may need to be tailored to your dataset, e.g. if preprocessing involves cropping around a structure prior, the structure name may need to be modified to match the labeling conventions of your dataset. This is done by modifying the structureName
value under the crop
field in the configuration file.
Further details of supported configurations are described here.
- From GUI
Load the CERR file in the Viewer and run:
global planC
- From file
lungExampleCerrFile = fullfile(getCERRPath,'..','Unit_Testing',...
'data_for_cerr_tests','CERR_plans','lung_ex1_20may03.mat.bz2');
planC = loadPlanC(lungExampleCerrFile,tempdir);
planC = updatePlanFields(planC);
planC = quality_assure_planC(baseCerrFile,planC);
The following command can be used to deploy AI models in most cases:
input_dicom_dir
:Directory containing DICOM images and associated RT objects for all the modalities required by the model. We recommend creating a new writable directory to house these results.
output_dicom_dir
is the path to which outputs (e.g. DVFs, segmentations as DICOM RTSTRUCTs, CERR archives) are written.
save_flag
is set to 'Yes'
to save CERR-format (planC
) archives in addition to DICOM (or 'No'
to skip).
planC
: CERR-specific data structure.
-
session_dir
Running the segmentation container creates a temporary session directory which is deleted once execution ends. The user must provide a "writable" location to create this temporary directory. We suggest making a new directory on the server to house temporary sessions. -
algorithm
is the name of the segmentation algorithm to execute (see list of valid algorithm names above). To run multiple algorithms in sequence, separate the names using the "^" sign, e.g.'CT_Heart_DeepLab^CT_Atria_DeepLab'
-
cmd_flag
is set tosingContainer
(Singularity Containers) orcondaEnv
(Conda Environemnts). -
container_path
is the full path to the supplied Singularity container. -
new_session
flag is set to '0' to use existing session directory (e.g. for sequential application of models) or '1' to create a new directory. -
waitbar_handle
is a handle to a progress bar -
ssh_config
This functionality is currently untested and we recommend passing an empty ([]
) value. This flag is intended to support invoking the model on a remote (Linux) server.
The following inputs are optional input:
-
inputS
is a data structure containing scan indices input to the model (inferred from scanidentifier
field of configuration file by default). -
output_scan_no
is the index of the scan to be associated with model output. This field is relevant for multi-input models. It can be instead inferred from theoutputAssocScan
field of configuration file if provided. -
skip_mask_export
flag is set to '0' if structure masks must be input to the model (turned off ('1') by default).
% Initialize dcm4che to create temp dir names
init_ML_DICOM
% Define I/O paths
inDcm = '/path/to/inputDcmDir';
outDcm = '/path/to/outputDcmDir';
sessionPath = '/path/to/segSessions';
container_path = '/path/to/CT_Heart_DeepLab_sing_conda_recipe.def_363df.sif'; % e.g.for cardiac substructures
% Specify algorithm<sup>a</sup>
algorithm = 'CT_HeartStructure_DeepLab^CT_HeartSubStructures_DeepLab^CT_Atria_DeepLab^CT_Pericardium_DeepLab^CT_Ventricles_DeepLab';
% algorithm = 'CT_LungOAR_incrMRRN'; % For Thoracic OAR segmentation model
%Specify scan to segment
scanNumToSegment = 1;
inputS.scan.scanNum = scanNumToSegment; % User-specifies 1st scan is to be segmented
outputAssocScan = scanNumToSegment; % User-specifies 1st scan is to be associated with result
% Set optional flags
ssh_config= '';
waitbar_handle= nan;
cmd_flag= 'singContainer';
new_session= true;
skip_mask_export = true; %Set to false if model requires input masks
- a See documentation for supported options ("Apps in Container").
DICOM-based
runAIforDicom(input_dicom_dir,output_dicom_dir,session_dir,algorithm,cmd_flag,save_flag,container_path,inputS,outputAssocScan,skip_mask_export );
planC
-based
planC = runAIforPlanC(planC,session_dir,algorithm,cmd_flag,new_session,ssh_config,waitbar_handle,container_path,inputS,outputAssocScan,skip_mask_export);
This video demonstrates the deployment of an AI model to segment cardiac substructures in CT using a packaged conda environment
- See documentation for references to pretrained models.
- Iyer, A., Locastro, E., Apte, A. P., Veeraraghavan, H., & Deasy, J. O. (2021). Portable framework to deploy deep learning segmentation models for medical images. bioRxiv. https://doi.org/10.1101/2021.03.17.435903
- Apte, A. P., Iyer, A., Thor, M., Pandya, R., Haq, R., Jiang, J., LoCastro, E., Shukla-Dave, A., Sasankan, N., Xiao, Y., Hu, Y. C., Elguindi, S., Veeraraghavan, H., Oh, J. H., Jackson, A., & Deasy, J. O. (2020). Library of deep-learning image segmentation and outcomes model-implementations. Physica Medica, 73, 190-196. https://doi.org/10.1016/j.ejmp.2020.04.011.