xcp_d.interfaces.restingstate module

Interfaces for working with resting-state fMRI data.

class xcp_d.interfaces.restingstate.ComputeALFF(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Compute amplitude of low-frequency fluctuation (ALFF).

Notes

The ALFF implementation is based on Yu-Feng et al.[1], although the ALFF values are not scaled by the mean ALFF value across the brain.

If censoring is applied (i.e., fd_thresh > 0), then the power spectrum will be estimated using a Lomb-Scargle periodogram [2][3][4][5].

References

[1]

Zang Yu-Feng, He Yong, Zhu Chao-Zhe, Cao Qing-Jiu, Sui Man-Qiu, Liang Meng, Tian Li-Xia, Jiang Tian-Zi, and Wang Yu-Feng. Altered baseline brain activity in children with adhd revealed by resting-state functional mri. Brain and Development, 29(2):83–91, 2007.

[2]

Nicholas R Lomb. Least-squares frequency analysis of unequally spaced data. Astrophysics and space science, 39:447–462, 1976.

[3]

Jeffrey D Scargle. Studies in astronomical time series analysis. ii-statistical aspects of spectral analysis of unevenly spaced data. Astrophysical Journal, Part 1, vol. 263, Dec. 15, 1982, p. 835-853., 263:835–853, 1982.

[4]

RHD Townsend. Fast calculation of the lomb–scargle periodogram using graphics processing units. The Astrophysical Journal Supplement Series, 191(2):247, 2010.

[5]

Paul A Taylor, Gang Chen, Daniel R Glen, Richard C Reynolds, and Robert W Cox. Lomb-scargle your way to rsfc parameter estimation in afni-fatcat. International Society for Magnetic Resonance in Medicine, 2018. Description of Lomb-Scargle applied to scrubbed fMRI data in AFNI.

Mandatory Inputs:

• TR (a float) – Repetition time.

• high_pass (a float) – High_pass filter in Hz.

• in_file (a pathlike object or string representing an existing file) – Nifti, cifti or gifti.

• low_pass (a float) – Low_pass filter in Hz.

Optional Inputs:

• mask (a pathlike object or string representing an existing file) – brain mask for nifti file.

• temporal_mask (a pathlike object or string representing an existing file or a _Undefined or None) – Temporal mask.

Outputs:

alff (a pathlike object or string representing an existing file) – alff.

class xcp_d.interfaces.restingstate.DespikePatch(**inputs)

Bases: Despike

Wrapped executable: 3dDespike.

Remove ‘spikes’ from the 3D+time input dataset.

For complete details, see the 3dDespike Documentation.

Examples

>>> from nipype.interfaces import afni
>>> despike = afni.Despike()
>>> despike.inputs.in_file = 'functional.nii'
>>> despike.cmdline
'3dDespike -prefix functional_despike functional.nii'
>>> res = despike.run()  

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input file to 3dDespike. Maps to a command-line argument: %s (position: -1).

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• num_threads (an integer) – Set number of threads. (Nipype default value: 1)

• out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

• outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

Outputs:

out_file (a pathlike object or string representing an existing file) – Output file.

class xcp_d.interfaces.restingstate.ReHoNamePatch(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Wrapped executable: 3dReHo.

Compute ReHo for a given neighbourhood, based on a local neighborhood of that voxel.

For complete details, see the 3dReHo Documentation.

Examples

>>> from nipype.interfaces import afni
>>> reho = afni.ReHo()
>>> reho.inputs.in_file = 'functional.nii'
>>> reho.inputs.out_file = 'reho.nii.gz'
>>> reho.inputs.neighborhood = 'vertices'
>>> reho.cmdline
'3dReHo -prefix reho.nii.gz -inset functional.nii -nneigh 27'
>>> res = reho.run()  

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input dataset. Maps to a command-line argument: -inset %s (position: 1).

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• chi_sq (a boolean) – Output the Friedman chi-squared value in addition to the Kendall’s W. This option is currently compatible only with the AFNI (BRIK/HEAD) output type; the chi-squared value will be the second sub-brick of the output dataset. Maps to a command-line argument: -chi_sq.

• ellipsoid (a tuple of the form: (a float, a float, a float)) – Tuple indicating the x, y, and z radius of an ellipsoid defining the neighbourhood of each voxel. The ‘hood is then made according to the following relation: \((i/A)^2 + (j/B)^2 + (k/C)^2 \le 1.\) which will have approx. \(V=4 \pi \, A B C/3\). The impetus for this freedom was for use with data having anisotropic voxel edge lengths. Maps to a command-line argument: -neigh_X %s -neigh_Y %s -neigh_Z %s. Mutually exclusive with inputs: sphere, neighborhood.

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• label_set (a pathlike object or string representing an existing file) – A set of ROIs, each labelled with distinct integers. ReHo will then be calculated per ROI. Maps to a command-line argument: -in_rois %s.

• mask_file (a pathlike object or string representing a file) – Mask within which ReHo should be calculated voxelwise. Maps to a command-line argument: -mask %s.

• neighborhood (‘faces’ or ‘edges’ or ‘vertices’) – voxels in neighborhood. can be: faces (for voxel and 6 facewise neighbors, only), edges (for voxel and 18 face- and edge-wise neighbors), vertices (for voxel and 26 face-, edge-, and node-wise neighbors). Maps to a command-line argument: -nneigh %s. Mutually exclusive with inputs: sphere, ellipsoid.

• out_file (a pathlike object or string representing a file) – Output dataset. Maps to a command-line argument: -prefix %s (position: 0).

• overwrite (a boolean) – Overwrite output file if it already exists. Maps to a command-line argument: -overwrite.

• sphere (a float) – For additional voxelwise neighborhood control, the radius R of a desired neighborhood can be put in; R is a floating point number, and must be >1. Examples of the numbers of voxels in a given radius are as follows (you can roughly approximate with the ol’ \(4\pi\,R^3/3\) thing):

  • R=2.0 -> V=33

  • R=2.3 -> V=57,

  • R=2.9 -> V=93,

  • R=3.1 -> V=123,

  • R=3.9 -> V=251,

  • R=4.5 -> V=389,

  • R=6.1 -> V=949,

  but you can choose most any value. Maps to a command-line argument: -neigh_RAD %s. Mutually exclusive with inputs: neighborhood, ellipsoid.

Outputs:

• out_file (a pathlike object or string representing an existing file) – Voxelwise regional homogeneity map.

• out_vals (a pathlike object or string representing a file) – Table of labelwise regional homogeneity values.

class xcp_d.interfaces.restingstate.SurfaceReHo(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Calculate regional homogeneity (ReHo) on a surface file.

Examples

>>> from tempfile import TemporaryDirectory
>>> tmpdir = TemporaryDirectory()
>>> os.chdir(tmpdir.name)
.. doctest::
>>> surfacereho_wf = SurfaceReHo()
>>> surfacereho_wf.inputs.surf_bold = 'rhhemi.func.gii'
>>> surfacereho_wf.inputs.surf_hemi = 'R'
>>> surfacereho_wf.run()
.. testcleanup::
>>> tmpdir.cleanup()

Mandatory Inputs:

• surf_bold (a pathlike object or string representing an existing file) – Left or right hemisphere gii .

• surf_hemi (a string) – L or R .

Outputs:

surf_gii (a pathlike object or string representing an existing file) – lh hemisphere reho.