Bootstrap Analysis of Stable Clusters

CPAC.basc.create_basc(name='basc')[source]

Bootstrap Analysis of Stable Clusters (BASC)

This workflow performs group-level BASC.

name : string, optional
Name of the workflow.
basc : nipype.pipeline.engine.Workflow
BASC workflow.

Workflow Inputs:

inputspec.roi : string (nifti file)
    Mask of region(s) of interest
inputpsec.subjects : list (nifti files)
    4-D timeseries of a group of subjects normalized to MNI space
inputspec.dataset_bootstraps : integer
    Number of bootstrap samples of the dataset
inputspec.timeseries_bootstraps : integer
    Number of bootstraps of each subject's timeseries
inputspec.k_clusters : integer
    Number of clusters at both the individiual and group level
inputspec.affinity_threshold : list (floats)
    Minimum threshold for similarity matrix based on correlation to create an edge

Workflow Outputs:

outputspec.gsm : ndarray
    Group stability matrix
outputspec.gsclusters: ndarray
    Matrix partitioning each cluster of the group stability matrix
outputspec.gsmap: ndarray
    Group stability map using gsm and gscluster to calculate average within-cluster stability
outputspec.gsclusters_img : string (nifti file)
    3-D volume of brain regions partitioned with gsclusters
outputspec.gsmap_img : string (nifti file)
    3-D volume of brain regions associated with gs_map
outputspec.ismap_imgs : list of strings (nifti files)
    3-D volumes of stability scores of each cluster based on group clustering

BASC Procedure:

  1. Generate individual stability matrices based on multiple clusterings of each bootstrap sample for a single subject
  2. Use stratified bootstrap to sample new datasets of subjects
  3. Calculate average stability matrix of each new dataset using individual stability matrices generated at step 1
  4. Cluster each average stabiilty matrix
  5. Average to create a group stability matrix
  6. Cluster the group stability matrix
  7. Calculate average within-cluster stability based on the clustering of step 6

Workflow Graph:

workflows/../images/basc.dot.png

Detailed Workflow Graph:

workflows/../images/basc_detailed.dot.png
[1]
  1. Bellec, P. Rosa-Neto, O. C. Lyttelton, H. Benali, and A. C. Evans, “Multi-level bootstrap analysis of stable clusters in resting-state fMRI.,” NeuroImage, vol. 51, no. 3, pp. 1126-39, Jul. 2010.
>>> from CPAC import basc
CPAC.basc.nifti_individual_stability(subject_file, roi_mask_file, n_bootstraps, k_clusters, cbb_block_size=None, affinity_threshold=0.5)[source]

Calculate the individual stability matrix for a single subject by using Circular Block Bootstrapping method for time-series data.

subject_file : string
Nifti file of a subject
roi_mask_file : string
Region of interest (this method is too computationally intensive to perform on a whole-brain volume)
n_bootstraps : integer
Number of bootstraps
k_clusters : integer
Number of clusters
cbb_block_size : integer, optional
Size of the time-series block when performing circular block bootstrap
affinity_threshold : float, optional
Minimum threshold for similarity matrix based on correlation to create an edge
ism : array_like
Individual stability matrix of shape (V, V), V voxels
CPAC.basc.group_stability_matrix(indiv_stability_list, n_bootstraps, k_clusters, stratification=None)[source]

Calculate the group stability matrix of the entire dataset by bootstrapping the dataset

indiv_stability_list : list of strings
A length N list of file paths to numpy matrices of shape (V, V), N subjects, V voxels
n_bootstraps : integer
Number of bootstrap datasets
k_clusters : integer
Number of clusters
stratification : array_like, optional
List of integer entries denoting stratums for indiv_stability_list
G : array_like
Group stability matrix of shape (V, V), V voxels
clusters_G : array_like
Length V array of cluster assignments for each voxel
cluster_voxel_scores : array_like
K by V matrix of within-cluster average values for each cluster of each voxel
CPAC.basc.ndarray_to_vol(data_array, roi_mask_file, sample_file, filename)[source]

Converts a numpy array to a nifti file given an roi mask

data_array : array_like
A data array with the same column length and index alignment as the given roi_mask_file. If data_array is two dimensional, first dimension is considered temporal dimension
roi_mask_file : string
Path of the roi_mask_file
sample_file : string or list of strings
Path of sample nifti file(s) to use for header of the output. If list, the first file is chosen.
filename : string
Name of output file
img_file : string
Path of the nifti file output
CPAC.basc.individual_group_clustered_maps(indiv_stability_list, clusters_G, roi_mask_file)[source]

Calculate the individual stability maps of each subject based on the group stability clustering solution.

indiv_stability_list : list of strings
A length N list of file paths to numpy matrices of shape (V, V), N subjects, V voxels
clusters_G : array_like
Length V array of cluster assignments for each voxel
individual_cluster_voxel_scores : list of strings
A length N list of nifti files of the individual group clustered stability maps for each cluster. Temporal dimension of each file corresponds to each subject.
CPAC.basc.timeseries_bootstrap(tseries, block_size)[source]

Generates a bootstrap sample derived from the input time-series. Utilizes Circular-block-bootstrap method described in [1]_.

tseries : array_like
A matrix of shapes (M, N) with M timepoints and N variables
block_size : integer
Size of the bootstrapped blocks
bseries : array_like
Bootstrap sample of the input timeseries
[1]P. Bellec; G. Marrelec; H. Benali, A bootstrap test to investigate changes in brain connectivity for functional MRI. Statistica Sinica, special issue on Statistical Challenges and Advances in Brain Science, 2008, 18: 1253-1268.
>>> x = np.arange(50).reshape((5,10)).T
>>> sample_bootstrap(x,3)
array([[ 7, 17, 27, 37, 47],
       [ 8, 18, 28, 38, 48],
       [ 9, 19, 29, 39, 49],
       [ 4, 14, 24, 34, 44],
       [ 5, 15, 25, 35, 45],
       [ 6, 16, 26, 36, 46],
       [ 0, 10, 20, 30, 40],
       [ 1, 11, 21, 31, 41],
       [ 2, 12, 22, 32, 42],
       [ 4, 14, 24, 34, 44]])
CPAC.basc.standard_bootstrap(dataset)[source]

Generates a bootstrap sample from the input dataset

dataset : array_like
A matrix of where dimension-0 represents samples
bdataset : array_like
A bootstrap sample of the input dataset
CPAC.basc.cluster_timeseries(X, n_clusters, similarity_metric='k_neighbors', affinity_threshold=0.0, neighbors=10)[source]

Cluster a given timeseries

X : array_like
A matrix of shape (N, M) with N samples and M dimensions
n_clusters : integer
Number of clusters
similarity_metric : {‘k_neighbors’, ‘correlation’, ‘data’}
Type of similarity measure for spectral clustering. The pairwise similarity measure specifies the edges of the similarity graph. ‘data’ option assumes X as the similarity matrix and hence must be symmetric. Default is kneighbors_graph [1]_ (forced to be symmetric)
affinity_threshold : float
Threshold of similarity metric when ‘correlation’ similarity metric is used.
y_pred : array_like
Predicted cluster labels
[1]http://scikit-learn.org/dev/modules/generated/sklearn.neighbors.kneighbors_graph.html
CPAC.basc.adjacency_matrix(cluster_pred)[source]

Calculate adjacency matrix for given cluster predictions

cluster_pred : array_like
A matrix of shape (N, 1) with N samples
A : array_like
Adjacency matrix of shape (N,`N`)
>>> import numpy as np
>>> from CPAC.basc import cluster_adjacency_matrix
>>> x = np.asarray([1, 2, 2, 3, 1])[:,np.newaxis]
>>> cluster_adjacency_matrix(x).astype('int')
array([[1, 0, 0, 0, 1],
       [0, 1, 1, 0, 0],
       [0, 1, 1, 0, 0],
       [0, 0, 0, 1, 0],
       [1, 0, 0, 0, 1]])
CPAC.basc.cluster_matrix_average(M, cluster_assignments)[source]

Calculate the average element value within a similarity matrix for each cluster assignment, a measure of within cluster similarity. Self similarity (diagonal of similarity matrix) is removed.

M : array_like cluster_assignments : array_like

s : array_like

>>> import numpy as np
>>> from CPAC import basc
>>> S = np.arange(25).reshape(5,5)
>>> assign = np.array([0,0,0,1,1])
>>> basc.cluster_matrix_average(S, assign)
array([  6.,   6.,   6.,  21.,  21.])
CPAC.basc.individual_stability_matrix(Y, n_bootstraps, k_clusters, cbb_block_size=None, affinity_threshold=0.5)[source]

Calculate the individual stability matrix of a single subject by bootstrapping their time-series

Y : array_like
A matrix of shape (N, V) with N timepoints and V voxels
n_bootstraps : integer
Number of bootstrap samples
k_clusters : integer
Number of clusters
cbb_block_size : integer, optional
Block size to use for the Circular Block Bootstrap algorithm
affinity_threshold : float, optional
Minimum threshold for similarity matrix based on correlation to create an edge
S : array_like
A matrix of shape (V, V), each element v_{ij} representing the stability of the adjacency of voxel i with voxel j