Using the XNAT API: How to Configure Scan Quality Labels

Contents

Each scan data type (MR scan, CT scan, etc.) includes a quality label. By default, the scan quality can be set to usable, questionable, or unusable, but the set of scan quality labels can be customized. This demo uses the Legacy XNAT Site Configuration API and the Project Configuration API. Each API call demonstrated is performed in the Terminal using curl, where {username:password} should be replaced with a valid login or user alias token (see the User Alias Token API) and https://my.xnat.org/ should be replaced with the root path to your XNAT webapp.

Get The Current Site-wide Scan Quality Label Definitions

To start out, see what scan quality labels have been defined in your site.

CODE

$ curl -X GET -u {username:password} https://my.xnat.org/data/config/scan-quality/labels

If your XNAT has never been modified, this call will return the following object. Note that the "contents" parameter contains a comma-separated string that lists the labels themselves.

CODE

{
  "ResultSet": {
    "Result": [
      {
        "contents": "usable, questionable, unusable",
        "create_date": "2018-01-02 17:39:14.675",
        "path": "labels",
        "project": "",
        "reason": "Set default scan quality labels configuration",
        "status": "enabled",
        "tool": "scan-quality",
        "unversioned": "true",
        "user": "admin",
        "version": "1"
      }
    ]
  }
}

You can also look and see if a set of scan quality labels has been defined in your project.

CODE

$ curl -X GET -u {username:password} https://my.xnat.org/data/projects/{project-id}/config/scan-quality/labels

However, if no custom scan type label setting has ever been set for this project, a call to the tool-specific config will return a 404 response code like the following:

TEXT

Couldn't find config for user {username} and project {project-id} on tool [scan-quality] path [labels]

Define Custom Scan Quality Labels For Your Site

1. Create a plain text file containing the custom scan quality labels, separated by commas. Let's call it scan-quality-labels.txt. For example:

CODE

dunno,great,fine,meh,ugh

The first label is the default value, so if your custom labels include "undefined" or an equivalent, that should probably come first.

2. Upload the quality labels file to the scan-quality XNAT configuration service:

CODE

$ curl -X PUT -u {username:password} https://my.xnat.org/data/config/scan-quality/labels?inbody=true --data-binary @scan-quality-labels.txt

Define Custom Scan Quality Labels For A Specific Project

Custom scan quality labels can also be defined for an individual project. Project-specific config settings will supersede site-wide config settings for a given tool.

CODE

$ curl -X PUT -u {username:password} https://my.xnat.org/data/projects/MyProject/config/scan-quality/labels?inbody=true --data-binary @scan-quality-labels.txt

Once this configuration is set, you can set these scan labels in any given Edit Image Session page, or through a quality assessment.

Developer Tip: Modifying Scan Quality Listing Appearance

Each scan quality label is reflected in image session scan listings, and also generates a named CSS class for that listing's surrounding table cell. For example, the scan label "great" will be enclosed within a <td class="quality-great"> tag.

If you want the custom scan quality labels to appear in colors (as the default usable, questionable, and unusable appear in green, orange, and red), modify the default XNAT stylesheet located at {XNAT_HOME}/style/app.css.

This will only work if your scan quality label generates a valid CSS identifier. You should only use alphanumeric characters, dashes and underscores in your label names.

CODE

/* XNAT defaults */
td.quality-usable {
  color:green;font-weight:700
}
td.quality-questionable {
  color:orange;font-weight:700
}
td.quality-unusable {
  color:red;font-weight:700
}

/* My custom labels */
td.quality-great {
  color:green; font-weight: 700
}
td.quality-fine {
...