How To’s

Developing and installing a task session

Let’s consider a relatively simple application, as an example to give more insight in the workflow of the Task Manager. Suppose you want to assign the task to a group of users to carry out a few measurements in an MR sequence of the brain. And suppose that these measurements can be done by indicating a set of anatomical landmarks in the MR data. The 3D coordinates of these landmarks can then be used afterwards to calculate some anatomical distances in the brain. Let’s consider that these measurements should be carried out in a cohort of 1000 patients. This measurement application can be realized with (for example) the following steps:

1. Add the group of users to the selected Taskmanager.

This means that the group should be defined in the Task Manager (if it is not there already), the users should be defined (if they are not there already), and these specific users should be added to (become a member of) the group just created/defined.

Adding a new group and new users is done using the REST API. To add a user, click on POST   /users. You will see an example of the input object:

{
  "username": "string",
  "name": "string",
  "active": true,
  "email": "string",
  "password": "string",
  "assignment_weight": 0
}

Click on “Try it out”. After that you can edit the six fields shown above. Fill in the username, name (real name of the person, the email address, some password, and the assignment_weight. The assignement weight is an indication of how many tasks (of the total number available) will be shown to this user. If the assignment_weight is 0, no task will be assigned to that specific user. If the assignment_weight equals 1, all tasks will be assigned (shown) to that user. If the user is a group member and the tasks are assigned to the group, also other users can pick up the task. If the assignment_weight is for example 0.1, only 10 percent of the uploaded tasks (assigned to the group) will be shown to this specific user. If a user is inactive (active == false), he or she is currently not involved in carrying out tasks. After filling in all the desired in a correct way, click on ‘execute’. Repeat this procedure for every new user you want to add.

To define a new group, click on ‘POST group’. You will see the following example model:

{
  "groupname": "string",
  "name": "string"
}

Fill in (edit) the “groupname” (used as referring ‘id’) and also give a more descriptive “name” in the second field. The click on execute. Now you are at the fase of making the new users a member of the group. At the moment this is not yet possible with the REST API. It should be done from ipython or by executing python scripts directly on the database.

Note

Adding a user to a group (make him/her a group member) is currently not yet possible with the REST API. For now it should done directly from the ipython command line or by python scripts.

2. Write the task_template

Writing a JSON file with the ‘description/definition’ of the Task Manager task_template, needed to give the ViewR the optimal appearance in which the desired measurements can be carried out.

Details on how to write a viewr task template can be found at ViewR template documentation.

3. Upload the task_template to the Task Manager

This means adding the template, mentioned/written in step 2 to the collection of templates known by (stored in) the Task Manager. This can be done using the REST API, but it is more convenient to use another approach, namely the Task Manager command line scripts mentioned before. If you use the API you have to click on ‘POST /task_templates’. You will see a model like this:

{
  "label": "string",
  "content": {}
}

You have to fill in the label. That’s just the name of the task_template that will be used as a kind of referred name/id. The contents should be the complete template (JSON) as shown in step 2. It is more convenient to put this contents into a JSON file, and upload the file with command line scripts (executables). For more details see the section Task Manager commands from the command line.

4. Write the specific task needed

This means writing a JSON file with the overall ‘description/definition’ of the task to be carried out by the users. This task has to be linked to the desired template. In general a ‘task’ is less complex than a ‘template’ to write. An important issue to pay attention to is that the task should be linked to a template. This doesn’t mean only that the name of the task_template that should be used for this task should be filled in to the model (JSON file), but also that specific field in the task and task_template should be coherent and consistently linked to each other. More details will follow using the next example.

In this (example) case, the task could look this:

{
    "scan_sources": {
        "T1":"http://10.20:30:40/data/experiments/E1234/scans/T1W/resources/NIFTI/files/T1W.nii.gz"
    },
    "_vars": {
        "SYSTEM_URL": "http://10.20:3:4",
        "EXPERIMENT_ID": "E1234",
        "LABEL": "L100"
    },
    "name": "L100 pinealis",
    "fields": {},
    "template": "glandula_pinealis",
    "fields_file": "http://10.20:3:4/data/experiments/E1234/resources/FIELDS/files/out{timestamp}.json",
    "windowing": {
    "width": 50.0,
    "center": 100.0
    }
}

Important in this task example is the definition of the scan_sources. In this example only one MR sequence will be used and shown in the ViewR during execution of the task. The MR sequence is a T1-weighted scan. The URL after T1: points to the location on a specific XNAT host where the input data (T1) for this task can be retrieved.

If you look at the template definition above, you will see that there is a field scans. Also there is only 1 sequence defined, a T1. The protocol and modality are additional info.

Note

Keep in mind the name(s) of the input scan(s), in this case T1 should be equal (consistent) in both the task.json and the template.json! If not the task will not run properly when loaded in the ViewR

5. Upload the tasks to the Task Manager

This means that for every dataset, specific MR sequence present in the cohort of 1000 patients, a task should be defined and uploaded to the Task Manager. This can almost be done using the REST API. With the REST API you have to post all 1000 tasks (one measurement task per data set) one by one. It is therefore more convenient to use the Task Manager command line scripts.

6. Apply the measurements

This means: start the ViewR (as one of the users) and connect it to the Task Manager containing the info generated in step 1 to 5. This will be described in more detail in the following section.

Items to be discussed

  • Roles and privileges (at least user and admin)

  • Description of the model Task

  • How to create a Task

  • How to assign a Task to a user

  • How to upload a Task to the Task Manager

  • How to link a Task with a Template

  • Status of a Task (queued, locked, done, etc)

  • Relation ViewR, Task Manager, XNAT

  • How to deal with Tasks in de ViewR

  • TaskGroups, TaskTemplates, TaskTags

  • Creating a group and/or adding a user to the groep is still difficult.

  • Relation taskmodel with usermodel

  • Usergroups

  • Assignment weights

  • Installation of the Task Manager? With a VirtualEnv? Or is that not needed?

  • REST-API! … Flask … What can you post put get delete etc.

  • How to connect the viewer to a specific Task Manager

  • Callback to the Syncotron.

  • With PUT you can change particular contents of tasks

  • With status you can make a task done (REST API)

  • Exploring the contents of the Taskmanager

  • Roles! What can a user do … and what can admin do … and intermediate … superuser