graynet package

Submodules

graynet.freesurfer module

graynet.freesurfer.get_data(fs_dir, subject_id, base_feature, fwhm=10, atlas='fsaverage')[source]

Reads the specified features from both hemispheres for a given subject.

graynet.freesurfer.import_features(fs_dir, subject_list, base_feature='freesurfer_thickness', fwhm=10, atlas='fsaverage')[source]

Reads features after ensuring subjects are provided and their data exist.

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_atlas_annot(atlas_dir, hemi_list=None)[source]

Returns atlas annotations

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.parcellate.roi_labels_centroids(atlas_name, node_size=None)[source]

Returns a list of ROI centroids, for use in visualizations (nodes on a network)

graynet.parcellate.subdivide_cortex(atlas_dir, hemi_list=None)[source]

Subdivides the given cortical parcellation (each label into smaller patches)

graynet.run_workflow module

graynet.run_workflow.cli_run()[source]

command line interface!

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_thickness and

  • (-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_kstat as 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.cli_run()[source]

command line interface!

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_thickness and

  • (-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_kstat as 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.