COBRA

Version 0.2 (2003)
Copyright (c) 2003 Serge O. Dumoulin and Rick Hoge (see COPYRIGHT file)

COBRA is a free set of Matlab functions to segment early visual areas
(Cortical Organization and Border Reconstruction of Retinotopic
Areas). A volumetric phase-encoded retinotopic mapping technique is used
to identify the visual field sign (VFS) of each voxel without the need
for an explicit reconstruction of the cortical surface. The
surface-normals are taken directly from the anatomical MRI.  Hereby
early visual areas can be segmented (V1 up to V3A and V4v, with parts of
V3B, V7, V8). 

We would appreciate that at least the following article be referenced to
describe the method in all publications of data analyzed using the COBRA
package: 

Dumoulin SO, Hoge RD, Baker Jr CL, Hess RF, Achtman RL, Evans AC (2003)
Automatic volumetric segmentation of human visual retinotopic
cortex. NeuroImage. 18(3):  576-587.

--------------------------------------------------------

COBRA requires:
 MATLAB (http://www.mathworks.com/)
  The computing environment COBRA runs in.
  I have only used the UNIX version of MATLAB 5.3 & 6.1, but it "should" 
  be able to run on other platform. Potential problems could be 
  the frequent system calls (for MINC tools) of COBRA.

Furthermore COBRA requires the following MNI tools: 
 (http://www.bic.mni.mcgill.ca/software/)
 MINC        (http://www.bic.mni.mcgill.ca/software/minc/minc.html)
             The file format COBRA uses.
 EMMA        (http://www.bic.mni.mcgill.ca/software/emma/)
             A MATLAB interface for MINC files.
 MNI_AutoReg (http://www.bic.mni.mcgill.ca/users/louis/MNI_AUTOREG_home/)
             An automated linear registration package, some of whose 
             functions COBRA uses.

--------------------------------------------------------

The software settings are optimized for my particular fMRI-data to yield
the best final results, determined using simulated data. 

The software is not at all optimized for either speed, memory usage or
(temporary) disk-space usage, though I am in the process of trying to
improve on these issues. It does create rather large files so make sure
you have enough disk space, therefore the option is provided to specify
another working directory than /tmp/.

--------------------------------------------------------

The following basic information may be useful for using COBRA.

Add folders to matlab path:
 Cobra/
 Misc/
 (example: "addpath('Cobra');")

Main program:
 Cobra/cobra.m
 Typing -- "cobra" (or "help cobra")
in MATLAB will give you a usage message with most relevant information.

The input data (fMRI and aMRI) need to be in MINC format (.mnc) where
the fMRI-files are 4D (x,y,z,time) and the aMRI 3D (x,y,z).
Furthermore, it is crucial that the fMRI and aMRI files are properly
aligned. Optional, a transformation file (.xfm) can be provided, that
aligns the fMRI and aMRI data. 

The dimensions of the aMRI and fMRI can be different. The fMRI data will
be resampled to that of the aMRI. I strongly suggest providing the aMRI
data at a higher sampling grid (resolution) than the fMRI data, this
improves the accuracy of the VFS-computation. 

--------------------------------------------------------

Example of COBRA invocation as used in Dumoulin et al. (2003):
(>> indicates MATLAB command line)

Define output base name: 
 >> output = 'my_output_filename'
E.g. the outputs will then be my_output_filename_VFS.mnc etc.

The aMRI data was provided at 1mm3 resolution in MNI-space (Collins et
al., 1994, Talairach et al., 1988) only covering the occipital lobe (see
for example "Example/SubjectSD_t1w_occ.mnc.gz"). If the aMRI is in
MNI-space it can be reshaped to the dimensions of the example using
mincresample like: [mincresample -like Example/SubjectSD_t1w_occ.mnc.gz
aMRI_tal.mnc aMRI_tal_occ.mnc], since the fMRI data will be resampled to
the aMRI data (main time and disk hogger) this will save disk-space and
time.
Anatomical MRI:
 >> aMRI = 'aMRI_tal_occ.mnc'

The fMRI data (4D file) with polar angle stimulation (rotating wedges) in
native space at 4mm3 resolution, 2 files for two scans:  
 >> fmri_pol=strvcat('fMRI_pol_01.mnc','fMRI_pol_02.mnc') 
Same for scans with eccentricity stimulation (expanding rings):
 >> fmri_ecc=strvcat('fMRI_ecc_01.mnc','fMRI_ecc_02.mnc')

Because the fMRI and aMRI are not aligned (native and MNI space,
respectively) a transformation file needs to be given which aligns
them:
 >> xfm = 'fMRI_native_to_aMRI_tal.xfm' 
If the two fMRI scans were acquired in different sessions, two
corresponding xfm-files may be given:
 >> xfm = strvcat('fMRI_native_to_aMRI_tal_01.xfm',...
                  'fMRI_native_to_aMRI_tal_02.xfm')
This is not necessary if the fMRI and aMRI are aligned:
 >> xfm = []

The inverse is needed as well but will be created using [xfminvert] if it is 
not given:
 >> xfminverse = []  
or:
 >> xfminverse = 'fMRI_native_to_aMRI_tal_inv.xfm'
or:
 >> xfminverse = strvcat('fMRI_native_to_aMRI_tal_01_inv.xfm',...
                         'fMRI_native_to_aMRI_tal_02_inv.xfm')

Lastly, the file can be defined where the other variables can be
found. If this is not given it will take the variables from the file
"RetinoGlobals.m" (for more specific details see Variable definitions 
below):
 >> variables_file = 'RetinoGlobals_modified_by_me'

Now you are ready to call COBRA:
 >> cobra(output,aMRI,fmri_pol,fmri_ecc,xfm,xfminverse,variables_file);
This may run for one to several hours, depending on the data-size and
processing speed.

--------------------------------------------------------

Variable definitions:
The file where all variables are defined: Cobra/RetinoGlobals.m This is the
default file that program uses, and should be modified according to your
needs. This file can be renamed and the new file name can be given as
an input to COBRA.

Some more information on the relevant options in RetinoGlobals:  
% scanning parameters:
RET_STIM_CYCLES : 
 Number of cycles (rotation or expansions) of the retinotopic stimuli in
 fMRI time-frames _without_ RET_BLANKS. Has to be an whole number - used
 to encode the phase in that particular fft-bin.
 Two values can be specified if different stimulus cycles are used for 
 rotations and expansions: [number_of_rotations; number_of_expansions];
 e.g. [10; 8]; or [10 8];
RET_BLANKS      : 
 Initial fMRI time-frames to ignore in analysis due to magnetization
 transients in the fMRI-data.
 Two sets of values can be specified if different initial time-frames need 
 to be ignored for phase-angle and eccentricity scans (padded with zeros):
 [frames_to_ignore_rotations; frames_to_ignore_expansions];
 e.g. [1:8; 1:6 0 0];

% preprocess parameters:
PREPROC_BLUR_KERNEL : 
 Size of the blurring kernel (mm of the fwhm) used in preprocessing the
 fMRI-data (typically used prior to motion correction).
 Use: [], empty if no blurring was used.

%--- other descriptive stats: (that may be useful)
KEEP_INDIVIDUAL_MAPS :
 Save individual maps, e.g. polar-angle and eccentricity phase-maps.
GET_TMAP :
 Create t-statistical map and use this to weight the VFS-map
 (tVFS). This is quite slow.
GET_VISUAL_QUADRANTS :
 Segments the polar-angle phase maps into the four visual
 quadrants. This is only accurate if an accurate Q_BORDER_SHIFT is
 specified. (used for debugging purposes).
Q_BORDER_SHIFT :
 Shift of polar-angle phases from 0-pi/2-pi-3*pi/2, due to hemodynamic
 response function and/or stimulus start position. (used for debugging 
 purposes).
GET_GRADIENT_MAP : 
 (used for debugging purposes).
GET_SECOND_DERS :
 Not supported any more.

%--- COBRA Parameters:  
Optimized for my data (raw fMRI resolution = 4mm3). I would suggest ONLY
varying DERIVATIVES_KERNEL and ANAT_DER_KERNEL, if necessary.

DERIVATIVES_KERNEL :
 Size of the derivative kernel (fwhm in mm) to create the derivatives
 from the phase-maps, which will be used to determine the VFS. The results
 are relatively stable across a small range of fwhms (2-4mm), but outside
 this range artifacts may occur. If the fMRI resolution is very different
 from mine (4mm3), I suggest trying 3/4*[x y z] resolutions.
ANAT_DER_KERNEL :
 Same as DERIVATIVES_KERNEL for anatomical data.
RET_FAST_METH: 
 Not working any more. Potential shortcut in the data analysis that
 creatly reduces processing time and introduces artifacts.

% resample parameters if other than anatomy file(=[])
RET_LIKE_FILE :
 Suggest providing the anatomical file at resolution that that the output
 data is required in ([]).  Note that the whole fMRI-scan is resampled to
 that resolution (main time consumer and disk hogger) I personally
 transform the data in Tal-space and use only the occipital lobe. For an
 example see: Cobra/Example/SubjectSD_t1w_occ.mnc.gz The data does not
 need to be resampled to Tal-space but I strongly recommend resampling it
 to a higher resolution.

% thresholding parameters
Not used any more - may speed things up and introduce artifacts.

%--- no effect on functioning of the algorithm
RET_TMP_DIR :
 Suggest defining RET_TMP_DIR to have enough disk space available.
RET_TMP_SUBDIR :
 Temporary working directory created by COBRA.
CUR_DIR :
 Where final outputs will be stored.
KEEP_TMP :
 Keep temporary workspace (used for debugging purposes).

--------------------------------------------------------

Known bugs (so far):

- No cleanup after crashes,
- Cannot start or stop halfway
  (copying and pasting into matlab will work though ---
  making sure all the variables are there, ie load variables.mat),
- Program could be sped up quite a lot,
  however I'm not sure about the trade off's (so left it that way).

--------------------------------------------------------

Good luck! Please let me know if you have any questions, requests, 
comments or improvements:  
  
Serge Dumoulin (serge@bic.mni.mcgill.ca)
McGill Vision Research Unit 
Department of Ophthalmology 
687 Pine Avenue West, H4-14 
Montreal, Quebec, 
H3A 1A1 Canada

http://www.bic.mni.mcgill.ca/users/serge

--------------------------------------------------------

Package date: 16-Apr-2003.