Command line interface

The command line interface for graynet (preferred interface, given its target is HPC) is shown below. Check the bottom of this page for examples.

usage: graynet [-h] [-s SUBJECT_IDS_PATH] -i INPUT_DIR [-f [FEATURES ...]] [-o OUT_DIR] [-w [WEIGHT_METHODS ...]] [-r [ROI_STATS ...]] [-m] [-b NUM_BINS] [-e min max]
               [-t [SUMMARY_STAT ...]] [-l [min max ...]] [-a ATLAS] [-n NODE_SIZE] [-p SMOOTHING_PARAM] [-c NUM_PROCS] [-d] [-v]

Named Arguments

-s, --subject_ids_path

Path to file containing list of subject IDs (one per line)

-i, --input_dir

Path to a folder containing input data. It could, for example, be a Freesurfer SUBJECTS_DIR, if the chosen feature is from Freesurfer output.

-f, --feature

Type of feature to be used for analysis.

Default: freesurfer_thickness

Choices: freesurfer_thickness, freesurfer_sulc, freesurfer_curv, freesurfer_area, freesurfer_pial_area, freesurfer_pial_lgi, freesurfer_jacobian_white, freesurfer_volume, gmdensity, spm_cat_gmdensity, spm_cat_wmdensity

-o, --out_dir

Where to save the extracted features.

Type of computation

Choose one among single edge, multiedge or simply ROI stats.

-w, --weight_method

List of methods used to estimate the weight of the edge between the pair of nodes.

Default : manhattan.

Available options:

histogram-based: 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, sorensen_dist

weights on original features : diff_medians, diff_medians_abs, diff_means, diff_means_abs, exp_diff_means_norm_std, ranksum_statistic

-r, --roi_stats

Option to compute summary statistics within each ROI of the chosen parcellation. These statistics (such as the median) can 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 . When this option is chosen, network computation is not allowed. You need to compute networks and ROI stats separately.

-m, --do_multi_edge

Option to compute multiple edges between ROIs based on different features. Default False. If True, two valid features must be specified. Use –multi_edge_range to specify edge ranges for each feature to be processed.

Weight parameters

Parameters relevant to histogram edge weight calculations

-b, --num_bins

Number of bins used to construct the histogram within each ROI or group. Default : 25

-e, --edge_range

The range of edges (two finite values) within which to bin the given values e.g. --edge_range 0.0 5.0 .Setting this is crucial to ensure correspondence across multiple invocations of graynet, for different subjects, in terms of range across all bins as well as individual bin edges.

Default : None, to automatically compute from the given values.

Multi-edge

Parameters related to computation of multiple edges

-t, --summary_stat

Summary statistic [one or more] to compute on all the weights from multiple edges.This must be a string representing a method (like ‘median’, ‘prod’ or ‘max’), that is available as a member of numpy or scipy.stats.

-l, --multi_edge_range

Set of edge ranges (for each of the features)

within which to bin the given values - see above. For example,

-f freesurfer_thickness freesurfer_curv --edge_range 0.0 5.0 -0.3 +0.3

will set the a range of [0.0, 5.0] for thickness and [-0.3, 0.3] for curv.

Default : {‘freesurfer_thickness’: (0.0, 5.0), ‘freesurfer_curv’: (-0.3, 0.3), ‘freesurfer_sulc’: (-1.5, 1.5), ‘freesurfer_area’: (0.0, 1.5)}.

Atlas

Parameters describing the atlas, its parcellation and any smoothing of features.

-a, --atlas

Name or path to atlas to containing the parcellation of ROIs. For cortical features, you can also specify the absolute path for the Freesurfer parcellation of that atlas. This directory must have the standard Freesurfer structure, with the following key files that must exist: label/?h.aparc.annot and surf/?h.orig.

Cortical atlases supported: fsaverage and glasser2016. In addition, you can also specify an absolute path to the Freesurfer processing of any arbitrary atlas. Read these instructions before trying: https://raamana.github.io/graynet/cortical.html#using-a-different-atlas

Volumetric atlases supported for CAT12 features: cat_aal, cat_lpba40, and cat_ibsr.In addition, you can also directly specify an absolute path to a single 3D volume. Make sure name this file properly as itwould be used to encode all the processing i.e. make it clean as well as fully reflective of the properties of the parcellation inside.

Default: fsaverage

-n, --node_size

Size of individual patch for the atlas parcellation, in terms of minimum number of vertices per patch. This is ONLY valid for cortical version of graynet, when using atlas fsaverage only, that has precomputed parcellation for a set of predetermined patch sizes.

Allowed values: (None, 250, 500, 1000, 2000, 3000, 5000, 10000).

Default : None

-p, --smoothing_param

Smoothing parameter for feature. Default: FWHM of 10 for Freesurfer thickness.

Computing

Options related to computing and parallelization.

-c, --num_procs

Number of CPUs to use in parallel to speed up processing. Default : 2, capping at available number of CPUs in the processing node.

-d, --overwrite_results

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

-v, --version

show program’s version number and exit

Simple example

A rough example of usage can be:

#!/bin/bash
#$ -l mf=2G -q queue_name.q -wd /work/project
cd /work/project
graynet -s subject_ids.txt -f freesurfer_thickness -i /work/project/freesurfer_reconall \
    -w manhattan eucledian chebyshev -a GLASSER2016 -p 10 -o /work/project/graynet_processing

Note you can specify mulitple weight metrics to save on I/O activity and walltime on HPC.