Usage

Info

Get basic project info

$ mdai project info --help
Usage: mdai project info [options]

Display project info

Options:
  -i, --project-id <id>  project id
  -h, --help             display help for command

Example:

$ mdai project info --project-id MwBeWjNr

Project MwBeWjNr - Test Project
--------------------------------------------------
Description:
Private:    YES
Created:    2018-10-07 19:10:16
Updated:    2018-10-07 19:11:39

Get list of project datasets

$ mdai project list-datasets --help
Usage: mdai project list-datasets [options]

List project datasets

Options:
  -i, --project-id <id>  project id
  -h, --help             display help for command

Example:

$ mdai project list-datasets --project-id MwBeWjNr

Project MwBeWjNr: Test Project
--------------------------------------------------
Datasets:
ID         Name      Type    Source   Created               Updated               Processing
D_NbrqAB   Head CT   DICOM   upload   2018-10-07 19:11:39   2018-10-07 19:11:39

Get dataset info

$ mdai dataset info --help
Usage: mdai dataset info [options]

Display dataset info

Options:
  -i, --dataset-id <id>  dataset id
  -h, --help             display help for command

Example:

$ mdai dataset info --dataset-id D_NbrqAB

Dataset D_NbrqAB: Head CT
--------------------------------------------------
Type          DICOM
Source        upload
Description
Created       2018-10-07 19:11:39
Updated       2018-10-07 19:14:50
# Studies     1
# Series      1
# Images      11

Creating projects and datasets

Create new project

$ mdai project create --help
Usage: mdai project create [options]

Create new project

Options:
  -n, --name <name>                project name (use quotes if contains spaces)
  -d, --description <description>  [optional] project description (use quotes if contains spaces)
  -m, --model <name>               [optional] sample model name
  -s, --setting <pathname>         [optional] project settings
  -h, --help                       display help for command

Example:

$ mdai project create --name 'New Project' --description 'This is a _markdown_ formatted description.'

Successfully created project New Project [id: L4RJwoNP]

Project name is required, but providing a description is optional.

Clone existing dataset

$ mdai dataset clone --help
Usage: mdai dataset clone [options]

Clone dataset to a different project

Options:
  -i, --dataset-id <id>  dataset id to clone from
  -p, --project-id <id>  target project to clone to
  -h, --help             display help for command

Example:

$ mdai dataset clone --dataset-id D_6BWvjY --project-id VpBQwNA6

Successfully cloned dataset Test_Dataset [id: D_6BWvjY] to Project Test_Project [id: VpBQwNA6]

Loading DICOM resources

Load DICOM into dataset (`upload` source only)

$ mdai dataset load --help
Usage: mdai dataset load [options] <pathname>

Load files/folders into dataset (upload source only)

Options:
  -i, --dataset-id <id>            dataset id
  -o, --order-exams-by <ordering>  [optional] order exams by [ default, patient_id, study_date_time, study_desc, random ] (default: "default")
  -h, --help                       display help for command

All files and folders under the specified path will be included, including any symlinked files or folders.

Example:

$ mdai dataset load --dataset-id D_GmxvgB dicom_dir

Preparing to upload 'dicom_dir' to DICOM dataset D_GmxvgB...
File count: 11
Total size: 5.52 MB

Uploading:
100% [==================================================] 11/11 [0.0s<0.0s, 478/s]
Completed. No errors.

Done uploading for batch id 1e6ddfed-a32f-4cd4-8113-c683b9122134.
Run `mdai dataset progress -i D_GmxvgB` to track progress.

Load DICOM into dataset (`google-cloud-storage` or `amazon-s3` source only)

For datasets created with source google-cloud-storage or amazon-s3, provide the bucket name (with optional file prefix to filter on).

Bucket permissions must be maintained for the corresponding MD.ai external data service account with at least the Storage Object Viewer role. See the web UI for the service account email, or see the resulting error message for this command when permissions are not present or sufficient.

$ mdai dataset connect --help
Usage: mdai dataset connect [options]

Connect cloud storage bucket into dataset (google-cloud-storage or amazon-s3 source only)

Options:
  -i, --dataset-id <id>            dataset id
  -b, --bucket <bucket>            bucket name
  -p, --prefix <prefix>            [optional] folder prefix
  -o, --order-exams-by <ordering>  [optional] order exams by [ default, patient_id, study_date_time, study_desc, random ] (default: "default")
  -h, --help                       display help for command

Example:

$ mdai dataset connect --dataset-id D_1j4M2B --bucket mdai-test-bucket --prefix test

Dataset D_1j4M2B - New Dataset 2
──────────────────────────────────────────────────
       Bucket: mdai-test-bucket
       Prefix: test
  Order Exams: default

Successfully connected bucket. Run `mdai dataset progress -i D_1j4M2B` to track progress.

Check progress of DICOM processing for dataset

$ mdai dataset progress --help
Usage: mdai dataset progress [options]

Check dataset processing progress

Options:
  -i, --dataset-id <id>  dataset id
  -h, --help             display help for command

Example:

$ mdai dataset progress --dataset-id D_NbrqAB

Dataset D_NbrqAB: Head CT
--------------------------------------------------
Type: DICOM
Source: upload
Processing progress for worker batch id 1e6ddfed-a32f-4cd4-8113-c683b9122134

Status                                FINISHED
Subtask: process uploaded files
  # Completed                         11
  # Remaining                         0
  # Errors                            0
Subtask: generate series thumbnails
  # Completed                         1
  # Remaining                         0
  # Errors                            0
Started                               2018-10-07 19:13:36
Elapsed time                          1
Percent complete                      100%

Deleting DICOM resources

Delete existing dataset

$ mdai dataset delete --help
Usage: mdai dataset delete [options]

Delete dataset

Options:
  -i, --dataset-id <id>  dataset id
  -h, --help             display help for command

Example:

$ mdai dataset delete -i D_Zb5Eb4

Dataset D_Zb5Eb4 - VAL
This cannot be undone! Enter the dataset name VAL to comfirm deletion:
VAL

Start deleting dataset VAL

Done deleting dataset VAL

Delete existing studies/series/instances from dataset by UIDs

Delete studies:

$ mdai dataset remove-study --help
Usage: mdai dataset remove-study [options]

Remove studies from dataset by UIDs

Options:
  -i, --dataset-id <id>    dataset id
  -U, --study-uids <uids>  StudyInstanceUIDs, separated by commas(no spaces)
  -h, --help               display help for command

Delete series:

$ mdai dataset remove-series --help
Usage: mdai dataset remove-series [options]

Remove series from dataset by UIDs

Options:
  -i, --dataset-id <id>     dataset id
  -U, --series-uids <uids>  SeriesInstanceUIDs, separated by commas(no spaces)
  -h, --help                display help for command

Delete instances:

$ mdai dataset remove-instance --help
Usage: mdai dataset remove-instance [options]

Remove instances from dataset by UIDs

Options:
  -i, --dataset-id <id>       dataset id
  -U, --instance-uids <uids>  SOPInstanceUIDs, separated by commas(no spaces)
  -h, --help                  display help for command

Example:

$ mdai dataset remove-study -i D_vBnWb1 -U 1.2.276.0.7230010.3.1.2.8323329.15697.1531787477.263823,1.2.276.0.7230010.3.1.2.8323329.15695.1531787477.240488

Dataset D_vBnWb1 - TRAIN
Successfully deleted DICOM studies with StudyInstanceUID:
 1.2.276.0.7230010.3.1.2.8323329.15697.1531787477.263823
 1.2.276.0.7230010.3.1.2.8323329.15695.1531787477.240488

$ mdai dataset remove-series -i D_vBnWb1 -U 1.2.276.0.7230010.3.1.3.8323329.15825.1531787477.370926

Dataset D_vBnWb1 - TRAIN
Successfully deleted DICOM series with SeriesInstanceUID:
 1.2.276.0.7230010.3.1.3.8323329.15825.1531787477.370926

$ mdai dataset remove-instance -i D_vBnWb1 -U 1.2.276.0.7230010.3.1.4.8323329.15772.1531787477.330136,1.2.276.0.7230010.3.1.4.8323329.15650.1531787477.198749,1.2.276.0.7230010.3.1.4.8323329.15664.1531787477.222040

Dataset D_vBnWb1 - TRAIN
Successfully deleted DICOM series with SOPInstanceUID:
 1.2.276.0.7230010.3.1.4.8323329.15772.1531787477.330136
 1.2.276.0.7230010.3.1.4.8323329.15650.1531787477.198749
 1.2.276.0.7230010.3.1.4.8323329.15664.1531787477.222040

User management

Add users

$ mdai project add-user --help
Usage: mdai project add-user [options]

Add user to project

Options:
  -i, --project-id <id>  project id
  -e, --email <email>    user email
  -r, --role <role>      role of project user [ READER, WRITER, QA, ADMIN ]
  -h, --help             display help for command

Example:

$ mdai project add-user --project-id maBjAq5 --email user@email.com --role WRITER

Successfully added user U_eMzVMx with WRITER role.

Get list of users

List users in project with their user id, name, email, and role.

$ mdai project list-users --help
Usage: mdai project list-users [options]

List project users

Options:
  -i, --project-id <id>  project id
  -j, --json             [optional] output as JSON
  -h, --help             display help for command

Example:

$ mdai project list-users --project-id MwBeWjNr

ID           Name            Email             Role    Pending
-----------------------------------------------------------------
 U_y01508    Jane Doe        jane@md.ai        ADMIN    No

Get list of assignments

List user assignments in project with their user id, name, label group restrictions, and exams list (dicomStudyRestriction).

$ mdai project list-user-assignments --help
Usage: mdai project list-user-assignments [options]

List assignments for project users

Options:
  -i, --project-id <id>  project id
  -j, --json             [optional] output as JSON
  -h, --help             display help for command

Example:

$ mdai project list-user-assignments --project-id MwBeWjNr

userId    name                labelGroupRestriction   dicomStudyRestriction
U_8dX2w8  femur@yopmail.com   G_WjoBx1,G_ADkazj       D_WmRdXB: 20-30,35,37
U_6vkyr8  ulna@yopmail.com    G_A1AXoD                None

Add --json to get output in JSON format:

$ mdai project list-user-assignments --project-id MwBeWjNr --json

"data": [
  {
    "userId": "U_8dX2w8",
    "name": "femur@yopmail.com",
    "labelGroupRestriction": [
      "G_WjoBx1",
      "G_ADkazj"
    ],
    "dicomStudyRestriction": [
      {
        "dicomDatasetId": "D_WmRdXB",
        "dicomDatasetStudyNumbers": "20-30,35,37"
      }
    ]
  },
  {
    "userId": "U_6vkyr8",
    "name": "ulna@yopmail.com",
    "labelGroupRestriction": ["G_A1AXoD"],
    "dicomStudyRestriction": []
  }
]

Add/update assignments

$ mdai project update-user-assignment --help
Usage: mdai project update-user-assignment [options]

Update assignments for project users

Options:
  -i, --project-id <id>          project id
  -u, --user-id <id>             user id
  -d, --dataset-id <id>          [optional: use with --exams] dataset id
  -e, --exams <sequence>         [optional: use with --dataset-id] for specified dataset, assign exams such as 1-3,3-4 (use '' to reset)
  -g, --label-group <number(s)>  [optional] label group number, or multiple comma-separated numbers (use '' to reset)
  -h, --help                     display help for command

This command will assign a range of exams and specific label group(s) to a user programmatically. Users need to be invited to the project first in order to have a user id. The following values need to be known:

project id
user id
dataset id, if specific exams are to be assigned
label group number, if specific label groups are to be assigned

Exam assignments are tied to a specific dataset so it must be provided together with a dataset id. For multiple datasets, multiple commands can be issued (one for each dataset).

Example (generic):

$ mdai project update-user-assignment --project-id PROJECT_ID --user-id USER_ID \
  --dataset-id DATASET_ID --exams EXAM_NUMBERS \
  --label-group LABEL_GROUP_NUMBER

Successfully updated project user assignment.

Example (specific):

$ mdai project update-user-assignment --project-id maBjAq5 --user-id U_oVjzV \
  --dataset-id D_v0B1N --exams '1-30,47,51-100' \
  --label-group '1,4'

Successfully updated project user assignment.

Assignments cannot be made for project admin users. Invite the user with an alternate email address (which will create a separate user with a separate user id) if an assignment needs to be made for that user.

In order to remove/reset assignments or parts of an assignment, use an empty string. For example:

$ mdai project update-user-assignment --project-id maBjAq5 --user-id U_oVjzV \
--dataset-id D_v0B1N --exams '' \
--label-group ''

Models

Check model info

$ mdai model info --help
Usage: mdai model info [options]

Display model info

Options:
  -i, --model-id <id>  model id
  -h, --help           display help for command

Example:

$ mdai model info --model-id M_0N3ADm

Model M_0N3ADm - X-Ray Classifier
──────────────────────────────────────────────────
Description:   Classifies X-rays as chest or abdomen
Scope:         Image
Created:       2022-09-13 11:35:19
Updated:       2022-09-13 11:36:51
Privacy:       Private
AutoRun:       No
Exportable:    No
Cloneable:     No
──────────────────────────────────────────────────
Labels With Class Index
──────────────────────────────────────────────────────────────────
 class index  │ label id │ label name │ label type │ label scope
──────────────────────────────────────────────────────────────────
 0            │ L_QRb9NQ │ Abdomen    │ Global     │ Image
──────────────────────────────────────────────────────────────────
 1            │ L_gw3RNg │ Chest      │ Global     │ Image
──────────────────────────────────────────────────────────────────
──────────────────────────────────────────────────
Versions
─────────────────────────────────────────────────────────────────────────────────────────────────────
 #  │ id  │ Docker Image:Tag                        │ Created             │ Build Status │ Hardware
─────────────────────────────────────────────────────────────────────────────────────────────────────
 1  │ 541 │ gcr.io/mdai-models/staging/model-198/v1 │ 2022-09-13 11:35:20 │ Success      │ CPU
─────────────────────────────────────────────────────────────────────────────────────────────────────

Clone model

$ mdai model clone --help
Usage: mdai model clone [options]

Clone project models

Options:
  --from-project-id <id>    original project id
  --to-project-ids <ids>    target project ids, separated by commas
  --from-model-ids <ids>    [optional] original model ids in original project, separated by commas
  --from-domain <domain>    [optional] original project MD.ai domain (e.g., public.md.ai)
  -c, --config-file <path>  [optional] clone config file (.json or .yaml)
  -h, --help                display help for command

Example:

$ mdai model clone --from-project-id MmRa7Mqr --to-project-ids 0pqXObNZ

Clone result of project 0pqXObNZ: Clones 3 models into project
Clone models complete!

Update model

$ mdai model set --help
Usage: mdai model set [options]

Update model

Options:
  -i, --model-id <id>                      model id
  -n, --model-name <name>                  [optional] model name (use quotes if contains spaces)
  -d, --model-description <description>    [optional] model description (use quotes if contains spaces)
  -p, --model-privacy <privacy>            [optional] configure model privacy (private or public)
  -a, --model-autorun-inference [autorun]  [optional] configure model autorun (y/n, yes or no)
  -e, --model-exportable [exportable]      [optional] configure model exportable (y/n, yes or no)
  -c, --model-cloneable [cloneable]        [optional] configure model cloneable (y/n, yes or no)
  -s, --model-clone-scope <scope>          [optional] model clone scope (SITE_ONLY or ALL_DOMAINS)
  -h, --help                               display help for command

Example:

Change model name:

$ mdai model set --model-id M_7bxME5 --model-name "Demo model"

Successfully set model [id: M_7bxME5] name to be Demo Models

Set model autorun inference to yes:

$ mdai model set --model-id M_7bxME5 --model-autorun-inference yes

Successfully set model [id: M_7bxME5] autorun inference to be yes.

Delete model

$ mdai model delete --help
Usage: mdai model delete [options]

Delete model

Options:
  -i, --model-id <id>  model id
  -h, --help           display help for command

Example:

$ mdai model delete --model-id M_BkQJWl

Successfully deleted model test [id: M_BkQJWl]

Create model task

$ mdai model create-task --help
Usage: mdai model create-task [options]

Create new model inference task on dataset

Options:
  -m, --model-version-id <id>  model version id
  -i, --dataset-id <id>        dataset id
  -j, --json                   [optional] output as JSON
  -h, --help                   display help for command

Example:

$ mdai model create-task --model-version-id 13 --dataset-id D_vbvwom

Successfully created model inference task [Task ID: 190] on dataset Finetuning [Dataset ID: D_vbvwom]

Clone model outputs as annotations

$ mdai model clone-output --help
Usage: mdai model clone-output [options]

Clone model outputs as annotations for entire model task

Options:
  -i, --model-task-id <id>  model task id
  -h, --help                display help for command

Example:

$ mdai model clone-output --model-task-id 189

Successfully clones 700 model outputs as annotations.

Project starter packs with models

List available models

Currently supported models for starter packs:

$ mdai model create --list-models

─────────────────────────────────────────────────────────────────────────
 name                    │ description
─────────────────────────────────────────────────────────────────────────
 mdai:xray-classifier    │ Classifies X-rays as chest or abdomen
─────────────────────────────────────────────────────────────────────────
 mdai:lung-segmentation  │ Generates segmentation for lungs in xray images
─────────────────────────────────────────────────────────────────────────
 mdai:pixel-deid         │ Pixel level De-identification
─────────────────────────────────────────────────────────────────────────

Create new project with selected models

$ mdai project create --help
Usage: mdai project create [options]

Create new project

Options:
  -n, --name <name>                project name (use quotes if contains spaces)
  -d, --description <description>  [optional] project description (use quotes if contains spaces)
  -m, --model <name>               [optional] sample model name
  -s, --setting <pathname>         [optional] project settings
  -h, --help                       display help for command

Example:

$ mdai project create --name "Test Project" --model mdai:xray-classifier

Successfully created project Test Project [id: Y2qrE9Nv] and model X-Ray Classifier [id: M_0N3ADm]

Add model to project

$ mdai model create --help
Usage: mdai model create [options]

Create model

Options:
  -l, --list-models        list available sample models
  -i, --project-id <id>    project id
  -n, --model-name <name>  sample model name
  -h, --help               display help for command

Example:

$ mdai model create --project-id Y2qrE9Nv --model-name mdai:xray-classifier

Successfully created model X-Ray Classifier [id: M_0N3ADm] in project [id: Y2qrE9Nv]

De-identification (De-ID)

Create De-ID task

Creates a DeID task that can be found in the De-ID panel on the UI. Can be used to create both pixel redaction and dicom tag redaction tasks.

$ mdai deid create-task --help
Usage: mdai deid create-task [options]

Create De-ID task

Options:
  -i, --dataset-id <id>                  dataset id
  -a, --auto-inference [value]           [optional] Apply automatic inference (y/n, yes or no)
  -m, --auto-inference-model <name>      [optional] Automatic inference model name (defaults to "mdai:pixel-deid")
  -l, --label-ids <ids>                  [optional] label ids, separated by commas (no spaces)
  -r, --remove-private-tags [value]      [optional] Remove private tags (y/n, yes or no)
  -c, --tags-config <path or "default">  [optional] path to DICOM tags modification JSON config file (load default if "default")
  -j, --json                             [optional] output as JSON
  -h, --help                             display help for command

Example:

To run the entire De-identification workflow (including adding the latest De-ID model to the project, running infernece, and redacting all the model outputs by running the De-ID task) using one single command:

$ mdai deid create-task -i D_emLA9j -a yes

Successfully created De-ID task [id: 126] for dataset [id: D_emLA9j]

To just run a part of the workflow where you want to redact manually created or inferenced labels you can choose to add the label IDs to redact:

$ mdai deid create -i D_emLA9j -l L_EM2rPN,L_ZgDraE

Successfully created De-ID task [id: 127] for dataset [id: D_emLA9j]

To create a dicom tag redaction task with the default tag redaction config file:

$ mdai deid create -i D_emLA9j -c default

Successfully created De-ID task [id: 128] for dataset [id: D_emLA9j]

To create a dicom tag redaction tasl the utilizes your own config file for tags:

# Export default tags config file, exported config file name would be `mdai_deid_tags_config.json`
mdai deid export-tags
# ......
# Do some custom modification for tags config file
# ......
# Use custom tags config file when create De-ID task
mdai deid create -i D_emLA9j -c mdai_deid_tags_config.json

Successfully created De-ID task [id: 126] for dataset [id: D_VNJgbG]

Get task info

$ mdai deid task-info --help
Usage: mdai deid task-info [options]

Display deid task info

Options:
  -i, --deid-task-id <id>  deid task id
  -j, --json               [optional] output as JSON
  -h, --help               display help for command

Example

$ mdai deid task-info -i 125

DEID Task 125
──────────────────────────────────────────────────
Type:           DEID
Status:         SUCCEEDED
Progress:       100
Created at:     2024-01-02 16:30:25
Start Time:     2024-01-02 16:30:29
End Time:       2024-01-02 16:40:19
Success Count:  3
Error Count:
New Dataset ID: D_LNqELN

Export default dicom tag redaction config

$ mdai deid export-tags --help
Usage: mdai deid export-tags [options]

Export default DICOM tags modification config file

Options:
  -d, --export-dir <path>  [optional] export dir
  -h, --help               display help for command

Example

$ mdai deid export-tags

Exported DICOM tags modification default config file to mdai_deid_tags_config.json

Info

Get basic project info

Get list of project datasets

Get dataset info

Creating projects and datasets

Create new project

Create new dataset

Clone existing dataset

Loading DICOM resources

Load DICOM into dataset (`upload` source only)

Load DICOM into dataset (`google-cloud-storage` or `amazon-s3` source only)

Check progress of DICOM processing for dataset

Deleting DICOM resources

Delete existing dataset

Delete existing studies/series/instances from dataset by UIDs

User management

Add users

Get list of users

Get list of assignments

Add/update assignments

Models

Check model info

Clone model

Update model

Delete model

Create model task

Clone model outputs as annotations

Project starter packs with models

List available models

Create new project with selected models

Add model to project

De-identification (De-ID)

Create De-ID task

Get task info

Export default dicom tag redaction config

On this page