COBRA

Version 0.1 (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/)
  I have only used the UNIX version of MATLAB 5.3, 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)
 MNI_AutoReg (http://www.bic.mni.mcgill.ca/users/louis/MNI_AUTOREG_home/)
 EMMA        (http://www.bic.mni.mcgill.ca/software/emma/)

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

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.

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

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.
RET_BLANKS      : 
 Initial fMRI time-frames to ignore in analysis due to magnetization
 transients in the fMRI-data.

% preprocess parameters:
PREPROC_BLUR_KERNEL : 
 Blurring kernel used in preprocessing the fMRI-data (typically used
 prior to motion correction).

%--- 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 :
 Some 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, 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: 01-Apr-2003.
