nigsp.workflow.nigsp

nigsp.workflow.nigsp(fname, scname, atlasname=None, outname=None, outdir=None, comp_metric=[], index='median', surr_type=None, n_surr=1000, method='Bernoulli', p=0.05, seed=None, lgr_degree='info')[source]

Main workflow for nigsp, following the methods described in [1].

Parameters:
fnamestr or os.PathLike

Path to the timeseries data file. It can be a text, nifti, or matlab file (and variants). To see the full list of support, check the general documentation.

scnamestr or os.PathLike

Path to the structural connectivity data file. It can be a text, nifti, or matlab file (and variants). To see the full list of support, check the general documentation.

atlasnamestr, os.PathLike, or None, optional

Path to the atlas data file. It can be a text, nifti, or matlab file (and variants). To see the full list of support, check the general documentation.

outnamestr, os.PathLike, or None, optional

Path to the output file - or just its full name. It can be a text, nifti, or matlab file (and variants). If an extension is not declared, or if it is not currently supported, the program will automatically export a csv file. To see the full list of support, check the general documentation. It is not necessary to declare both this and outdir - the full path can be specified here.

outdirstr, os.PathLike, or None, optional

Path to the output folder. If it doesn’t exist, it will be created. If both outdir and outname are declared, outdir overrides the path specified in outname (but not the filename!)

comp_metriclist or None, optional

List of metrics that should be computed. If empty (default), compute all metrics available.

index‘median’ or int, optional

The index of the eigenvector/harmonic of the graph to split the graph in multiple parts, or the method to find this index. Currently supports median energy split (‘median’), which is the default. Note that indexing is one-based (i.e. indexing starts at 1, not 0).

surr_type‘informed’, ‘uninformed’, or None, optional

The type of surrogates to create for statistical testing. ‘Informed’ surrogates are created using the empirical SC decomposition, shuffling eigenvectors’ signs. ‘Uninformed’ surrogates use a configuration model of the same degree of the empirical SC instead. If surr_type is None, no statistical test is run.

n_surrint, optional

Number of surrogates to be created.

method‘Bernoulli’, ‘frequentist’, or None, optional

Method to use for statistical testing or empirical data vs surrogates. Supported possibilities are ‘Bernoulli’, to test empirical data at the group level against a random Bernoulli process, or ‘frequentist’, to test empirical data at the group or subject level against the plain surrogate distribution.

pfloat (in range [0 1]), optional

The two-tailed p value to use for testing. Must be between 0 and 1. The two tails will be tested against half of this value.

seedint or None, optional

The seed to use to reinitialise the random number generator for surrogates creation. If seed is None, it will use internally specified seeds to guarantee replicability. It’s suggested either not specify it, or specify a different one for each type of surrogate created.

lgr_degree‘debug’, ‘info’, or ‘quiet’, optional

The degree of verbosity of the logger. Default is ‘info’.

Returns:
0

If there are no errors.

Raises:
NotImplementedError

If SC file is not of a supported type. If timeseries file is not of a supported type. If atlas file is not of a supported type. If timeseries file is a nifti file but atlas file is not. If statistical method is not within supported method (or None). If surrogate type is not within supported type (or None).

ValueError

If index is not int or is not median. If p is not in the range [0 1]. If the projected timeseries are not split to compute SDI or gSDI.

Notes

See the original paper on SDI [1] for more details.

A configuration model [2] is used to create uninformed surrogates.

References

[1] (1,2)

Preti, M.G., Van De Ville, D. Decoupling of brain function from structure reveals regional behavioral specialization in humans. Nat Commun 10, 4747 (2019). https://doi.org/10.1038/s41467-019-12765-7