API Reference¶
MONAILabel APP¶
- class monailabel.interfaces.app.MONAILabelApp(app_dir, studies, conf, name='', description='', version='2.0', labels=None)[source]
Default Pre-trained Path for downloading models
Base Class for Any MONAI Label App
- Parameters
app_dir (
str
) – path for your App directorystudies (
str
) – path for studies/datalistconf (
Dict
[str
,str
]) – dictionary of key/value pairs provided by user while running the app
- __init__(app_dir, studies, conf, name='', description='', version='2.0', labels=None)[source]
Base Class for Any MONAI Label App
- Parameters
app_dir (
str
) – path for your App directorystudies (
str
) – path for studies/datalistconf (
Dict
[str
,str
]) – dictionary of key/value pairs provided by user while running the app
- batch_infer(request, datastore=None)[source]
Run batch inference for an existing pre-trained model.
- Parameters
request – JSON object which contains model, params and device
datastore –
Datastore object. If None then use default app level datastore to fetch the images
For example:
{ "device": "cuda" "model": "segmentation_spleen", "images": "unlabeled", "label_tag": "original" }
- Raises
MONAILabelException – When
model
is not found- Returns
JSON containing label and params
- infer(request, datastore=None)[source]
Run Inference for an exiting pre-trained model.
- Parameters
request – JSON object which contains model, image, params and device
datastore –
Datastore object. If None then use default app level datastore to save labels if applicable
For example:
{ "device": "cuda" "model": "segmentation_spleen", "image": "file://xyz", "save_label": "true/false", "label_tag": "original" }
- Raises
MONAILabelException – When
model
is not found- Returns
JSON containing label and params
- info()[source]
Provide basic information about APP. This information is passed to client.
- next_sample(request)[source]
Run Active Learning selection. User APP has to implement this method to provide next sample for labelling.
- Parameters
request –
JSON object which contains active learning configs that are part APP info
For example:
{ "strategy": "random" }
- Returns
JSON containing next image info that is selected for labeling
- on_save_label(image_id, label_id)[source]
Callback method when label is saved into datastore by a remote client
- scoring(request, datastore=None)[source]
Run scoring task over labels.
- Parameters
request – JSON object which contains model, params and device
datastore –
Datastore object. If None then use default app level datastore to fetch the images
For example:
{ "device": "cuda" "method": "dice", "y": "final", "y_pred": "original", }
- Raises
MONAILabelException – When
method
is not found- Returns
JSON containing result of scoring method
- train(request)[source]
Run Training. User APP has to implement this method to run training
- Parameters
request –
JSON object which contains train configs that are part APP info
For example:
{ "model": "mytrain", "device": "cuda" "max_epochs": 1, }
- Returns
JSON containing train stats
- class monailabel.interfaces.datastore.Datastore[source]
- abstract add_image(image_id, image_filename, image_info)[source]
Save a image for the given image id and return the newly saved image’s id
- Parameters
image_id (
str
) – the image id for the image; If None then base filename will be usedimage_filename (
str
) – the path to the image fileimage_info (
Dict
[str
,Any
]) – additional info for the image
- Return type
str
- Returns
the image id for the saved image filename
- abstract datalist()[source]
Return a dictionary of image and label pairs corresponding to the ‘image’ and ‘label’ keys respectively
- Return type
List
[Dict
[str
,Any
]]- Returns
the {‘image’: image, ‘label’: label} pairs for training
- abstract description()[source]
Return the user-set description of the dataset
- Return type
str
- Returns
the user-set description of the dataset
- abstract get_image(image_id, params=None)[source]
Retrieve image object based on image id
- Parameters
image_id (
str
) – the desired image’s idparams – any optional params
- Return type
Any
- Returns
return the “image”
- abstract get_image_info(image_id)[source]
Get the image information for the given image id
- Parameters
image_id (
str
) – the desired image id- Return type
Dict
[str
,Any
]- Returns
image info as a list of dictionaries Dict[str, Any]
- abstract get_image_uri(image_id)[source]
Retrieve image uri based on image id
- Parameters
image_id (
str
) – the desired image’s id- Return type
str
- Returns
return the image uri
- abstract get_label(label_id, label_tag, params=None)[source]
Retrieve image object based on label id
- Parameters
label_id (
str
) – the desired label’s idlabel_tag (
str
) – the matching label’s tagparams – any optional params
- Return type
Any
- Returns
return the “label”
- abstract get_label_by_image_id(image_id, tag)[source]
Retrieve label id for the given image id and tag
- Parameters
image_id (
str
) – the desired image’s idtag (
str
) – matching tag name
- Return type
str
- Returns
label id
- abstract get_label_info(label_id, label_tag)[source]
Get the label information for the given label id
- Parameters
label_id (
str
) – the desired label idlabel_tag (
str
) – the matching label tag
- Return type
Dict
[str
,Any
]- Returns
label info as a list of dictionaries Dict[str, Any]
- abstract get_label_uri(label_id, label_tag)[source]
Retrieve label uri based on image id
- Parameters
label_id (
str
) – the desired label’s idlabel_tag (
str
) – the matching label’s tag
- Return type
str
- Returns
return the label uri
- abstract get_labeled_images()[source]
Get all images that have a corresponding final label
- Return type
List
[str
]- Returns
list of image ids List[str]
- abstract get_labels_by_image_id(image_id)[source]
Retrieve all label ids for the given image id
- Parameters
image_id (
str
) – the desired image’s id- Return type
Dict
[str
,str
]- Returns
label ids mapped to the appropriate LabelTag as Dict[LabelTag, str]
- abstract get_unlabeled_images()[source]
Get all images that have no corresponding final label
- Return type
List
[str
]- Returns
list of image ids List[str]
- abstract json()[source]
Return json representation of datastore
- abstract list_images()[source]
Return list of image ids available in the datastore
- Return type
List
[str
]- Returns
list of image ids List[str]
- abstract name()[source]
Return the human-readable name of the datastore
- Return type
str
- Returns
the name of the dataset
- abstract refresh()[source]
Refresh the datastore
- Return type
None
- abstract remove_image(image_id)[source]
Remove image for the datastore. This will also remove all associated labels.
- Parameters
image_id (
str
) – the image id for the image to be removed from datastore- Return type
None
- abstract remove_label(label_id, label_tag)[source]
Remove label from the datastore
- Parameters
label_id (
str
) – the label id for the label to be removed from datastorelabel_tag (
str
) – the label tag for the label to be removed from datastore
- Return type
None
- abstract save_label(image_id, label_filename, label_tag, label_info)[source]
Save a label for the given image id and return the newly saved label’s id
- Parameters
image_id (
str
) – the image id for the labellabel_filename (
str
) – the path to the label filelabel_tag (
str
) – the user-provided tag for the labellabel_info (
Dict
[str
,Any
]) – additional info for the label
- Return type
str
- Returns
the label id for the given label filename
- abstract set_description(description)[source]
A human-readable description of the datastore
- Parameters
description (
str
) – string for description
- abstract set_name(name)[source]
Set the name of the datastore
- Parameters
name (
str
) – a human-readable name for the datastore
- abstract status()[source]
Return current statistics of datastore
- Return type
Dict
[str
,Any
]
- abstract update_image_info(image_id, info)[source]
Update (or create a new) info tag for the desired image
- Parameters
image_id (
str
) – the id of the image we want to add/update infoinfo (
Dict
[str
,Any
]) – a dictionary of custom image information Dict[str, Any]
- Return type
None
- abstract update_label_info(label_id, label_tag, info)[source]
Update (or create a new) info tag for the desired label
- Parameters
label_id (
str
) – the id of the label we want to add/update infolabel_tag (
str
) – the matching label taginfo (
Dict
[str
,Any
]) – a dictionary of custom label information Dict[str, Any]
- Return type
None
- class monailabel.interfaces.exception.MONAILabelError(value)[source]
- SERVER_ERROR - Server Error
- UNKNOWN_ERROR - Unknown Error
- CLASS_INIT_ERROR - Class Initialization Error
- MODEL_IMPORT_ERROR - Model Import Error
- INFERENCE_ERROR - Inference Error
- TRANSFORM_ERROR - Transform Error
- INVALID_INPUT - Invalid Input
- APP_INIT_ERROR - Initialization Error
- APP_INFERENCE_FAILED - Inference Failed
- APP_TRAIN_FAILED - Train Failed
- APP_ERROR APP - General Error
- class monailabel.interfaces.exception.MONAILabelException(error, msg)[source]
MONAI Label Exception
Tasks¶
- class monailabel.interfaces.tasks.infer.InferType[source]
Type of Inference Model
- SEGMENTATION - Segmentation Model
- ANNOTATION - Annotation Model
- CLASSIFICATION - Classification Model
- DEEPGROW - Deepgrow Interactive Model
- DEEPEDIT - DeepEdit Interactive Model
- SCRIBBLES - Scribbles Model
- OTHERS - Other Model Type
- class monailabel.interfaces.tasks.infer.InferTask(path, network, type, labels, dimension, description, model_state_dict='model', input_key='image', output_label_key='pred', output_json_key='result', config=None, load_strict=False, roi_size=None, preload=False, train_mode=False, skip_writer=False)[source]
Basic Inference Task Helper
- Parameters
path (
Union
[None
,str
,Sequence
[str
]]) – Model File Path. Supports multiple paths to support versions (Last item will be picked as latest)network (
Optional
[Any
]) – Model Network (e.g. monai.networks.xyz). None in case if you use TorchScript (torch.jit).type (
Union
[str
,InferType
]) – Type of Infer (segmentation, deepgrow etc..)dimension (
int
) – Input dimensiondescription (
str
) – Descriptionmodel_state_dict (
str
) – Key for loading the model state from checkpointinput_key (
str
) – Input key for running inferenceoutput_label_key (
str
) – Output key for storing result/label of inferenceoutput_json_key (
str
) – Output key for storing result/label of inferenceconfig (
Optional
[Dict
[str
,Any
]]) – K,V pairs to be part of user configload_strict (
bool
) – Load model in strict moderoi_size – ROI size for scanning window inference
preload – Preload model/network on all available GPU devices
train_mode – Run in Train mode instead of eval (when network has dropouts)
skip_writer – Skip Writer and return data dictionary
- __init__(path, network, type, labels, dimension, description, model_state_dict='model', input_key='image', output_label_key='pred', output_json_key='result', config=None, load_strict=False, roi_size=None, preload=False, train_mode=False, skip_writer=False)[source]
- Parameters
path (
Union
[None
,str
,Sequence
[str
]]) – Model File Path. Supports multiple paths to support versions (Last item will be picked as latest)network (
Optional
[Any
]) – Model Network (e.g. monai.networks.xyz). None in case if you use TorchScript (torch.jit).type (
Union
[str
,InferType
]) – Type of Infer (segmentation, deepgrow etc..)dimension (
int
) – Input dimensiondescription (
str
) – Descriptionmodel_state_dict (
str
) – Key for loading the model state from checkpointinput_key (
str
) – Input key for running inferenceoutput_label_key (
str
) – Output key for storing result/label of inferenceoutput_json_key (
str
) – Output key for storing result/label of inferenceconfig (
Optional
[Dict
[str
,Any
]]) – K,V pairs to be part of user configload_strict (
bool
) – Load model in strict moderoi_size – ROI size for scanning window inference
preload – Preload model/network on all available GPU devices
train_mode – Run in Train mode instead of eval (when network has dropouts)
skip_writer – Skip Writer and return data dictionary
- inverse_transforms(data=None)[source]
Provide List of inverse-transforms. They are normally subset of pre-transforms. This task is performed on output_label (using the references from input_key)
- Parameters
data – current data dictionary/request which can be helpful to define the transforms per-request basis
- Return one of the following.
None: Return None to disable running any inverse transforms (default behavior).
Empty: Return [] to run all applicable pre-transforms which has inverse method
list: Return list of specific pre-transforms names/classes to run inverse method
For Example:
return [ monai.transforms.Spacingd, ]
- Return type
Optional
[Sequence
[Callable
]]
- abstract post_transforms(data=None)[source]
Provide List of post-transforms
- Parameters
data –
current data dictionary/request which can be helpful to define the transforms per-request basis
For Example:
return [ monai.transforms.AddChanneld(keys='pred'), monai.transforms.Activationsd(keys='pred', softmax=True), monai.transforms.AsDiscreted(keys='pred', argmax=True), monai.transforms.SqueezeDimd(keys='pred', dim=0), monai.transforms.ToNumpyd(keys='pred'), monailabel.interface.utils.Restored(keys='pred', ref_image='image'), monailabel.interface.utils.ExtremePointsd(keys='pred', result='result', points='points'), monailabel.interface.utils.BoundingBoxd(keys='pred', result='result', bbox='bbox'), ]
- Return type
Sequence
[Callable
]
- abstract pre_transforms(data=None)[source]
Provide List of pre-transforms
- Parameters
data –
current data dictionary/request which can be helpful to define the transforms per-request basis
For Example:
return [ monai.transforms.LoadImaged(keys='image'), monai.transforms.AddChanneld(keys='image'), monai.transforms.Spacingd(keys='image', pixdim=[1.0, 1.0, 1.0]), monai.transforms.ScaleIntensityRanged(keys='image', a_min=-57, a_max=164, b_min=0.0, b_max=1.0, clip=True), ]
- Return type
Sequence
[Callable
]
- run_inferer(data, convert_to_batch=True, device='cuda')[source]
Run Inferer over pre-processed Data. Derive this logic to customize the normal behavior. In some cases, you want to implement your own for running chained inferers over pre-processed data
- Parameters
data – pre-processed data
convert_to_batch – convert input to batched input
device – device type run load the model and run inferer
- Returns
updated data with output_key stored that will be used for post-processing
- writer(data, extension=None, dtype=None)[source]
You can provide your own writer. However, this writer saves the prediction/label mask to file and fetches result json
- Parameters
data – typically it is post processed data
extension – output label extension
dtype – output label dtype
- Return type
Tuple
[Any
,Any
]- Returns
tuple of output_file and result_json
- class monailabel.interfaces.tasks.train.TrainTask(description)[source]
Basic Train Task
- class monailabel.interfaces.tasks.strategy.Strategy(description)[source]
Basic Active Learning Strategy
- class monailabel.interfaces.tasks.scoring.ScoringMethod(description)[source]
Basic Scoring Method
Utils¶
- class monailabel.tasks.train.basic_train.BasicTrainTask(model_dir, description=None, config=None, amp=True, load_path=None, load_dict=None, publish_path=None, stats_path=None, train_save_interval=20, val_interval=1, n_saved=5, final_filename='checkpoint_final.pt', key_metric_filename='model.pt', model_dict_key='model', find_unused_parameters=False, load_strict=False, labels=None, **kwargs)[source]
This provides Basic Train Task to train a model using SupervisedTrainer and SupervisedEvaluator from MONAI
- Parameters
model_dir – Base Model Dir to save the model checkpoints, events etc…
description – Description for this task
config – K,V pairs to be part of user config
amp – Enable AMP for training
load_path – Initialize model from existing checkpoint (pre-trained)
load_dict – Provide dictionary to load from checkpoint. If None, then net will be loaded
publish_path – Publish path for best trained model (based on best key metric)
stats_path – Path to save the train stats
train_save_interval – checkpoint save interval for training
val_interval – validation interval (run every x epochs)
n_saved – max checkpoints to save
final_filename – name of final checkpoint that will be saved
key_metric_filename – best key metric model file name
model_dict_key – key to save network weights into checkpoint
find_unused_parameters – Applicable for DDP/Multi GPU training
load_strict – Load pretrained model in strict mode
- __init__(model_dir, description=None, config=None, amp=True, load_path=None, load_dict=None, publish_path=None, stats_path=None, train_save_interval=20, val_interval=1, n_saved=5, final_filename='checkpoint_final.pt', key_metric_filename='model.pt', model_dict_key='model', find_unused_parameters=False, load_strict=False, labels=None, **kwargs)[source]
- Parameters
model_dir – Base Model Dir to save the model checkpoints, events etc…
description – Description for this task
config – K,V pairs to be part of user config
amp – Enable AMP for training
load_path – Initialize model from existing checkpoint (pre-trained)
load_dict – Provide dictionary to load from checkpoint. If None, then net will be loaded
publish_path – Publish path for best trained model (based on best key metric)
stats_path – Path to save the train stats
train_save_interval – checkpoint save interval for training
val_interval – validation interval (run every x epochs)
n_saved – max checkpoints to save
final_filename – name of final checkpoint that will be saved
key_metric_filename – best key metric model file name
model_dict_key – key to save network weights into checkpoint
find_unused_parameters – Applicable for DDP/Multi GPU training
load_strict – Load pretrained model in strict mode
Client¶
- class monailabel.client.client.MONAILabelClient(server_url, tmpdir=None, client_id=None)[source]
Basic MONAILabel Client to invoke infer/train APIs over http/https
- Parameters
server_url – Server URL for MONAILabel (e.g. http://127.0.0.1:8000)
tmpdir – Temp directory to save temporary files. If None then it uses tempfile.tempdir
client_id – Client ID that will be added for all basic requests
- __init__(server_url, tmpdir=None, client_id=None)[source]
- Parameters
server_url – Server URL for MONAILabel (e.g. http://127.0.0.1:8000)
tmpdir – Temp directory to save temporary files. If None then it uses tempfile.tempdir
client_id – Client ID that will be added for all basic requests
- create_session(image_in, params=None)[source]
Create New Session
- Parameters
image_in – filepath for image to be sent to server as part of session creation
params – additional JSON params as part of session reqeust
- Returns
json response which contains session id and other details
- get_server_url()[source]
Return server url
- Returns
the url for monailabel server
- get_session(session_id)[source]
Get Session
- Parameters
session_id – Session Id
- Returns
json response which contains more details about the session
- infer(model, image_id, params, label_in=None, file=None, session_id=None)[source]
Run Infer
- Parameters
model – Name of Model
image_id – Image Id
params – Additional configs/json params as part of Infer request
label_in – File path for label mask which is needed to run Inference (e.g. In case of Scribbles)
file – File path for Image (use raw image instead of image_id)
session_id – Session ID (use existing session id instead of image_id)
- Returns
response_file (label mask), response_body (json result/output params)
- info()[source]
Invoke /info/ request over MONAILabel Server
- Returns
json response
- next_sample(strategy, params)[source]
Get Next sample
- Parameters
strategy – Name of strategy to be used for fetching next sample
params – Additional JSON params as part of strategy request
- Returns
json response which contains information about next image selected for annotation
- remove_session(session_id)[source]
Remove any existing Session
- Parameters
session_id – Session Id
- Returns
json response
- save_label(image_id, label_in, tag='', params=None)[source]
Save/Submit Label
- Parameters
image_id – Image Id for which label needs to saved/submitted
label_in – Label File path which shall be saved/submitted
tag – Save label against tag in datastore
params – Additional JSON params for the request
- Returns
json response
- set_server_url(server_url)[source]
Set url for monailabel server
- Parameters
server_url – server url for monailabel
- train_start(model, params)[source]
Run Train Task
- Parameters
model – Name of Model
params – Additional configs/json params as part of Train request
- Returns
json response
- train_status(check_if_running=False)[source]
Check Train Task Status
- Parameters
check_if_running – Fast mode. Only check if training is Running
- Returns
boolean if check_if_running is enabled; else json response that contains of full details
- train_stop()[source]
Stop any running Train Task(s)
- Returns
json response
- upload_image(image_in, image_id=None, params=None)[source]
Upload New Image to MONAILabel Datastore
- Parameters
image_in – Image File Path
image_id – Force Image ID; If not provided then Server it auto generate new Image ID
params – Additional JSON params
- Returns
json response which contains image id and other details
- wsi_infer(model, image_id, body=None, output='dsa', session_id=None)[source]
Run WSI Infer in case of Pathology App
- Parameters
model – Name of Model
image_id – Image Id
body – Additional configs/json params as part of Infer request
output – Output File format (dsa|asap|json)
session_id – Session ID (use existing session id instead of image_id)
- Returns
response_file (None), response_body
- class monailabel.client.client.MONAILabelError[source]
Type of Inference Model
- SERVER_ERROR - Server Error
- SESSION_EXPIRED - Session Expired
- UNKNOWN - Unknown Error