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 directory

  • studies (str) – path for studies/datalist

  • conf (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 directory

  • studies (str) – path for studies/datalist

  • conf (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 used

  • image_filename (str) – the path to the image file

  • image_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_dataset_archive(limit_cases)[source]

Retrieve ZIP archive of the full dataset containing images, labels and metadata

Parameters

limit_cases (Optional[int]) – limit the included cases to this number

Return type

str

Returns

path to ZIP archive of the full dataset

abstract get_image(image_id, params=None)[source]

Retrieve image object based on image id

Parameters
  • image_id (str) – the desired image’s id

  • params – 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 id

  • label_tag (str) – the matching label’s tag

  • params – 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 id

  • tag (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 id

  • label_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 id

  • label_tag (str) – the matching label’s tag

Return type

str

Returns

return the label uri

abstract get_labeled_images(label_tag=None, labels=None)[source]

Get all images that have a corresponding final label

Parameters
  • label_tag (Optional[str]) – the matching label tag

  • labels (Optional[List[str]]) – list of matching labels

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(label_tag=None, labels=None)[source]

Get all images that have no corresponding final label

Parameters
  • label_tag (Optional[str]) – the matching label tag

  • labels (Optional[List[str]]) – list of matching labels

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 datastore

  • label_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 label

  • label_filename (str) – the path to the label file

  • label_tag (str) – the user-provided tag for the label

  • label_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 info

  • info (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 info

  • label_tag (str) – the matching label tag

  • info (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(value)[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]
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..)

  • labels (Union[str, None, Sequence[str], Dict[Any, Any]]) – Labels associated to this Infer

  • dimension (int) – Input dimension

  • description (str) – Description

  • model_state_dict (str) – Key for loading the model state from checkpoint

  • input_key (str) – Input key for running inference

  • output_label_key (str) – Output key for storing result/label of inference

  • output_json_key (str) – Output key for storing result/label of inference

  • config (Optional[Dict[str, Any]]) – K,V pairs to be part of user config

  • load_strict (bool) – Load model in strict mode

  • roi_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)
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..)

  • labels (Union[str, None, Sequence[str], Dict[Any, Any]]) – Labels associated to this Infer

  • dimension (int) – Input dimension

  • description (str) – Description

  • model_state_dict (str) – Key for loading the model state from checkpoint

  • input_key (str) – Input key for running inference

  • output_label_key (str) – Output key for storing result/label of inference

  • output_json_key (str) – Output key for storing result/label of inference

  • config (Optional[Dict[str, Any]]) – K,V pairs to be part of user config

  • load_strict (bool) – Load model in strict mode

  • roi_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

class monailabel.interfaces.tasks.train.TrainTask(description)[source]

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, disable_tracking=False)[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 pre-trained model in strict mode

  • labels – Labels to be used as part of training context (some transform might need)

  • disable_tracking – Disable tracking for faster training rate (unless you are using MetaTensor/batched transforms)

__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, disable_tracking=False)[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 pre-trained model in strict mode

  • labels – Labels to be used as part of training context (some transform might need)

  • disable_tracking – Disable tracking for faster training rate (unless you are using MetaTensor/batched transforms)

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

Modules