API Reference

MONAILabel APP

class monailabel.interfaces.app.MONAILabelApp(app_dir, studies, conf, name='', description='', version='2.0', labels=None)

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)

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)

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)

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()

Provide basic information about APP. This information is passed to client.

next_sample(request)

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)

Callback method when label is saved into datastore by a remote client

scoring(request, datastore=None)

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)

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

abstract add_image(image_id, image_filename, image_info)

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()

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()

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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()

Return json representation of datastore

abstract list_images()

Return list of image ids available in the datastore

Return type

List[str]

Returns

list of image ids List[str]

abstract name()

Return the human-readable name of the datastore

Return type

str

Returns

the name of the dataset

abstract refresh()

Refresh the datastore

Return type

None

abstract remove_image(image_id)

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)

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)

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)

A human-readable description of the datastore

Parameters

description (str) – string for description

abstract set_name(name)

Set the name of the datastore

Parameters

name (str) – a human-readable name for the datastore

abstract status()

Return current statistics of datastore

Return type

Dict[str, Any]

abstract update_image_info(image_id, info)

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)

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)

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)

MONAI Label Exception

Tasks

class monailabel.interfaces.tasks.infer.InferType(value)

Type of Inference Model

SEGMENTATION -            Segmentation Model

ANNOTATION -              Annotation Model

CLASSIFICATION -          Classification Model

DEEPGROW -                Deepgrow Interactive Model

DEEPEDIT -                DeepEdit Interactive Model

SCRIBBLES -               Scribbles Model

DETECTION -               Detection 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=True, 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

__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=True, 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)

Train Task

class monailabel.interfaces.tasks.strategy.Strategy(description)

Basic Active Learning Strategy

class monailabel.interfaces.tasks.scoring.ScoringMethod(description)

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_meta_tracking=False, tracking='mlflow', tracking_uri='', tracking_experiment_name=None)

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_meta_tracking – Disable tracking for faster training rate (unless you are using MetaTensor/batched transforms)

• tracking – Tracking Manager for Experiment Management (only ‘mlflow’ is supported)

• tracking_uri – Tracking URI for Experiment Management

• tracking_experiment_name – Name for tracking experiment

__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_meta_tracking=False, tracking='mlflow', tracking_uri='', tracking_experiment_name=None)

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_meta_tracking – Disable tracking for faster training rate (unless you are using MetaTensor/batched transforms)

• tracking – Tracking Manager for Experiment Management (only ‘mlflow’ is supported)

• tracking_uri – Tracking URI for Experiment Management

• tracking_experiment_name – Name for tracking experiment

Client

class monailabel.client.client.MONAILabelClient(server_url, tmpdir=None, client_id=None)

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)

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

auth_enabled()

Check if Auth is enabled

Return type

bool

auth_token(username, password)

Fetch Auth Token. Currently only basic authentication is supported.

Parameters

• username – UserName for basic authentication

• password – Password for basic authentication

create_session(image_in, params=None)

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()

Return server url

Returns

the url for monailabel server

get_session(session_id)

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)

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()

Invoke /info/ request over MONAILabel Server

Returns

json response

next_sample(strategy, params)

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)

Remove any existing Session

Parameters

session_id – Session Id

Returns

json response

save_label(image_id, label_in, tag='', params=None)

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)

Set url for monailabel server

Parameters

server_url – server url for monailabel

train_start(model, params)

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)

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()

Stop any running Train Task(s)

Returns

json response

upload_image(image_in, image_id=None, params=None)

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)

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

Type of Inference Model

SERVER_ERROR -           Server Error

SESSION_EXPIRED -        Session Expired

UNKNOWN -                Unknown Error

Modules

• monailabel
  • monailabel package
    • Subpackages
      • monailabel.client package
      • monailabel.datastore package
      • monailabel.deepedit package
      • monailabel.interfaces package
      • monailabel.scribbles package
      • monailabel.tasks package
      • monailabel.transform package
      • monailabel.utils package
    • Submodules
      • monailabel.app module
      • monailabel.config module
      • monailabel.main module
    • Module contents

previous

Application Deployment

next

monailabel