Object-oriented fMRI

NOTES on what to add: 1. Getting started: Connect to Github, download repository, start matlab 2. Basic matlab tutorial/slides (youtube) 3. Basic neuroimaging terms (youtube channel-link to lecture) 4. Getting up and running with CANlab objects (walkthrough.m … 1, 2, 3) 5. Details on objects - readthedocs

(note, must add explanations for all attributes in class constructor methods)

Object-oriented tools offers a command-line interface for working with fMRI data and other data types interactively.

Objects include fmri_data objects, statistic_image objects (and a more general superclass of these called image_vector), fmridisplay objects, and canlab_dataset objects.

The tools are designed to offer simple commands, or 'methods,' that will perform operations on the data objects in an intuitive way. For a list of methods, type “methods(object_name), e.g., methods(fmri_data) Note that some methods might have the same name as generic matlab functions, e.g. plot(fmri_data). Plot is a generic matlab function to plot a vector (or whatever), whereas fmri_data.plot creates a figure with some different fmri-data specific graphs plus a spm_orthview of the data. –> As a consequence, when you want to read the help for a object-related method (e.g. plot for fmri_data), do not use help plot, but use help fmri_data.plot or help fmri_data/plot

There are subclasses of higher class objects, that will inherit all the methods of its 'parents' aka superclass-object. E.g. image-vector is a more general (higher order) object than fmri_data. Thus, all the methods that work with image-vector will also work with fmri_data, but not necessarily vice versa. Object types:

image_vector This object class stores 4-D image data in a vector form with one vector per image (obj.dat is a voxels x images data matrix). It provides various methods for reading, write and modifying images. The image_vector object is a superclass and subclass objects such as fmri_data and statistic_image inherit methods from the image_vector superclass.

fmri_data This subtype (child) of image_vector stores 4-D data from a series of one or more images (timeseries, contrast, etc.) It has special data fields for predictors, outcome data, and other associated information. It inherits all the methods from image_vector (e.g., fmri_data.orthviews), but also has special methods for data analysis, including fmri_data.predict, fmri_data.preprocess, fmri_data.rescale, and others.






fmri_mask_image This subtype (child) of image_vector is intended to store information about masks specifically. Used in fmri_data, but redundant functionality with other image_vector types (masks can be fmri_data objects, for example). You don't really need to create instances of this class.


The objects store dataa in a vector form and allow various methods to read, write and modify the image. The image_vector object is a superclass and subclass objects such as fmri_data and statistic_image inherit methods from the image_vector superclass

Methods include the following: apply_mask - Applies a mask (or pattern expression weight) to the image_vector extract_roi_averages - Given a mask, extract averages from the image_vector by cluster flip - Flip the data in an image_vector from left to right mean - create a new image_vector object that is the mean of all images in the image_vector preprocess - manipulate raw data to create new, cleaned data

  Other applications for preprocess include:
    - 'resid'    - make residulaized images (useful for removing motion covariates)
    - 'hpfilter' - apply high-pass filter to data, and output new image_vector

union - make union and intersection versions of masks in the image_vector object write - write image_vector to .nii or .img file (make sure to rename the field!!)


  • Inherits (child of) image_vector, so everything pertaining to image_vector also applies here – see above
  • the .mask field is basically redundant and a suboptimal implementation, avoid using this field. Cannot be removed for legacy reasons




This is an object that serves to display a region object on specific montages. Montages are configurations of slices.

Methods include: montage: creates a new montage of the fmridisplay object, specify the slices used (with coordinates, and view such as coronal, saggital, axial) addblobs: add blobs (region-objects, e.g. from a thresholded contrast image or whatever) removeblobs: removes all the blobs addpoints: add points on montage

use methods(fmridisplay) to see all of them


disp = fmridisplay; disp = montage(disp, 'axial', 'wh_slice', [0 0 12; 0 0 32; 0 0 48], 'onerow'); disp = montage(disp, 'saggital', 'wh_slice', [-4 0 0]); disp = removeblobs(disp) disp = addblobs(disp, r, 'color', [.8 .2 0]); disp = addblobs(disp, r, 'color', [0 0 0], 'outline');

To just create a figure with a montage:



All behavioral meta-data should be saved in canlab_dataset format and a flat text file with all the data at the sub-trial level, trial level, person level, and experiment level in one object. The canlab_dataset object allows for easy writing to a flat text file.

Key links: Meta-data format Google Doc

Google Doc with example canlab_dataset object and how to create

The dataset (D) is a way of collecting behavioral data and/or meta-data about fMRI (and other) studies in a standardized format. it has entries for experiment description, Subject-level variables, Event-level variables (e.g., for fMRI events or trials in a behavioral experiment) and other fields for sub-event level data (e.g., physio or continuous ratings within trials).

Dataset methods include:

write_text → writes a flat text file (data across all subjects) concatenate → returns flat matrix of data across all subjects to the workspace get_var → get event-level data from one variable and return in matrix and cell formats scatterplot → standard or multi-line scatterplot of relationship between two variables scattermatrix → Scatterplot matrix of pairwise event-level variables …and others.

The brief tutorial below will walk you through creating a dataset and using some of its functions.


You will create an empty canlab_dataset object and assign data to the fields.

Download the example dataset, which contains a .mat file and an .m file that turns it into a canlab_dataset object. This is the PAL behavioral data from Mathieu.


Use simple operators to get data from variables and make plots. This object is in early stages of development; please give it a spin, and add to it (judiciously!)

Download the example canlab_dataset object, PAL_data_25-Feb-2013_00_46.mat.zip, and unzip it to try the examples below.

A single command can create a multi-line scatterplot, with one line per subject, as shown at right.

%% Load saved example dataset
load PAL_data_25-Feb-2013_00_46.mat
%% "Flatten" dataset and build text files with header and data
[headername, dataname, fid] = write_text(D);
%% concatenate into flat 2-D matrix
[names, ids, dat] = concatenate(D);
%% get variable
to_plot = 'Anxiety';
[dat, dcell] = get_var(D, to_plot);
%% plot variable as a function of event number
% Average across subjects, with std. err across subjects
h = fill_around_line(mean(dat),ste(dat),'k');
plot(mean(dat), 'k', 'LineWidth', 3);
xlabel('Event number');
%% scatterplot
scatterplot(D, 'Anxiety', 'Frustration');
%% scatterplot matrix
wh = [6 7 8 9];
fig_han = scattermatrix(D, wh);


This object is intended to store design meta-data, and is modeled after SPM's SPM.mat structure (with some similar fields). Methods include design matrix construction (e.g., with spline basis set). HOWEVER: THIS HAS NOT BEEN USED EXTENSIVELY AND NEEDS TO BE CHECKED/DEBUGGED.



help/core/object_oriented_fmri.txt · Last modified: 2016/08/19 18:00 (external edit)
CC Attribution-Noncommercial-Share Alike 4.0 International
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0