codespell: fix typos surfaced on master; whitelist hask

.codespellrc

@@ -26,4 +26,6 @@ ignore-regex = https?://\S+|^%   data: \{"dataType":"image".*
 #   atleast, whch, whn, includ -- variable names (renaming would break code; "atleast" -> "at least" would be a syntax error)
 #   efficency -- legacy function file name OptimizeDesign11/core_functions/efficency.m (sibling efficiency.m is the newer version; both retained)
 #   ony, nam, tha, thre, firt, jus -- ambiguous variable/string fragments in context
-ignore-words-list = ons,ans,fpr,ttests,myu,whos,ser,htmp,fwe,dout,ttest,indx,alph,te,ist,selt,multy,shft,delt,dum,datin,fixin,runn,nneeded,figurestyle,cxan,losin,commun,pres,ues,assignin,evalin,inout,ment,sepulcre,shepard,shure,claus,lew,nd,ore,fo,atmost,sessons,lightening,prctiles,atleast,whch,whn,includ,efficency,ony,nam,tha,thre,firt,jus
+#   hask -- local "has key" anonymous-function helper (`hask = @(k) any(strcmp(args,k))`)
+#           in canlab_colormap.m and @fmridisplay/render_layer_surfaces.m
+ignore-words-list = ons,ans,fpr,ttests,myu,whos,ser,htmp,fwe,dout,ttest,indx,alph,te,ist,selt,multy,shft,delt,dum,datin,fixin,runn,nneeded,figurestyle,cxan,losin,commun,pres,ues,assignin,evalin,inout,ment,sepulcre,shepard,shure,claus,lew,nd,ore,fo,atmost,sessons,lightening,prctiles,atleast,whch,whn,includ,efficency,ony,nam,tha,thre,firt,jus,hask

CanlabCore/@image_vector/hansen_neurotransmitter_maps.m

@@ -206,7 +206,7 @@
 end
 
 % -------------------------------------------------------------------------
-% INTIALIZE OUTPUT
+% INITIALIZE OUTPUT
 % -------------------------------------------------------------------------
 stats = struct();
 [hh, hhfill] = deal(' ');

CanlabCore/Statistics_tools/canlab_pattern_similarity.m

@@ -93,8 +93,8 @@
 % By default, data images with values of zero or NaN are considered out-of-mask, as they
 % are not valid values. That is, 0 is typically treated as a missing data value in images
 % This can be changed by setting ['treat_zero_as_data', true].  
-% This function does not exlude 0 voxels from the pattern_mask input, where it is assumed 
-% that 0 is a meaninful value (for a neuromarker or binary mask). 
+% This function does not exclude 0 voxels from the pattern_mask input, where it is assumed 
+% that 0 is a meaningful value (for a neuromarker or binary mask). 
 % Thus, this function treats values of 0 in DATA images, not pattern masks,
 % as missing values, and excludes these voxels from both image and
 % mask when calculating similarity.

CanlabCore/Unit_tests/walkthroughs/private/.!15888!canlab_help_2c_loading_datasets.m

@@ -0,0 +1,158 @@
+%% Datasets used in CANlab tutorials
+%
+% Note: this report was generated from |canlab_help_2c_loading_datasets.m|
+% in the repository <https://github.com/canlab/CANlab_help_examples>
+%
+
+%% The Neuroimaging_pattern_masks Github repository and website
+%
+% For these walkthroughs, we'll load several image datasets.
+% Some are stored in Github, if the files are small enough.
+% The Wager 2008 emotion regulation dataset, for example, is
+% in the CANlab Core repository. Others are on figshare or Neurovault.
+%
+% Many tutorials apply pre-trained patterns and masks. 
+% These are stored in this Github repository:
+% 
+% <https://github.com/canlab/Neuroimaging_Pattern_Masks>
+% 
+% In addition, you can explore these and find more information here:
+% <https://sites.google.com/dartmouth.edu/canlab-brainpatterns/home>
+%
+% To run this tutorial and many others in this series, you'll need to
+% download the Neuroimaging_Pattern_Masks Github repository and add it to
+% your Matlab path with subfolders.
+% The Github site has three main types of datasets, shown here:
+% 
+% <<Neuroimaging_pattern_masks_site.png>>
+%
+%% Registries for easy loading
+% There are several functions that contain sets of images that you can load
+% by name. For example:
+%
+% |load_image_set()| includes a registry of datasets that you can access by
+% name. Try |help load_image|set| for a list of images you can load by
+% keyword.  
+%
+% |load_atlas()| also has a named set of atlases/brain parcellations you can load.
+%
+% |canlab_load_ROI| has a registry of many named regions derived from previous
+% studies. This is particularly useful for loading a subcortical ROI and
+% visualizing it or applying it to data.
+
+%% Emotion regulation dataset
+% "Wager_et_al_2008_Neuron_EmotionReg"
+% The dataset is a series of contrast images from N = 30 participants.
+% Each image is a contrast image for [reappraise neg vs. look neg]
+% 
+% These data were published in:
+% Wager, T. D., Davidson, M. L., Hughes, B. L., Lindquist, M. A., 
+% Ochsner, K. N.. (2008). Prefrontal-subcortical pathways mediating 
+% successful emotion regulation. Neuron, 59, 1037-50.
+%
+% To load, try the following:
+
+[data_obj, subject_names, image_names] = load_image_set('emotionreg', 'noverbose');
+
+montage(mean(data_obj), 'trans', 'compact2');
+drawnow, snapnow
+
+% data_obj is an fmri_data object containing all 30 images.
+% subject_names is a list of short names for each image.
+% image_names is a list of the full image names with their path.
+
+%% Buckner lab resting-state connectivity maps
+%
+% A popular series of masks is a set of "networks" developed from resting-state fMRI
+% connectivity in 1,000 people. For our purposes, the "network" maps
+% consist of a set of voxels that load most highly on each of 7 ICA
+% components from the 1,000 Functional Connectomes project. 
+% These were published by Randy Buckner's lab in 2011 in three papers:
+% Choi et al., Buckner et al., and Yeo et al.  We'll use the cortical
+% networks from Yeo et al. here.
+%
+
+[bucknermaps, mapnames] = load_image_set('bucknerlab', 'noverbose'); % loads 7 masks from Yeo et al.
+disp(char(mapnames))
+
+% Create a montage plot
+o2 = montage(get_wh_image(bucknermaps, 1), 'trans', 'compact2', 'color', rand(1, 3));
+for i = 2:7, o2 = addblobs(o2, region(get_wh_image(bucknermaps, i)), 'trans', 'color', rand(1, 3)); end
+drawnow, snapnow
+
+%% Pain, Cognition, Emotion balanced N = 270 dataset
+%
+% This dataset is an fmri_data object class object created using CANlab tools (canlab.github.io). 
+% It contains 270 single-participant fMRI contrast maps across 18 studies (with 15 participants per study). 
+% Studies are grouped into three domains: Pain, Cognitive Control, and Negative Emotion, with 9 studies each. 
+% Each domain includes 3 subdomains, with 3 studies each.
+%
+% The dataset is from Kragel et al. 2018, Nature Neuroscience. 
+% It is too large for Github, and it's stored on Neurovault.org
+% as collection #504. You could get it using CANlab tools like this:
+%
+% |[files_on_disk, url_on_neurovault, mycollection, myimages] = retrieve_neurovault_collection(504);|
+%
+% It is also available on Figshare, with DOI 10.6084/m9.figshare.24033402
+% https://figshare.com/ndownloader/files/42143352
+%
+% If you download from Neurovault, you'd
+% have to add metadata for the study category labels to use it.
+% Therefore, we suggest you use the CANLab load_image_set() function, as below. 
+% It saves a file on your hard drive the first time you run it:
+% 
+% |kragel_2018_nat_neurosci_270_subjects_test_images.mat|
+%
+% This file also has metadata that is not necessarily on Neurovault.
+% If you save this file somewhere on your Matlab path, you'll be able to
+% reload and reuse the dataset easily.
+
+[test_images, names] = load_image_set('kragel18_alldata', 'noverbose');
+
+% This field contains a table object with metadata for each image:
+metadata = test_images.metadata_table;
+
+disp('Metadata available in test_images.metadata_table:')
+metadata(1:5, :)
+
+% Make a plot of the spatial correlation of the average image for each study
+
+imgs = cellstr(test_images.image_names);
+m = mean(test_images);
+
+for i = 1:length(names)
+
+    % Create a mean image for each study and store in "m" object.
+
+    wh = metadata.Studynumber == i;
+    studymean = mean(get_wh_image(test_images, find(wh)));
+    m.dat(:, i) = studymean.dat;
+
+end
+
+disp('Map of spatial correlations across the mean images for each study');
+
+plot_correlation_matrix(m.dat, 'names', names, 'partitions', [ones(1, 6) 2*ones(1, 6) 3*ones(1, 6)], 'partitionlabels', {'Pain', 'Cognition', 'Emotion'});
+drawnow, snapnow
+
+%% Pain across six intensity levels per person (BMRK3)
+%
+% The dataset contains data from 33 participants, with brain responses to six levels
+% of heat (non-painful and painful). Each image is the average over several
+% (4-8) trials of heat delivered at a single stimulus intensity, ranging
+% from 44.3 - 49.3 degrees C in one-degree increments. Each image is also
+% paired with an average reported pain value for that set of trials, rated
+% immediately after heat experience. 
+%
+% This dataset is interesting for mixed-effects and predictive analyses, as
+% it has both within-person and between-person sources of variance.
+% 
+% Aspects of this data appear in these papers:
+% Wager, T.D., Atlas, L.T., Lindquist, M.A., Roy, M., Choong-Wan, W., Kross, E. (2013). 
+% An fMRI-Based Neurologic Signature of Physical Pain. The New England Journal of Medicine. 368:1388-1397
+% (Study 2)
+%
+% Woo, C. -W., Roy, M., Buhle, J. T. & Wager, T. D. (2015). Distinct brain systems 
+% mediate the effects of nociceptive input and self-regulation on pain. PLOS Biology. 13(1): 
+% e1002036. doi:10.1371/journal.pbio.1002036
+%

CanlabCore/Unit_tests/walkthroughs/private/.!15889!canlab_help_3b_atlases_and_ROI_analysis.m

@@ -0,0 +1,137 @@
+%% Using the atlas object for Region of Interest (ROI) analyses
+
+%% About the atlas object
+% An atlas-class object is a specialized subclass of fmri_data that stores
+% information about a series of parcels, or pre-defined regions, and in
+% some cases the probalistic maps that underlie the final parcellation.
+% 
+% Some common uses of atlas objects include:
+% * Labeling regions by best-matching atlas regions, as in region.table()
+% * Analysis within specific ROIs, or on ROI averages
+% * Defining regions for connectivity and graph theoretic analyses
+%
+% A list of pre-defined atlases is contained in the function |load_atlas|.
+% The default atlas for some CANlab functions is the "CANlab combined 2018"
+% This was created by Tor Wager from other published atlases. It includes:
+%
+% * Glasser 2016 Nature 180-region cortical parcellation (in MNI space, not indivdidualized)
+% * Pauli 2016 PNAS basal ganglia subregions
+% * Amygdala/hippocampal and basal forebrain regions from SPM Anatomy Toolbox
+% * Thalamus regions from the Morel thalamus atlas
+% * Subthalamus/Basal forebrain regions from Pauli "reinforcement learning" HCP atlas
+% * Diedrichsen cerebellar atlas regions
+% * Multiple named brainstem nuclei localized based on individual papers
+% * Additional Shen atlas parcels to cover areas (esp. brainstem) not otherwise named
+%
+% References for the corresponding papers are stored in the atlas object, and 
+% printed in tables generated with the region.table() method.
+%
+% There are many methods for atlas, including all the fmri_data methods.
+% You can see those with |methods(atlas)|. For example:
+%
+% Using the |select_atlas_subset()| method:
+% You can select any subset of atlas regions by name or number, and return
+% them in a new atlas object. You can also 'flatten' regions, combining
+% them into a single new region. 
+%
+% % Using the |extract_data()| method:
+% You can extract average data from every image in an atlas, for a series of target images.
+%
+% We will explore these here.
+
+%% load an atlas
+% 'atlas' objects are a class of objects specially designed for brain
+% atlases. Here is more information on this class (also try |doc atlas|)
+
+help atlas
+
+% The function load_atlas in the CANlab toolbox loads a number of named
+% atlases included with the toolbox.  Here is a list of named atlases:
+
+help load_atlas
+
+% Now load the "CANlab combined 2018" atlas:
+atlas_obj = load_atlas('canlab2018_2mm');
+
+
+%% visualize the atlas regions
+
+orthviews(atlas_obj);
+
+o2 = montage(atlas_obj);
+
+drawnow, snapnow
+%% Selecting regions of interest
+% There are several ways of selecting regions of interest. You can do it:
+% * By name or part of name (in the .labels, .labels_2, or other fields)
+% * By number
+% * Graphically, or by entering a coordinate and a search radius
+
+%% 
+% *Select regions graphically or by coordinate*
+
+% First bring up the orthviews display:
+orthviews(atlas_obj);
+
+% Now click on a coordinate in the center of vmPFC
+% We'll use the SPM code below to do this here:
+
+spm_orthviews('Reposition', [0 38 -11])
+
+% Running this will create a subset atlas containing only regions with centers 
+% within 20 mm of that coordinate.
+
+[obj_within_20mm,index_vals] = select_regions_near_crosshairs(atlas_obj, 'thresh', 20);
+
+orthviews(obj_within_20mm);
+drawnow, snapnow
+
+% To reproduce this later in a script, you can enter the coordinates as
+% input instead:
+
+[obj_within_20mm,index_vals] = select_regions_near_crosshairs(atlas_obj, 'coords', [0 38 -11], 'thresh', 20);
+
+% This function returns index values, so you can use these directly to
+% specify the regions in select_atlas_subset as well.
+
+find(index_vals)
+
+test_obj = select_atlas_subset(atlas_obj, find(index_vals));
+
+% % This should yield the same map of vmPFC regions: orthviews(test_obj)
+
+%% 
+% *Select regions by name*
+% Let's select all the regions in the thalamus. All regions are labeled in
+% the atlas object, so we can select them by name.
+
+% Select all regions with "Thal" in the label:
+thal = select_atlas_subset(atlas_obj, {'Thal'})
+
+% Print the labels:
+thal.labels
+
+% Select a few thalamus/epithalamus regions of interest:
+thal = select_atlas_subset(atlas_obj, {'Thal_Intra', 'Thal_VL', 'Thal_MD', 'Thal_LGN', 'Thal_MGN', 'Thal_Hb'});
+thal.labels
+
+% Select all the regions with "Thal" in the label, and collapse them into a single region:
+whole_thal = select_atlas_subset(atlas_obj, {'Thal'}, 'flatten');
+
+%% Extract and analyze data from atlas regions
+% 
+
+%%
+% First, we'll load a dataset to extract data from for an ROI analysis
+% The dataset contains data from 33 participants, with brain responses to six levels
+% of heat (non-painful and painful).  
+% 
+% Aspects of this data appear in these papers:
+% Wager, T.D., Atlas, L.T., Lindquist, M.A., Roy, M., Choong-Wan, W., Kross, E. (2013). 
+% An fMRI-Based Neurologic Signature of Physical Pain. The New England Journal of Medicine. 368:1388-1397
+% (Study 2)
+%
+% Woo, C. -W., Roy, M., Buhle, J. T. & Wager, T. D. (2015). Distinct brain systems 
+% mediate the effects of nociceptive input and self-regulation on pain. PLOS Biology. 13(1): 
+% e1002036. doi:10.1371/journal.pbio.1002036
+%

CanlabCore/Unit_tests/walkthroughs/private/canlab_help_2b_basic_image_visualization.m

@@ -92,7 +92,7 @@
 % slices, so as to show the "whole picture" and not omit any results.
 %
 % You can customize this a lot, as it uses the fmridisplay() object class,
-% which allows you to add custom montages (in axial, saggital, and coronal 
+% which allows you to add custom montages (in axial, sagittal, and coronal 
 % orientations, add blobs of various types, and remove them and re-plot.
 % See |help fmridisplay| and |help fmridisplay.addblobs| for more details.
 %

CanlabCore/Unit_tests/walkthroughs/private/canlab_help_2c_loading_datasets.m

@@ -1,3 +1,3 @@
 %% Datasets used in CANlab tutorials
 %
 % Note: this report was generated from |canlab_help_2c_loading_datasets.m|
@@ -142,7 +142,7 @@
 % (4-8) trials of heat delivered at a single stimulus intensity, ranging
 % from 44.3 - 49.3 degrees C in one-degree increments. Each image is also
 % paired with an average reported pain value for that set of trials, rated
-% immmediately after heat experience. 
+% immediately after heat experience. 
 %
 % This dataset is interesting for mixed-effects and predictive analyses, as
 % it has both within-person and between-person sources of variance.

CanlabCore/Unit_tests/walkthroughs/private/canlab_help_3b_atlases_and_ROI_analysis.m

@@ -1,3 +1,3 @@
 %% Using the atlas object for Region of Interest (ROI) analyses
 
 %% About the atlas object
@@ -214,8 +214,8 @@
 %
 % With the pain dataset, for a real analysis we might worry that multiple
 % images come from the same subject. We can't do stats across all the
-% iamges without accounting for the correlations among images belonging to
-% the same subject. But first, let's plot the averages and see waht we get:
+% images without accounting for the correlations among images belonging to
+% the same subject. But first, let's plot the averages and see what we get:
 
 % Concatenate the region averages into a matrix:
 roi_averages = cat(2, r.dat);
@@ -306,7 +306,7 @@
 % NAc = select_atlas_subset(atlas_obj, {'V_Str'});
 %
 % 2. try the t-test on 48 degree only images above. What do you see? Which
-% regions show sigificant activation?
+% regions show significant activation?
 %
 % 3. Try to identify which prefrontal regions show the greatest emotion
 % regulation effect, and which show the greatest response during pain.

CanlabCore/Unit_tests/walkthroughs/private/canlab_help_4b_3D_visualization.m

@@ -105,9 +105,9 @@
 %%
 % You can see some prepackaged sets in |help canlab_results_fmridisplay|
 % These include: 
-% 'full'            Axial, coronal, and saggital slices, 4 cortical surfaces
-% 'compact'         Midline saggital and two rows of axial slices [the default] 
-% 'compact2'        A single row showing midline saggital and axial slices
+% 'full'            Axial, coronal, and sagittal slices, 4 cortical surfaces
+% 'compact'         Midline sagittal and two rows of axial slices [the default] 
+% 'compact2'        A single row showing midline sagittal and axial slices
 % 'multirow'        A series of 'compact2' displays in one figure for comparing different images/maps side by side
 % 'regioncenters'   A series of separate axes, each focused on one region
 %

CanlabCore/Unit_tests/walkthroughs/private/canlab_help_5_regression_walkthrough.m

@@ -367,7 +367,7 @@
 % Do a standard OLS regression and view the results:
 out = regress(image_obj_untouched, 'nodisplay');        
 
-% Treshold at q < .05 FDR and display
+% Threshold at q < .05 FDR and display
 t_untouched = threshold(out.t, .05, 'fdr');
 
 o2 = montage(t_untouched);

CanlabCore/Unit_tests/walkthroughs/private/canlab_help_7_multivariate_prediction_basics.m

@@ -1,3 +1,3 @@
 %% Multivariate prediction of a continuous outcome
 
 %%
@@ -17,7 +17,7 @@
 % (4-8) trials of heat delivered at a single stimulus intensity, ranging
 % from 44.3 - 49.3 degrees C in one-degree increments. Each image is also
 % paired with an average reported pain value for that set of trials, rated
-% immmediately after heat experience. 
+% immediately after heat experience. 
 %
 % This dataset is interesting for mixed-effects and predictive analyses, as
 % it has both within-person and between-person sources of variance.