====== importrfxglmfromspms ======

===== Motivation =====
With SPM being one of the tools I found most frequently used as a neuroimaging analysis tool, NeuroElf offers a way to import an existing line of analysis (models and results of single subject, first-level regressions) into the format used by both BrainVoyager QX and NeuroElf to simplify data extraction and visualization.

===== Requirements =====
To be able to use this functionality, you should have concluded the first-level modeling stage of your study, so that for each subject you have

  * an identical sub-folder structure (to simplify lookup of  files)
  * one folder containing an SPM.mat file with the accompanying beta_XXXX.hdr/img files, whereas
    * identical conditions have the same name across sessions and subjects
    * the order of conditions may vary across sessions and subjects
  * optionally the preprocessed (referenced) data available (in case you would like to import these as well)
  * depending on whether or not you wish to also import the functional (timecourse) data, enough free disk space

===== Function reference ('help importrfxglmfromspms') =====
<file>  importrfxglmfromspms  - import SPM beta maps to a BrainVoyager GLM file
 
  FORMAT:       glm = importrfxglmfromspms(spms, opts)
 
  Input fields:
 
        spms        list of SPM.mat filenames to use for import
        opts        options for the import
         .bbox      bounding box to use (in BVS notation)
         .cond      1xC structure with fields (default: auto detect)
          .bvname   condition name for the BV file
          .color    1x3 RGB color for condition
          .spmname  SPM based name (or pattern)
         .filename  output GLM filename (otherwise unsaved)
         .imeth     interpolation 'cubic', 'lanczos3', {'linear'}, 'nearest'
         .impvtc    pattern for VTCs (default: '', e.g. '#_run%02d.vtc')
         .mmaskfac  mean-masking factor, default 0.5
                    results in masking out voxels where constant < 0.25
                    of its mean overall value (per subject)
         .pbar      either xprogress or xfigure:XProgress object
         .res       resolution (default: floor of SPM resolution)
         .subjids   subject identifiers (default: auto detect)
         .trans     either {'none'}, 'psc'
                    PSC-transform uses estimated mean (constant) as 100!
         .vweight   variance-based weighting (false, uses SPM.xX.Bcov)
 
  Output fields:
 
        glm         GLM object (saved if .filename is given)
 
  Note: if VTC import is desired, the VTC filename pattern (.impvtc)
        must contain one or two occurrences of the hash mark (which will be
        replaced by the subject ID) and one occurrence %d or %XXd for the
        Sess number; other arguments (bbox, imeth, res) will be passed on</file>

==== Notes ====
Preferably, the ''spms'' argument should contain absolute pathnames.

===== Options =====

==== .bbox ====
The bounding box must be given in BrainVoyager notation, so that the three dimensions have values between 0 and 256, the axes order is the same as with the Talairach/MNI convention, but the direction of each axis is reversed when compared to Talairach/MNI notation. If left empty, this will be automatically determined.

==== .cond ====
A multi-element struct with fields ''bvname'' (target name appearing in the output GLM), ''color'' (RGB color used for beta/time-course plotting UIs), and ''spmname'' (source regressor name as it appears in the SPM.xX.name field) identifying the conditions to import into the GLM. If left empty, all conditions will be automatically selected in the order in which they appear in the first SPM.mat file.

==== .filename ====
If given the resulting GLM file will be saved under this filename. Additionally, a relative path in the ''.impvtc'' option will be prepended with any absolute path in this field.

==== .imeth ====
Interpolation method; determines the amount of additional smoothing that occurs when importing the data. For unsmoothed (or very little smoothed) data, a larger interpolation kernel (either cubic or lanczos3, which is sinc with a window size of 3) is suggested; otherwise linear interpolation should be sufficient.

==== .impvtc ====
If given must contain at least one hash mark (''#''), which will be replaced with the subject identifier, as well as one format suitable for ''sprintf'' to add the session number into the filename. The subject identifier (hash mark) may occur multiple times, which can be used to store output files into separate folders for different subjects.

==== .mmaskfac ====
Mean-based masking factor. All voxels for which the mean (average beta estimate for the all-1 regressors) is lower than this fraction of the global mean thereof will be set to 0; this works as a post-hoc relative global signal intensity mask. The default value is set to 0.25.

==== .pbar ====
In case you wish to call this from a script or to integrate into a UI, a progress bar object can be passed into the function.

==== .res ====
VTC/GLM resolution (supported values: 1, 2, or 3). The default is to auto-detect the resolution from the data (avoiding further smoothing and/or information loss).

==== .subjids ====
List of subject identifiers, must be the same size as the ''spms'' argument and contain one unique string per subject. If left empty, an auto-detection is attempted.

==== .trans ====
If set to '''psc''' the function will scale each beta by the term ''(100 / All_1s_beta)'' for each session, which is virtually identical with a percent change transformation on time-courses.

==== .vweight ====
If set to ''true'' the sum of betas coming from the same condition but across different sessions of the same subject will be weighted by the square root of the inverse of the corresponding value in the inverse design matrix (found in SPM.xX.Bcov), which is an estimate for the variance produced by a regressor (after filtering). Otherwise (which is the default), betas of the same condition across sessions will be added and divided by the number of betas for that condition (unweighted mean).

===== UI-based mode =====
Next to a command-line- or scripting-only mode, this function comes with its own UI to allow flexible configuration of the settings:

{{:neuroelf_gui:importrfxglmfromspms_gui.png|importrfxglmfromspms UI}}

To invoke this mode, the first argument must be the string '''ui''':

<code matlab importrfxglmfromspms_uimode.m>% use UI mode for GLM import
glm = importrfxglmfromspms('ui');</code>

==== Step-by-step instructions ====
This list of instructions is meant to cover the majority of cases, but **certain conditions, such as multiple groups in completely different locations or different sub-folder depths, might make it necessary to import several separate GLMs which can be combined later, given that the number and names of conditions across subjects match!**

  - use the Browse button to locate one of the SPM.mat files used for the import; importantly this file must be prototypical for the other files w.r.t. the condition names!
  - adapt the search pattern box (containing the single filename of the selected SPM.mat file) to reflect a generic template to locate several SPM.mat files (e.g. by replacing the subject identification part in the path by an asterisk)
  - click the search button (this might take between a few seconds and several minutes, depending on the complexity of the search request)
  - make sure that the detected subject identifiers (top left listbox) are useful (unique and allow back-referencing to other data of the subject, e.g. behavioral measures, etc.) and, if not so yet, anonymous!
    - selecting a single entry followed by a click on the ''properties'' button (third button from the top next to the top right listbox) allows to rename a subject identifier
    - selecting multiple entries followed by a click on the ''properties'' button allows to apply a search-and-replace (regular expression) operation to the selected identifiers
  - if required, remove unwanted items from the list using the ''minus'' button (last button next to the top right listbox)
  - if the search pattern didn't locate all SPM.mat files, additional items can be added using the ''plus'' button (second-to-last button next to the top right listbox)
  - if required, re-sort the list by selecting entries and using the ''move-up'' and ''move-down'' buttons (first and second button from the top next to the top right listbox)
  - in case all conditions are to be imported with their names as found in the SPM.xX.name array, the auto-detect condition names checkbox can remain enabled
  - otherwise, disable the auto-detect condition names checkbox (first checkbox below the condition names listboxes) then
    - remove conditions that are not to be imported into the GLM (confounds, conditions of no interest, etc.)
    - comparable to the subject identifier list, rename single conditions (single selection) or apply a search-and-replace operation (multiple selection) to the condition names for the output using the ''properties'' button
    - re-set the (randomly assigned!) colors by clicking the ''colorpicker'' button (this opens the [[colorpicker]] tool for all configured conditions)
    - re-order the conditions to reflect the desired order using the ''move-up'' and ''move-down'' buttons after selecting the desired items to move
  - configure the percent change setting to your liking (UI default is to use the transform, see ''.trans'' option)
  - configure the variance-estimate based weighting setting to your liking (UI default is to use this weighting, see ''.vweight'' option)
  - set the desired interpolation quality (default is linear, see ''.imeth'' option)
  - to override the automatically defined bounding box and resolution, uncheck the auto-detection for bounding-box and resolution box
    - if so, set the resolution and bounding box (see ''.bbox'' and ''.res'' options)
  - in case you wish to automatically save the resulting GLM, either manually edit the target filename field or click the Save-As-button to select a folder and filename
  - to enable the side-by-side import of VTC, PRT, and SDM files from the referenced data and SPM.mat files, check the data-import box at the bottom of the dialog
    - in which case you should ensure that the output filename pattern is valid
  - click on ''Import...''

Should an unrecoverable error occur (e.g. an SPM.mat file is not found or invalid), you will be notified.

===== Usage notes =====
In case you select the import-VTC feature, the GLM file will contain references to the newly created files, which will allow to inspect time courses quickly from the [[NeuroElf GUI|NeuroElf main UI]]. Also, this allows to easily create an MDM file by using the ''GLM::CreateMDM'' function.

The VTC import feature is "tried" (using error handling) for each session separately, and if the import fails on one session (corrupt or missing file, etc.), this study will not be added to the GLM at the end, but this does not lead to an unrecoverable error!