Page tree
Skip to end of metadata
Go to start of metadata


Introduction

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.

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

{
  "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

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.

 Show JSON Response Object
{
  "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.

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
fileRequired file to be submitted in the body of the request. XML is the most reliable format.
inbody=trueOptional 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

201Created
403Permission Denied – User does not have permission to create data in this project
404Not Found – Project ID not recognized
417Expectation Failed – No xsiType parameter was specified, XNAT cannot parse the assessor data
422Unprocessable 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:

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.

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
fileRequired file to be submitted in the body of the request. XML is the most reliable format.
inbody=trueOptional 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

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.

labelOptional 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

200OK
403Forbidden (User does not have permission to perform the requested operation)
404Project Not Found
409Conflict 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

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

{
  "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.

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
  • No labels