COBRA

Version 0.3 (2004)
Copyright (c) 2003-2004 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 & 6.5, 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.

Reported compatible platforms:
mips-sgi-irix6.5, alpha-dec-osf4.0, 
i386-pc-linux-gnu, i386-pc-windows-cygwin
ppc-mac-osx3.3

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

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):
Please note that COBRA invocation has changed (v0.3) in an attempt to
have a more user friendly and more intuitive (commandline) interface.
(>> 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')

The number of cycles (rotation or expansions) of the retinotopic stimuli in
fMRI time-frames _without_ tf_ignore. It 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];
 >> stim_freq = [10 10]

The 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];
 >> tf_ignore = [1:8; 1:8] 

The relative direction of the fMRI stimulation
[clockwise/counter-clockwise file1 expanding/contracting file1;
 clockwise/counter-clockwise file2 expanding/contracting file2];
 >> directions = [ 1  1; 
                  -1 -1];

The output that are required (see help cobra for more info):
 >> add_outputs = 0

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
"cobra_options.m" (for more specific details see "help cobra_options' or
 "cobra options?"):
 >> variables_file = 'cobra_options_modified_by_me'

Alternatively, specific options can be defined on the command line as 
well (see "help cobra_options" or "cobra options?").

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.

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

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: 14-May-2004.
