API¶

A tutorial-like presentation is available at Examples using API, using the following API:

API Reference¶

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.

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.

multi_edge.extract_multiedge(subject_id_list, input_dir, base_feature_list=('freesurfer_thickness', 'freesurfer_curv'), weight_method_list=('manhattan',), summary_stats=('prod', 'median'), num_bins=25, edge_range_dict={'freesurfer_area': (0.0, 1.5), 'freesurfer_curv': (-0.3, 0.3), 'freesurfer_sulc': (-1.5, 1.5), 'freesurfer_thickness': (0.0, 5.0)}, atlas='fsaverage', smoothing_param=10, node_size=None, out_dir=None, return_results=False, overwrite_results=False, num_procs=2)[source]¶

Extracts weighted networks (matrix of pair-wise ROI distances) based on multiple 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. This can be Freesurfer’s SUBJECTS_DIR, where output processing is stored. Or another directory with a structure that graynet can parse.

base_feature_listlist

Set of features that drive the different edges between the pair of ROIs.

For example, if you choose thickness and pial_curv, each pair of ROIs will have two edges.

This multi-edge network can be turned into a single network based on averaging weights from different individual networks, or computing another summary statistic of your interest.

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’.

summary_statslist of str

A string, or list of strings, each representing a method: (like ‘median’, ‘prod’ or ‘max’),

to compute a summay statistic from the array of multiple weights computed.

This must be available as a member of numpy or scipy.stats.

num_binsint

Number of histogram bins to use when computing pair-wise weights. Default : 25

edge_range_dicttuple 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 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_list. 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, 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.

overwrite_resultsbool

Flag to request overwriting of existing results, in case of reruns/failed jobs. By default, if the expected output file exists and is of non-zero size, its computation is skipped (assuming the file is complete, usable and not corrupted).

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 0.5.4 documentation

API¶

API Reference¶

Table of Contents

Previous topic

Next topic

This Page