rapidtide 3.0.10__py3-none-any.whl → 3.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. rapidtide/Colortables.py +492 -27
  2. rapidtide/OrthoImageItem.py +1053 -47
  3. rapidtide/RapidtideDataset.py +1533 -86
  4. rapidtide/_version.py +3 -3
  5. rapidtide/calccoherence.py +196 -29
  6. rapidtide/calcnullsimfunc.py +191 -40
  7. rapidtide/calcsimfunc.py +245 -42
  8. rapidtide/correlate.py +1210 -393
  9. rapidtide/data/examples/src/testLD +56 -0
  10. rapidtide/data/examples/src/testalign +1 -1
  11. rapidtide/data/examples/src/testdelayvar +0 -1
  12. rapidtide/data/examples/src/testfmri +19 -1
  13. rapidtide/data/examples/src/testglmfilt +5 -5
  14. rapidtide/data/examples/src/testhappy +30 -1
  15. rapidtide/data/examples/src/testppgproc +17 -0
  16. rapidtide/data/examples/src/testrolloff +11 -0
  17. rapidtide/data/models/model_cnn_pytorch/best_model.pth +0 -0
  18. rapidtide/data/models/model_cnn_pytorch/loss.png +0 -0
  19. rapidtide/data/models/model_cnn_pytorch/loss.txt +1 -0
  20. rapidtide/data/models/model_cnn_pytorch/model.pth +0 -0
  21. rapidtide/data/models/model_cnn_pytorch/model_meta.json +68 -0
  22. rapidtide/data/reference/JHU-ArterialTerritoriesNoVent-LVL1_space-MNI152NLin2009cAsym_2mm.nii.gz +0 -0
  23. rapidtide/data/reference/JHU-ArterialTerritoriesNoVent-LVL1_space-MNI152NLin2009cAsym_2mm_mask.nii.gz +0 -0
  24. rapidtide/decorators.py +91 -0
  25. rapidtide/dlfilter.py +2225 -108
  26. rapidtide/dlfiltertorch.py +4843 -0
  27. rapidtide/externaltools.py +327 -12
  28. rapidtide/fMRIData_class.py +79 -40
  29. rapidtide/filter.py +1899 -810
  30. rapidtide/fit.py +2004 -574
  31. rapidtide/genericmultiproc.py +93 -18
  32. rapidtide/happy_supportfuncs.py +2044 -171
  33. rapidtide/helper_classes.py +584 -43
  34. rapidtide/io.py +2363 -370
  35. rapidtide/linfitfiltpass.py +341 -75
  36. rapidtide/makelaggedtcs.py +211 -20
  37. rapidtide/maskutil.py +423 -53
  38. rapidtide/miscmath.py +827 -121
  39. rapidtide/multiproc.py +210 -22
  40. rapidtide/patchmatch.py +234 -33
  41. rapidtide/peakeval.py +32 -30
  42. rapidtide/ppgproc.py +2203 -0
  43. rapidtide/qualitycheck.py +352 -39
  44. rapidtide/refinedelay.py +422 -57
  45. rapidtide/refineregressor.py +498 -184
  46. rapidtide/resample.py +671 -185
  47. rapidtide/scripts/applyppgproc.py +28 -0
  48. rapidtide/simFuncClasses.py +1052 -77
  49. rapidtide/simfuncfit.py +260 -46
  50. rapidtide/stats.py +540 -238
  51. rapidtide/tests/happycomp +9 -0
  52. rapidtide/tests/test_dlfiltertorch.py +627 -0
  53. rapidtide/tests/test_findmaxlag.py +24 -8
  54. rapidtide/tests/test_fullrunhappy_v1.py +0 -2
  55. rapidtide/tests/test_fullrunhappy_v2.py +0 -2
  56. rapidtide/tests/test_fullrunhappy_v3.py +1 -0
  57. rapidtide/tests/test_fullrunhappy_v4.py +2 -2
  58. rapidtide/tests/test_fullrunrapidtide_v7.py +1 -1
  59. rapidtide/tests/test_simroundtrip.py +8 -8
  60. rapidtide/tests/utils.py +9 -8
  61. rapidtide/tidepoolTemplate.py +142 -38
  62. rapidtide/tidepoolTemplate_alt.py +165 -44
  63. rapidtide/tidepoolTemplate_big.py +189 -52
  64. rapidtide/util.py +1217 -118
  65. rapidtide/voxelData.py +684 -37
  66. rapidtide/wiener.py +19 -12
  67. rapidtide/wiener2.py +113 -7
  68. rapidtide/wiener_doc.py +255 -0
  69. rapidtide/workflows/adjustoffset.py +105 -3
  70. rapidtide/workflows/aligntcs.py +85 -2
  71. rapidtide/workflows/applydlfilter.py +87 -10
  72. rapidtide/workflows/applyppgproc.py +522 -0
  73. rapidtide/workflows/atlasaverage.py +210 -47
  74. rapidtide/workflows/atlastool.py +100 -3
  75. rapidtide/workflows/calcSimFuncMap.py +294 -64
  76. rapidtide/workflows/calctexticc.py +201 -9
  77. rapidtide/workflows/ccorrica.py +97 -4
  78. rapidtide/workflows/cleanregressor.py +168 -29
  79. rapidtide/workflows/delayvar.py +163 -10
  80. rapidtide/workflows/diffrois.py +81 -3
  81. rapidtide/workflows/endtidalproc.py +144 -4
  82. rapidtide/workflows/fdica.py +195 -15
  83. rapidtide/workflows/filtnifti.py +70 -3
  84. rapidtide/workflows/filttc.py +74 -3
  85. rapidtide/workflows/fitSimFuncMap.py +206 -48
  86. rapidtide/workflows/fixtr.py +73 -3
  87. rapidtide/workflows/gmscalc.py +113 -3
  88. rapidtide/workflows/happy.py +813 -201
  89. rapidtide/workflows/happy2std.py +144 -12
  90. rapidtide/workflows/happy_parser.py +149 -8
  91. rapidtide/workflows/histnifti.py +118 -2
  92. rapidtide/workflows/histtc.py +84 -3
  93. rapidtide/workflows/linfitfilt.py +117 -4
  94. rapidtide/workflows/localflow.py +328 -28
  95. rapidtide/workflows/mergequality.py +79 -3
  96. rapidtide/workflows/niftidecomp.py +322 -18
  97. rapidtide/workflows/niftistats.py +174 -4
  98. rapidtide/workflows/pairproc.py +88 -2
  99. rapidtide/workflows/pairwisemergenifti.py +85 -2
  100. rapidtide/workflows/parser_funcs.py +1421 -40
  101. rapidtide/workflows/physiofreq.py +137 -11
  102. rapidtide/workflows/pixelcomp.py +208 -5
  103. rapidtide/workflows/plethquality.py +103 -21
  104. rapidtide/workflows/polyfitim.py +151 -11
  105. rapidtide/workflows/proj2flow.py +75 -2
  106. rapidtide/workflows/rankimage.py +111 -4
  107. rapidtide/workflows/rapidtide.py +272 -15
  108. rapidtide/workflows/rapidtide2std.py +98 -2
  109. rapidtide/workflows/rapidtide_parser.py +109 -9
  110. rapidtide/workflows/refineDelayMap.py +143 -33
  111. rapidtide/workflows/refineRegressor.py +682 -93
  112. rapidtide/workflows/regressfrommaps.py +152 -31
  113. rapidtide/workflows/resamplenifti.py +85 -3
  114. rapidtide/workflows/resampletc.py +91 -3
  115. rapidtide/workflows/retrolagtcs.py +98 -6
  116. rapidtide/workflows/retroregress.py +165 -9
  117. rapidtide/workflows/roisummarize.py +173 -5
  118. rapidtide/workflows/runqualitycheck.py +71 -3
  119. rapidtide/workflows/showarbcorr.py +147 -4
  120. rapidtide/workflows/showhist.py +86 -2
  121. rapidtide/workflows/showstxcorr.py +160 -3
  122. rapidtide/workflows/showtc.py +159 -3
  123. rapidtide/workflows/showxcorrx.py +184 -4
  124. rapidtide/workflows/showxy.py +185 -15
  125. rapidtide/workflows/simdata.py +262 -36
  126. rapidtide/workflows/spatialfit.py +77 -2
  127. rapidtide/workflows/spatialmi.py +251 -27
  128. rapidtide/workflows/spectrogram.py +305 -32
  129. rapidtide/workflows/synthASL.py +154 -3
  130. rapidtide/workflows/tcfrom2col.py +76 -2
  131. rapidtide/workflows/tcfrom3col.py +74 -2
  132. rapidtide/workflows/tidepool.py +2972 -133
  133. rapidtide/workflows/utils.py +19 -14
  134. rapidtide/workflows/utils_doc.py +293 -0
  135. rapidtide/workflows/variabilityizer.py +116 -3
  136. {rapidtide-3.0.10.dist-info → rapidtide-3.1.dist-info}/METADATA +10 -9
  137. {rapidtide-3.0.10.dist-info → rapidtide-3.1.dist-info}/RECORD +141 -122
  138. {rapidtide-3.0.10.dist-info → rapidtide-3.1.dist-info}/entry_points.txt +1 -0
  139. {rapidtide-3.0.10.dist-info → rapidtide-3.1.dist-info}/WHEEL +0 -0
  140. {rapidtide-3.0.10.dist-info → rapidtide-3.1.dist-info}/licenses/LICENSE +0 -0
  141. {rapidtide-3.0.10.dist-info → rapidtide-3.1.dist-info}/top_level.txt +0 -0
@@ -21,9 +21,12 @@ import warnings
21
21
  warnings.simplefilter(action="ignore", category=FutureWarning)
22
22
  import argparse
23
23
  import sys
24
+ from argparse import Namespace
25
+ from typing import Any, Callable, Dict, List, Optional, Tuple, Union
24
26
 
25
27
  import nibabel as nib
26
28
  import numpy as np
29
+ from numpy.typing import NDArray
27
30
  from scipy.stats import pearsonr
28
31
 
29
32
  import rapidtide.correlate as tide_corr
@@ -38,9 +41,29 @@ DEFAULT_DETREND_ORDER = 3
38
41
  DEFAULT_CORRWEIGHTING = "phat"
39
42
 
40
43
 
41
- def _get_parser():
44
+ def _get_parser() -> Any:
42
45
  """
43
- Argument parser for ccorrica
46
+ Argument parser for ccorrica.
47
+
48
+ This function constructs and returns an `argparse.ArgumentParser` object configured
49
+ with all required and optional arguments for the `ccorrica` tool, which computes
50
+ temporal cross-correlations between timecourses.
51
+
52
+ Returns
53
+ -------
54
+ argparse.ArgumentParser
55
+ Configured argument parser for the ccorrica tool.
56
+
57
+ Notes
58
+ -----
59
+ The parser includes support for specifying sample rate or timestep, windowing options,
60
+ search range parameters, filtering, correlation weighting methods, detrending, and
61
+ oversampling factors. It also supports debugging output.
62
+
63
+ Examples
64
+ --------
65
+ >>> parser = _get_parser()
66
+ >>> args = parser.parse_args(['--timecoursefile', 'data.txt', '--outputroot', 'out'])
44
67
  """
45
68
  parser = argparse.ArgumentParser(
46
69
  prog="ccorrica",
@@ -134,7 +157,77 @@ def _get_parser():
134
157
  return parser
135
158
 
136
159
 
137
- def ccorrica(args):
160
+ def ccorrica(args: Any) -> None:
161
+ """
162
+ Compute cross-correlations between time series components and save results in NIfTI and text formats.
163
+
164
+ This function reads time course data from a text file, applies preprocessing including
165
+ filtering, resampling, detrending, and windowing, then computes cross-correlations
166
+ between all pairs of components. The results are saved as NIfTI files and text vectors
167
+ for further analysis.
168
+
169
+ Parameters
170
+ ----------
171
+ args : argparse.Namespace
172
+ Command-line arguments containing configuration options such as:
173
+ - timecoursefile : str
174
+ Path to the input time course file.
175
+ - samplerate : float or str
176
+ Sampling rate of the data. If "auto", it must be specified in the file header.
177
+ - oversampfactor : int
178
+ Oversampling factor for upsampling the data. If less than 0, it is auto-computed.
179
+ - detrendorder : int
180
+ Order of detrending to apply.
181
+ - windowfunc : str
182
+ Windowing function to apply.
183
+ - corrweighting : str
184
+ Type of weighting to use in correlation computation.
185
+ - debug : bool
186
+ If True, display plots during correlation computation.
187
+ - outputroot : str
188
+ Root name for output files.
189
+
190
+ Returns
191
+ -------
192
+ None
193
+ This function does not return a value but saves multiple output files:
194
+ - `_filtereddata.txt`: Filtered time series.
195
+ - `_xcorr.nii.gz`: Cross-correlation data as 4D NIfTI.
196
+ - `_pxcorr.nii.gz`: Pearson correlation coefficients.
197
+ - `_corrmax.nii.gz`: Maximum correlation values.
198
+ - `_corrlag.nii.gz`: Lag at maximum correlation.
199
+ - `_corrwidth.nii.gz`: Width of the correlation peak.
200
+ - `_corrmask.nii.gz`: Mask indicating correlation significance.
201
+ - `_reformdata.txt`: Final reformatted and normalized data.
202
+
203
+ Notes
204
+ -----
205
+ The function performs the following steps:
206
+ 1. Reads input data from a text file.
207
+ 2. Applies post-processing filter options.
208
+ 3. Resamples data if necessary.
209
+ 4. Filters data using a specified prefilter.
210
+ 5. Normalizes data using standard and correlation normalization.
211
+ 6. Computes cross-correlations using fast FFT-based methods.
212
+ 7. Fits Gaussian peaks to find maximum correlation lag and width.
213
+ 8. Saves symmetric matrices for correlation maxima, lags, widths, and masks.
214
+ 9. Outputs results in both NIfTI and text formats.
215
+
216
+ Examples
217
+ --------
218
+ >>> import argparse
219
+ >>> args = argparse.Namespace(
220
+ ... timecoursefile='data.txt',
221
+ ... samplerate=2.0,
222
+ ... oversampfactor=1,
223
+ ... detrendorder=1,
224
+ ... windowfunc='hanning',
225
+ ... corrweighting='none',
226
+ ... debug=False,
227
+ ... outputroot='output'
228
+ ... )
229
+ >>> ccorrica(args)
230
+ """
138
231
  args, theprefilter = pf.postprocessfilteropts(args)
139
232
 
140
233
  # read in data
@@ -172,7 +265,7 @@ def ccorrica(args):
172
265
  if args.oversampfactor == 1:
173
266
  print("data array shape is ", reformdata.shape)
174
267
  else:
175
- resampdata = np.zeros((numcomponents, tclen * args.oversampfactor), dtype=np.float)
268
+ resampdata = np.zeros((numcomponents, tclen * args.oversampfactor), dtype=float)
176
269
  for component in range(0, numcomponents):
177
270
  resampdata[component, :] = tide_resample.upsample(
178
271
  reformdata[component, :], Fs, Fs * args.oversampfactor, intfac=True
@@ -16,7 +16,10 @@
16
16
  # limitations under the License.
17
17
  #
18
18
  #
19
+ from typing import Any, Callable, Dict, List, Optional, Tuple, Union
20
+
19
21
  import numpy as np
22
+ from numpy.typing import NDArray
20
23
 
21
24
  import rapidtide.correlate as tide_corr
22
25
  import rapidtide.filter as tide_filt
@@ -27,35 +30,171 @@ import rapidtide.simfuncfit as tide_simfuncfit
27
30
 
28
31
 
29
32
  def cleanregressor(
30
- outputname,
31
- thepass,
32
- referencetc,
33
- resampref_y,
34
- resampnonosref_y,
35
- fmrifreq,
36
- oversampfreq,
37
- osvalidsimcalcstart,
38
- osvalidsimcalcend,
39
- lagmininpts,
40
- lagmaxinpts,
41
- theFitter,
42
- theCorrelator,
43
- lagmin,
44
- lagmax,
45
- LGR=None,
46
- check_autocorrelation=True,
47
- fix_autocorrelation=True,
48
- despeckle_thresh=5.0,
49
- lthreshval=0.0,
50
- fixdelay=False,
51
- detrendorder=3,
52
- windowfunc="hamming",
53
- respdelete=False,
54
- displayplots=False,
55
- debug=False,
56
- rt_floattype="float64",
57
- rt_floatset=np.float64,
58
- ):
33
+ outputname: Any,
34
+ thepass: Any,
35
+ referencetc: Any,
36
+ resampref_y: Any,
37
+ resampnonosref_y: Any,
38
+ fmrifreq: Any,
39
+ oversampfreq: Any,
40
+ osvalidsimcalcstart: Any,
41
+ osvalidsimcalcend: Any,
42
+ lagmininpts: Any,
43
+ lagmaxinpts: Any,
44
+ theFitter: Any,
45
+ theCorrelator: Any,
46
+ lagmin: Any,
47
+ lagmax: Any,
48
+ LGR: Optional[Any] = None,
49
+ check_autocorrelation: bool = True,
50
+ fix_autocorrelation: bool = True,
51
+ despeckle_thresh: float = 5.0,
52
+ lthreshval: float = 0.0,
53
+ fixdelay: bool = False,
54
+ detrendorder: int = 3,
55
+ windowfunc: str = "hamming",
56
+ respdelete: bool = False,
57
+ displayplots: bool = False,
58
+ debug: bool = False,
59
+ rt_floattype: str = "float64",
60
+ rt_floatset: Any = np.float64,
61
+ ) -> Tuple[
62
+ NDArray,
63
+ NDArray,
64
+ NDArray,
65
+ float,
66
+ float | None,
67
+ float | None,
68
+ float,
69
+ float | None,
70
+ float | None,
71
+ ]:
72
+ """
73
+ Clean and preprocess a regressor signal by checking and correcting autocorrelation properties.
74
+
75
+ This function performs several operations on the input regressor signal, including:
76
+ detrending, normalization, optional filtering to remove periodic components, and
77
+ autocorrelation analysis to detect and correct sidelobes. It returns cleaned versions
78
+ of the regressor and associated metadata for further use in time series analysis.
79
+
80
+ Parameters
81
+ ----------
82
+ outputname : Any
83
+ Base name for output files.
84
+ thepass : Any
85
+ Pass identifier, used for labeling output files.
86
+ referencetc : Any
87
+ Reference time course data (normalized).
88
+ resampref_y : Any
89
+ Resampled reference signal.
90
+ resampnonosref_y : Any
91
+ Non-oversampled reference signal.
92
+ fmrifreq : Any
93
+ fMRI sampling frequency.
94
+ oversampfreq : Any
95
+ Oversampled frequency.
96
+ osvalidsimcalcstart : Any
97
+ Start index for valid data in oversampled signal.
98
+ osvalidsimcalcend : Any
99
+ End index for valid data in oversampled signal.
100
+ lagmininpts : Any
101
+ Minimum lag in samples for autocorrelation calculation.
102
+ lagmaxinpts : Any
103
+ Maximum lag in samples for autocorrelation calculation.
104
+ theFitter : Any
105
+ Fitter object for fitting autocorrelation data.
106
+ theCorrelator : Any
107
+ Correlator object for computing cross-correlations.
108
+ lagmin : Any
109
+ Minimum lag in seconds.
110
+ lagmax : Any
111
+ Maximum lag in seconds.
112
+ LGR : Optional[Any], optional
113
+ Logger object for logging messages. Default is None.
114
+ check_autocorrelation : bool, optional
115
+ If True, perform autocorrelation checks. Default is True.
116
+ fix_autocorrelation : bool, optional
117
+ If True, attempt to fix detected autocorrelation issues. Default is True.
118
+ despeckle_thresh : float, optional
119
+ Threshold for despeckling autocorrelation data. Default is 5.0.
120
+ lthreshval : float, optional
121
+ Low threshold value for fitting. Default is 0.0.
122
+ fixdelay : bool, optional
123
+ If True, fix delay in fitting. Default is False.
124
+ detrendorder : int, optional
125
+ Order of detrending polynomial. Default is 3.
126
+ windowfunc : str, optional
127
+ Window function to use for normalization. Default is "hamming".
128
+ respdelete : bool, optional
129
+ If True, remove periodic components from the reference signal. Default is False.
130
+ displayplots : bool, optional
131
+ If True, display plots during processing. Default is False.
132
+ debug : bool, optional
133
+ If True, print debugging information. Default is False.
134
+ rt_floattype : str, optional
135
+ Data type for real-time processing. Default is "float64".
136
+ rt_floatset : Any, optional
137
+ Float type setting for real-time processing. Default is np.float64.
138
+
139
+ Returns
140
+ -------
141
+ tuple
142
+ A tuple containing:
143
+ - cleaned_resampref_y : np.ndarray
144
+ Cleaned resampled reference signal.
145
+ - cleaned_referencetc : np.ndarray
146
+ Cleaned reference time course.
147
+ - cleaned_nonosreferencetc : np.ndarray
148
+ Cleaned non-oversampled reference signal.
149
+ - despeckle_thresh : float
150
+ Updated despeckle threshold.
151
+ - sidelobeamp : float or None
152
+ Amplitude of detected sidelobe, or None if not found.
153
+ - sidelobetime : float or None
154
+ Time of detected sidelobe in seconds, or None if not found.
155
+ - lagmod : float
156
+ Lag modulus value used for correction.
157
+ - acwidth : float or None
158
+ Width of autocorrelation function, or None if not computed.
159
+ - absmaxsigma : float or None
160
+ Absolute maximum sigma value, or None if not computed.
161
+
162
+ Notes
163
+ -----
164
+ - If `respdelete` is True, the function applies frequency tracking and filtering to remove
165
+ periodic components from the reference signal.
166
+ - Autocorrelation analysis is performed using `tide_corr.check_autocorrelation` to detect
167
+ sidelobes that may affect the regressor quality.
168
+ - If `fix_autocorrelation` is True, detected sidelobes are corrected by applying a notch filter
169
+ and adjusting the lag modulus.
170
+
171
+ Examples
172
+ --------
173
+ >>> cleanregressor(
174
+ ... outputname="test_output",
175
+ ... thepass=1,
176
+ ... referencetc=ref_tc,
177
+ ... resampref_y=resamp_ref,
178
+ ... resampnonosref_y=resamp_nonos_ref,
179
+ ... fmrifreq=2.0,
180
+ ... oversampfreq=10.0,
181
+ ... osvalidsimcalcstart=0,
182
+ ... osvalidsimcalcend=100,
183
+ ... lagmininpts=5,
184
+ ... lagmaxinpts=20,
185
+ ... theFitter=fitter,
186
+ ... theCorrelator=correlator,
187
+ ... lagmin=-10,
188
+ ... lagmax=10,
189
+ ... check_autocorrelation=True,
190
+ ... fix_autocorrelation=True,
191
+ ... detrendorder=3,
192
+ ... windowfunc="hamming",
193
+ ... respdelete=False,
194
+ ... displayplots=False,
195
+ ... debug=False,
196
+ ... )
197
+ """
59
198
  # print debugging info
60
199
  if debug:
61
200
  print("cleanregressor:")
@@ -22,9 +22,12 @@ import logging
22
22
  import os
23
23
  import sys
24
24
  import time
25
+ from argparse import Namespace
25
26
  from pathlib import Path
27
+ from typing import Any, Callable, Dict, List, Optional, Tuple, Union
26
28
 
27
29
  import numpy as np
30
+ from numpy.typing import NDArray
28
31
  from scipy.stats import pearsonr
29
32
  from sklearn.decomposition import PCA
30
33
  from tf_keras.src.dtensor.integration_test_utils import train_step
@@ -63,14 +66,34 @@ DEFAULT_DELAYOFFSETSPATIALFILT = -1
63
66
  DEFAULT_WINDOWSIZE = 30.0
64
67
  DEFAULT_SYSTEMICFITTYPE = "pca"
65
68
  DEFAULT_PCACOMPONENTS = 1
66
- DEFAULT_LAGMIN = 0.0
67
- DEFAULT_LAGMAX = 0.0
69
+ DEFAULT_LAGMIN = -999
70
+ DEFAULT_LAGMAX = -999
68
71
  DEFAULT_TRAINSTEP = 0.5
69
72
 
70
73
 
71
- def _get_parser():
74
+ def _get_parser() -> Any:
72
75
  """
73
- Argument parser for glmfilt
76
+ Argument parser for glmfilt.
77
+
78
+ This function constructs and returns an `argparse.ArgumentParser` object configured
79
+ for parsing command-line arguments used by the `glmfilt` tool. It defines required
80
+ and optional arguments for processing fMRI data, including file paths, filtering
81
+ options, output settings, and experimental parameters.
82
+
83
+ Returns
84
+ -------
85
+ argparse.ArgumentParser
86
+ Configured argument parser for the glmfilt tool.
87
+
88
+ Notes
89
+ -----
90
+ The parser includes both standard and experimental options. Experimental options
91
+ are marked as such and may not be fully tested or stable.
92
+
93
+ Examples
94
+ --------
95
+ >>> parser = _get_parser()
96
+ >>> args = parser.parse_args()
74
97
  """
75
98
  parser = argparse.ArgumentParser(
76
99
  prog="delayvar",
@@ -265,7 +288,102 @@ def _get_parser():
265
288
  return parser
266
289
 
267
290
 
268
- def delayvar(args):
291
+ def delayvar(args: Any) -> None:
292
+ """
293
+ Perform windowed delay variance analysis on fMRI data.
294
+
295
+ This function conducts a comprehensive delay variance analysis on fMRI data,
296
+ computing delay offsets for each voxel across temporal windows. It supports
297
+ various filtering options, PCA-based systemic component removal, and outputs
298
+ detailed timing information and processed maps.
299
+
300
+ Parameters
301
+ ----------
302
+ args : Any
303
+ Namespace object containing all required arguments for the analysis.
304
+ Expected attributes include:
305
+ - fmrifile : str
306
+ Path to the input fMRI NIfTI file.
307
+ - datafileroot : str
308
+ Root name for output files.
309
+ - lag_extrema : tuple of int
310
+ Minimum and maximum lag values for analysis.
311
+ - alternateoutput : str, optional
312
+ Alternate output name.
313
+ - debug : bool
314
+ Enable debug mode.
315
+ - outputlevel : str
316
+ Level of output files to save ('min', 'less', 'normal', 'more', 'max').
317
+ - nprocs : int
318
+ Number of processes to use.
319
+ - hpf : bool
320
+ Apply highpass filtering.
321
+ - windowsize : float
322
+ Size of temporal windows in seconds.
323
+ - windelayoffsetgausssigma : float
324
+ Sigma for Gaussian smoothing of delay offsets.
325
+ - delaypatchthresh : float
326
+ Threshold for patch-based delay correction.
327
+ - systemicfittype : str
328
+ Type of systemic component removal ('pca' or 'mean').
329
+ - pcacomponents : float
330
+ Number of PCA components to use.
331
+ - trainstep : float
332
+ Step size for training the delay model.
333
+ - numskip : int
334
+ Number of initial timepoints to skip.
335
+ - focaldebug : bool
336
+ Enable focal debugging mode.
337
+ - verbose : bool
338
+ Enable verbose output.
339
+ - showprogressbar : bool
340
+ Show progress bar during processing.
341
+
342
+ Returns
343
+ -------
344
+ None
345
+ This function does not return a value but writes multiple output files
346
+ including:
347
+ - Delay offset maps in temporal windows
348
+ - Systemic component timeseries
349
+ - PCA component information
350
+ - Timing and runoptions files
351
+ - Histograms of delay offsets
352
+ - Various intermediate processing results
353
+
354
+ Notes
355
+ -----
356
+ The function performs the following key steps:
357
+ 1. Windowed processing of fMRI data
358
+ 2. Derivative ratio calculation and filtering
359
+ 3. Delay offset training and calculation
360
+ 4. Systemic component removal (PCA or mean)
361
+ 5. Output generation and cleanup
362
+
363
+ Examples
364
+ --------
365
+ >>> import argparse
366
+ >>> args = argparse.Namespace(
367
+ ... fmrifile='data.nii.gz',
368
+ ... datafileroot='output',
369
+ ... lag_extrema=(0, 10),
370
+ ... debug=False,
371
+ ... outputlevel='normal',
372
+ ... nprocs=4,
373
+ ... hpf=True,
374
+ ... windowsize=30.0,
375
+ ... windelayoffsetgausssigma=2.0,
376
+ ... delaypatchthresh=0.5,
377
+ ... systemicfittype='pca',
378
+ ... pcacomponents=0.8,
379
+ ... trainstep=0.1,
380
+ ... numskip=5,
381
+ ... focaldebug=False,
382
+ ... verbose=True,
383
+ ... showprogressbar=True
384
+ ... )
385
+ >>> delayvar(args)
386
+ """
269
387
  # get the pid of the parent process
270
388
  args.pid = os.getpid()
271
389
 
@@ -289,7 +407,7 @@ def delayvar(args):
289
407
  logger_filename=f"{outputname}_retrolog.txt",
290
408
  timing_filename=f"{outputname}_retroruntimings.tsv",
291
409
  error_filename=f"{outputname}_retroerrorlog.txt",
292
- verbose=False,
410
+ isverbose=False,
293
411
  debug=args.debug,
294
412
  )
295
413
  TimingLGR.info("Start")
@@ -618,8 +736,12 @@ def delayvar(args):
618
736
  winsLFOfitmean, winsLFOfitmean_shm = tide_util.allocarray(
619
737
  internalwinspaceshape, rt_outfloattype, shared=usesharedmem
620
738
  )
621
- winrvalue, winrvalue_shm = tide_util.allocarray(internalwinspaceshape, rt_outfloattype, shared=usesharedmem)
622
- winr2value, winr2value_shm = tide_util.allocarray(internalwinspaceshape, rt_outfloattype, shared=usesharedmem)
739
+ winrvalue, winrvalue_shm = tide_util.allocarray(
740
+ internalwinspaceshape, rt_outfloattype, shared=usesharedmem
741
+ )
742
+ winr2value, winr2value_shm = tide_util.allocarray(
743
+ internalwinspaceshape, rt_outfloattype, shared=usesharedmem
744
+ )
623
745
  winfitNorm, winfitNorm_shm = tide_util.allocarray(
624
746
  internalwinspaceshapederivs, rt_outfloattype, shared=usesharedmem
625
747
  )
@@ -629,7 +751,9 @@ def delayvar(args):
629
751
  winmovingsignal, winmovingsignal_shm = tide_util.allocarray(
630
752
  internalwinfmrishape, rt_outfloattype, shared=usesharedmem
631
753
  )
632
- winlagtc, winlagtc_shm = tide_util.allocarray(internalwinfmrishape, rt_floattype, shared=usesharedmem)
754
+ winlagtc, winlagtc_shm = tide_util.allocarray(
755
+ internalwinfmrishape, rt_floattype, shared=usesharedmem
756
+ )
633
757
  winfiltereddata, winfiltereddata_shm = tide_util.allocarray(
634
758
  internalwinfmrishape, rt_outfloattype, shared=usesharedmem
635
759
  )
@@ -1112,9 +1236,38 @@ def delayvar(args):
1112
1236
  Path(f"{outputname}_DELAYVARDONE.txt").touch()
1113
1237
 
1114
1238
 
1115
- def process_args(inputargs=None):
1239
+ def process_args(inputargs: Optional[Any] = None) -> None:
1116
1240
  """
1117
1241
  Compile arguments for delayvar workflow.
1242
+
1243
+ This function processes input arguments for the delayvar workflow by parsing
1244
+ command line arguments or provided input arguments using a predefined parser.
1245
+
1246
+ Parameters
1247
+ ----------
1248
+ inputargs : Any, optional
1249
+ Input arguments to be processed. Can be None (default) to use command line
1250
+ arguments, or a list of arguments to parse. Default is None.
1251
+
1252
+ Returns
1253
+ -------
1254
+ dict
1255
+ Parsed arguments as a dictionary. The exact structure depends on the
1256
+ argument parser (_get_parser) used internally.
1257
+
1258
+ Notes
1259
+ -----
1260
+ This function internally calls `pf.setargs` with the `_get_parser` function
1261
+ and the provided input arguments. The returned arguments are typically used
1262
+ to configure the delayvar workflow parameters.
1263
+
1264
+ Examples
1265
+ --------
1266
+ >>> # Using default command line arguments
1267
+ >>> args = process_args()
1268
+
1269
+ >>> # Using custom arguments
1270
+ >>> args = process_args(['--input', 'data.txt', '--output', 'result.txt'])
1118
1271
  """
1119
1272
  args, argstowrite = pf.setargs(_get_parser, inputargs=inputargs)
1120
1273
  return args
@@ -18,18 +18,46 @@
18
18
  #
19
19
  import argparse
20
20
  import copy
21
+ from argparse import Namespace
22
+ from typing import Any, Callable, Dict, List, Optional, Tuple, Union
21
23
 
22
24
  import nibabel as nib
23
25
  import numpy as np
24
26
  import pandas as pd
27
+ from numpy.typing import NDArray
25
28
 
26
29
  import rapidtide.io as tide_io
27
30
  import rapidtide.workflows.parser_funcs as pf
28
31
 
29
32
 
30
- def _get_parser():
33
+ def _get_parser() -> Any:
31
34
  """
32
- Argument parser for diffrois
35
+ Argument parser for diffrois.
36
+
37
+ This function creates and configures an argument parser for the diffrois command-line tool.
38
+ It defines required and optional arguments needed to process ROI (Region of Interest) data
39
+ from a CSV file and generate difference matrices.
40
+
41
+ Returns
42
+ -------
43
+ argparse.ArgumentParser
44
+ Configured argument parser object with defined arguments for diffrois.
45
+
46
+ Notes
47
+ -----
48
+ The parser is configured with:
49
+ - A required datafile argument (CSV input)
50
+ - A required outputroot argument (root name for output files)
51
+ - Optional keyfile argument to specify region label order
52
+ - Optional maxlines argument to limit processing to first N lines
53
+ - Optional debug flag for verbose output
54
+
55
+ Examples
56
+ --------
57
+ >>> parser = _get_parser()
58
+ >>> args = parser.parse_args(['data.csv', 'output_root'])
59
+ >>> print(args.datafile)
60
+ 'data.csv'
33
61
  """
34
62
  parser = argparse.ArgumentParser(
35
63
  prog="diffrois",
@@ -77,7 +105,57 @@ def _get_parser():
77
105
  return parser
78
106
 
79
107
 
80
- def diffrois(args):
108
+ def diffrois(args: Any) -> None:
109
+ """
110
+ Compute pairwise differences between regions in a CSV file and save results as NIfTI images.
111
+
112
+ This function reads region data from a CSV file, computes pairwise differences between
113
+ regions, and saves the results as NIfTI images. It also computes mean and standard
114
+ deviation maps of the differences and saves those as well. The function supports
115
+ optional masking of invalid (NaN) values and can limit the number of input lines
116
+ processed.
117
+
118
+ Parameters
119
+ ----------
120
+ args : argparse.Namespace
121
+ An object containing the following attributes:
122
+ - datafile : str
123
+ Path to the input CSV file containing region data.
124
+ - keyfile : str, optional
125
+ Path to a file listing column keys in the CSV to use for processing.
126
+ - outputroot : str
127
+ Root name for output NIfTI files.
128
+ - maxlines : int, optional
129
+ Maximum number of lines to process from the input CSV.
130
+ - debug : bool
131
+ If True, print debug information during execution.
132
+
133
+ Returns
134
+ -------
135
+ None
136
+ This function does not return any value but saves multiple NIfTI files to disk.
137
+
138
+ Notes
139
+ -----
140
+ The function saves the following NIfTI files:
141
+ - `{outputroot}_diffs.nii.gz`: Pairwise differences between regions.
142
+ - `{outputroot}_mask.nii.gz`: Binary mask indicating valid (non-NaN) values.
143
+ - `{outputroot}_meandiffs.nii.gz`: Mean of differences for each region pair.
144
+ - `{outputroot}_stddiffs.nii.gz`: Standard deviation of differences for each region pair.
145
+ - `{outputroot}_demeaneddiffs.nii.gz`: Demeaned differences (difference minus mean).
146
+
147
+ Examples
148
+ --------
149
+ >>> import argparse
150
+ >>> args = argparse.Namespace(
151
+ ... datafile='data.csv',
152
+ ... keyfile='keys.txt',
153
+ ... outputroot='output',
154
+ ... maxlines=100,
155
+ ... debug=False
156
+ ... )
157
+ >>> diffrois(args)
158
+ """
81
159
  df = pd.read_csv(args.datafile)
82
160
 
83
161
  theregions = np.array(df.columns[1:].values)