Table of Contents
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
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.
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
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
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 create_figure(to_plot) % 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'); ylabel(to_plot); %% 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.
TO BE REMOVED