algorithms.confounds¶
ACompCor¶
Anatomical compcor; for input/output, see CompCor. If the mask provided is an anatomical mask, CompCor == ACompCor
Inputs:
[Mandatory]
realigned_file: (an existing file name)
already realigned brain image (4D)
[Optional]
components_file: (a file name, nipype default value:
components_file.txt)
filename to store physiological components
header: (a unicode string)
the desired header for the output tsv file (one column).If
undefined, will default to "CompCor"
ignore_exception: (a boolean, nipype default value: False)
Print an error message instead of throwing an exception in case the
interface fails to run
mask_file: (an existing file name)
mask file that determines ROI (3D)
num_components: (an integer (int or long), nipype default value: 6)
regress_poly_degree: (an integer >= 1, nipype default value: 1)
the degree polynomial to use
use_regress_poly: (a boolean, nipype default value: True)
use polynomial regressionpre-component extraction
Outputs:
components_file: (an existing file name)
text file containing the noise components
References:: None
CompCor¶
Interface with core CompCor computation, used in aCompCor and tCompCor
Example¶
>>> ccinterface = CompCor()
>>> ccinterface.inputs.realigned_file = 'functional.nii'
>>> ccinterface.inputs.mask_file = 'mask.nii'
>>> ccinterface.inputs.num_components = 1
>>> ccinterface.inputs.use_regress_poly = True
>>> ccinterface.inputs.regress_poly_degree = 2
Inputs:
[Mandatory]
realigned_file: (an existing file name)
already realigned brain image (4D)
[Optional]
components_file: (a file name, nipype default value:
components_file.txt)
filename to store physiological components
header: (a unicode string)
the desired header for the output tsv file (one column).If
undefined, will default to "CompCor"
ignore_exception: (a boolean, nipype default value: False)
Print an error message instead of throwing an exception in case the
interface fails to run
mask_file: (an existing file name)
mask file that determines ROI (3D)
num_components: (an integer (int or long), nipype default value: 6)
regress_poly_degree: (an integer >= 1, nipype default value: 1)
the degree polynomial to use
use_regress_poly: (a boolean, nipype default value: True)
use polynomial regressionpre-component extraction
Outputs:
components_file: (an existing file name)
text file containing the noise components
References:: None
ComputeDVARS¶
Computes the DVARS.
Inputs:
[Mandatory]
in_file: (an existing file name)
functional data, after HMC
in_mask: (an existing file name)
a brain mask
[Optional]
figdpi: (an integer (int or long), nipype default value: 100)
output dpi for the plot
figformat: (u'png' or u'pdf' or u'svg', nipype default value: png)
output format for figures
figsize: (a tuple of the form: (a float, a float), nipype default
value: (11.7, 2.3))
output figure size
ignore_exception: (a boolean, nipype default value: False)
Print an error message instead of throwing an exception in case the
interface fails to run
remove_zerovariance: (a boolean, nipype default value: True)
remove voxels with zero variance
save_all: (a boolean, nipype default value: False)
output all DVARS
save_nstd: (a boolean, nipype default value: False)
save non-standardized DVARS
save_plot: (a boolean, nipype default value: False)
write DVARS plot
save_std: (a boolean, nipype default value: True)
save standardized DVARS
save_vxstd: (a boolean, nipype default value: False)
save voxel-wise standardized DVARS
series_tr: (a float)
repetition time in sec.
Outputs:
avg_nstd: (a float)
avg_std: (a float)
avg_vxstd: (a float)
fig_nstd: (an existing file name)
output DVARS plot
fig_std: (an existing file name)
output DVARS plot
fig_vxstd: (an existing file name)
output DVARS plot
out_all: (an existing file name)
output text file
out_nstd: (an existing file name)
output text file
out_std: (an existing file name)
output text file
out_vxstd: (an existing file name)
output text file
References:: None None
FramewiseDisplacement¶
Calculate the FD as in [Power2012]. This implementation reproduces the calculation in fsl_motion_outliers
| [Power2012] | (1, 2) Power et al., Spurious but systematic correlations in functional connectivity MRI networks arise from subject motion, NeuroImage 59(3), 2012. doi:10.1016/j.neuroimage.2011.10.018. |
Inputs:
[Mandatory]
in_plots: (an existing file name)
motion parameters as written by FSL MCFLIRT
[Optional]
figdpi: (an integer (int or long), nipype default value: 100)
output dpi for the FD plot
figsize: (a tuple of the form: (a float, a float), nipype default
value: (11.7, 2.3))
output figure size
ignore_exception: (a boolean, nipype default value: False)
Print an error message instead of throwing an exception in case the
interface fails to run
normalize: (a boolean, nipype default value: False)
calculate FD in mm/s
out_figure: (a file name, nipype default value: fd_power_2012.pdf)
output figure name
out_file: (a file name, nipype default value: fd_power_2012.txt)
output file name
radius: (a float, nipype default value: 50)
radius in mm to calculate angular FDs, 50mm is the default since it
is used in Power et al. 2012
save_plot: (a boolean, nipype default value: False)
write FD plot
series_tr: (a float)
repetition time in sec.
Outputs:
fd_average: (a float)
average FD
out_figure: (a file name)
output image file
out_file: (a file name)
calculated FD per timestep
References:: None
TCompCor¶
Interface for tCompCor. Computes a ROI mask based on variance of voxels.
Example¶
>>> ccinterface = TCompCor()
>>> ccinterface.inputs.realigned_file = 'functional.nii'
>>> ccinterface.inputs.mask_file = 'mask.nii'
>>> ccinterface.inputs.num_components = 1
>>> ccinterface.inputs.use_regress_poly = True
>>> ccinterface.inputs.regress_poly_degree = 2
>>> ccinterface.inputs.percentile_threshold = .03
Inputs:
[Mandatory]
realigned_file: (an existing file name)
already realigned brain image (4D)
[Optional]
components_file: (a file name, nipype default value:
components_file.txt)
filename to store physiological components
header: (a unicode string)
the desired header for the output tsv file (one column).If
undefined, will default to "CompCor"
ignore_exception: (a boolean, nipype default value: False)
Print an error message instead of throwing an exception in case the
interface fails to run
mask_file: (an existing file name)
mask file that determines ROI (3D)
num_components: (an integer (int or long), nipype default value: 6)
percentile_threshold: (0.0 < a floating point number < 1.0, nipype
default value: 0.02)
the percentile used to select highest-variance voxels, represented
by a number between 0 and 1, exclusive. By default, this value is
set to .02. That is, the 2% of voxels with the highest variance are
used.
regress_poly_degree: (an integer >= 1, nipype default value: 1)
the degree polynomial to use
use_regress_poly: (a boolean, nipype default value: True)
use polynomial regressionpre-component extraction
Outputs:
components_file: (a file name, nipype default value:
components_file.txt)
filename to store physiological components
header: (a unicode string)
the desired header for the output tsv file (one column).If
undefined, will default to "CompCor"
high_variance_mask: (an existing file name)
voxels excedding the variance threshold
ignore_exception: (a boolean, nipype default value: False)
Print an error message instead of throwing an exception in case the
interface fails to run
mask_file: (an existing file name)
mask file that determines ROI (3D)
num_components: (an integer (int or long), nipype default value: 6)
realigned_file: (an existing file name)
already realigned brain image (4D)
regress_poly_degree: (an integer >= 1, nipype default value: 1)
the degree polynomial to use
use_regress_poly: (a boolean, nipype default value: True)
use polynomial regressionpre-component extraction
References:: None
TSNR¶
Computes the time-course SNR for a time series
Typically you want to run this on a realigned time-series.
Example¶
>>> tsnr = TSNR()
>>> tsnr.inputs.in_file = 'functional.nii'
>>> res = tsnr.run()
Inputs:
[Mandatory]
in_file: (a list of items which are an existing file name)
realigned 4D file or a list of 3D files
[Optional]
detrended_file: (a file name, nipype default value: detrend.nii.gz)
input file after detrending
ignore_exception: (a boolean, nipype default value: False)
Print an error message instead of throwing an exception in case the
interface fails to run
mean_file: (a file name, nipype default value: mean.nii.gz)
output mean file
regress_poly: (an integer >= 1)
Remove polynomials
stddev_file: (a file name, nipype default value: stdev.nii.gz)
output tSNR file
tsnr_file: (a file name, nipype default value: tsnr.nii.gz)
output tSNR file
Outputs:
detrended_file: (a file name)
detrended input file
mean_file: (an existing file name)
mean image file
stddev_file: (an existing file name)
std dev image file
tsnr_file: (an existing file name)
tsnr image file
compute_dvars()¶
Compute the DVARS [Power2012].
Particularly, the standardized DVARS [Nichols2013] are computed.
| [Nichols2013] | Nichols T, Notes on creating a standardized version of DVARS, 2013. |
Note
Implementation details
Uses the implementation of the Yule-Walker equations from nitime for the AR filtering of the fMRI signal.
| param numpy.ndarray func: | |
|---|---|
| functional data, after head-motion-correction. | |
| param numpy.ndarray mask: | |
| a 3D mask of the brain | |
| param bool output_all: | |
| write out all dvars | |
| param str out_file: | |
| a path to which the standardized dvars should be saved. | |
| return: | the standardized DVARS |
regress_poly()¶
returns data with degree polynomial regressed out. Be default it is calculated along the last axis (usu. time). If remove_mean is True (default), the data is demeaned (i.e. degree 0). If remove_mean is false, the data is not.
zero_remove()¶
Modify inputted mask to also mask out zero values
| param numpy.ndarray data: | |
|---|---|
| e.g. voxelwise stddev of fMRI dataset, after motion correction | |
| param numpy.ndarray mask: | |
| brain mask (same dimensions as data) | |
| return: | the mask with any additional zero voxels removed (same dimensions as inputs) |
| rtype: | numpy.ndarray |