graynet package¶
Submodules¶
graynet.freesurfer module¶
graynet.parcellate module¶
Module with handling the parcellation of different cortical atlases.
- graynet.parcellate.freesurfer_roi_labels(atlas_name, node_size=None)[source]¶
- Returns just the vertex-wise indices for grouping the vertices into ROIs.
Order: left followed by right.
- graynet.parcellate.get_atlas_annot(atlas_name=None)[source]¶
High level wrapper to get all the info just by using a name.
- graynet.parcellate.get_atlas_path(atlas_name=None)[source]¶
Validates the atlas name and returns its location
- graynet.parcellate.load_subdivision_patchwise(atlas_name, min_vtx_per_patch=100)[source]¶
Loads a precomputed subdivision of the cortex Originally generated in Matlab based on k-means clustering (Raamana PhD thesis);
adaptive subdivision ensuring a specified minimum number of vertices per patch
more details –> graynet/scripts/export_precomputed_ctx_parc_in_numpy_format.py
- graynet.parcellate.read_freesurfer_atlas(atlas_spec, hemi_list=None)[source]¶
Script to read the pre-computed parcellations for fsaverage and HCP-MMP-1.0
graynet.run_workflow module¶
- graynet.run_workflow.extract(subject_id_list, input_dir, base_feature=('freesurfer_thickness',), weight_method_list=('manhattan',), num_bins=25, edge_range=None, atlas='fsaverage', smoothing_param=10, node_size=None, out_dir=None, return_results=False, num_procs=2)[source]¶
Extracts weighted networks (matrix of pair-wise ROI distances) from gray matter features based on Freesurfer processing.
- Parameters:
- subject_id_liststr or list
must be path to a file containing subject IDs, or a list of subject IDs
- input_dirstr
Path to the input directory where features can be read. For example, this can be Freesurfer’s SUBJECTS_DIR, where output processing is stored. Or another directory with a structure that graynet can parse.
- base_featurestr
Specific type of feature to read for each subject from the input directory.
- weight_method_liststring(s), optional
Type of distance (or metric) to compute between the pair of histograms.
It must be one of the following methods:
‘chebyshev’
‘chebyshev_neg’
‘chi_square’
‘correlate’
‘correlate_1’
‘cosine’
‘cosine_1’
‘cosine_2’
‘cosine_alt’
‘euclidean’
‘fidelity_based’
‘histogram_intersection’
‘histogram_intersection_1’
‘jensen_shannon’
‘kullback_leibler’
‘manhattan’
‘minowski’
‘noelle_1’
‘noelle_2’
‘noelle_3’
‘noelle_4’
‘noelle_5’
‘relative_bin_deviation’
‘relative_deviation’
Note only the following are metrics:
‘manhattan’
‘minowski’
‘euclidean’
‘noelle_2’
‘noelle_4’
‘noelle_5’
The following are semi- or quasi-metrics:
‘kullback_leibler’
‘jensen_shannon’
‘chi_square’
‘chebyshev’
‘cosine_1’
‘chebyshev_neg’
‘correlate_1’
‘histogram_intersection_1’
‘relative_deviation’
‘relative_bin_deviation’
‘noelle_1’
‘noelle_3’
The following are classified to be similarity functions:
‘histogram_intersection’
‘correlate’
‘cosine’
‘cosine_2’
‘cosine_alt’
‘fidelity_based’
Default choice: ‘manhattan’.
- num_binsint
Number of histogram bins to use when computing pair-wise weights. Default: 25
- edge_rangetuple or list
The range of edges (two finite values) within which to build the histogram e.g.,
--edge_range 0 5. This can be helpful (and important) to ensure correspondence across multiple invocations of graynet (e.g. for different subjects), in terms of range across all bins as well as individual bin edges.Default :
( 0.0, 5.0) for
freesurfer_thicknessand(-0.3, 0.3) for
freesurfer_curv.
- atlasstr
Name of the atlas whose parcellation to be used. Choices for cortical parcellation: [‘fsaverage’, ‘glasser2016’], which are primary cortical. Volumetric whole-brain atlases will be added soon.
- smoothing_paramscalar
Smoothing parameter, which could be fwhm for Freesurfer cortical features, or another relevant for the chosen base_feature. Default: assumed as fwhm=10mm for the default feature choice ‘thickness’
- node_sizescalar, optional
Parameter to indicate the size of the ROIs, subparcels or patches, depending on type of atlas or feature. This feature is not implemented yet, and this arg is just a placeholder and to enable default computation.
- out_dirPath or str, optional
Path to output directory to store results. Default: None, results are returned, but not saved to disk. If this is None, return_results must be true.
- return_resultsbool
Flag to indicate whether to return the results to be returned. This flag helps to reduce the memory requirements, when the number of nodes in a parcellation or the number of subjects or weight methods are large, as it doesn’t retain results for all combinations, when running from commmand line interface (or HPC). Default: False If this is False, out_dir must be specified to save the results to disk.
- num_procsint
Number of parallel processes to use to speed up computation.
- Returns:
- edge_weights_alldict, None
If return_results is True, this will be a dictionary keyed in by a tuple: (weight method, subject_ID) The value of each edge_weights_all[(weight method, subject_ID)] is a numpy array of length p = k*(k-1)/2, with k = number of nodes in the atlas parcellation. If return_results is False, this will be None, which is the default.
- graynet.run_workflow.roiwise_stats_indiv(subject_id_list, input_dir, base_feature=('freesurfer_thickness',), chosen_roi_stats='median', atlas='fsaverage', smoothing_param=10, node_size=None, out_dir=None, return_results=False)[source]¶
Computes the chosen summary statistics within each ROI. These summary stats (such as median) can help serve as a baseline for network-level values produced by graynet.
Options for summary statistics include ‘median’, ‘entropy’, ‘kurtosis’ and any other appropriate summary statistics listed under scipy.stats: https://docs.scipy.org/doc/scipy/reference/stats.html#statistical-functions
- Parameters:
- subject_id_liststr or list
must be path to a file containing subject IDs, or a list of subject IDs
- input_dirstr
Path to the input directory where features can be read. For example, this can be Freesurfer’s SUBJECTS_DIR, where output processing is stored. Or another directory with a structure that graynet can parse.
- base_featurestr
Specific type of feature to read for each subject from the input directory.
- chosen_roi_statslist of str or callable
If requested, graynet will compute chosen summary statistics (such as median) within each ROI of the chosen parcellation (and network weight computation is skipped). Default: ‘median’. Supported summary statistics include ‘median’, ‘mode’, ‘mean’, ‘std’, ‘gmean’, ‘hmean’, ‘variation’, ‘entropy’, ‘skew’ and ‘kurtosis’
Other appropriate summary statistics listed under scipy.stats could used by passing in a callable with their parameters encapsulated: https://docs.scipy.org/doc/scipy/reference/stats.html#statistical-functions For example, if you would like to compute 3rd k-statistic, you could construct a callable and passing
third_kstatas in the argument:third_kstat = lambda array: scipy.stats.kstat(array, n = 3) roi_medians = roiwise_stats_indiv(subject_id_list, fs_dir, base_feature, chosen_measure = third_kstat, atlas, fwhm, out_dir=None, return_results=True)
Other possible options could trimmed mean estimator with 5% outliers removed or 3rd k-statistic: .. code-block:: python
trimmed_mean = lambda array: scipy.stats.trim_mean(array, proportiontocut = 0.05) third_kstat = lambda array: scipy.stats.kstat(array, n = 3)
Notes: ‘hmean’ requires all values be positive.
- atlasstr
Name of the atlas whose parcellation to be used. Available choices for cortical parcellation: [‘fsaverage’, ‘glasser2016’]. Volumetric whole-brain atlases will be added soon.
- smoothing_paramscalar
Smoothing parameter, which could be fwhm for Freesurfer cortical features, or another relevant for the chosen base_feature. Default: assumed as fwhm=10mm for the default feature choice ‘thickness’
- node_sizescalar, optional
Parameter to indicate the size of the ROIs, subparcels or patches, depending on type of atlas or feature. NOT implemented yet.
- out_dirstr, optional
Path to output directory to store results. Default: None, results are returned, but not saved to disk. If this is None, return_results must be true.
- return_resultsbool
Flag to indicating whether to keep the results to be returned to caller method. Helps to save memory (as it doesn’t retain results all subjects and weight combinations), when running from command line interface (or HPC). Default: False If this is False, out_dir must be specified to save the results to disk.
- Returns:
- roi_stats_alldict, None
If return_results is True, this will be a dictionary keyed in by subject_ID The value of each key roi_summary_all[subject] is a numpy array of length k, with k = number of nodes in the atlas parcellation. If return_results is False, this will be None, which is the default.
Module contents¶
- graynet.draw3Dnx(graph=None, out_path=None, perc_threshold=None, positions_array=None, positions_dict=None, plot_title='', plot_description='', colorscale='Set3', notebook_mode=True, auto_open=False)[source]¶
Draws a given graph in 3D
- graynet.extract(subject_id_list, input_dir, base_feature=('freesurfer_thickness',), weight_method_list=('manhattan',), num_bins=25, edge_range=None, atlas='fsaverage', smoothing_param=10, node_size=None, out_dir=None, return_results=False, num_procs=2)[source]¶
Extracts weighted networks (matrix of pair-wise ROI distances) from gray matter features based on Freesurfer processing.
- Parameters:
- subject_id_liststr or list
must be path to a file containing subject IDs, or a list of subject IDs
- input_dirstr
Path to the input directory where features can be read. For example, this can be Freesurfer’s SUBJECTS_DIR, where output processing is stored. Or another directory with a structure that graynet can parse.
- base_featurestr
Specific type of feature to read for each subject from the input directory.
- weight_method_liststring(s), optional
Type of distance (or metric) to compute between the pair of histograms.
It must be one of the following methods:
‘chebyshev’
‘chebyshev_neg’
‘chi_square’
‘correlate’
‘correlate_1’
‘cosine’
‘cosine_1’
‘cosine_2’
‘cosine_alt’
‘euclidean’
‘fidelity_based’
‘histogram_intersection’
‘histogram_intersection_1’
‘jensen_shannon’
‘kullback_leibler’
‘manhattan’
‘minowski’
‘noelle_1’
‘noelle_2’
‘noelle_3’
‘noelle_4’
‘noelle_5’
‘relative_bin_deviation’
‘relative_deviation’
Note only the following are metrics:
‘manhattan’
‘minowski’
‘euclidean’
‘noelle_2’
‘noelle_4’
‘noelle_5’
The following are semi- or quasi-metrics:
‘kullback_leibler’
‘jensen_shannon’
‘chi_square’
‘chebyshev’
‘cosine_1’
‘chebyshev_neg’
‘correlate_1’
‘histogram_intersection_1’
‘relative_deviation’
‘relative_bin_deviation’
‘noelle_1’
‘noelle_3’
The following are classified to be similarity functions:
‘histogram_intersection’
‘correlate’
‘cosine’
‘cosine_2’
‘cosine_alt’
‘fidelity_based’
Default choice: ‘manhattan’.
- num_binsint
Number of histogram bins to use when computing pair-wise weights. Default: 25
- edge_rangetuple or list
The range of edges (two finite values) within which to build the histogram e.g.,
--edge_range 0 5. This can be helpful (and important) to ensure correspondence across multiple invocations of graynet (e.g. for different subjects), in terms of range across all bins as well as individual bin edges.Default :
( 0.0, 5.0) for
freesurfer_thicknessand(-0.3, 0.3) for
freesurfer_curv.
- atlasstr
Name of the atlas whose parcellation to be used. Choices for cortical parcellation: [‘fsaverage’, ‘glasser2016’], which are primary cortical. Volumetric whole-brain atlases will be added soon.
- smoothing_paramscalar
Smoothing parameter, which could be fwhm for Freesurfer cortical features, or another relevant for the chosen base_feature. Default: assumed as fwhm=10mm for the default feature choice ‘thickness’
- node_sizescalar, optional
Parameter to indicate the size of the ROIs, subparcels or patches, depending on type of atlas or feature. This feature is not implemented yet, and this arg is just a placeholder and to enable default computation.
- out_dirPath or str, optional
Path to output directory to store results. Default: None, results are returned, but not saved to disk. If this is None, return_results must be true.
- return_resultsbool
Flag to indicate whether to return the results to be returned. This flag helps to reduce the memory requirements, when the number of nodes in a parcellation or the number of subjects or weight methods are large, as it doesn’t retain results for all combinations, when running from commmand line interface (or HPC). Default: False If this is False, out_dir must be specified to save the results to disk.
- num_procsint
Number of parallel processes to use to speed up computation.
- Returns:
- edge_weights_alldict, None
If return_results is True, this will be a dictionary keyed in by a tuple: (weight method, subject_ID) The value of each edge_weights_all[(weight method, subject_ID)] is a numpy array of length p = k*(k-1)/2, with k = number of nodes in the atlas parcellation. If return_results is False, this will be None, which is the default.
- graynet.read_freesurfer_atlas(atlas_spec, hemi_list=None)[source]¶
Script to read the pre-computed parcellations for fsaverage and HCP-MMP-1.0
- graynet.roiwise_stats_indiv(subject_id_list, input_dir, base_feature=('freesurfer_thickness',), chosen_roi_stats='median', atlas='fsaverage', smoothing_param=10, node_size=None, out_dir=None, return_results=False)[source]¶
Computes the chosen summary statistics within each ROI. These summary stats (such as median) can help serve as a baseline for network-level values produced by graynet.
Options for summary statistics include ‘median’, ‘entropy’, ‘kurtosis’ and any other appropriate summary statistics listed under scipy.stats: https://docs.scipy.org/doc/scipy/reference/stats.html#statistical-functions
- Parameters:
- subject_id_liststr or list
must be path to a file containing subject IDs, or a list of subject IDs
- input_dirstr
Path to the input directory where features can be read. For example, this can be Freesurfer’s SUBJECTS_DIR, where output processing is stored. Or another directory with a structure that graynet can parse.
- base_featurestr
Specific type of feature to read for each subject from the input directory.
- chosen_roi_statslist of str or callable
If requested, graynet will compute chosen summary statistics (such as median) within each ROI of the chosen parcellation (and network weight computation is skipped). Default: ‘median’. Supported summary statistics include ‘median’, ‘mode’, ‘mean’, ‘std’, ‘gmean’, ‘hmean’, ‘variation’, ‘entropy’, ‘skew’ and ‘kurtosis’
Other appropriate summary statistics listed under scipy.stats could used by passing in a callable with their parameters encapsulated: https://docs.scipy.org/doc/scipy/reference/stats.html#statistical-functions For example, if you would like to compute 3rd k-statistic, you could construct a callable and passing
third_kstatas in the argument:third_kstat = lambda array: scipy.stats.kstat(array, n = 3) roi_medians = roiwise_stats_indiv(subject_id_list, fs_dir, base_feature, chosen_measure = third_kstat, atlas, fwhm, out_dir=None, return_results=True)
Other possible options could trimmed mean estimator with 5% outliers removed or 3rd k-statistic: .. code-block:: python
trimmed_mean = lambda array: scipy.stats.trim_mean(array, proportiontocut = 0.05) third_kstat = lambda array: scipy.stats.kstat(array, n = 3)
Notes: ‘hmean’ requires all values be positive.
- atlasstr
Name of the atlas whose parcellation to be used. Available choices for cortical parcellation: [‘fsaverage’, ‘glasser2016’]. Volumetric whole-brain atlases will be added soon.
- smoothing_paramscalar
Smoothing parameter, which could be fwhm for Freesurfer cortical features, or another relevant for the chosen base_feature. Default: assumed as fwhm=10mm for the default feature choice ‘thickness’
- node_sizescalar, optional
Parameter to indicate the size of the ROIs, subparcels or patches, depending on type of atlas or feature. NOT implemented yet.
- out_dirstr, optional
Path to output directory to store results. Default: None, results are returned, but not saved to disk. If this is None, return_results must be true.
- return_resultsbool
Flag to indicating whether to keep the results to be returned to caller method. Helps to save memory (as it doesn’t retain results all subjects and weight combinations), when running from command line interface (or HPC). Default: False If this is False, out_dir must be specified to save the results to disk.
- Returns:
- roi_stats_alldict, None
If return_results is True, this will be a dictionary keyed in by subject_ID The value of each key roi_summary_all[subject] is a numpy array of length k, with k = number of nodes in the atlas parcellation. If return_results is False, this will be None, which is the default.