[wiki:QdecProject/UseCases top]

Use Case

[http://www.xnat.org/ XNAT] is a sophisticated database access tool allowing query and retrieval of freesurfer processed data. The [http://www.oasis-brains.org OASIS dataset] is one instantiation of XNAT storing freesurfer-processed data. The qdec functionality needs to be integrated into it in the following way:

1. Via the existing XNAT web interface, the user selects a dataset to query. The existing web interface allows selection of subjects and factors of interest. A new option to the interface is the Qdec processing option, which allows selection of a small set of factors (no more than two discrete and two continuous). Once these are selected, the user clicks a 'submit' button, which submits the job to a server (by wrapping the input parameters in an XML file), and the server, having the freesurfer toolset (or at the very least mri_glmfit), performs the GLM fit.
2. Once the server completes the execution of mri_glmfit, the results (found in a /tmp directory on the server), are tarballed in a file with .xar extention. The user is emailed a message that the results are complete.
3. The user, once notified of the results, may download the tarball. They will then need to have a qdec for their particular architecture, which they can download via the XNAT web interface. Qdec will extract the tarball and display the results data.

The freesurfer data should already have been presmoothed at the common smoothing levels, fwhm: 0,5,10,15,20,25.

Architecture

                                               o--------o
                                 +---------+   | Slicer |
     (1)             (2)         |  QDEC   |   o--------o
 o---------o   o-------------o   | Project |  /
 | Website |-->| qdec_glmfit |-->|  file   |-<    (3)
 o---------o   o-------------o   | (.qdec) |  \
                                 +---------+   o--------o
                                               |  qdec  |
                                               o--------o

1. XNAT website
   1. INPUT: User visits XNAT website to select subjects and factors as the input into GLMfit (this is analogous to the current qdec.table.dat file). Additionally, user selects measure, hemisphere and smoothing level to regress (analogous to Qdec's Design panel).
2. qdec_glmfit is on a server with local copies of the average data set and all subjects that might be used in analysis.
   1. INPUT: XNAT calls qdec_glmfit directly and passes average subject to use,the qdec.table.dat file, factors to regress, and other necessary parameters.
   2. OUTPUT: A .qdec file (probably a tarball of data, maybe a .xar file) that contains all the data needed to run a Qdec visualization session, including the average surface configurations, annotation data, contrasts, GDF, and other metadata.
3. Slicer or Qdec can be run locally on a workstation. The user downloads a .qdec file.

   1. INPUT: A .qdec file, which in the case of Qdec is read with File->Load Project File... and instantiates a viewing session. This is basically everything that happens after the user clicks "Analyze" in the current Qdec, without the actual processing.

Tasks

High level

• Move the current dev/qdec/Qdec* code into a new library called libqdecproject. This library will be completely independent of libutils or other FreeSurfer code. libqdecproject will have the new functionality of being able to read and write .qdec files, and using a .qdec file, provide clients access to filenames to all the data needed to run a visualization session in Qdec (or Slicer). qdec_glmfit will use libqdecproject to start a glm fit process from a .glm file and then create a .qdec file, and Qdec and Slicer will use it to get access to data.

• Write qdec_glmfit which creates a QdecProject, takes input from the command line to specify a QdecGlmDesign, tells it to run the fit process, and tells it to write its output to a .qdec file.

• Decide how XNAT will start qdec_glmfit and what parameters it needs to pass on the command line. It needs to generate the qdec.table.dat data. [attachment:qdec.table.txt Here is an example qdec.table.dat file] used by the libqdecproject. While not currently used this way in qdec, the qdec.table.dat can be used by XNAT to implicitly specify the user chosen subjects and factors: the table would merely contain a column containing the selected subject ids, and each additional columns (up to four) would implicitly specify the selected factors. For instance, if the 'age' data is included, then that implies that age is a factor. An additional file would need to specify the surface-based measure data: thickness, area, area.pial, sulc, curv or jacobian_white; hemisphere: rh or lh; and smoothing-level: 0, 5, 10, 15, 20, or 25. Note that surface-based measure data is one type of measure data. In the near future, volume-based measures will be an option. For this XNAT project, it is probably easiest to use the default average subject, 'fsaverage', instead of explicitly allowing its specification.

• Design the .qdec format. This will probably be a tarball containing the necessary average subject data including everything needed by MRISread, the contents of a current Qdec project directory (e.g. subjects/qdec/$ANALYSIS_NAME), and some metadata needed to instantiate a QdecProject. It will be totally portable, without relying on having an existing SUBJECTS_DIR, but will likely require a lot of tmp space into which to expand its data. Documentation here: https://surfer.nmr.mgh.harvard.edu/fswiki/QdecProjectFileFormat

• Qdec will use libqdecproject to read a .qdec file and access the data with functions like QdecProject::GetAverageSubjectFileName, which it can then pass into its libutils based IO functions and dispaly normally. Slicer will also be able to link in libqdecproject (as it will be independent from libutils) and use its own Freesurfer file format readers.

• We may also write a converter for legacy Qdec data, with a small interface for entering the average subject location and qdec project data directory, and will create a .qdec file.

Breakdown

1. Factor out Qdec* code into libqdecproject

   1. Kevin: Move all Qdec* code into a new library, make it compile. Have Qdec link in the library, and make sure Qdec still works normally. libqdecproject should also be able to compile on its own with no libutils code. DONE

2. Add functionality to libqdecproject to read and write .qdec files.

   1. Kevin: Determine what needs to go into the .qdec file type. Should include average subject data, analyzed data, and metadata needed to instantiate QdecProject and other internal objects. DONE

   2. Kevin with input from Nick: Write .qdec file type. It should contain all data in a single file, so that reading one doesn't depend on any local data. It should be versioned. This can be a tarball with some kind of internal info file, or .xar, whichever is appropriate. DONE

   3. Kevin: Document the .qdec file type with an example file. DONE https://surfer.nmr.mgh.harvard.edu/fswiki/QdecProjectFileFormat

   4. Kevin: Add QdecProject:{Read,Write}ProjectFile() functions to QdecProject to read and write .qdec files. DONE

3. Write qdec_glmfit to to use libqdecproject to take a .glm file as input and make a .qdec file as output.

   1. Kevin: Write qdec_glmfit to take all input params needed to start a QdecGlmDesign. DONE

   2. Kevin: Start the fitting process and save out to a .qdec file. DONE

   3. Kevin: Document qdec_glmfit. DONE https://surfer.nmr.mgh.harvard.edu/fswiki/qdec_5fglmfit

4. Modify qdec to use libqdecproject to read a .qdec file and visualize the data.

   1. Kevin: Add File1->{Load,Save} Project File... menu options to Qdec, which will call the corresponding QdecProject functions and instantiate a QdecProject without having to run Analyze first. DONE

   2. Kevin: Qdec should be able to still start an analysis from scratch, and then save a project file, as a testing point. Then you can restart Qdec and load in the project file and see if everything is correct. DONE

5. Modify XNAT so that it generates a qdec.table.dat .

   1. XNAT: Website needs to generate qdec.table.dat from user input.

6. Hook together XNAT, qdec_glmfit, and qdec.

   1. XNAT: XNAT needs to generate the qdec.table.dat and call qdec_glmfit, passing in the correct parameters.

   2. XNAT: XNAT makes results (.qdec file) available to user for download.