[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)       | GLMFit |         (2)         |  QDEC   |   o--------o
 o---------o   | input  |   o-------------o   | Project |  /
 | Website |-->|  file  |-->| qdec_glmfit |-->|  file   |-<    (3)
 o---------o   | (.glm) |   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. OUTPUT: A .glm file (probably a .xml file) containing all the data needed to generate a traditional command line to run mri_glmfit.
  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: A .glm file, which can be read by qdec_glmfit and provides the same information as a traditional mri_glmfit command line, including which average subject to use, which subjects to use, the qdec.table.dat file, and the factors to regress.
    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

   My_Project.qdec -> My_Project/fsaverage/surf/{l,r}h.{inflated,white,pial}
                                          /label/*.annot
                                          /mri/orig.mgz
                                          /mri/transforms/talairach.mgz
                                /qdec_project/*
                                /QdecProjectData.txt

(The orig.mgz and talairach.mgz files are necessary for MRISread, and there may be other files needed by it as well. MRISread expects certain files to be available from which to extract metadata. Slicer will probably not use this extra information and can safely ignore it.)

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 a .glm file.
    1. Kevin: Determine what information mri_glmfit needs to run, assuming all data is still local.

    2. Nick: Determine if XML or .xar is appropriate for .glm format, and how to represent that information in the file type. Keep in mind XNAT will have to generate this file type without the use of libqdecproject.

    3. Kevin: Write .glm file type. Modify libqdecproject to take this file type as input to instantiate a QdecGlmDesign object, same as its current Create() function.

    4. Kevin: Document .glm file type with an example file.

  3. 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

  4. 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 an input file and use it with QdecProject to run the glm process.

    2. Kevin: Document qdec_glmfit.

  5. 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

  6. Modify XNAT so that it generates a .glm file.
    1. Nick: Website needs to generate the file from user input.

  7. Hook together XNAT, qdec_glmfit, and qdec.
    1. Nick: Website needs to transfer file to qdec_glmfit on its own server.

    2. Nick: qdec_glmfit needs to start and use that file. How is it notified?

    3. Nick: qdec_glmfit should have some way of notifying the user or website that the processing is done and the project file is ready for download.