Skip to content

Commit 0f94b22

Browse files
aghayooraghayoor
committed
ENH: modified afni NetCorr development
1 parent a8ee022 commit 0f94b22

File tree

1 file changed

+125
-22
lines changed

1 file changed

+125
-22
lines changed

‎nipype/interfaces/afni/preprocess.py

+125-22
Original file line numberDiff line numberDiff line change
@@ -2557,23 +2557,126 @@ def _format_arg(self, name, trait_spec, value):
25572557

25582558

25592559
class NetCorrInputSpec(AFNICommandInputSpec):
2560-
in_file = File(exists=True, argstr="-inset %s", mandatory=True)
2561-
in_rois = File(exists=True, argstr="-in_rois %s", mandatory=True)
2562-
mask = File(exists=True, argstr="-mask %s")
2563-
weight_ts = File(exists=True, argstr="-weight_ts %s")
2564-
fish_z = traits.Bool(argstr="-fish_z")
2565-
part_corr = traits.Bool(argstr="-part_corr")
2566-
ts_out = traits.Bool(argstr="-ts_out")
2567-
ts_label = traits.Bool(argstr="-ts_label")
2568-
ts_indiv = traits.Bool(argstr="-ts_indiv")
2569-
ts_wb_corr = traits.Bool(argstr="-ts_wb_corr")
2570-
ts_wb_Z = traits.Bool(argstr="-ts_wb_Z")
2571-
ts_wb_strlabel = traits.Bool(argstr="-ts_wb_strlabel")
2572-
nifti = traits.Bool(argstr="-nifti")
2573-
output_mask_nonnull = traits.Bool(argstr="-output_mask_nonnull")
2574-
push_thru_many_zeros = traits.Bool(argstr="-push_thru_many_zeros")
2575-
ignore_LT = traits.Bool(argstr="-ignore_LT")
2560+
in_file = File(
2561+
desc="input time series file (4D data set)",
2562+
exists=True,
2563+
argstr="-inset %s",
2564+
mandatory=True)
2565+
in_rois = File(
2566+
desc="input set of ROIs, each labelled with distinct integers",
2567+
exists=True,
2568+
argstr="-in_rois %s",
2569+
mandatory=True)
2570+
mask = File(
2571+
desc="can include a whole brain mask within which to "
2572+
"calculate correlation. Otherwise, data should be "
2573+
"masked already",
2574+
exists=True,
2575+
argstr="-mask %s")
2576+
weight_ts = File(
2577+
desc="input a 1D file WTS of weights that will be applied "
2578+
"multiplicatively to each ROI's average time series. "
2579+
"WTS can be a column- or row-file of values, but it "
2580+
"must have the same length as the input time series "
2581+
"volume. "
2582+
"If the initial average time series was A[n] for "
2583+
"n=0,..,(N-1) time points, then applying a set of "
2584+
"weights W[n] of the same length from WTS would "
2585+
"produce a new time series: B[n] = A[n] * W[n]",
2586+
exists=True,
2587+
argstr="-weight_ts %s")
2588+
fish_z = traits.Bool(
2589+
desc="switch to also output a matrix of Fisher Z-transform "
2590+
"values for the corr coefs (r): "
2591+
"Z = atanh(r) , "
2592+
"(with Z=4 being output along matrix diagonals where "
2593+
"r=1, as the r-to-Z conversion is ceilinged at "
2594+
"Z = atanh(r=0.999329) = 4, which is still *quite* a "
2595+
"high Pearson-r value",
2596+
argstr="-fish_z")
2597+
part_corr = traits.Bool(
2598+
desc="output the partial correlation matrix",
2599+
argstr="-part_corr")
2600+
ts_out = traits.Bool(
2601+
desc="switch to output the mean time series of the ROIs that "
2602+
"have been used to generate the correlation matrices. "
2603+
"Output filenames mirror those of the correlation "
2604+
"matrix files, with a '.netts' postfix",
2605+
argstr="-ts_out")
2606+
ts_label = traits.Bool(
2607+
desc="additional switch when using '-ts_out'. Using this "
2608+
"option will insert the integer ROI label at the start "
2609+
"of each line of the *.netts file created. Thus, for "
2610+
"a time series of length N, each line will have N+1 "
2611+
"numbers, where the first is the integer ROI label "
2612+
"and the subsequent N are scientific notation values",
2613+
argstr="-ts_label")
2614+
ts_indiv = traits.Bool(
2615+
desc="switch to create a directory for each network that "
2616+
"contains the average time series for each ROI in "
2617+
"individual files (each file has one line). "
2618+
"The directories are labelled PREFIX_000_INDIV/, "
2619+
"PREFIX_001_INDIV/, etc. (one per network). Within each "
2620+
"directory, the files are labelled ROI_001.netts, "
2621+
"ROI_002.netts, etc., with the numbers given by the "
2622+
"actual ROI integer labels",
2623+
argstr="-ts_indiv")
2624+
ts_wb_corr = traits.Bool(
2625+
desc="switch to create a set of whole brain correlation maps. "
2626+
"Performs whole brain correlation for each "
2627+
"ROI's average time series; this will automatically "
2628+
"create a directory for each network that contains the "
2629+
"set of whole brain correlation maps (Pearson 'r's). "
2630+
"The directories are labelled as above for '-ts_indiv' "
2631+
"Within each directory, the files are labelled "
2632+
"WB_CORR_ROI_001+orig, WB_CORR_ROI_002+orig, etc., with "
2633+
"the numbers given by the actual ROI integer labels",
2634+
argstr="-ts_wb_corr")
2635+
ts_wb_Z = traits.Bool(
2636+
desc="same as above in '-ts_wb_corr', except that the maps "
2637+
"have been Fisher transformed to Z-scores the relation: "
2638+
"Z=atanh(r). "
2639+
"To avoid infinities in the transform, Pearson values "
2640+
"are effectively capped at |r| = 0.999329 (where |Z| = 4.0). "
2641+
"Files are labelled WB_Z_ROI_001+orig, etc",
2642+
argstr="-ts_wb_Z")
2643+
ts_wb_strlabel = traits.Bool(
2644+
desc="by default, '-ts_wb_{corr,Z}' output files are named "
2645+
"using the int number of a given ROI, such as: "
2646+
"WB_Z_ROI_001+orig. "
2647+
"With this option, one can replace the int (such as '001') "
2648+
"with the string label (such as 'L-thalamus') "
2649+
"*if* one has a labeltable attached to the file",
2650+
argstr="-ts_wb_strlabel")
2651+
nifti = traits.Bool(
2652+
desc="output any correlation map files as NIFTI files "
2653+
"(default is BRIK/HEAD). Only useful if using "
2654+
"'-ts_wb_corr' and/or '-ts_wb_Z'",
2655+
argstr="-nifti")
2656+
output_mask_nonnull = traits.Bool(
2657+
desc="internally, this program checks for where there are "
2658+
"nonnull time series, because we don't like those, in "
2659+
"general. With this flag, the user can output the "
2660+
"determined mask of non-null time series.",
2661+
argstr="-output_mask_nonnull")
2662+
push_thru_many_zeros = traits.Bool(
2663+
desc="by default, this program will grind to a halt and "
2664+
"refuse to calculate if any ROI contains >10 percent "
2665+
"of voxels with null times series (i.e., each point is "
2666+
"0), as of April, 2017. This is because it seems most "
2667+
"likely that hidden badness is responsible. However, "
2668+
"if the user still wants to carry on the calculation "
2669+
"anyways, then this option will allow one to push on "
2670+
"through. However, if any ROI *only* has null time "
2671+
"series, then the program will not calculate and the "
2672+
"user will really, really, really need to address their masking",
2673+
argstr="-push_thru_many_zeros")
2674+
ignore_LT = traits.Bool(
2675+
desc="switch to ignore any label table labels in the "
2676+
"'-in_rois' file, if there are any labels attached",
2677+
argstr="-ignore_LT")
25762678
out_file = File(
2679+
desc="output file name part",
25772680
name_template="%s_netcorr",
25782681
desc="output file name part",
25792682
argstr="-prefix %s",
@@ -2588,22 +2691,22 @@ class NetCorr(AFNICommand):
25882691
"""Calculate correlation matrix of a set of ROIs (using mean time series of
25892692
each). Several networks may be analyzed simultaneously, one per brick.
25902693
2591-
For complete details, see the `3dTcorrMap Documentation.
2592-
<https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dNetCorr.html>`_
2694+
For complete details, see the `3dNetCorr Documentation
2695+
<https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dNetCorr.html>`_.
25932696
25942697
Examples
25952698
--------
25962699
>>> from nipype.interfaces import afni
25972700
>>> ncorr = afni.NetCorr()
25982701
>>> ncorr.inputs.in_file = 'functional.nii'
25992702
>>> ncorr.inputs.mask = 'mask.nii'
2600-
>>> ncorr.inputs.in_rois = 'rois.nii'
2703+
>>> ncorr.inputs.in_rois = 'maps.nii'
26012704
>>> ncorr.inputs.ts_wb_corr = True
26022705
>>> ncorr.inputs.ts_wb_Z = True
26032706
>>> ncorr.inputs.fish_z = True
2604-
>>> ncorr.inputs.prefix = 'sub0.tp1.ncorr'
2605-
>>> ncorr.cmdline # doctest: +SKIP
2606-
'3dNetCorr -prefix sub0.tp1.ncorr -inset functional.nii -mask mask.nii -in_rois rois.nii -ts_wb_corr -ts_wb_Z -fish_z'
2707+
>>> ncorr.inputs.out_file = 'sub0.tp1.ncorr'
2708+
>>> ncorr.cmdline
2709+
'3dNetCorr -prefix sub0.tp1.ncorr -inset functional.nii -mask mask.nii -in_rois maps.nii -ts_wb_corr -ts_wb_Z -fish_z'
26072710
>>> res = ncorr.run() # doctest: +SKIP
26082711
26092712
"""

0 commit comments

Comments
 (0)