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.