Getting help

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 canlab.github.io % -------------------------------------------------------------------- % 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 canlab.github.io These are also found in the CANlab_help_examples repository at https://github.com/canlab/CANlab_help_examples 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

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

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