Image Assessor API

Related

Experiment Assessors such as a Manual QC performed on an Image Session are also experiments in their own right. As such, the Experiment API applies in many cases to assessors as well. In fact, assessors show up alongside other image sessions and experiments in a "Get All Experiments" API call. However, there are custom API calls related to managing an assessor in relationship to the image session it relates to. There are also custom behaviors as related to assessors that result from pipeline executions.

In nearly all cases, experiment assessors are created in relation to an Image Session. Hence, this documentation refers to them as "Image Assessors".

Get All Assessors Associated With An Image Session

This API call is essentially a search of one or more data types, and is formatted to return a table of results.

CODE

GET - /data/experiments/{session-id}/assessors
GET - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{session-id | session-label}/assessors

Parameters

{session-id} or {session-label}	Required path parameter. session-label is a project-specific field and can only be used if project-id is also specified
{subject-id} or {subject-label}	Optional (but common) path parameter. subject-label is a project-specific field and can only be used if project-id is also specified
{project-id}	Optional (but common) path parameter
format	Optional querystring parameter json (default) html xml csv
columns	Optional querystring parameter, specifying specific columns via Experiment Data REST XML Path Shortcuts. Always included: ID URI Included by default if no columns are specified: date insert_date label project session_ID session_label xnat:imageassessordata/id xsiType
date	Optional querystring parameter – can be used to restrict the search to a single date or a date range. The date must be formatted as MM/DD/YYYY. Example: `?date=01/01/2017` `?date=01/01/2017-01/01/2018`
{param}	Optional querystring parameter – can be used to restrict the search by any string parameter listed in Image Assessor Data REST XML Path Shortcuts, using a wildcard string search. Example: `?xsiType=xnat:qcManualAssessor` `?ID=XNAT_E0001` `?label=GSU001_v*_mr`

Response

CODE

{
  "ResultSet": {
    "Result": [
      {
        "date": "date",
        "insert_date": "datetime",
        "ID": "string {assessor-id}",
        "label": "string {assessor-label}",
        "project": "string",
        "session_ID": "string {session-id}",
        "session_label": "string {session-label}",
        "URI": "/data/experiments/{assessor-id}"
        "xnat:imageassessordata/id": "string {assessor-id}",
        "xsiType": "xsiType",
      },
      ...
    ],
    "totalRecords": "integer"
  }
}

Get A Specific Assessor Associated With An Image Session

This API call returns a much more detailed experiment record, including child data that is owned by the experiment, including scans and assessors

CODE

GET - /data/experiments/{session-id}/assessors/{assessor-id}
GET - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{session-id | session-label}/assessors/{assessor-id | assessor-label}

Parameters

{assessor-id} or {assessor-label}	Required path parameter. assessor-label is a project-specific field and can only be used if project-id is also specified
{session-id} or {session-label}	Required path parameter. session-label is a project-specific field and can only be used if project-id is also specified
{subject-id} or {subject-label}	Optional (but common) path parameter. subject-label is a project-specific field and can only be used if project-id is also specified
{project-id}	Optional (but common) path parameter
format	Optional querystring parameter html (default) xml json csv

Response

Each assessor's data response will have a unique set of parameters. Here is an example Manual QC, represented in JSON. A QC is performed on one or more scans of the parent image session, hence the assessor object also contains a "scans/scan" object. Note that there is a "Pass" parameter for each scan, and another "Pass" parameter for the overall assessor.

CODE

{
  "items": [
    {
      "children": [
        {
          "field": "sharing/share",
          "items": [ ... ]
        },
        {
          "field": "scans/scan",
          "items": [
            {
              "children": [],
              "data_fields": {
                "coverage": "0",
                "imageScan_ID": "6",
                "motion": "0",
                "otherImageArtifacts": "0",
                "pass": "1",
                "xnat_qcScanData_id": 3
              },
              "meta": {
                "create_event_id": 325,
                "isHistory": false,
                "start_date": "Thu Jan 04 16:20:30 UTC 2018",
                "xsi:type": "xnat:qcScanData"
              }
            },
            ...
          ]
        }
      ],
      "data_fields": {
        "comments": "Performed at 06:30 AM.",
        "date": "2017-01-01",
        "id": "XNAT_E00033",
        "ID": "XNAT_E00033",
        "incidentalFindings": "Subject appears to be mostly healthy overall, although some spots in\n\n        the right frontal lobe are slightly concerning.",
        "imageSession_ID": "XNAT_E00032",
        "label": "RIQ_AA_MR1_QC_2017_01_01",
        "pass": "1",
        "payable": "1",
        "project": "QC_Review",
        "rater": "Will Horton",
        "rescan": "0",
        "stereotacticMarker": "0"
      },
      "meta": {
        "create_event_id": 325,
        "isHistory": false,
        "start_date": "Thu Jan 04 16:20:30 UTC 2018",
        "xsi:type": "xnat:qcManualAssessorData"
      }
    }
  ]
}

Upload A New Image Assessor

The most reliable method for creating new assessors via the API is to upload an XML definition file via a POST.

CODE

POST - /data/experiments/{session-id}/assessors
POST - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{session-id | session-label}/assessors

Parameters

{session-id} or {session-label}	Required path parameter session-label is a project-specific field and can only be used if project-id is also specified
{subject-id} or {subject-label}	Optional (but common) path parameter. subject-label is a project-specific field and can only be used if project-id is also specified
{project-id}	Optional (but common) path parameter
file	Required file to be submitted in the body of the request. XML is the most reliable format.
inbody=true	Optional querystring parameter. Use if the file is being submitted in the body of the request, rather than as part of multi-part form data.

Response Codes

201	Created
403	Permission Denied – User does not have permission to create data in this project
404	Not Found – Project ID not recognized
417	Expectation Failed – No xsiType parameter was specified, XNAT cannot parse the assessor data
422	Unprocessable Entity – Unknown xsiType parameter was specified, XNAT cannot parse the assessor data

Response Format

On 201 - Success, the response is a simple string of the new experiment's accession ID. For example:

CODE

XNAT_E00057

Modify An Existing Image Assessor

It is possible to modify select experiment metadata by performing a PUT to this URI without a file attached, by specifying Image Assessor Data REST XML Path Shortcuts as params. However, there are so few of these fields that can be modified in this manner that a more reliable method is to simply PUT a new XML definition file in place of the original.

CODE

PUT - /data/experiments/{session-id}/assessors/{assessor-id}
PUT - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{session-id | session-label}/assessors/{assessor-id | assessor-label}

Parameters

{assessor-id} or {assessor-label}	Required path parameter assessor-label is a project-specific field and can only be used if project-id is also specified
{session-id} or {session-label}	Required path parameter session-label is a project-specific field and can only be used if project-id is also specified
{subject-id} or {subject-label}	Optional (but common) path parameter. subject-label is a project-specific field and can only be used if project-id is also specified
{project-id}	Optional (but common) path parameter
file	Required file to be submitted in the body of the request. XML is the most reliable format.
inbody=true	Optional querystring parameter. Use if the file is being submitted in the body of the request, rather than as part of multi-part form data.

Sharing Image Assessors into a new project does not have much effect unless you share the subject record as well. See Subject Sharing API.

Share An Image Assessor Into A New Project

CODE

PUT - /data/projects/{original-project-id}/subjects/{subject-id}/experiments/{session-id}/assessors/{assessor-id}/projects/{shared-project-id}

Parameters

{original-project-id}	Required path parameter. Specify the ID of the project that owns a given image assessor.
{subject-id} or {subject-label}	Required path parameter.
{experiment-id} or {experiment-label}	Required path parameter.
{assessor-id} or {assessor-label}	Required path parameter.
{shared-project-id}	Required path parameter. Specify the ID of the project that you intend a subject to be shared into. Logged-in user must have ownership permissions in the shared project.
label	Optional querystring parameter. Specify a new label for this assessor that will be used in the shared project, if desired.
primary	Optional querystring parameter. If set to "true", you are changing the primary ownership of the assessor from the original project to the new project. Logged-in user must have ownership permissions in both projects to change the primary ownership.

Response Codes

200	OK
403	Forbidden (User does not have permission to perform the requested operation)
404	Project Not Found
409	Conflict Found – Attempting to share data into an object that already exists

Response Format

Returns the assessor's experiment accession ID as a string

Get A List Of Shared Projects Associated With An Image Assessor

CODE

GET - /data/projects/{original-project-id}/subjects/{subject-id}/experiments/{session-id}/assessors/{assessor-id}/projects

Parameters

{original-project-id}	Required path parameter. Specify the ID of the project that owns a given image assessor.
{subject-id} or {subject-label}	Required path parameter.
{session-id} or {session-label}	Required path parameter.
{assessor-id} or {assessor-label}	Required path parameter.
format	Optional querystring parameter. Specify the format of the returned response. html (default) json xml csv

Response

Displaying JSON results. Note that the response does not specify which project owns an experiment

CODE

{
  "ResultSet": {
    "Result": [
      {
        "label": "string",
        "ID": "string",
        "Secondary_ID": "string",
        "Name": "string"
      },
      ...
    ]
  }
}

Delete (Or Unshare) An Image Assessor

Performing this call in a project that owns an image assessor record will permanently delete the experiment data from your project and your XNAT archive.

Performing this call in a project that this assessor has been shared into will simply delete the sharing relationship – no data will be deleted from your XNAT archive, it will simply be removed from this project.

CODE

DELETE - /data/experiments/{session-id}/assessors/{assessor-id}
DELETE - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{session-id | session-label}/assessors/{assessor-id | assessor-label}

Parameters

{assessor-id} or {assessor-label}	Required path parameter assessor-label is a project-specific field and can only be used if project-id is also specified
{session-id} or {session-label}	Required path parameter session-label is a project-specific field and can only be used if project-id is also specified
{subject-id} or {subject-label}	Optional (but common) path parameter. subject-label is a project-specific field and can only be used if project-id is also specified
{project-id}	Optional (but common) path parameter