MrVista 1 conventions

From VISTA LAB WIKI

Jump to: navigation, search

Contents

[edit] Programming conventions

[edit] Naming

We use the lower Camel Case system for naming variables and functions. The first letter is lower case, and words are capitlized, i.e., lowerCamelCase.

When a data structure becomes very important, we implement three key functions for accessing the structure: create, set, get. We try not to adjust the structure fields directly, but only through the accessor functions.

[edit] Functions

Functions should be short. Function names should be carefully chosen to reflect the actions they perform. Comment your functions. We create web-pages from the functions themselves.

[edit] Names

Functions typically are named <subGroup><Description><Action>. We prepend function names with a short acronym that indicates their functional group. For example, most of the diffusion tensor imaging methods are start dti<>. Another example, the functions that adjust the mrSession variable are mrSessionGet and mrSessionSet. Certain general mrVista commands start with mrv<>. Anatomical functions have mra<>. This convention evolved, so there are many failures to follow this rule. As we clean, we hope to get everything into this shape.

There are other functional groups as well - and we will list them here at some point. - This has the advantage that one can type dt<TAB> at the command window and see the list of functions in a group easily.

[edit] Comments

We use a particular format for the comments at the start of all functions. This format allows us to automate the process of creating web-pages for each of the functions. We use the tool XXXX to create these web-pages. The great advantage of this approach is that we only need to keep comments in one place (the function header). Comments should be specific and plentiful. They should tell you something that is not entirely obvious from the code itself.

An unnecessary comment is

% Set y to x
y = x;

A good comment is

% Store x temporarily in y, we clear it later
y = x;

[edit] Data Conventions

This page describes some of the nuts and bolts of how information is stored for mrVista sessions.

[edit] mrSESSION.mat

One of the key files we use is mrSESSION.mat, which contains info on the inplane (anatomies which are co-registered to functionals) and functional data for a session. mrSESSION has the following variables:

mrSESSION (struct): header info for original files (functionals, inplane anatomies); session code; alignment to reference volume

dataTYPES (struct): names of scan groups for a session (called data types); analysis parameters for each scan.


vANATOMYPATH (string): path to the reference volume anatomy ( vAnatomy.dat). Needed for Volume/Gray, Mesh, and Flat analyses, but not needed if you will analyze data on Inplanes only.


[edit] mrSESSION variable structure

Some key fields in the mrSESSION variable:

  • functionals: information on each functional scan in the 'Original' data type.
    • functionals.cropSize: actual size of each slice for the tSeries files.
    • functionals.crop: the bounds (rows / cols) from the original data from which the tSeries are taken.
    • functionals.voxelSize: the size represented by each voxel afterresampling (corresponding to a column in the tSeries variable, and in the P#####.7.mag file).
    • functionals(.effectiveResolution: the actual size our scan protocol could resolve, and what we generally report as the 'true' resolution.

The reason for having both a voxel size and an effective resolution is that the image reconstruction from Fourier space (which, at Lucas Center, happens when Gary Glover's recon scripts produce a P*.7.mag file from a P*.7 file) needs to resample to an image matrix which is a power of 2 (e.g., 64 x 64 for each slice, or 128 x 128, 256 x 256, etc... This happens, I believe, because of the numerical methods used in many Fourier Transforms.) Thus, the voxelSize may be smaller than you expect, due to this upsampling, but the actual resolution achieved by the protocol is given by the effective resolution.

  • inplanes: path information for the inplane anatomy file.

[edit] dataTYPES variable structure

dataTYPES is a struct array, with one entry for each data type in a given session. The first data type is almost always 'Original'; that is, those functional scans derived from the Raw P*.7.mag or ANALYZE files. Other data types may be created from the data, or imported from another session. Common data types include things such as 'Averages', 'MotionComp', 'Timed' (slice-time-corrected), 'Imported_[other data type]', or 'GLMs'.

Each entry in dataTYPES has a .name field indicating the data type name, and several parameter fields. Each of these fields is a struct array, where each entry is one scan in the data type:

[edit] scanParams

A set of basic scan parameters, similar to the .functionals field in the mrSESSION variable. The Event-Related code also appends the fields .parfile and .scanGroup here (as well as the event-related params below), due to some legacy code

[edit] blockedAnalysisParams

Saved parameters for performing traveling-wave analyses.

The key field is nCycles. This determines the number of cycles a traveling-wave / phase-encoded experiment uses in each scan. (For ABAB block designs, it reflects the number of complete AB cycles in a scan.) When computing the traveling wave analysis (corAnal), the code will use the amplitude of this harmonic compared to other harmonics to determine the signal coherence.

Additionally, if you select the 'Set Visual Field Mapping Parameters' option in the ColorMap or Edit menus in mrVista, a parameter 'visualFieldMap' is added to the code in the blockedAnalysisParams. This field is a struct describing how a stimulus moved in a retinotopic mapping experiment (such as where a rotating wedge started or how wide a ring was). It is used to relate the traveling wave phase to an estimate of real-world physical units.

[edit] eventAnalysisParams

Saved parameters for performing GLM and other analyses in which the condition order is specified by .par files. Can be updated using EventRelated | Set EventRelated Params or Edit|Data Type|Edit EventRelated Params. In addition to the Preprocessing flags the fields are:

  • timeWindow: a time window, in seconds about the onset of an event, from which to extract event-triggered averages. Can include negative times, occuring before the stimulus onset. [default -8:24]
  • bslPeriod: a subset of the time window (also in secs) for which you expect time series to be relatively inactive, e.g. before the stimulus begins. [default -8:0]
  • peakPeriod: a subset of the time window (also in secs) for which you expect stimulus-related activations. [default 4:14].
  • normBsl: a flag to set the mean activity during the baseline periods to be zero in event-triggered averages. If 1, will subtract the mean signal for each event/trial during the baseline period from that event's time course. [default 1]
  • onsetDelta: if there is a discrepancy between the saved time series and the description of stimulus onsets in the .par files, set this parameter to a non-zero value to shift the onsets relative to the time series (in seconds) without having to regerenate .par files. For example: if the first 4 seconds are accidentally clipped from a scan, set this to -4. (E.g. An onset specified at 10 seconds from the scan start actually happened at 6 seconds relative to the first time series frame.) [default 0]
  • snrConds: specify which conditions you want to use when computing the signal-to-noise ratio for a time course. These conditions will also be used to compute the HRF if the glmHRF flag is set to 1 (see below). [default 1]
  • glmHRF: a flag describing what hemodynamic impulse response function (HRF or HIRF) to use for GLM analyses:
    • 0: "deconvolve": estimate the peri-stimulus signal using separate predictors for each time point, as per Template:RefBurock and Dale, HBM, 2000.
    • 1: Use the event-triggered average for the conditions set in snrConds.
    • 2: Use the Boynton et al Template:Ref Boynton et al 96 gamma HRF. [2=default value]
    • 3: Use the SPM difference-of-gammas HRF. (requires that you have a version spm installed).
    • 4: Use the Dale + Buckner Template:Ref Dale et al 99 HRF.
    • 5: provide a dialog to select a saved HRF file.
    • (string): path to a saved HRF file.
  • glmHRF_params: if glmHRF is set to 2, 3, or 4 (a pre-set HRF), this field will determine the parameters used to describe that HRF. (Further descriptions forthcoming).
  • glmWhiten: flag to "whiten" the data (make it conform more to a Gaussian noise model by computing a cross-correlation matrix) when applying a GLM. See Smith et al 2007 for more background on this issue. [default 0]
  • eventsPerBlock: set the duration of the predictors in MR frames in a GLM design matrix before convolving the HRF. For event-triggered averages, this should be set to 1, and each event will be treated as a Kronecker delta function. For block designs, this should be set to the number of TRs for which the block lasted, in which case the event will be treated as a square wave of that duration. This is equivalent to specifying separate onsets for each event within a block in the .par files. However, specifying multiple events in .par files may cause the event-triggered average to be off, since you'll be averageing responses from the start and end of a block. So, it's better to specify only the block onset, and get a mean block response, and use this to set the GLM design matrix to be correct. [default 1]
  • ampType: method to use to estimate the amplitude of response of a voxel for each condition in multi-voxel analyses.
    • 'difference': use the difference in signal between the peak and baseline periods in the event-triggered avereages. [default]
    • 'betas': use the beta values from a GLM analysis.
    • 'zscore': use the Z score of signal / variance from the event-triggered averages.
    • 'deconvolved': use the peak-baseline method, but calculate using the beta estimates from the "deconvolved" time courses.
    • 'projamps': use the "projected amplitude" or dot-product amplitude method as described in Template:Ref. (This method is not working properly as of 01/07).

[edit] Preprocessing flags

The dataTYPES structure stores some flags determining how to preprocess time series before analyses. The logic behind this is that the time series saved is intended to be as close to the original data as possible (for instance, the 'Original' data type is the raw image data after reconstruction), and it is generally quicker and more flexible to preprocess on the fly. These parameters are set in the 'blockedAnalysisParams' and 'eventAnalysisParams' fields of dataTYPES. (They are set separately to allow for different preprocessing paths for different types of analyses.) The parameters can initially be set when running mrInitRet, but can be updated anytime by selecting the menu option Edit | Data Type | Edit Data Type. There is also a dedicated dialog for setting event-related parameters in Edit Event-Related Parameters.

  • detrend: option for whether to, and how to, remove drift trends from time series. The different possible flag values are:
    • 0: don't detrend
    • 1: high-pass filter: actually multiple boxcar smoothing with a cutoff determined by detrendFrames (see Template:Ref). [default]
    • 2: remove quadratic (2nd-order) detrend line
    • -1: remove a linear detrend line
  • detrendFrames: if detrend is set to 1, this determines the length of the cycle (in images, not seconds) which serves as the cutoff for the high-pass filter. On-off cycles shorter than [detrendFrames images] will be retained, but longer cycles will be removed. To calculate the cutoff frequency you will need to multiply this by your TR and invert: cutoff frequency = 1/detrendFrames*TR [default detrendFrames=20]
  • inhomoCorrect: option for how to deal with spatial inhomogeneity in signal intensity:
    • 0: don't do anything
    • 1: divide each voxel's time series by the mean intensity at that voxel [default]
    • 2: divide by an estimate of the 'null' condition (not yet implemented)
    • 3: divide by a robust estimate of the spatial gradient. This method is potentially more robust at removing large artifacts in sinuses and draining vains, according to Template:Ref. However, you'll need to run Analysis|Compute Spatial Gradient first.
  • temporalNormalization: if 1, will scale each time series slice (in Volume/Gray views, all time series) such that each temporal frame has the same mean intensity across voxels. [default 0]

[edit] References

  1. Template:Note Boynton 1996
  2. Template:Note Burrock 2000
  3. Template:Note Dale 1999
  4. Template:Note Ress 2000
  5. Template:Note Ress D, Glover GH, Liu J, Wandell B. (2007) Laminar profiles of functional activity in the human brain. Neuroimage. 34(1):74-84. Epub 2006 Sep 29.
Personal tools