importrfxglmfromspms
Differences
This shows you the differences between two versions of the page.
Next revisionBoth sides next revision | |||
importrfxglmfromspms [2011/04/13 20:01] – created (screenshot only) jochen | importrfxglmfromspms [2011/04/13 22:57] – added text jochen | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== importrfxglmfromspms ====== | ====== 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, | ||
+ | |||
+ | * an identical sub-folder structure (to simplify lookup of files) | ||
+ | * one folder containing an SPM.mat file with the accompanying beta_XXXX.hdr/ | ||
+ | * equal 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' | ||
+ | < | ||
+ | |||
+ | FORMAT: | ||
+ | |||
+ | Input fields: | ||
+ | |||
+ | spms list of SPM.mat filenames to use for import | ||
+ | opts options for the import | ||
+ | | ||
+ | | ||
+ | .bvname | ||
+ | .color | ||
+ | .spmname | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | results in masking out voxels where constant < 0.25 | ||
+ | of its mean overall value (per subject) | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | PSC-transform uses estimated mean (constant) as 100! | ||
+ | | ||
+ | |||
+ | 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</ | ||
+ | |||
+ | ==== Notes ==== | ||
+ | Preferably, the '' | ||
+ | |||
+ | ===== 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/ | ||
+ | |||
+ | ==== .cond ==== | ||
+ | A multi-element struct with fields '' | ||
+ | |||
+ | ==== .filename ==== | ||
+ | If given the resulting GLM file will be saved under this filename. Additionally, | ||
+ | |||
+ | ==== .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 (''#'' | ||
+ | |||
+ | ==== .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, | ||
+ | |||
+ | ==== .trans ==== | ||
+ | If set to ''' | ||
+ | |||
+ | ==== .vweight ==== | ||
+ | If set to '' | ||
+ | |||
+ | ===== 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: | ||
+ | |||
+ | {{: | ||
+ | |||
+ | To invoke this mode, the first argument must be the string ''' | ||
+ | |||
+ | <code matlab importrfxglmfromspms_uimode.m> | ||
+ | glm = importrfxglmfromspms(' | ||
+ | |||
+ | ==== 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 and, if not so yet, anonymous | ||
+ | - selecting a single entry followed by a click on the '' | ||
+ | - selecting multiple entries followed by a click on the '' | ||
+ | - if required, remove unwanted items from the list using the '' | ||
+ | - if the search pattern didn't locate all SPM.mat files, additional items can be added using the '' | ||
+ | - if required, re-sort the list by selecting entries and using the '' | ||
+ | - 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 '' | ||
+ | - re-set the (randomly assigned!) colors by clicking the '' | ||
+ | - re-order the conditions to reflect the desired order using the '' | ||
+ | - configure the percent change setting to your liking (UI default is to use the transform, see '' | ||
+ | - configure the variance-estimate based weighting setting to your liking (UI default is to use this weighting, see '' | ||
+ | - set the desired interpolation quality (default is linear, see '' | ||
+ | - 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 '' | ||
+ | - 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 '' | ||
+ | |||
+ | 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 '' | ||
+ | |||
+ | The VTC import feature is " |
importrfxglmfromspms.txt · Last modified: 2011/04/14 20:21 by jochen