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

rapidtide/workflows/niftidecomp.py

@@ -18,8 +18,11 @@
 #
 import argparse
 import sys
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
+from numpy.typing import NDArray
 from sklearn.decomposition import PCA, FastICA, SparsePCA
 
 import rapidtide.filter as tide_filt
@@ -27,9 +30,47 @@ import rapidtide.io as tide_io
 from rapidtide.workflows.parser_funcs import is_float, is_valid_file
 
 
-def _get_parser(decompaxis):
+def _get_parser(decompaxis: Any) -> Any:
     """
-    Argument parser for spatialdecomp and temporaldecomp
+    Argument parser for spatialdecomp and temporaldecomp.
+
+    This function constructs and returns an `argparse.ArgumentParser` object
+    configured for either spatial or temporal decomposition tasks. The parser
+    is tailored to handle common arguments required for PCA or ICA decomposition
+    of neuroimaging data (e.g., NIfTI files).
+
+    Parameters
+    ----------
+    decompaxis : Any
+        Specifies the axis along which decomposition is performed. Must be
+        either "temporal" or "spatial". Determines the program name and
+        description of the parser.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the specified decomposition type.
+
+    Raises
+    ------
+    ValueError
+        If `decompaxis` is not "temporal" or "spatial".
+
+    Notes
+    -----
+    The returned parser includes support for:
+    - Input data file validation
+    - Output root naming
+    - Data masking
+    - Number of components to extract
+    - Spatial smoothing
+    - Decomposition type (PCA, ICA, sparse)
+    - Preprocessing options such as demeaning and variance normalization
+
+    Examples
+    --------
+    >>> parser = _get_parser("temporal")
+    >>> args = parser.parse_args(['data.nii', 'output_root'])
     """
     if decompaxis == "temporal":
         parser = argparse.ArgumentParser(
@@ -109,15 +150,96 @@ def _get_parser(decompaxis):
     return parser
 
 
-def _get_parser_temporal():
+def _get_parser_temporal() -> Any:
+    """
+    Get parser for the temporal variant of the program.
+
+    This function is a convenience wrapper that calls the internal `_get_parser`
+    function with the argument "temporal" to obtain the temporal parser object.
+
+    Returns
+    -------
+    Any
+        The temporal parser instance. The specific type depends on the implementation
+        of the underlying `_get_parser` function and the temporal parser configuration.
+
+    Notes
+    -----
+    This function is intended for internal use only and should not be called directly
+    by end users. The returned parser is typically used for parsing temporal data
+    such as dates, times, and time intervals.
+
+    Examples
+    --------
+    >>> parser = _get_parser_temporal()
+    >>> # Use parser for temporal data processing
+    """
     return _get_parser("temporal")
 
 
-def _get_parser_spatial():
+def _get_parser_spatial() -> Any:
+    """
+    Get parser for the spatial variant of the program.
+
+    Returns
+    -------
+    Any
+        The spatial parser object returned by `_get_parser` function.
+
+    Notes
+    -----
+    This function is a convenience wrapper that calls `_get_parser` with the
+    argument "spatial". It is used internally to retrieve spatial parsing
+    capabilities for the application.
+
+    Examples
+    --------
+    >>> parser = _get_parser_spatial()
+    >>> isinstance(parser, SomeParserClass)
+    True
+    """
     return _get_parser("spatial")
 
 
-def transposeifspatial(data, decompaxis="temporal"):
+def transposeifspatial(data: Any, decompaxis: str = "temporal") -> None:
+    """
+    Transpose data if decomposition axis is spatial.
+
+    Parameters
+    ----------
+    data : Any
+        Input data to be transposed if necessary
+    decompaxis : str, default="temporal"
+        Decomposition axis specification. If "spatial", the data will be transposed
+        using numpy.transpose() function. Otherwise, the original data is returned
+        unchanged.
+
+    Returns
+    -------
+    Any
+        Transposed data if decompaxis is "spatial", otherwise returns the original data
+
+    Notes
+    -----
+    This function provides a conditional transpose operation based on the decomposition
+    axis specification. It's useful in scenarios where data processing needs to
+    adapt based on the spatial or temporal nature of the decomposition.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> data = np.array([[1, 2, 3], [4, 5, 6]])
+    >>> transposed = transposeifspatial(data, decompaxis="spatial")
+    >>> print(transposed)
+    [[1 4]
+     [2 5]
+     [3 6]]
+
+    >>> original = transposeifspatial(data, decompaxis="temporal")
+    >>> print(original)
+    [[1 2 3]
+     [4 5 6]]
+    """
     if decompaxis == "spatial":
         return np.transpose(data)
     else:
@@ -125,16 +247,90 @@ def transposeifspatial(data, decompaxis="temporal"):
 
 
 def niftidecomp_workflow(
-    decompaxis,
-    datafilelist,
-    datamaskname=None,
-    decomptype="pca",
-    pcacomponents=0.5,
-    icacomponents=None,
-    varnorm=True,
-    demean=True,
-    sigma=0.0,
-):
+    decompaxis: Any,
+    datafilelist: Any,
+    datamaskname: Optional[Any] = None,
+    decomptype: str = "pca",
+    pcacomponents: float = 0.5,
+    icacomponents: Optional[Any] = None,
+    varnorm: bool = True,
+    demean: bool = True,
+    sigma: float = 0.0,
+) -> None:
+    """
+    Perform PCA or ICA decomposition on 4D NIfTI data along a specified axis.
+
+    This function reads a list of NIfTI files, applies optional smoothing and masking,
+    and performs either Principal Component Analysis (PCA) or Independent Component Analysis (ICA)
+    on the data. The decomposition is performed along either the temporal or spatial axis,
+    depending on the `decompaxis` parameter. The results include component images, coefficients,
+    and inverse-transformed data.
+
+    Parameters
+    ----------
+    decompaxis : Any
+        Axis along which to perform decomposition. Either "temporal" or "spatial".
+    datafilelist : Any
+        List of paths to NIfTI data files to be processed.
+    datamaskname : Any, optional
+        Path to a NIfTI mask file. If provided, only voxels within the mask will be processed.
+        Default is None.
+    decomptype : str, optional
+        Type of decomposition to perform. Either "pca" or "ica". Default is "pca".
+    pcacomponents : float, optional
+        Number of components to retain for PCA. If less than 1, specifies the fraction of
+        variance to retain. Default is 0.5.
+    icacomponents : Any, optional
+        Number of components to retain for ICA. If None, all components are returned.
+        Default is None.
+    varnorm : bool, optional
+        Whether to perform variance normalization. Default is True.
+    demean : bool, optional
+        Whether to demean the data. Default is True.
+    sigma : float, optional
+        Standard deviation for Gaussian smoothing. If 0.0, no smoothing is applied.
+        Default is 0.0.
+
+    Returns
+    -------
+    tuple
+        A tuple containing:
+        - outputcomponents : ndarray
+            Decomposed components reshaped to original spatial dimensions.
+        - outputcoefficients : ndarray
+            Coefficients of the decomposition.
+        - outinvtrans : ndarray
+            Inverse-transformed data.
+        - exp_var : ndarray
+            Explained variance for each component.
+        - exp_var_pct : ndarray
+            Explained variance percentage for each component.
+        - datafile_hdr : dict
+            Header of the input data file.
+        - datafiledims : list
+            Dimensions of the input data file.
+        - datafilesizes : list
+            Size parameters of the input data file.
+
+    Notes
+    -----
+    - The function assumes all input NIfTI files have matching spatial and temporal dimensions.
+    - For ICA, the `FastICA` algorithm is used.
+    - For PCA, both regular PCA and Sparse PCA are supported.
+    - If `datamaskname` is provided, the mask is applied before decomposition.
+    - The output data is reshaped to match the original NIfTI dimensions.
+
+    Examples
+    --------
+    >>> niftidecomp_workflow(
+    ...     decompaxis="temporal",
+    ...     datafilelist=["data1.nii", "data2.nii"],
+    ...     decomptype="pca",
+    ...     pcacomponents=0.95,
+    ...     varnorm=True,
+    ...     demean=True
+    ... )
+    """
     print(f"Will perform {decomptype} analysis along the {decompaxis} axis")
 
     if decompaxis == "temporal":
@@ -360,7 +556,55 @@ def niftidecomp_workflow(
     )
 
 
-def main(decompaxis, args):
+def main(decompaxis: Any, args: Any) -> None:
+    """
+    Main function for performing decomposition analysis on neuroimaging data.
+
+    This function handles the configuration of decomposition parameters based on
+    the number of components specified (`ncomp`), and then executes the decomposition
+    workflow using `niftidecomp_workflow`. It saves the results including components,
+    coefficients, and explained variance to disk.
+
+    Parameters
+    ----------
+    decompaxis : Any
+        The axis along which decomposition is performed (e.g., 'temporal' or 'spatial').
+    args : Any
+        A dictionary containing various configuration parameters such as:
+        - `ncomp`: Number of components to extract.
+        - `datafile`: Path to the input data file.
+        - `datamaskname`: Path to the data mask file.
+        - `decomptype`: Type of decomposition (e.g., PCA, ICA).
+        - `varnorm`: Whether to normalize variance.
+        - `demean`: Whether to demean the data.
+        - `sigma`: Sigma value for smoothing.
+        - `outputroot`: Root name for output files.
+
+    Returns
+    -------
+    None
+        This function does not return a value but writes multiple output files to disk.
+
+    Notes
+    -----
+    - If `ncomp` is less than 0.0, `pcacomponents` is set to 0.5 and `icacomponents` is set to None.
+    - If `ncomp` is between 0.0 and 1.0, `pcacomponents` is set to `ncomp` and `icacomponents` is set to None.
+    - Otherwise, both `pcacomponents` and `icacomponents` are set to the integer value of `ncomp`.
+
+    Examples
+    --------
+    >>> args = {
+    ...     "ncomp": 5,
+    ...     "datafile": "data.nii.gz",
+    ...     "datamaskname": "mask.nii.gz",
+    ...     "decomptype": "pca",
+    ...     "varnorm": True,
+    ...     "demean": True,
+    ...     "sigma": 2.0,
+    ...     "outputroot": "output"
+    ... }
+    >>> main("temporal", args)
+    """
     if args["ncomp"] < 0.0:
         args["pcacomponents"] = 0.5
         args["icacomponents"] = None
@@ -448,9 +692,69 @@ def main(decompaxis, args):
     )
 
 
-def main_temporal(args):
+def main_temporal(args: Any) -> None:
+    """
+    Execute main function for temporal processing.
+
+    This function serves as a wrapper that calls the main execution function
+    with "temporal" as the processor type and converts the arguments to a dictionary.
+
+    Parameters
+    ----------
+    args : Any
+        Command line arguments or configuration arguments containing
+        parameters needed for temporal processing. Typically contains
+        various temporal processing options and settings.
+
+    Returns
+    -------
+    None
+        This function does not return any value.
+
+    Notes
+    -----
+    The function delegates to a main execution function with "temporal" processor
+    type, making it a specialized entry point for temporal data processing workflows.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> parser = argparse.ArgumentParser()
+    >>> parser.add_argument('--input', type=str, help='Input file path')
+    >>> args = parser.parse_args(['--input', 'data.csv'])
+    >>> main_temporal(args)
+    """
     main("temporal", vars(args))
 
 
-def main_spatial(args):
+def main_spatial(args: Any) -> None:
+    """
+    Main function for spatial processing pipeline.
+
+    This function serves as the entry point for spatial data processing operations,
+    delegating to the main processing function with "spatial" as the operation type.
+
+    Parameters
+    ----------
+    args : Any
+        Command line arguments or configuration parameters containing spatial
+        processing options. Expected to be an argparse.Namespace or similar
+        structure with relevant attributes for spatial operations.
+
+    Returns
+    -------
+    None
+        This function does not return any value.
+
+    Notes
+    -----
+    The function internally calls `main("spatial", vars(args))` which routes
+    the spatial processing workflow to the main execution engine.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(input_file="data.csv", output_dir="output/")
+    >>> main_spatial(args)
+    """
     main("spatial", vars(args))

rapidtide/workflows/niftistats.py

@@ -21,8 +21,11 @@ import copy
 import platform
 import sys
 import time
+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 ttest_ind, ttest_rel
 from tqdm import tqdm
 
@@ -33,7 +36,44 @@ import rapidtide.util as tide_util
 from rapidtide.workflows.parser_funcs import is_float, is_valid_file
 
 
-def _get_parser(calctype="icc"):
+def _get_parser(calctype: str = "icc") -> Any:
+    """
+    Generate an argument parser for ICC or t-test calculation workflows.
+
+    This function creates an `argparse.ArgumentParser` tailored for either
+    calculating per-voxel Intraclass Correlation Coefficient (ICC(3,1)) or
+    performing per-voxel t-tests on 4D NIfTI images.
+
+    Parameters
+    ----------
+    calctype : str, optional
+        Type of calculation to perform. Either "icc" for ICC(3,1) or "ttest"
+        for t-test. Default is "icc".
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the specified calculation type.
+
+    Raises
+    ------
+    ValueError
+        If `calctype` is not "icc" or "ttest".
+
+    Notes
+    -----
+    The parser supports both required and optional arguments depending on
+    the calculation type. For ICC, an additional `measurementlist` argument
+    is required. For t-test, optional arguments such as `--paired` and
+    `--alternative` are available.
+
+    Examples
+    --------
+    >>> parser = _get_parser("icc")
+    >>> args = parser.parse_args(["file1.nii", "file2.nii", "output_root"])
+    >>> parser = _get_parser("ttest")
+    >>> args = parser.parse_args(["file1.nii", "file2.nii", "output_root"])
+    """
     if calctype == "icc":
         parser = argparse.ArgumentParser(
             prog="calcicc",
@@ -161,7 +201,55 @@ def _get_parser(calctype="icc"):
     return parser
 
 
-def parsemeasurementlist(measlist, numfiles, debug=False):
+def parsemeasurementlist(measlist: Any, numfiles: Any, debug: bool = False) -> None:
+    """
+    Parse a measurement list to extract file and volume indices from string components.
+
+    This function processes a 2D array of strings, where each string contains either
+    one or two comma-separated integers representing file and volume indices. It
+    validates the indices against the number of available files and returns two
+    arrays of the same shape as `measlist` containing the parsed file and volume
+    indices.
+
+    Parameters
+    ----------
+    measlist : array-like
+        A 2D array of strings, where each string represents a measurement entry.
+        Each entry can contain one or two comma-separated integers:
+        - One integer: interpreted as volume index (file index defaults to 0)
+        - Two integers: interpreted as file index and volume index
+    numfiles : int
+        The total number of available files. Used to validate file indices.
+    debug : bool, optional
+        If True, prints debug information for each parsed element. Default is False.
+
+    Returns
+    -------
+    tuple of ndarray
+        A tuple containing two 2D arrays of integers:
+        - `filesel`: File indices parsed from `measlist`
+        - `volumesel`: Volume indices parsed from `measlist`
+
+    Notes
+    -----
+    - Entries in `measlist` must be strings that can be split by commas.
+    - File indices are validated to ensure they do not exceed `numfiles - 1`.
+    - If an entry has more than one comma, the function will exit with an error.
+    - The function prints error messages and exits if invalid input is detected.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> measlist = np.array([['0,5', '1,3'], ['2', '0,7']])
+    >>> numfiles = 5
+    >>> filesel, volumesel = parsemeasurementlist(measlist, numfiles)
+    >>> print(filesel)
+    [[0 1]
+     [2 0]]
+    >>> print(volumesel)
+    [[5 3]
+     [2 7]]
+    """
     nummeas, numsubjs = measlist.shape[0], measlist.shape[1]
     filesel = np.zeros((nummeas, numsubjs), dtype=int)
     volumesel = np.zeros((nummeas, numsubjs), dtype=int)
@@ -189,7 +277,53 @@ def parsemeasurementlist(measlist, numfiles, debug=False):
     return filesel, volumesel
 
 
-def makdcommandlinelist(arglist, starttime, endtime, extra=None):
+def makdcommandlinelist(
+    arglist: Any, starttime: Any, endtime: Any, extra: Optional[Any] = None
+) -> None:
+    """
+    Create a list of command line information for processing logs.
+
+    This function generates diagnostic information about a processing run including
+    timestamps, version information, and the command that was executed.
+
+    Parameters
+    ----------
+    arglist : Any
+        List of command line arguments that were used to invoke the process
+    starttime : Any
+        Start time of the process, typically a timestamp
+    endtime : Any
+        End time of the process, typically a timestamp
+    extra : Any, optional
+        Additional information to include in the output, by default None
+
+    Returns
+    -------
+    list of str
+        List containing diagnostic lines including:
+        - Processing date and time
+        - Processing duration
+        - Version and system information
+        - Extra information (if provided)
+        - The original command line
+
+    Notes
+    -----
+    The function uses `time.strftime` to format the start time and calculates
+    the processing duration as the difference between endtime and starttime.
+    The version information is retrieved using `tide_util.version()`.
+
+    Examples
+    --------
+    >>> arglist = ['python', 'script.py', '--input', 'data.txt']
+    >>> starttime = time.time() - 10
+    >>> endtime = time.time()
+    >>> makdcommandlinelist(arglist, starttime, endtime)
+    ['# Processed on Mon, 01 Jan 2024 12:00:00 UTC.',
+     '# Processing took 10.000 seconds.',
+     '# Using hostname (1.0.0, 2024-01-01)',
+     'python script.py --input data.txt']
+    """
     # get the processing date
     dateline = (
         "# Processed on "
@@ -226,7 +360,43 @@ def makdcommandlinelist(arglist, starttime, endtime, extra=None):
         return [dateline, timeline, nodeline, commandline]
 
 
-def niftistats_main(calctype="icc"):
+def niftistats_main(calctype: str = "icc") -> None:
+    """
+    Main function for computing intraclass correlation (ICC) or two-sample t-test on NIfTI files.
+
+    This function processes NIfTI data files to compute either an intraclass correlation (ICC)
+    or a two-sample t-test across subjects and measurements. It supports reading data from
+    multiple NIfTI files, applying smoothing, masking, and performing statistical analysis
+    voxel-wise. The results are saved as NIfTI files with corresponding statistics.
+
+    Parameters
+    ----------
+    calctype : str, optional
+        Type of statistical calculation to perform. Options are:
+        - "icc": Compute intraclass correlation (default)
+        - "ttest": Compute two-sample t-test
+        Default is "icc".
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves output NIfTI files and a command-line
+        log file to disk.
+
+    Notes
+    -----
+    For ICC calculation:
+        - Requires at least two measurements per subject.
+        - Outputs ICC, variance components, and session effect F-statistic.
+    For t-test calculation:
+        - Requires exactly two measurements.
+        - Outputs t-statistic and p-value.
+
+    Examples
+    --------
+    >>> niftistats_main(calctype="icc")
+    >>> niftistats_main(calctype="ttest")
+    """
     try:
         args = _get_parser(calctype=calctype).parse_args()
     except SystemExit: