Getting help

There are several resources to get help using CANlab object-oriented tools.
Table of Contents

Walkthroughs and tutorials

The “first stop” is
This includes pages on the object types and philosophy.
There are two sets of Matlab tutorials:

How-to Walkthroughs

“Walkthroughs” is designed as a set of “how-to” documents for the tools, with examples and code.

Didactic tutorials

“Tutorials” are more didactic and include more conceptual description, along with data and code. This also has a section on the SPM GUI and running statistical models with SPM.

Batch scripts: Modular example code

The "second-level batch scripts" run flexible pipelines for doing many things with CANlab object-oriented tools once you have a set of image files to work with (typically one image per task condition per participant). They also produce published reports.
These scripts illustrate commands and processes that can be used with image data at other levels of analysis, too. If you find output (figures, tables, etc.) that you want to know how to create, you can read the code to see how it's done.

Additional CANlab examples and tutorials

The code that generates the walkthroughs and tutorials on, and the "second-level batch" code, is in a Github repository, here:
It contains some "in progress" walkthroughs as well. We hope that people will be interested in contributing to and improving these!

Interactive help within Matlab

Much of the help available is embedded in the Matlab functions and object class definition files.
The info here is available by typing commands in Matlab:
doc <object class name>
help <function>
Try these:
doc fmri_data
doc atlas
And this:
help fmri_data
fmri_data: Data class for storing and analyzing neuroimaging datasets and associated information 'fmri_data' is a data class containing information about generic fmri datasets stored in a structure-like object. Using this has the advantages that the properties and methods are standardized and controlled. It also keeps track of the history of what was done to the dataset. ------------------------------------------------------------------------- Features and philosophy: ------------------------------------------------------------------------- - Store image data in a flat (2-d), space-efficient voxels x images matrix - Save space: Tools to remove out-of-image voxels and empty (zero/NaN) voxels, store data in single-precision format - Analysis-friendly: 2-d matrices can be read and analyzed in multiple packages/algorithms - Meta-data included to convert back to 3-d image volume space, with easy tools (methods) to reconstruct and visualize images Built-in resampling makes it easy to compare/combine datasets with different voxel sizes and image bounding boxes Reduces overhead for statisticians/data scientists unfamiliar with neuroimaging to apply their algorithms. - Multiple images can be stored in a single object - Methods have short, intuitive names, and perform high-level functions specialized for neuroimaging: - Visualization (plot, orthviews, surface, montage, histogram, isosurface methods) - Image manipulation (apply_mask, get_wh_image, resample_space, compare_space, flip, threshold methods) - Data extraction (apply_atlas, apply_parcellation, extract_gray_white_csf, extract_roi_averages) - Analysis (ica, mahal, image_math, and many more in the fmri_data subclass) - Provenance: Ability to track and update history of changes to objects fmri_data is a subclass of the image_vector object and inherits its properties and methods. ------------------------------------------------------------------------- To construct/create a new instance of an object: ------------------------------------------------------------------------- Basic usage: obj = fmri_data(image_names, [maskinput], [other optional inputs]) maskinput : [optional] name of mask image to use. Default: 'brainmask_canlab.nii', a brain mask that is distributed with SPM software and in the CANlab Core Tools Alternative in CANlab tools: which('gray_matter_mask.img') 'noverbose' : Suppress verbose output during image loading 'sample2mask' : Sample images to mask space. Default: Sample mask to image space, use native image space Creating class instances ----------------------------------------------------------------------- You can create an empty object by using: fmri_dat = fmri_data - fmri_dat is the object. - It will be created with a standard brain mask, brainmask_canlab.nii - This image should be placed on your Matlab path - The space information is stored in fmri_dat.volInfo - Data is stored in fmri_dat.dat, in a [voxels x images] matrix - You can replace or append data to the fmri_dat.dat field. You can create an object by assembling an image_vector object from parts (entering fields) and converting using fmri_obj = fmri_data(image_vec_obj) This can also be a structure with field names that match properties of the new intended fmri_data object. e.g., new_obj.volInfo = MC_Setup.volInfo; new_obj.dat = MC_Setup.unweighted_study_data(:, sym_cons); You can create an fmri_data object with extacted image data. - Let "imgs" be a string array or cell array of image names - This command creates an object with your (4-D) image data: - fmri_dat = fmri_data(imgs); - Images can be zipped (.gz) as well. fmri_data() will unpack them. - Only values in the standard brain mask, brainmask_canlab.nii, will be included. - This saves memory by reducing the number of voxels saved dramatically. You can specify any mask you'd like to extract data from. - Let "maskimagename" be a string array with a mask image name. - this command creates the object with data saved in the mask: - fmri_dat = fmri_data(imgs, maskimagename); - The mask information is saved in fmri_dat.mask e.g., this extracts data from images within the standard brain mask: dat = fmri_data(imgs, which('brainmask_canlab.nii')); Defining the space of the extracted data ----------------------------------------------------------------------- Note: There are two options for defining the space (i.e., coordinates/voxels) that the data is mapped to. By default, the mask is resliced to the same space as the first image in the input image name set (not coregistered; just resliced to the same voxel sizes. The images are assumed to be in register.) Reampling to mask space: YOU CAN ALSO map the image data to the space of the mask, by entering 'sample2mask' as in input argument. For loading images in different spaces together in one object, use the 'sample2mask' option. Attaching additional data ----------------------------------------------------------------------- The fmri_data object has a number of fields for appending specific types of data. - You can replace or append data to the fmri_dat.dat field. - The fmri_data object will also store predictor data (.X) also outcome data (.Y) - There are many fields for descriptions, notes, etc., like "dat_descrip" and "source_notes" - Attach custom descriptions in these fields to document your object. - The "history" field stores a cell array of strings with the processing history of the object. Some methods add to this history automatically. ----------------------------------------------------------------------- Properties and methods ----------------------------------------------------------------------- Properties are data fields associated with an object. Type the name of an object (class instance) you create to see its properties, and a link to its methods (things you can run specifically with this object type). For example: After creating an fmri_data object called fmri_dat, as above, type fmri_dat to see its properties. There are many other methods that you can apply to fmri_data objects to do different things. - Try typing methods(fmri_data) for a list. - You always pass in an fmri_data object as the first argument. - Methods include utilities for many functions - e.g.,: - resample_space(fmri_dat) resamples the voxels - write(fmri_dat) writes an image file to disk (careful not to overwrite by accident!) - regress(fmri_dat) runs multiple regression - predict(fmri_dat) runs cross-validated machine learning/prediction algorithms Key properties and methods (a partial list; type doc fmri_data for more): ------------------------------------------------------------------------- fmri_data Properties (a partial list; type doc fmri_data for more): dat - Image data, a [voxels x images] matrix, single-format fullpath - List of image names loaded into object with full paths history - History of object processing, for provenance image_names - List of image names loaded into object, no paths removed_images - Vector of images that have been removed (saves space; see remove_empty.m, replace_empty.m) removed_voxels - Vector of empty in-mask voxels that have been removed (saves space; see remove_empty.m, replace_empty.m) volInfo - Structure with info on brain mask (saves space) and mapping voxels to brain space fmri_data Methods (a partial list; type doc fmri_data for more): General: . descriptives - Get descriptives for an fmri_data or other image_vector object enforce_variable_types - Re-casts variables in objects into standard data types, which can save flip - Flips images stored in an object left-to-right history - Display history for image_vector object write - Write an image_vector object to hard drive as an Analyze image (uses .fullpath field for image names) Data extraction: apply_atlas - Computes the mean value or pattern expression for each reference region specified in an atlas object apply_mask - Apply a mask image (image filename or fmri_mask_image object) to an image_vector object apply_parcellation - Computes the mean value or pattern expression for each parcel specified in a data object extract_gray_white_csf - Extracts mean values (values) and top 5 component scores (components) extract_roi_averages - This image_vector method a extracts and averages data stored in an fmri_data object Handling brain space and image selection: compare_space - Compare spaces of two image_vector objects get_wh_image - For an image_vector with multiple images (cases, contrasts, etc.), select a subset. reconstruct_image - Reconstruct a 3-D or 4-D image from image_vector object obj remove_empty - remove vox: logical vector of custom voxels to remove, VOX x 1 reparse_contiguous - Re-construct list of contiguous voxels in an image based on in-image replace_empty - Replace empty/missing values in an image data object resample_space - Resample the images in an fmri_data object (obj) to the space of another Display and visualization: display_slices - Creates 3 separate montage views - ax, cor, sagg in a special figure window histogram - Create a histogram of image values or a series of histograms for each image_similarity_plot - Associations between images in object and set of 'spatial basis function' images (e.g., 'signatures' or pre-defined maps) isosurface - Create and visualize an isosurface created from the boundaries in an image object. montage - Create a montage of an image_vector (or statistic_image or fmri_data) orthviews - display SPM orthviews for CANlab image_vector (or fmri_data, statistic_image) object pattern_surf_plot_mip - axial maximum intensity projection pattern surface plot sagg_slice_movie - Movie of successive differences (sagittal slice) slices - Create a montage of single-slice results for every image in an image_vector object surface - Render image data on brain surfaces; options for cutaways and canonical surfaces wedge_plot_by_atlas - Plot a data object or 'signature' pattern divided into local regions Data processing and analysis: ica - Spatial ICA of an fmri_data object image_math - Perform simple mathematical and boolean operations on image objects (see also plus, minus, power) mahal - Mahalanobis distance for each image in a set compared to others in the set mean - Mean across a set of images. Returns a new image_vector object. preprocess - Preprocesses data in an image_vector (e.g., fmri_data) object; many options for filtering and outlier id qc_metrics_second_level - Quality metrics for a 2nd-level analysis (set of images from different subjects) searchlight - Run searchlight multivariate prediction/classification on an image_vector threshold - Threshold image_vector (or fmri_data or fmri_obj_image) object based on raw threshold values union - ...and intersection masks for two image_vector objects ------------------------------------------------------------------------- Examples and help: ------------------------------------------------------------------------- To list properties and methods for this object, type: doc fmri_data, methods(fmri_data) Example 1: Load images (and run a simple analysis) % -------------------------------------------------------------------- Load a sample dataset into an fmri_data object (subclass of image_vector) This loads one of a set of named image collections used in demos/help: data_obj = load_image_set('emotionreg'); You can load the same images manually, by locating the files, listing their names in a character array (or 1 x n cell array of strings), and then passing those into fmri_data: data_obj = fmri_data(which('Wager_2008_emo_reg_vs_look_neg_contrast_images.nii.gz')); filedir = what(fullfile('CanlabCore', 'Sample_datasets', 'Wager_et_al_2008_Neuron_EmotionReg')); image_names = filenames(fullfile(filedir.path, '*img')); data_obj = fmri_data(image_names); Now you can interact with the object. Try, e.g.,: methods(data_obj) % List methods for object type descriptives(data_obj); % Print summary of descriptive statistics for the dataset plot(data_obj) % Custom fmri_data specific plots t = ttest(data_obj); % Perform a voxel-wise one-sample t-test across images t = threshold(t, .005, 'unc', 'k', 10); % Re-threshold with extent threshold of 10 contiguous voxels r = region(t); % Turn t-map into a region object with one element per contig region Example 2: Extract data averaged over regions of interest: % -------------------------------------------------------------------- First run Example 1. Now you have a thresholded t-statistic map. Extract averages (across voxels) for each subject in each contiguous region by typing: r = extract_roi_averages(data_obj, t); This returns r, which is another object--a "region"-class object. Region objects contain vectors, one element per pre-defined region in the image (in this case, significant blobs from our analysis). Each element contains info that describes the region, including the voxels included, and average and voxel-by-voxel data if extracted from images and attached. Type "doc region" for more info. r has properties that hold multiple types of data: - .dat holds generic extracted data - .all_data holds voxel-by-voxel extracted data % -------------------------------------------------------------------- % Group one-sample t-test: % A simple, complete example of a group analysis % For more, see walkthroughs on % -------------------------------------------------------------------- % Load sample images, creating and fmri_data class object with 30 images imgs = load_image_set('emotionreg'); % Display a slice from each image in a montage: slices(imgs); % Display some useful summary plots of the dataset: plot(imgs); % Perform a t-test on each voxel, returning a statistic_image object % containing t-stats and p-values: t = ttest(imgs); % Display the unthresholded results in a quick-render montage of image % values only: display_slices(t, 'axial'); colormap summer; colorbar; % Display the unthresholded results over an anatomical underlay, % on a combination of slices and surfaces, % returning an fmridisplay class object with registered handles o2 = canlab_results_fmridisplay(t, 'full'); % Remove colors from slices and surfaces registered in the o2 object: o2 = removeblobs(o2); % Threshold the t-statistic_image object at p < 0.005 t = threshold(t, .005, 'unc'); % Re-display the thresholded images on slices/surfaces registered in o2: o2 = addblobs(o2, region(t), 'nolegend'); % Display the thresholded t-map with orthviews: orthviews(t); % display on a slice montage: create_figure('slices'); axis off; montage(t); % Re-threshold at q < 0.05 FDR, and re-display on orthviews: t = threshold(t, .05, 'fdr'); orthviews(t); % Print a table of results, and return a region-class object r with labels % from a default atlas (an atlas-class object): r = table(t); % Display a slice montage showing each activation blob, with labels: montage(r, 'regioncenters', 'colormap'); -------------------------------------------------------------------- For more examples and walkthroughs, see walkthroughs on These are also found in the CANlab_help_examples repository at Some example tutorials: canlab_help_1_installing_tools canlab_help_2_load_a_sample_dataset canlab_help_3_voxelwise_t_test_walkthrough canlab_help_4_write_data_to_image_file_format canlab_help_5_regression_walkthrough ... and more % -------------------------------------------------------------------- Documentation for fmri_data
There are a few object types (or "classes") that organize most of the things you can do with image data. Each class has methods associated with it, which are things you can run. You can list these methods using doc (see above) or using the "methods" command:
Defaults settings have been modified by file(s): /Users/f003vz1/Dropbox (Dartmouth College)/Matlab_code_external/spm12/spm_my_defaults.m Modified fields: stats Defaults settings have been modified by file(s): /Users/f003vz1/Dropbox (Dartmouth College)/Matlab_code_external/spm12/spm_my_defaults.m Modified fields: stats Methods for class fmri_data: apply_atlas prctile apply_mask predict apply_parcellation predict_test_suite canlab_connectivity_preproc preprocess cat qc_metrics_second_level check_image_filenames read_from_file compare_space rebuild_volinfo_from_dat create reconstruct_image descriptives regress display_slices remove_empty enforce_variable_types render_on_surface evaluate_spatial_scale reparse_contiguous expand_into_atlas_subregions replace_empty extract_gray_white_csf resample_space extract_measures_batch resample_time extract_roi_averages rescale flip riverplot fmri_data rmssd_movie get_wh_image robfit_parcelwise histogram rsa_regression history saveplots horzcat searchlight hrf_fit select_voxels_by_value ica signtest image_math sim_data image_similarity_plot slice_movie image_similarity_plot_bucknermaps slices interpolate split isempty spm_coregister isosurface subdivide_by_atlas mahal surface mean table minus test_generalizability model_brain_pathway threshold montage trim_mask neurosynth_feature_labels ttest orthviews ttest_table_and_lateralization_test outliers union pattern_surf_plot_mip wedge_plot_by_atlas plot windsorize plot_current_orthviews_coord write plus power
Then you can get help on any method by typing help <object class>.<method name>. For example:
help fmri_data.apply_mask
Apply a mask image (image filename or fmri_mask_image object) to an image_vector object stored in dat. This can be used to: - Mask an image_vector or fmri_data object with a mask - Obtain "pattern expression" for a weight map (entered as the mask, here) in a series of images stored in dat. The mask or weight map does not have to be in the same space as the dat; it will be resampled to the space of the data in dat. To extract pattern expression values for each ROI within a mask use extract_roi_averages() :Optional Inputs: **pattern_expression:** calculate and return the dot product of each image in dat and the values in the mask. This is useful if comparing expression values that are comprised of different datasets or differing number of voxels. **correlation:** calculate the pearson correlation coefficient of each image in dat and the values in the mask. **norm_mask:** normalize the mask weights by L2 norm, for patt expression only. **ignore_missing:** use with pattern expression only. Ignore weights on voxels with zero values in test image. If this is not entered, the function will check for these values and give a warning. **invert:** Invert the mask so that out-of-mask voxels are now in (using the mask as an 'exclude mask' rather than an include-mask. If pattern expression is requested, the behavior is different, and it inverts the sign of in-mask pattern weights. **cosine_similarity:** use with pattern expression only. scales expression by product of l2 norms (norm(mask)*norm(dat)) :Examples: :: [dat, mask] = apply_mask(dat, mask) [dat, mask] = apply_mask(dat, mask image name) [dat, mask] = apply_mask(dat, mask image vector object) [pattern_exp_values] = apply_mask(dat, weight map image, 'pattern_expression', 'ignore_missing') [pattern_exp_values] = apply_mask(dat, weight map image, 'pattern_expression', 'ignore_missing','correlation') :See also: extract_roi_averages, to get individual region averages / local pattern expression apply_nps, which does whole-pattern and local regional expression .. Notes: Last modified: 10/30/11 to add support for masks that are weight maps 12/15/13: Luke Chang - added correlation option for pattern-expression 5/10/2016: Phil Kragel - added cosine similarity 8/2/2018: Tor Wager - if mask is a statistic_image object, apply .sig field .. Help for fmri_data/apply_mask is inherited from superclass image_vector
Or, if there are not multiple "apply_mask" functions on your path, just:
help apply_mask

Other resources

Some older resources may also be helpful, and are here:

CANlab Core readthedocs

A "read" of the help included with Canlab Matlab functions. This describes the basic object types and methods, but has not been updated in several years.
Or, for a PDF version:
The info here is available by typing commands in Matlab (see above):
doc <object class name>
help <function>

CANlab Repos Guide
This is a quite detailed document with information on:

CANlab Toolbox-specific help

Toolboxes like the Mediation toolbox, Robust regression toolbox, and meta-analysis toolbox have their own help files as well. Increasingly, help is integrated into the Walkthroughs and Tutorials discussed above, but check out the Readme files in these Github repositories and documentation in the toolbox folders as well.

Study-specific repositories

The CANlab Github site contains many study-specific repositories, and many these are publicly available. Generally, they contain code and data that can be reused to generate new scripts and pipelines. You can search them here:

Resources for CANlab members: Data, templates, devices, more!

For those with access to restricted files, CANlab has a private repository that contains a lot of useful information. We are happy to share most of this on request, but believe it is more useful for the lab specifically than for general public use.
It includes:

Help with Matlab in general

This is not a comprehensive introduction to Matlab. It’s assumed that you will use other resources to supplement your basic understanding how to work with Matlab, including some linked here: