Inference API

Enables a developer to access information about model inferences on studies from an institution

Tip: Client SDK implements clients that make it easier to interact with our Inferences API in various languages.

The Inference object

This is an object representing a model inference on a study. It contains information about the model, the study, inputs derived from the study, and outputs estimated by running the model on the inputs derived from the study.

Inputs derived from the study correspond to DICOM data elements, such as the patient's sex, the pixel spacing of the series, or the X/Y/Z position of the image. A data element's value may apply to an entire study or only specific series or instances. For example, the patient's sex applies to the entire study, whereas the pixel spacing only applies to specific series and the X/Y/Z position only applies to specific instances.

Outputs estimated by running the model on the inputs may also apply to the entire study or only specific series or instances.

Attributes

---

model (dictionary)

Model information associated with the inference, including its name and version.

Show child attributes

---

model.name (string)

Name of the model.

---

model.version (string)

Version of the model, using semantic versioning.

---

study (dictionary)

Study information associated with the inference, including the date and references to DICOM files.

Show child attributes

---

study.date (string)

Date of the study, in YYYYMMDD format.

---

study.files (array containing dictionaries)

Files belonging to the study, grouped by series in the study.

Each dictionary has 3 attributes:

• study_instance_uid (string): The study instance UID of the study.

• series_instance_uid (string): The series instance UID of the series.

• url (string): The pre-signed URL of the compressed file containing files corresponding to the study and series.

---

inputs (dictionary)

Inputs passed to the model for inference that are derived from the study. Inputs that are too large to be easily serializable (e.g. pixel array) are excluded.

Show child attributes

---

The keys of the dictionary are the names of the inputs.

Since inputs derived from the study correspond to DICOM data elements and a data element's value may apply to the entire study or only specific series or instances, the format of the values of the dictionary varies based on the input:

• The value of an input that applies to an entire study is a dictionary, where the key is the study instance UID of the study and the value is the value of the input.

• The value of an input that applies to specific series is a nested dictionary, where the key is the study instance UID of the study and the value is an inner dictionary, where the keys are the series instance UIDs of the series and the values are the series-specific values of the respective inputs.

• The value of an input that applies to specific instances is a doubly-nested dictionary, where the keys of the inner-most dict are the instance numbers of the instances and the values are the instance-specific values of the respective inputs.

Examples of inputs objects

// Entire study
{
  "$INPUT_NAME": {
    "$STUDY_INSTANCE_UID": $VALUE
  }
}

// Series-specific
{
  "$INPUT_NAME": {
    "$STUDY_INSTANCE_UID": {
      "$SERIES_INSTANCE_UID": $VALUE
    }
  }
}

// Instance-specific
{
  "$INPUT_NAME": {
    "$STUDY_INSTANCE_UID": {
      "$SERIES_INSTANCE_UID": {
        1: $VALUE,
        2: $VALUE,
        ...
      }
    }
  }
}

---

outputs (dictionary)

Outputs estimated by running the model on the inputs for inference.

Show child attributes

---

The keys of the dictionary are the names of the outputs.

Since outputs estimated by a model may apply to the entire study or only specific series or instances, the format of the values of the dictionary varies based on the model and output:

• The value of an output that applies to an entire study is a dictionary, where the key is the study instance UID of the study and the value is the value of the output.

• The value of an output that applies to specific series is a nested dictionary, where the key is the study instance UID of the study and the value is an inner dictionary, where the keys are the series instance UIDs of the series and the values are the series-specific values of the respective outputs.

• The value of an output that applies to specific instances is a doubly-nested dictionary, where the keys of the inner-most dict are the instance numbers of the instances and the values are the instance-specific values of the respective outputs.

Example of outputs objects

// Entire study
{
  "$OUTPUT_NAME": {
    "$STUDY_INSTANCE_UID": $VALUE
  }
}

// Series-specific
{
  "$OUTPUT_NAME": {
    "$STUDY_INSTANCE_UID": {
      "$SERIES_INSTANCE_UID": $VALUE
    }
  }
}

// Instance-specific
{
  "$OUTPUT_NAME": {
    "$STUDY_INSTANCE_UID": {
      "$SERIES_INSTANCE_UID": {
        1: $VALUE,
        2: $VALUE,
        ...
      }
    }
  }
}

---

Example of an Inference object

{
  "model": {
    "name": "predicts_zeros",
    "version": "1.0.0"
  },
  "study": {
    "date": "20230101",
    "files": [
      {
        "study_instance_uid": "$STUDY_INSTANCE_UID",
        "series_instance_uid": "$SERIES_INSTANCE_UID",
        "url": "$PRESIGNED_URL"
      },
      {
        "study_instance_uid": "$STUDY_INSTANCE_UID",
        "series_instance_uid": "$SERIES_INSTANCE_UID",
        "url": "$PRESIGNED_URL"
      }
    ]
  }
  "inputs": {
    "patient_sex": {
      "$STUDY_INSTANCE_UID": "F"
    },
    "pixel_spacing": {
      "$STUDY_INSTANCE_UID": {
        "$SERIES_INSTANCE_UID": [0.5, 0.5]
      }
    },
    "image_position_patient": {
      "$STUDY_INSTANCE_UID": {
        "$SERIES_INSTANCE_UID": {
          1: [0, 0, 0.1],
          2: [0, 0, 0.2],
          3: [0, 0, 0.3],
          ...
        }
      }
    }
  },
  "outputs": {
    "estimated_number": {
      "$STUDY_INSTANCE_UID": 0
    },
    "estimated_string": {
      "$STUDY_INSTANCE_UID": "zero"
    },
    "estimated_segmentation_array": {
      "$STUDY_INSTANCE_UID": {
        "$SERIES_INSTANCE_UID": "$PRESIGNED_URL"
      }
    }
  }
]