Skip to content

CLI 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]  project description (use quotes if contains spaces)
  -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]

Note

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

Create new dataset

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

Create new dataset in project

Options:
  -i, --project-id <id>            project id
  -s, --source <source>            dataset source, one of: [ upload, dicom-push, google-cloud-storage, google-cloud-healthcare-api, amazon-s3 ]
  -n, --name <name>                dataset name (use quotes if contains spaces)
  -d, --description [description]  dataset description (use quotes if contains spaces)
  -h, --help                       display help for command

Example

$ mdai dataset create --project-id L4RJwoNP --source upload --name 'New Dataset' --description 'This is a _markdown_ formatted description.'

Successfully created DICOM dataset New Dataset with upload source [id: D_GmxvgB]

Note

Providing a description is optional.

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]  order exams by [ default, patient_id, study_date_time, study_desc, random ] (default: "default")
  -h, --help                       display help for command

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

Note

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]            folder prefix (optional)
  -o, --order-exams-by [ordering]  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 DICOM resources (studies/series/instances) from dataset by UIDs

$ 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
$ 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
$ 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, 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 userId, name, email, and permissions.

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

List project users

Options:
  -i, --project-id <id>  project id
  -j, --json             print json object
  -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 assignments in project with their userId, name, labelGroupRestriction, and exam 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             print json object
  -h, --help             display help for command

Example

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

  userId              name        labelGroupRestriction    dicomStudyRestriction
2   U_8dX2w8    femur@yopmail.com       2             [{'dicomDatasetId': 'D_xxxxx', 'dicomDatasetStudyNumbers': '20-30,35,37'}]
3   U_6vkyr8    ulna@yopmail.com        2             [{'dicomDatasetId': 'D_xxxxx', 'dicomDatasetStudyNumbers': '1-101,200'}]

Add --json to get output in JSON format:

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

"data": [
    {
      "userId": "U_y01508",
      "name": "Jane Doe",
      "labelGroupRestriction": null,
      "dicomStudyRestriction": null
    },
    {
      "userId": "U_8dX2w8",
      "name": "femur@yopmail.com",
      "labelGroupRestriction": 2,
      "dicomStudyRestriction": [
        {
          "dicomDatasetId": "D_7E0l4E",
          "dicomDatasetStudyNumbers": "21-40,80,90-95"
        }
      ]
    }]

Assign exams

$ 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]       dataset id
  -e, --exams [sequence]      assign exams such as 1-3,3-4
  -g, --label-group [number]  label group sorted index
  -h, --help                  display help for command

This command will assign a range of exams and specific label group to a user programmatically. Users need to be invited to the project first in order to have a userId. Variables needed include

  • project-id
  • user-id
  • dataset-id, if specific exams assigned
  • label-group which the number of the label group seen in the UI or 0 if unrestricted

Example (generic)

$ mdai project update-user-assignment --project-id PROJECT_ID --user-id USER_ID  --dataset-id DATASET_ID --exams 1,2,3-5,6  --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 4

Remember to set domain and token first.

Note

Users with Admin privileges cannot get assignments if an Admin needs to be given an assignment, invite the user with an additional email address with Read/Write access or the user will have two user_ids, one as an Admin and one as an Annotator.