Differences between revisions 17 and 18
Deletions are marked like this. Additions are marked like this.
Line 40: Line 40:
Design the .glm format. This is probably going to be .xml formatted output from XNAT, but it needs to contain the qdec.table.dat data as well as other inputs needed for mri_glmfit. [attachment:qdec.table.dat Here is an example qdec.table.dat file] used by the qdec app. The qdec.table.dat can also Design the .glm format. This is probably going to be .xml formatted output from XNAT, but it needs to contain the qdec.table.dat data as well as other inputs needed for mri_glmfit. [attachment:qdec.table.txt Here is an example qdec.table.dat file] used by the qdec app. The qdec.table.dat can also

[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 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

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.

Design the .glm format. This is probably going to be .xml formatted output from XNAT, but it needs to contain the qdec.table.dat data as well as other inputs needed for mri_glmfit. [attachment:qdec.table.txt Here is an example qdec.table.dat file] used by the qdec app. The qdec.table.dat can also

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. This will probably look like:

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

Write qdec_glmfit which creates a QdecProject, tells it to read a .glm file, tells it to run the fit process, and tells it to write its output to a .qdec file.

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.

Decide how the .glm file will get from the website to the qdec_glmfit server and how the qdec_glmfit process will find and use that file. Decide how the user will be notified of when their output data is ready.

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

    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.

    3. Kevin: Document the .qdec file type with an example file.

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

  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.

    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.

  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.

QdecProject/Xnat (last edited 2008-05-07 16:45:14 by NickSchmansky)