rapidtide 2.9.6__py3-none-any.whl → 3.1.3__py3-none-any.whl

rapidtide/workflows/pairproc.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2016-2024 Blaise Frederick
+#   Copyright 2016-2025 Blaise Frederick
 #
 #   Licensed under the Apache License, Version 2.0 (the "License");
 #   you may not use this file except in compliance with the License.
@@ -17,8 +17,11 @@
 #
 #
 import argparse
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
+from numpy.typing import NDArray
 from scipy.stats import pearsonr
 from tqdm import tqdm
 
@@ -27,7 +30,33 @@ import rapidtide.miscmath as tide_math
 from rapidtide.workflows.parser_funcs import is_valid_file
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure argument parser for pairproc command-line tool.
+
+    This function sets up an argument parser for comparing even and odd volumes
+    of 4D nifti files. It defines required and optional command-line arguments
+    needed for the pairproc workflow.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional
+        arguments for the pairproc tool.
+
+    Notes
+    -----
+    The parser is configured with:
+    - Required positional arguments: inputfile and outputroot
+    - Optional arguments for data masking, distribution analysis, demeaning, and debugging
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.nii.gz', 'output_root'])
+    >>> print(args.inputfile)
+    'input.nii.gz'
+    """
     parser = argparse.ArgumentParser(
         prog="pairproc",
         description="Compare the even and odd volumes of a 4D nifti file.",
@@ -68,7 +97,64 @@ def _get_parser():
     return parser
 
 
-def pairproc(args):
+def pairproc(args: Any) -> None:
+    """
+    Process paired time series data from NIfTI files and compute temporal and spatial correlations.
+
+    This function reads input NIfTI data, splits the time series into pairs (even and odd indices),
+    and computes Pearson correlations between the paired time series both temporally and spatially.
+    It supports optional demeaning and masking of data, and can output correlation maps and
+    statistics for real and shifted (rolled) odd time series.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing the following attributes:
+        - inputfile : str
+            Path to the input NIfTI file.
+        - datamaskname : str, optional
+            Path to the data mask NIfTI file. If provided, only voxels with mask values > 0.5
+            will be processed.
+        - outputroot : str
+            Root name for output files.
+        - demean : bool
+            If True, demean the time series before computing correlations.
+        - getdist : bool
+            If True, compute correlations for both real and shifted (rolled) odd time series.
+        - debug : bool
+            If True, print additional debug information.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves multiple NIfTI files and text files
+        containing correlation maps and statistics.
+
+    Notes
+    -----
+    - The input time series must have an even number of time points.
+    - The function assumes that the input data is organized as (x, y, z, t) where t is the time dimension.
+    - Temporal correlations are computed between even and odd time series for each voxel.
+    - Spatial correlations are computed between even and odd time series for each subject.
+    - Output files include:
+        - Temporal correlation maps (NIfTI)
+        - Temporal p-values (NIfTI)
+        - Spatial correlation values (text file)
+        - Spatial p-values (text file)
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfile="data.nii.gz",
+    ...     datamaskname="mask.nii.gz",
+    ...     outputroot="output",
+    ...     demean=True,
+    ...     getdist=False,
+    ...     debug=False
+    ... )
+    >>> pairproc(args)
+    """
     # read in the data files
     print("reading input file")
     input_img, input_data, input_hdr, thedims, thesizes = tide_io.readfromnifti(args.inputfile)
@@ -149,9 +235,13 @@ def pairproc(args):
             desc="Voxel",
             unit="voxels",
         ):
-            temporalcorrelations[vox], temporalpvalues[vox] = pearsonr(
+            thepearsonresult = pearsonr(
                 tide_math.stdnormalize(evenims[vox, :]), tide_math.stdnormalize(oddims[vox, :])
             )
+            temporalcorrelations[vox], temporalpvalues[vox] = (
+                thepearsonresult.statistic,
+                thepearsonresult.pvalue,
+            )
         print()
 
         outarray = np.zeros((xsize, ysize, numslices), dtype=np.double)
@@ -173,10 +263,14 @@ def pairproc(args):
             desc="Subject",
             unit="subjects",
         ):
-            spatialcorrelations[subject], spatialpvalues[subject] = pearsonr(
+            thepearsonresult = pearsonr(
                 tide_math.stdnormalize(evenims[:, subject]),
                 tide_math.stdnormalize(oddims[:, subject]),
             )
+            spatialcorrelations[subject], spatialpvalues[subject] = (
+                thepearsonresult.statistic,
+                thepearsonresult.pvalue,
+            )
         print()
 
         tide_io.writenpvecs(

rapidtide/workflows/pairwisemergenifti.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2016-2024 Blaise Frederick
+#   Copyright 2016-2025 Blaise Frederick
 #
 #   Licensed under the Apache License, Version 2.0 (the "License");
 #   you may not use this file except in compliance with the License.
@@ -17,13 +17,46 @@
 #
 #
 import argparse
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.io as tide_io
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure argument parser for pairwisemergenifti tool.
+
+    This function initializes an ArgumentParser object with specific arguments
+    required for merging adjacent timepoints in NIfTI files.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser with the following arguments:
+        - inputfile: The name of the input NIfTI file, including extension
+        - inputmask: The name of the mask NIfTI file, including extension
+        - outputfile: The name of the output NIfTI file, including extension
+        - --maskmerge: Input is a mask (boolean flag)
+        - --debug: Print debugging information (boolean flag)
+
+    Notes
+    -----
+    The parser is configured with:
+    - prog="pairwisemergenifti"
+    - description="Merges adjacent timepoints in a nifti file."
+    - allow_abbrev=False
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.nii', 'mask.nii', 'output.nii'])
+    >>> print(args.inputfile)
+    'input.nii'
+    """
     parser = argparse.ArgumentParser(
         prog="pairwisemergenifti",
         description="Merges adjacent timepoints in a nifti file.",
@@ -50,7 +83,57 @@ def _get_parser():
     return parser
 
 
-def pairwisemergenifti(args):
+def pairwisemergenifti(args: Any) -> None:
+    """
+    Pairwise merge NIfTI time series data based on a mask.
+
+    This function reads input NIfTI image and mask files, performs pairwise
+    averaging of time series data, and saves the result as a new NIfTI file.
+    The input image is expected to have an even number of time points, which
+    are merged in pairs. The mask is used to determine which voxels contribute
+    to the averaging.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing the following attributes:
+        - inputfile : str
+            Path to the input NIfTI image file.
+        - inputmask : str
+            Path to the input NIfTI mask file.
+        - outputfile : str
+            Path to the output NIfTI file.
+        - maskmerge : bool
+            If True, the mask is binarized before merging. If False, the
+            average of the input data is computed using the mask.
+
+    Returns
+    -------
+    None
+        The function does not return a value but saves the merged data to a
+        NIfTI file.
+
+    Notes
+    -----
+    - The function requires that the spatial dimensions of the input image
+      and mask match.
+    - The time dimension of the input image must be even.
+    - If `maskmerge` is True, the mask is converted to binary (0 or 1) before
+      merging.
+    - If `maskmerge` is False, the average of the input data is computed
+      using the mask to weight the voxels.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfile='input.nii.gz',
+    ...     inputmask='mask.nii.gz',
+    ...     outputfile='output.nii.gz',
+    ...     maskmerge=False
+    ... )
+    >>> pairwisemergenifti(args)
+    """
     print("reading input data")
     input_img, input_data, input_hdr, thedims, thesizes = tide_io.readfromnifti(args.inputfile)
     print("reading input mask")