pynets.fmri package¶
Submodules¶
pynets.fmri.clustering module¶
Created on Tue Nov 7 10:40:07 2017 Copyright (C) 2017
- pynets.fmri.clustering.discretisation(eigen_vec, eps=2.2204e-16)[source]¶
This function performs the second step of normalized cut clustering which assigns features to clusters based on the eigen vectors from the LaPlacian of a similarity matrix. There are a few different ways to perform this task. Shi and Malik (2000) iteratively bisect the features based on the positive and negative loadings of the eigenvectors. Ng, Jordan and Weiss (2001) proposed to perform K-means clustering on the rows of the eigenvectors. The method implemented here was proposed by Yu and Shi (2003) and it finds a discrete solution by iteratively rotating a binarised set of vectors until they are maximally similar to the the eigenvectors. An advantage of this method over K-means is that it is _more_ deterministic, i.e. you should get very similar results every time you run the algorithm on the same data.
The number of clusters that the features are clustered into is determined by the number of eignevectors (number of columns) in the input array eigen_vec. A caveat of this method, is that number of resulting clusters is bound by the number of eignevectors, but it may contain less.
- Parameters
- eigen_vecarray
Eigenvectors of the normalized LaPlacian calculated from the similarity matrix for the corresponding clustering problem.
- Returns
- eigen_vec_discretearray
Discretised eigenvector outputs, i.e. vectors of 0 and 1 which indicate whether or not a feature belongs to the cluster defined by the eigen vector. e.g. a one in the 10th row of the 4th eigenvector (column) means that feature 10 belongs to cluster #4.
References
- 1
Stella Yu and Jianbo Shi, “Understanding Popout through Repulsion,” Computer Vision and Pattern Recognition, December, 2001.
- 2
Shi, J., & Malik, J. (2000). Normalized cuts and image segmentation. IEEE Transactions on Pattern Analysis and Machine Intelligence, 22(8), 888-905. doi: 10.1109/34.868688.
- 3
Yu, S. X., & Shi, J. (2003). Multiclass spectral clustering. Proceedings Ninth IEEE International Conference on Computer Vision, (1), 313-319 vol.1. Ieee. doi: 10.1109/ICCV.2003.1238361
- pynets.fmri.clustering.indx_1dto3d(idx, sz)[source]¶
- Translate 1D vector coordinates to 3D matrix coordinates for a 3D matrix
of size sz.
- Parameters
- idxarray
A 1D numpy coordinate vector.
- szarray
Shape of 3D matrix idx.
- Returns
- xint
x-coordinate of 3D matrix coordinates.
- yint
y-coordinate of 3D matrix coordinates.
- zint
z-coordinate of 3D matrix coordinates.
- pynets.fmri.clustering.indx_3dto1d(idx, sz)[source]¶
- Translate 3D matrix coordinates to 1D vector coordinates for a 3D matrix
of size sz.
- Parameters
- idxarray
A 3D numpy array of matrix coordinates.
- szarray
Shape of 3D matrix idx.
- Returns
- idx1array
A 1D numpy coordinate vector.
- pynets.fmri.clustering.make_local_connectivity_scorr(func_img, clust_mask_img, thresh)[source]¶
Constructs a spatially constrained connectivity matrix from a fMRI dataset. The weights w_ij of the connectivity matrix W correspond to the spatial correlation between the whole brain FC maps generated from the time series from voxel i and voxel j. Connectivity is only calculated between a voxel and the 27 voxels in its 3D neighborhood (face touching and edge touching).
- Parameters
- func_imgNifti1Image
4D Nifti1Image containing fMRI data.
- clust_mask_imgNifti1Image
3D NIFTI file containing a mask, which restricts the voxels used in the analysis.
- threshstr
Threshold value, correlation coefficients lower than this value will be removed from the matrix (set to zero).
- Returns
- WCompressed Sparse Matrix
A Scipy sparse matrix, with weights corresponding to the spatial correlation between the time series from voxel i and voxel j
References
- 1
Craddock, R. C., James, G. A., Holtzheimer, P. E., Hu, X. P., & Mayberg, H. S. (2012). A whole brain fMRI atlas generated via spatially constrained spectral clustering. Human Brain Mapping. https://doi.org/10.1002/hbm.21333
- pynets.fmri.clustering.make_local_connectivity_tcorr(func_img, clust_mask_img, thresh)[source]¶
Constructs a spatially constrained connectivity matrix from a fMRI dataset. The weights w_ij of the connectivity matrix W correspond to the temporal correlation between the time series from voxel i and voxel j. Connectivity is only calculated between a voxel and the 27 voxels in its 3D neighborhood (face touching and edge touching).
- Parameters
- func_imgNifti1Image
4D Nifti1Image containing fMRI data.
- clust_mask_imgNifti1Image
3D NIFTI file containing a mask, which restricts the voxels used in the analysis.
- threshstr
Threshold value, correlation coefficients lower than this value will be removed from the matrix (set to zero).
- Returns
- WCompressed Sparse Matrix
A Scipy sparse matrix, with weights corresponding to the temporal correlation between the time series from voxel i and voxel j
References
- 1
Craddock, R. C., James, G. A., Holtzheimer, P. E., Hu, X. P., & Mayberg, H. S. (2012). A whole brain fMRI atlas generated via spatially constrained spectral clustering. Human Brain Mapping. https://doi.org/10.1002/hbm.21333
- pynets.fmri.clustering.ncut(W, nbEigenValues, offset=0.5, maxiterations=100, eigsErrorTolerence=1e-06, eps=2.2204e-16)[source]¶
This function performs the first step of normalized cut spectral clustering. The normalized LaPlacian is calculated on the similarity matrix W, and top nbEigenValues eigenvectors are calculated. The number of eigenvectors corresponds to the maximum number of classes (K) that will be produced by the clustering algorithm.
- Parameters
- Warray
Numpy array containing a symmetric #feature x #feature sparse matrix representing the similarity between voxels, traditionally this matrix should be positive semidefinite, but regularization is employed to allow negative matrix entries (Yu 2001).
- nbEigenValuesint
Number of eigenvectors that should be calculated, this determines the maximum number of clusters (K) that can be derived from the result.
- Returns
- eigen_valarray
Eigenvalues from the eigen decomposition of the LaPlacian of W.
- eigen_vecarray
Eigenvectors from the eigen decomposition of the LaPlacian of W.
References
- 1
Stella Yu and Jianbo Shi, “Understanding Popout through Repulsion,” Computer Vision and Pattern Recognition, December, 2001.
- 2
Shi, J., & Malik, J. (2000). Normalized cuts and image segmentation. IEEE Transactions on Pattern Analysis and Machine Intelligence, 22(8), 888-905. doi: 10.1109/34.868688.
- 3
Yu, S. X., & Shi, J. (2003). Multiclass spectral clustering. Proceedings Ninth IEEE International Conference on Computer Vision, (1), 313-319 vol.1. Ieee. doi: 10.1109/ICCV.2003.1238361
- pynets.fmri.clustering.parcellate(func_boot_img, local_corr, clust_type, _local_conn_mat_path, num_conn_comps, _clust_mask_corr_img, _standardize, _detrending, k, _local_conn, conf, _dir_path, _conn_comps)[source]¶
API for performing any of a variety of clustering routines available through NiLearn.
- pynets.fmri.clustering.parcellate_ncut(W, k, mask_img)[source]¶
Converts a connectivity matrix into a nifti file where each voxel intensity corresponds to the number of the cluster to which it belongs. Clusters are renumberd to be contiguous.
- Parameters
- WCompressed Sparse Matrix
A Scipy sparse matrix, with weights corresponding to the temporal/spatial correlation between the time series from voxel i and voxel j.
- kint
Numbers of clusters that will be generated.
- mask_imgNifti1Image
3D NIFTI file containing a mask, which restricts the voxels used in the analysis.
References
- 1
Craddock, R. C., James, G. A., Holtzheimer, P. E., Hu, X. P., & Mayberg, H. S. (2012). A whole brain fMRI atlas generated via spatially constrained spectral clustering. Human Brain Mapping. https://doi.org/10.1002/hbm.21333
pynets.fmri.estimation module¶
Created on Tue Nov 7 10:40:07 2017 Copyright (C) 2017
- pynets.fmri.estimation.fill_confound_nans(confounds, dir_path, drop_thr=0.5)[source]¶
Fill the NaN values of a confounds dataframe with mean values
- pynets.fmri.estimation.get_conn_matrix(time_series, conn_model, dir_path, node_radius, smooth, dens_thresh, subnet, ID, roi, min_span_tree, disp_filt, parc, prune, atlas, parcellation, labels, coords, norm, binary, hpass, signal)[source]¶
Computes a functional connectivity matrix based on a node-extracted time-series array. Includes a library of routines across Nilearn, scikit-learn, and skggm packages, among others.
- Parameters
- time_seriesarray
2D m x n array consisting of the time-series signal for each ROI node where m = number of scans and n = number of ROI’s.
- conn_modelstr
Connectivity estimation model (e.g. corr for correlation, cov for covariance, sps for precision covariance, partcorr for partial correlation). sps type is used by default.
- dir_pathstr
Path to directory containing subject derivative data for given run.
- node_radiusint
Spherical centroid node size in the case that coordinate-based centroids are used as ROI’s.
- smoothint
Smoothing width (mm fwhm) to apply to time-series when extracting signal from ROI’s.
- dens_threshbool
Indicates whether a target graph density is to be used as the basis for thresholding.
- subnetstr
Resting-state subnet based on Yeo-7 and Yeo-17 naming (e.g. ‘Default’) used to filter nodes in the study of brain subgraphs.
- IDstr
A subject id or other unique identifier.
- roistr
File path to binarized/boolean region-of-interest Nifti1Image file.
- min_span_treebool
Indicates whether local thresholding from the Minimum Spanning Tree should be used.
- disp_filtbool
Indicates whether local thresholding using a disparity filter and ‘backbone subnet’ should be used.
- parcbool
Indicates whether to use parcels instead of coordinates as ROI nodes.
- prunebool
Indicates whether to prune final graph of disconnected nodes/isolates.
- atlasstr
Name of atlas parcellation used.
- parcellationstr
File path to atlas parcellation Nifti1Image in MNI template space.
- labelslist
List of string labels corresponding to ROI nodes.
- coordslist
List of (x, y, z) tuples corresponding to a coordinate atlas used or which represent the center-of-mass of each parcellation node.
- normint
Indicates method of normalizing resulting graph.
- binarybool
Indicates whether to binarize resulting graph edges to form an unweighted graph.
- hpassbool
High-pass filter values (Hz) to apply to node-extracted time-series.
- signalstr
The name of a valid function used to reduce the time-series region extraction.
- Returns
- conn_matrixarray
Adjacency matrix stored as an m x n array of nodes and edges.
- conn_modelstr
Connectivity estimation model (e.g. corr for correlation, cov for covariance, sps for precision covariance, partcorr for partial correlation). sps type is used by default.
- dir_pathstr
Path to directory containing subject derivative data for given run.
- node_radiusint
Spherical centroid node size in the case that coordinate-based centroids are used as ROI’s for tracking.
- smoothint
Smoothing width (mm fwhm) to apply to time-series when extracting signal from ROI’s.
- dens_threshbool
Indicates whether a target graph density is to be used as the basis for thresholding.
- subnetstr
Resting-state subnet based on Yeo-7 and Yeo-17 naming (e.g. ‘Default’) used to filter nodes in the study of brain subgraphs.
- IDstr
A subject id or other unique identifier.
- roistr
File path to binarized/boolean region-of-interest Nifti1Image file.
- min_span_treebool
Indicates whether local thresholding from the Minimum Spanning Tree should be used.
- disp_filtbool
Indicates whether local thresholding using a disparity filter and ‘backbone subnet’ should be used.
- parcbool
Indicates whether to use parcels instead of coordinates as ROI nodes.
- prunebool
Indicates whether to prune final graph of disconnected nodes/isolates.
- atlasstr
Name of atlas parcellation used.
- parcellationstr
File path to atlas parcellation Nifti1Image in MNI template space.
- labelslist
List of string labels corresponding to graph nodes.
- coordslist
List of (x, y, z) tuples corresponding to a coordinate atlas used or which represent the center-of-mass of each parcellation node.
- normint
Indicates method of normalizing resulting graph.
- binarybool
Indicates whether to binarize resulting graph edges to form an unweighted graph.
- hpassbool
High-pass filter values (Hz) to apply to node-extracted time-series.
- signalstr
The name of a valid function used to reduce the time-series region extraction.
References
- 1
Varoquaux, G., & Craddock, R. C. (2013). Learning and comparing functional connectomes across subjects. NeuroImage. https://doi.org/10.1016/j.neuroimage.2013.04.007
- 2
Jason Laska, Manjari Narayan, 2017. skggm 0.2.7: A scikit-learn compatible package for Gaussian and related Graphical Models. doi:10.5281/zenodo.830033
- pynets.fmri.estimation.timeseries_bootstrap(tseries, block_size)[source]¶
Generates a bootstrap sample derived from the input time-series. Utilizes Circular-block-bootstrap method described in [1].
- Parameters
- tseriesarray_like
A matrix of shapes (M, N) with M timepoints and N variables
- block_sizeinteger
Size of the bootstrapped blocks
- Returns
- bseriesarray_like
Bootstrap sample of the input timeseries
References
- 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.