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

rapidtide/RapidtideDataset.py

@@ -19,9 +19,11 @@
 import copy
 import os
 import sys
+from typing import Any, Callable
 
 import nibabel as nib
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.filter as tide_filt
 import rapidtide.io as tide_io
@@ -39,7 +41,42 @@ atlases = {
 }
 
 
-def check_rt_spatialmatch(dataset1, dataset2):
+def check_rt_spatialmatch(dataset1: Any, dataset2: Any) -> tuple[bool, bool, bool, bool]:
+    """
+    Check spatial matching between two datasets for dimension, size, space, and affine properties.
+
+    This function compares four key spatial attributes between two datasets to determine
+    if they are spatially compatible for further processing or analysis.
+
+    Parameters
+    ----------
+    dataset1 : Any
+        First dataset object containing spatial attributes xdim, ydim, zdim, xsize, ysize,
+        zsize, space, and affine.
+    dataset2 : Any
+        Second dataset object containing the same spatial attributes as dataset1.
+
+    Returns
+    -------
+    tuple[bool, bool, bool, bool]
+        A tuple of four boolean values representing:
+        - dimmatch: True if all spatial dimensions (xdim, ydim, zdim) match
+        - sizematch: True if all spatial sizes (xsize, ysize, zsize) match
+        - spacematch: True if spatial coordinate systems (space) match
+        - affinematch: True if affine transformation matrices (affine) match
+
+    Notes
+    -----
+    The function performs element-wise comparison of spatial attributes. For affine matrices,
+    the comparison uses Python's default equality operator, which may be sensitive to
+    floating-point precision differences.
+
+    Examples
+    --------
+    >>> dimmatch, sizematch, spacematch, affinematch = check_rt_spatialmatch(dataset1, dataset2)
+    >>> if dimmatch and sizematch:
+    ...     print("Datasets have matching dimensions and sizes")
+    """
     if (
         (dataset1.xdim == dataset2.xdim)
         and (dataset1.ydim == dataset2.ydim)
@@ -72,18 +109,72 @@ class Timecourse:
 
     def __init__(
         self,
-        name,
-        filename,
-        namebase,
-        samplerate,
-        displaysamplerate,
-        starttime=0.0,
-        label=None,
-        report=False,
-        isbids=False,
-        limits=None,
-        verbose=0,
-    ):
+        name: str,
+        filename: str,
+        namebase: str,
+        samplerate: float,
+        displaysamplerate: float,
+        starttime: float = 0.0,
+        label: str | None = None,
+        report: bool = False,
+        isbids: bool = False,
+        limits: tuple[float, float] | None = None,
+        verbose: int = 0,
+    ) -> None:
+        """
+        Initialize a Timecourse object for reading and managing time series data.
+
+        This constructor sets up the basic properties of a timecourse and reads the
+        time series data from the specified file.
+
+        Parameters
+        ----------
+        name : str
+            The name of the timecourse, used for identification
+        filename : str
+            The full path to the data file containing the time series
+        namebase : str
+            The base name of the file (without path)
+        samplerate : float
+            The sampling rate of the time series data in Hz
+        displaysamplerate : float
+            The sampling rate used for display purposes in Hz
+        starttime : float, default=0.0
+            The start time of the time series in seconds
+        label : str, optional
+            The label to use for display. If None, defaults to the name parameter
+        report : bool, default=False
+            Whether to generate a report during initialization
+        isbids : bool, default=False
+            Whether the data follows BIDS (Brain Imaging Data Structure) format
+        limits : tuple of float, optional
+            The (min, max) value limits for the time series data
+        verbose : int, default=0
+            Verbosity level for logging output (0 = quiet, higher values = more verbose)
+
+        Returns
+        -------
+        None
+            This method initializes the object and does not return any value
+
+        Notes
+        -----
+        The method automatically reads the time series data using the readTimeData method
+        after setting all the internal attributes. If verbose level is greater than 1,
+        a message is printed indicating the file being read.
+
+        Examples
+        --------
+        >>> tc = Timecourse(
+        ...     name="ECG",
+        ...     filename="/data/ecg_data.dat",
+        ...     namebase="ecg_data",
+        ...     samplerate=1000.0,
+        ...     displaysamplerate=100.0,
+        ...     starttime=0.0,
+        ...     label="Electrocardiogram"
+        ... )
+        """
         self.verbose = verbose
         self.name = name
         self.filename = filename
@@ -103,7 +194,45 @@ class Timecourse:
             print("reading Timecourse ", self.name, " from ", self.filename, "...")
         self.readTimeData(self.label)
 
-    def readTimeData(self, thename):
+    def readTimeData(self, thename: str) -> None:
+        """
+        Read time series data from a file and compute associated statistics and spectral properties.
+
+        This function reads time series data either from a BIDS-compatible TSV file or a vector file,
+        depending on whether the object is configured to use BIDS format. It computes the time axis,
+        spectral data, and statistical measures (kurtosis and skewness) for the selected column or
+        the entire dataset.
+
+        Parameters
+        ----------
+        thename : str
+            The name of the column to extract from the BIDS TSV file. Ignored if not using BIDS format.
+
+        Returns
+        -------
+        None
+            This function does not return a value but updates the following attributes of the object:
+            - `timedata`: The time series data as a numpy array.
+            - `length`: The length of the time series.
+            - `timeaxis`: The time axis corresponding to the data.
+            - `specaxis`: The frequency axis for the power spectrum.
+            - `specdata`: The power spectrum of the time series.
+            - `kurtosis`, `kurtosis_z`, `kurtosis_p`: Kurtosis statistics.
+            - `skewness`, `skewness_z`, `skewness_p`: Skewness statistics.
+
+        Notes
+        -----
+        If the `thename` column is not found in a BIDS TSV file, the function sets `timedata` to `None`
+        and returns early. The function uses `tide_io.readbidstsv` for BIDS files and `tide_io.readvec`
+        for non-BIDS files. Spectral analysis and statistical computations are performed using
+        `tide_filt.spectrum`, `tide_math.corrnormalize`, and `tide_stats.kurtosisstats`/`skewnessstats`.
+
+        Examples
+        --------
+        >>> obj.readTimeData('signal')
+        >>> print(obj.timedata)
+        >>> print(obj.specdata)
+        """
         if self.isbids:
             dummy, dummy, columns, indata, dummy, dummy = tide_io.readbidstsv(self.filename)
             try:
@@ -146,7 +275,54 @@ class Timecourse:
 
             print()
 
-    def summarize(self):
+    def summarize(self) -> None:
+        """
+        Print a summary of the timecourse properties.
+
+        This method outputs a formatted summary of various properties associated with
+        the timecourse object, including name, label, file information, sampling rate,
+        length, and statistical measures.
+
+        Parameters
+        ----------
+        self : object
+            The timecourse object instance containing the properties to be summarized.
+            Expected attributes include:
+            - name: str, the name of the timecourse
+            - label: str, the label associated with the timecourse
+            - filename: str, the filename of the timecourse data
+            - namebase: str, the base name of the file
+            - samplerate: float, the sampling rate of the timecourse
+            - length: int, the length of the timecourse
+            - kurtosis: float, the kurtosis value of the timecourse
+            - kurtosis_z: float, the z-score of the kurtosis
+            - kurtosis_p: float, the p-value of the kurtosis
+
+        Returns
+        -------
+        None
+            This method prints the summary information to stdout and does not return any value.
+
+        Notes
+        -----
+        The output is formatted for readability with consistent indentation and
+        descriptive labels for each property. This method is typically used for
+        debugging and quick inspection of timecourse properties.
+
+        Examples
+        --------
+        >>> timecourse = Timecourse(name="test_signal", label="test", filename="test.csv")
+        >>> timecourse.summarize()
+        Timecourse name:       test_signal
+            label:            test
+            filename:         test.csv
+            namebase:         test
+            samplerate:       100.0
+            length:           1000
+            kurtosis:         0.5
+            kurtosis_z:       1.2
+            kurtosis_p:       0.23
+        """
         print()
         print("Timecourse name:      ", self.name)
         print("    label:            ", self.label)
@@ -166,22 +342,86 @@ class Overlay:
 
     def __init__(
         self,
-        name,
-        filespec,
-        namebase,
-        funcmask=None,
-        geommask=None,
-        label=None,
-        report=False,
-        lut_state=gen_gray_state(),
-        alpha=128,
-        endalpha=0,
-        display_state=True,
-        invertonload=False,
-        isaMask=False,
-        init_LUT=True,
-        verbose=1,
-    ):
+        name: str,
+        filespec: str,
+        namebase: str,
+        funcmask: NDArray | None = None,
+        geommask: NDArray | None = None,
+        label: str | None = None,
+        report: bool = False,
+        lut_state: dict = gen_gray_state(),
+        alpha: int = 128,
+        endalpha: int = 0,
+        display_state: bool = True,
+        invertonload: bool = False,
+        isaMask: bool = False,
+        init_LUT: bool = True,
+        verbose: int = 1,
+    ) -> None:
+        """
+        Initialize an overlay object for rapidtide image data visualization.
+
+        This constructor initializes an overlay by loading image data from a file,
+        applying functional and geometric masks, and setting up display properties
+        including lookup tables and affine transformations.
+
+        Parameters
+        ----------
+        name : str
+            Name of the overlay.
+        filespec : str
+            File specification string used to locate and load the image data.
+        namebase : str
+            Base name for the overlay, used in file naming and labeling.
+        funcmask : NDArray | None, optional
+            Functional mask to apply to the data. Default is None.
+        geommask : NDArray | None, optional
+            Geometric mask to apply to the data. Default is None.
+        label : str | None, optional
+            Label for the overlay. If None, defaults to the value of `name`. Default is None.
+        report : bool, optional
+            If True, enables reporting mode. Default is False.
+        lut_state : dict, optional
+            Lookup table state dictionary. Default is ``gen_gray_state()``.
+        alpha : int, optional
+            Initial alpha value for display. Default is 128.
+        endalpha : int, optional
+            End alpha value for display. Default is 0.
+        display_state : bool, optional
+            If True, initializes display state. Default is True.
+        invertonload : bool, optional
+            If True, inverts the data on load. Default is False.
+        isaMask : bool, optional
+            If True, treats the data as a mask. Default is False.
+        init_LUT : bool, optional
+            If True, initializes the lookup table. Default is True.
+        verbose : int, optional
+            Verbosity level. Default is 1.
+
+        Returns
+        -------
+        None
+            This method initializes the object in-place and does not return a value.
+
+        Notes
+        -----
+        The constructor performs the following steps:
+        1. Loads image data using `tide_io.processnamespec`.
+        2. Applies functional and geometric masks.
+        3. Sets up display parameters such as `dispmin` and `dispmax`.
+        4. Initializes lookup table if `init_LUT` is True.
+        5. Determines the spatial coordinate system and affine transformation matrix.
+        6. Determines the orientation (neurological or radiological) based on the affine matrix.
+
+        Examples
+        --------
+        >>> overlay = Overlay(
+        ...     name="my_overlay",
+        ...     filespec="/path/to/image.nii",
+        ...     namebase="overlay_base",
+        ...     verbose=2
+        ... )
+        """
         self.verbose = verbose
         self.name = name
         if label is None:
@@ -266,7 +506,41 @@ class Overlay:
         if self.verbose > 0:
             self.summarize()
 
-    def duplicate(self, newname, newlabel, init_LUT=True):
+    def duplicate(self, newname: str, newlabel: str, init_LUT: bool = True) -> Any:
+        """
+        Create a duplicate of the current overlay with new name and label.
+
+        Parameters
+        ----------
+        newname : str
+            The name for the new overlay instance.
+        newlabel : str
+            The label for the new overlay instance.
+        init_LUT : bool, optional
+            Whether to initialize the lookup table for the new overlay.
+            Default is True.
+
+        Returns
+        -------
+        Any
+            A new Overlay instance with the specified name and label,
+            inheriting all properties from the current overlay.
+
+        Notes
+        -----
+        This method creates a shallow copy of the current overlay with
+        updated name and label attributes. The new overlay maintains
+        references to the original data files and masks.
+
+        Examples
+        --------
+        >>> overlay = Overlay("original", "file.nii", "base")
+        >>> new_overlay = overlay.duplicate("copy", "Copy Label")
+        >>> print(new_overlay.name)
+        'copy'
+        >>> print(new_overlay.label)
+        'Copy Label'
+        """
         return Overlay(
             newname,
             self.filename,
@@ -279,7 +553,39 @@ class Overlay:
             verbose=self.verbose,
         )
 
-    def updateStats(self):
+    def updateStats(self) -> None:
+        """
+        Update statistical properties of the masked data.
+
+        This method calculates various statistical measures from the masked data,
+        including min/max values, quartiles, robust statistics, and histogram data.
+        The results are stored as instance attributes for later use.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return a value but updates instance attributes
+            with statistical calculations.
+
+        Notes
+        -----
+        The method uses the mask to filter data points where mask != 0.
+        Statistical calculations include:
+        - Minimum and maximum values
+        - Robust statistics (0.02, 0.25, 0.5, 0.75, 0.98 percentiles)
+        - Histogram data with 200 bins
+        - Quartiles (25th, 50th, 75th percentiles)
+
+        Examples
+        --------
+        >>> obj.updateStats()
+        >>> print(obj.minval, obj.maxval)
+        >>> print(obj.quartiles)
+        """
         calcmaskeddata = self.data[np.where(self.mask != 0)]
 
         self.minval = calcmaskeddata.min()
@@ -307,14 +613,87 @@ class Overlay:
                 self.quartiles,
             )
 
-    def setData(self, data, isaMask=False):
+    def setData(self, data: NDArray, isaMask: bool = False) -> None:
+        """
+        Set the data array and optionally convert it to a binary mask.
+
+        This method assigns the provided data array to the internal data attribute
+        and optionally converts it to a binary mask where values less than 0.5
+        are set to 0.0 and values greater than 0.5 are set to 1.0.
+
+        Parameters
+        ----------
+        data : NDArray
+            The input data array to be set. A copy of this array is stored internally.
+        isaMask : bool, optional
+            If True, converts the data to a binary mask. Values less than 0.5 become 0.0,
+            and values greater than 0.5 become 1.0. Default is False.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        The data is stored as a copy to prevent external modifications from affecting
+        the internal state. The mask conversion is performed using numpy's where function
+        for efficient element-wise operations.
+
+        Examples
+        --------
+        >>> obj.setData(np.array([0.2, 0.7, 0.3, 0.8]))
+        >>> obj.setData(np.array([0.2, 0.7, 0.3, 0.8]), isaMask=True)
+        """
         self.data = data.copy()
         if isaMask:
             self.data[np.where(self.data < 0.5)] = 0.0
             self.data[np.where(self.data > 0.5)] = 1.0
         self.updateStats()
 
-    def readImageData(self, isaMask=False):
+    def readImageData(self, isaMask: bool = False) -> None:
+        """
+        Read image data from a NIfTI file and process it based on specified flags.
+
+        This function loads image data from a NIfTI file using `tide_io.readfromnifti`,
+        applies optional inversion and masking operations, and extracts dimension and
+        spacing information from the header.
+
+        Parameters
+        ----------
+        isaMask : bool, optional
+            If True, process the data as a binary mask. For non-mask files, values
+            less than 0.5 are set to 0, and values greater than 0.5 are set to 1.
+            For mask files with `filevals` defined, the data is converted to a binary
+            mask based on matching values in `filevals`. Default is False.
+
+        Returns
+        -------
+        None
+            This function does not return a value but updates the instance attributes
+            `nim`, `data`, `header`, `dims`, `sizes`, `xdim`, `ydim`, `zdim`, `tdim`,
+            `xsize`, `ysize`, `zsize`, `tr`, and `toffset`.
+
+        Notes
+        -----
+        - If `invertonload` is True, the data is multiplied by -1.0.
+        - The function prints data range and header information if `verbose > 1`.
+        - Dimension and spacing information is parsed using `tide_io.parseniftidims` and
+          `tide_io.parseniftisizes`.
+
+        Examples
+        --------
+        >>> reader = ImageReader()
+        >>> reader.filename = "example.nii"
+        >>> reader.invertonload = True
+        >>> reader.verbose = 2
+        >>> reader.readImageData(isaMask=True)
+        Overlay data range: -1.0 1.0
+        header {'toffset': 0.0, ...}
+        Overlay dims: 64 64 32 1
+        Overlay sizes: 3.0 3.0 3.0 2.0
+        Overlay toffset: 0.0
+        """
         self.nim, self.data, self.header, self.dims, self.sizes = tide_io.readfromnifti(
             self.filename
         )
@@ -340,16 +719,97 @@ class Overlay:
             print("Overlay sizes:", self.xsize, self.ysize, self.zsize, self.tr)
             print("Overlay toffset:", self.toffset)
 
-    def setLabel(self, label):
+    def setLabel(self, label: str) -> None:
+        """
+        Set the label for the object.
+
+        Parameters
+        ----------
+        label : str
+            The label to assign to the object.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method directly assigns the provided label to the object's label attribute.
+        The label is typically used for identification or display purposes.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setLabel("New Label")
+        >>> print(obj.label)
+        'New Label'
+        """
         self.label = label
 
-    def real2tr(self, time):
+    def real2tr(self, time: float) -> float:
+        """
+        Convert real time to trigger time.
+
+        Convert a real time value to its corresponding trigger time value by applying
+        the time offset and trigger period parameters.
+
+        Parameters
+        ----------
+        time : float
+            The real time value to be converted to trigger time.
+
+        Returns
+        -------
+        float
+            The converted trigger time value, rounded to the nearest integer.
+
+        Notes
+        -----
+        The conversion is performed using the formula: ``round((time - toffset) / tr)``
+        where ``toffset`` is the time offset and ``tr`` is the trigger period.
+
+        Examples
+        --------
+        >>> obj.real2tr(10.5)
+        2.0
+        >>> obj.real2tr(5.0)
+        0.0
+        """
         return np.round((time - self.toffset) / self.tr, 0)
 
-    def tr2real(self, tpos):
+    def tr2real(self, tpos: int) -> float:
         return self.toffset + self.tr * tpos
 
-    def real2vox(self, xcoord, ycoord, zcoord, time):
+    def real2vox(
+        self, xcoord: float, ycoord: float, zcoord: float, time: float
+    ) -> tuple[int, int, int, int]:
+        """
+        Convert a time position to a real time value.
+
+        Parameters
+        ----------
+        tpos : int
+            Time position index to convert to real time value.
+
+        Returns
+        -------
+        float
+            The corresponding real time value calculated as `toffset + tr * tpos`.
+
+        Notes
+        -----
+        This function performs a linear transformation from discrete time positions
+        to continuous time values using the instance's time offset and time rate
+        parameters.
+
+        Examples
+        --------
+        >>> obj.tr2real(0)
+        10.0
+        >>> obj.tr2real(5)
+        15.0
+        """
         x, y, z = nib.apply_affine(self.invaffine, [xcoord, ycoord, zcoord])
         t = self.real2tr(time)
         return (
@@ -359,30 +819,183 @@ class Overlay:
             int(np.round(t, 0)),
         )
 
-    def vox2real(self, xpos, ypos, zpos, tpos):
+    def vox2real(self, xpos: int, ypos: int, zpos: int, tpos: int) -> NDArray:
+        """
+        Convert voxel coordinates to real-world coordinates.
+
+        This function transforms voxel coordinates (x, y, z, t) to real-world coordinates
+        using the affine transformation matrix and temporal transformation.
+
+        Parameters
+        ----------
+        xpos : int
+            X coordinate in voxel space
+        ypos : int
+            Y coordinate in voxel space
+        zpos : int
+            Z coordinate in voxel space
+        tpos : int
+            T coordinate in voxel space (temporal dimension)
+
+        Returns
+        -------
+        NDArray
+            Array containing real-world coordinates [x_real, y_real, z_real, t_real]
+
+        Notes
+        -----
+        The conversion uses nibabel's apply_affine function for spatial transformation
+        and self.tr2real for temporal transformation. The result includes both
+        spatial and temporal coordinates in real-world units.
+
+        Examples
+        --------
+        >>> vox2real(10, 20, 30, 5)
+        array([12.5, 25.0, 37.5, 2.5])
+        """
         return np.concatenate(
             (nib.apply_affine(self.affine, [xpos, ypos, zpos]), [self.tr2real(tpos)]),
             axis=0,
         )
 
-    def setXYZpos(self, xpos, ypos, zpos):
+    def setXYZpos(self, xpos: int, ypos: int, zpos: int) -> None:
+        """
+        Set the 3D position coordinates of the object.
+
+        Parameters
+        ----------
+        xpos : int
+            The x-coordinate position value.
+        ypos : int
+            The y-coordinate position value.
+        zpos : int
+            The z-coordinate position value.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        All position values are converted to integers before assignment.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setXYZpos(10, 20, 30)
+        >>> print(obj.xpos, obj.ypos, obj.zpos)
+        10 20 30
+        """
         self.xpos = int(xpos)
         self.ypos = int(ypos)
         self.zpos = int(zpos)
 
-    def setTpos(self, tpos):
+    def setTpos(self, tpos: int) -> None:
+        """
+        Set the temporal position attribute with bounds checking.
+
+        Parameters
+        ----------
+        tpos : int
+            The temporal position to set. If greater than self.tdim - 1,
+            it will be clamped to self.tdim - 1.
+
+        Returns
+        -------
+        None
+            This method modifies the instance in-place and does not return a value.
+
+        Notes
+        -----
+        The temporal position is bounded by the dimensionality of the temporal
+        space (self.tdim). If the input tpos exceeds this limit, it will be
+        automatically adjusted to the maximum valid position (self.tdim - 1).
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.tdim = 5
+        >>> obj.setTpos(3)
+        >>> obj.tpos
+        3
+        >>> obj.setTpos(10)
+        >>> obj.tpos
+        4
+        """
         if tpos > self.tdim - 1:
             self.tpos = int(self.tdim - 1)
         else:
             self.tpos = int(tpos)
 
-    def getFocusVal(self):
+    def getFocusVal(self) -> float:
+        """
+        Get the focus value at the current position.
+
+        This method retrieves the data value from the masked data array at the
+        current position coordinates. The method handles both 3D and 4D data arrays
+        by checking the time dimension.
+
+        Parameters
+        ----------
+        self : object
+            The instance of the class containing the masked data and position
+            coordinates.
+
+        Returns
+        -------
+        float
+            The data value at the current position. For 4D data (tdim > 1), returns
+            the value at [xpos, ypos, zpos, tpos]. For 3D data (tdim <= 1), returns
+            the value at [xpos, ypos, zpos].
+
+        Notes
+        -----
+        The method assumes that the instance has the following attributes:
+        - maskeddata: numpy array containing the data
+        - xpos, ypos, zpos, tpos: integer coordinates
+        - tdim: integer representing the time dimension
+
+        Examples
+        --------
+        >>> value = obj.getFocusVal()
+        >>> print(value)
+        0.5
+        """
         if self.tdim > 1:
             return self.maskeddata[self.xpos, self.ypos, self.zpos, self.tpos]
         else:
             return self.maskeddata[self.xpos, self.ypos, self.zpos]
 
-    def setFuncMask(self, funcmask, maskdata=True):
+    def setFuncMask(self, funcmask: NDArray | None, maskdata: bool = True) -> None:
+        """
+        Set the functional mask for the object.
+
+        Parameters
+        ----------
+        funcmask : array-like, optional
+            The functional mask to be set. If None, a default mask is created based on
+            the dimensionality of the data. If provided, a copy of the mask is stored.
+        maskdata : bool, default=True
+            If True, calls maskData() method after setting the functional mask.
+
+        Returns
+        -------
+        None
+            This method modifies the object in-place and does not return any value.
+
+        Notes
+        -----
+        When funcmask is None, the method creates a default mask:
+        - For 1D data (tdim == 1): creates a mask with the same shape as self.data
+        - For higher dimensional data: creates a mask with shape (self.data.shape[0], self.data.shape[1], self.data.shape[2], 1)
+
+        Examples
+        --------
+        >>> obj.setFuncMask(None)
+        >>> obj.setFuncMask(np.ones((10, 10)))
+        >>> obj.setFuncMask(None, maskdata=False)
+        """
         self.funcmask = funcmask
         if self.funcmask is None:
             if self.tdim == 1:
@@ -394,7 +1007,35 @@ class Overlay:
         if maskdata:
             self.maskData()
 
-    def setGeomMask(self, geommask, maskdata=True):
+    def setGeomMask(self, geommask: NDArray | None, maskdata: bool = True) -> None:
+        """
+        Set the geometric mask for the object and optionally mask the data.
+
+        Parameters
+        ----------
+        geommask : ndarray or None
+            Geometric mask array. If None, a default mask is created based on the
+            object's dimensions. If not None, the provided mask is copied and used.
+        maskdata : bool, default=True
+            If True, applies the mask to the data by calling maskData() method.
+            If False, only sets the geometric mask without masking the data.
+
+        Returns
+        -------
+        None
+            This method modifies the object in-place and does not return any value.
+
+        Notes
+        -----
+        When geommask is None and tdim == 1, a mask of ones with the same shape as
+        self.data is created. Otherwise, a mask of ones with the shape of
+        self.data[:, :, :, 0] is created.
+
+        Examples
+        --------
+        >>> obj.setGeomMask(None)
+        >>> obj.setGeomMask(mask_array, maskdata=False)
+        """
         self.geommask = geommask
         if self.geommask is None:
             if self.tdim == 1:
@@ -406,7 +1047,36 @@ class Overlay:
         if maskdata:
             self.maskData()
 
-    def maskData(self):
+    def maskData(self) -> None:
+        """
+        Apply mask to data and update statistics if mask has changed.
+
+        This method combines geometric and functional masks to create a final mask,
+        then checks if the mask has changed since the last update. If the mask has
+        changed, it applies the mask to the data, sets masked values to zero, and
+        updates the statistics.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method modifies the instance in-place and does not return any value.
+
+        Notes
+        -----
+        The method uses a hash-based approach to efficiently detect when the mask
+        has changed, avoiding expensive operations when the mask remains the same.
+        The mask is applied by setting values to zero where the combined mask is
+        less than 0.5.
+
+        Examples
+        --------
+        >>> obj.maskData()
+        # Applies mask and updates statistics if mask has changed
+        """
         self.mask = self.geommask * self.funcmask
         maskhash = hash(self.mask.tobytes())
         # these operations are expensive, so only do them if the mask is changed
@@ -420,16 +1090,137 @@ class Overlay:
             self.updateStats()
             self.maskhash = maskhash
 
-    def setReport(self, report):
+    def setReport(self, report: bool) -> None:
+        """
+        Set the report flag for the object.
+
+        Parameters
+        ----------
+        report : bool
+            Flag indicating whether reporting is enabled or disabled.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method assigns the provided boolean value to the internal `report` attribute
+        of the object. The attribute can be accessed later to check the current reporting state.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setReport(True)
+        >>> obj.report
+        True
+        >>> obj.setReport(False)
+        >>> obj.report
+        False
+        """
         self.report = report
 
-    def setTR(self, trval):
+    def setTR(self, trval: float) -> None:
+        """
+        Set the TR (repetition time) value for the object.
+
+        Parameters
+        ----------
+        trval : float
+            The repetition time value to be set. This parameter represents the
+            time interval between successive MRI pulse sequences in seconds.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method directly assigns the provided value to the internal `tr` attribute
+        of the object. The TR value is commonly used in MRI data processing and
+        represents the time between the start of one pulse sequence and the start
+        of the next.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setTR(2.0)
+        >>> print(obj.tr)
+        2.0
+        """
         self.tr = trval
 
-    def settoffset(self, toffset):
+    def settoffset(self, toffset: float) -> None:
+        """
+        Set the time offset value.
+
+        Parameters
+        ----------
+        toffset : float
+            The time offset value to set.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method assigns the provided time offset value to the instance variable
+        `self.toffset`. The time offset is typically used to adjust timing references
+        in time-series data processing or temporal calculations.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.settoffset(5.0)
+        >>> print(obj.toffset)
+        5.0
+        """
         self.toffset = toffset
 
-    def setLUT(self, lut_state, alpha=255, endalpha=128):
+    def setLUT(self, lut_state: dict, alpha: int = 255, endalpha: int = 128) -> None:
+        """
+        Set the lookup table (LUT) state with optional alpha blending adjustments.
+
+        This function configures the lookup table state for gradient visualization,
+        applying alpha transparency adjustments to the color ticks and restoring
+        the gradient state with the updated LUT.
+
+        Parameters
+        ----------
+        lut_state : dict
+            Dictionary containing the lookup table state with keys:
+            - "ticks": list of tuples representing color stops
+            - "mode": color mapping mode
+            - "name": name of the LUT
+        alpha : int, optional
+            Alpha value (0-255) to apply to intermediate color ticks, by default 255
+        endalpha : int, optional
+            Alpha value (0-255) to apply to the end color ticks, by default 128
+
+        Returns
+        -------
+        None
+            This function modifies the instance state in-place and does not return anything.
+
+        Notes
+        -----
+        The function applies alpha blending to intermediate color ticks while preserving
+        the original alpha values of the first and last ticks. When verbose mode is enabled
+        (verbose > 1), the modified tick values are printed to the console.
+
+        Examples
+        --------
+        >>> lut_state = {
+        ...     "ticks": [(0, (0, 0, 0, 255)), (128, (128, 128, 128, 255)), (255, (255, 255, 255, 255))],
+        ...     "mode": "RGB",
+        ...     "name": "grayscale"
+        ... }
+        >>> setLUT(lut_state, alpha=128, endalpha=64)
+        """
         if alpha is not None:
             theticks = [lut_state["ticks"][0]]
             for theelement in lut_state["ticks"][1:-1]:
@@ -449,10 +1240,80 @@ class Overlay:
         self.theLUT = self.gradient.getLookupTable(512, alpha=True)
         self.LUTname = lut_state["name"]
 
-    def setisdisplayed(self, display_state):
+    def setisdisplayed(self, display_state: bool) -> None:
+        """
+        Set the display state of the object.
+
+        Parameters
+        ----------
+        display_state : bool
+            The display state to set. True indicates the object should be displayed,
+            False indicates it should be hidden.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method directly assigns the provided display state to the internal
+        `display_state` attribute of the object. The display state controls whether
+        the object is visible in the user interface or not.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setisdisplayed(True)
+        >>> print(obj.display_state)
+        True
+        >>> obj.setisdisplayed(False)
+        >>> print(obj.display_state)
+        False
+        """
         self.display_state = display_state
 
-    def summarize(self):
+    def summarize(self) -> None:
+        """
+        Print a summary of the overlay's properties and metadata.
+
+        This method outputs a formatted summary of the overlay's key attributes,
+        including name, label, file information, dimensions, orientation, and
+        data statistics. It also indicates whether geometric and functional masks
+        are set.
+
+        Notes
+        -----
+        The output is printed directly to the console and does not return any value.
+        This method is intended for debugging or inspection purposes.
+
+        Examples
+        --------
+        >>> overlay = Overlay(...)
+        >>> overlay.summarize()
+        Overlay name:          my_overlay
+            label:            My Overlay
+            filename:         /path/to/my_overlay.nii
+            namebase:         my_overlay
+            xdim:             64
+            ydim:             64
+            zdim:             32
+            tdim:             100
+            space:            MNI
+            orientation:       radiological
+            toffset:          0.0
+            tr:               2.0
+            min:              -1.5
+            max:              2.0
+            robustmin:        -1.0
+            robustmax:        1.5
+            dispmin:          -1.5
+            dispmax:          2.0
+            data shape:       (64, 64, 32, 100)
+            masked data shape: (64, 64, 32, 100)
+            geometric mask is set
+            functional mask not set
+        """
         print()
         print("Overlay name:         ", self.name)
         print("    label:            ", self.label)
@@ -517,24 +1378,89 @@ class RapidtideDataset:
 
     def __init__(
         self,
-        name,
-        fileroot,
-        anatname=None,
-        geommaskname=None,
-        funcmaskname=None,
-        graymaskspec=None,
-        whitemaskspec=None,
-        userise=False,
-        usecorrout=False,
-        useatlas=False,
-        minimal=False,
-        forcetr=False,
-        forceoffset=False,
-        coordinatespace="unspecified",
-        offsettime=0.0,
-        init_LUT=True,
-        verbose=0,
-    ):
+        name: str,
+        fileroot: str,
+        anatname: str | None = None,
+        geommaskname: str | None = None,
+        funcmaskname: str | None = None,
+        graymaskspec: str | None = None,
+        whitemaskspec: str | None = None,
+        userise: bool = False,
+        usecorrout: bool = False,
+        useatlas: bool = False,
+        minimal: bool = False,
+        forcetr: bool = False,
+        forceoffset: bool = False,
+        coordinatespace: str = "unspecified",
+        offsettime: float = 0.0,
+        init_LUT: bool = True,
+        verbose: int = 0,
+    ) -> None:
+        """
+        Initialize a RapidtideDataset object for processing neuroimaging data.
+
+        This constructor sets up the dataset configuration based on provided parameters,
+        determines the naming convention used by the dataset (BIDS or legacy), and
+        initializes internal structures for regressor and overlay handling.
+
+        Parameters
+        ----------
+        name : str
+            Name of the dataset.
+        fileroot : str
+            Root path to the dataset files.
+        anatname : str, optional
+            Path to the anatomical image file. Default is None.
+        geommaskname : str, optional
+            Path to the geometric mask file. Default is None.
+        funcmaskname : str, optional
+            Path to the functional mask file. Default is None.
+        graymaskspec : str, optional
+            Specification for gray matter mask. Default is None.
+        whitemaskspec : str, optional
+            Specification for white matter mask. Default is None.
+        userise : bool, optional
+            Whether to use RISE (reconstruction of instantaneous signal estimates). Default is False.
+        usecorrout : bool, optional
+            Whether to use corrected output. Default is False.
+        useatlas : bool, optional
+            Whether to use atlas-based processing. Default is False.
+        minimal : bool, optional
+            Whether to run in minimal mode. Default is False.
+        forcetr : bool, optional
+            Whether to force TR (repetition time) correction. Default is False.
+        forceoffset : bool, optional
+            Whether to force offset correction. Default is False.
+        coordinatespace : str, optional
+            Coordinate space of the data. Default is "unspecified".
+        offsettime : float, optional
+            Time offset to apply. Default is 0.0.
+        init_LUT : bool, optional
+            Whether to initialize lookup tables. Default is True.
+        verbose : int, optional
+            Verbosity level. Default is 0.
+
+        Returns
+        -------
+        None
+            This method initializes the object and does not return any value.
+
+        Notes
+        -----
+        The function automatically detects whether the dataset uses BIDS-style naming
+        conventions by checking for the presence of specific files like
+        ``<fileroot>desc-maxtime_map.nii.gz``. If not found, it checks for legacy naming
+        patterns such as ``<fileroot>fitmask.nii.gz``.
+
+        Examples
+        --------
+        >>> dataset = RapidtideDataset(
+        ...     name="test_dataset",
+        ...     fileroot="/path/to/data",
+        ...     anatname="/path/to/anat.nii.gz",
+        ...     verbose=1
+        ... )
+        """
         self.verbose = verbose
         self.name = name
         self.fileroot = fileroot
@@ -574,7 +1500,47 @@ class RapidtideDataset:
         self.setupregressors()
         self.setupoverlays()
 
-    def _loadregressors(self):
+    def _loadregressors(self) -> None:
+        """
+        Load regressor timecourses from specified files.
+
+        This method iterates through the list of regressor specifications (`self.regressorspecs`)
+        and attempts to load each regressor from the corresponding file. If a file exists, it is
+        read into a `Timecourse` object and stored in `self.regressors`. If no regressor is
+        successfully loaded, the first one in the list is set as the focus regressor.
+
+        Parameters
+        ----------
+        self : object
+            The instance of the class containing the method. Expected to have the following
+            attributes:
+            - `regressorspecs`: list of tuples specifying regressor files and parameters.
+            - `fileroot`: string, base path for regressor files.
+            - `regressors`: dict, to store loaded regressors.
+            - `focusregressor`: str, name of the currently focused regressor.
+            - `verbose`: int, level of verbosity for logging.
+            - `bidsformat`: bool, flag indicating BIDS format usage.
+            - `regressorsimcalclimits`: tuple, limits for regressor calculation.
+            - `isbids`: bool, flag indicating BIDS format usage (likely a typo for `bidsformat`).
+
+        Returns
+        -------
+        None
+            This method modifies the instance's attributes in place and does not return any value.
+
+        Notes
+        -----
+        - If a regressor file does not exist and the corresponding flag in `regressorspecs` is True,
+          a `FileNotFoundError` is raised.
+        - If a regressor file does not exist and the flag is False, the file is skipped with a message.
+        - The first successfully loaded regressor is set as the `focusregressor` if none is already set.
+
+        Examples
+        --------
+        >>> loader = MyLoader()
+        >>> loader._loadregressors()
+        # Loads regressors specified in `loader.regressorspecs` into `loader.regressors`.
+        """
         self.focusregressor = None
         for thisregressor in self.regressorspecs:
             if os.path.isfile(self.fileroot + thisregressor[2]):
@@ -601,7 +1567,9 @@ class RapidtideDataset:
                     self.focusregressor = thisregressor[0]
             else:
                 if thisregressor[6]:
-                    raise FileNotFoundError(f"regressor file {self.fileroot + thisregressor[2]} does not exist")
+                    raise FileNotFoundError(
+                        f"regressor file {self.fileroot + thisregressor[2]} does not exist"
+                    )
                 else:
                     if self.verbose > 1:
                         print(
@@ -610,7 +1578,46 @@ class RapidtideDataset:
                             " does not exist - skipping...",
                         )
 
-    def _loadfuncmaps(self):
+    def _loadfuncmaps(self) -> None:
+        """
+        Load functional maps from NIfTI files and initialize overlays.
+
+        This function iterates through the list of functional maps specified in
+        `self.funcmaps`, loads each map from a NIfTI file (if it exists), and
+        initializes an `Overlay` object for each. It ensures that all loaded
+        maps have consistent dimensions and voxel sizes. If a map is listed in
+        `mapstoinvert`, it will be inverted upon loading.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This function does not return a value but updates the following
+            instance attributes:
+            - `self.overlays`: Dictionary mapping map names to `Overlay` objects.
+            - `self.loadedfuncmaps`: List of successfully loaded map names.
+
+        Notes
+        -----
+        - The function checks for the existence of `.nii.gz` files before attempting
+          to load them.
+        - If dimensions or voxel sizes of the loaded maps do not match, the program
+          will exit with an error message.
+        - Map names in `mapstoinvert` (currently only "varChange") will be inverted
+          during loading.
+
+        Examples
+        --------
+        Assuming `self.funcmaps` contains entries like:
+        [("varChange", "varchange_map"), ("tstat", "tstat_map")]
+
+        And the corresponding files exist, this function will load these maps and
+        store them in `self.overlays` with appropriate inversion applied where
+        needed.
+        """
         mapstoinvert = ["varChange"]
         self.loadedfuncmaps = []
         xdim = 0
@@ -671,7 +1678,53 @@ class RapidtideDataset:
         if self.verbose > 1:
             print("functional maps loaded:", self.loadedfuncmaps)
 
-    def _loadfuncmasks(self):
+    def _loadfuncmasks(self) -> None:
+        """
+        Load functional masks from specified files and create overlay objects.
+
+        This method iterates through the functional masks defined in `self.funcmasks`
+        and attempts to load each mask file. If a mask file exists, it creates an
+        Overlay object and stores it in `self.overlays` with the mask name as key.
+
+        Parameters
+        ----------
+        self : object
+            The instance containing the following attributes:
+            - funcmasks : list of tuples
+                List of (maskname, maskfilename) pairs to load
+            - fileroot : str
+                Root directory path for mask files
+            - overlays : dict
+                Dictionary to store loaded overlay objects
+            - verbose : int
+                Verbosity level for printing status messages
+            - init_LUT : bool, optional
+                Flag to initialize lookup table for overlays
+            - loadedfuncmasks : list
+                List to store names of successfully loaded masks
+
+        Returns
+        -------
+        None
+            This method modifies instance attributes in-place and does not return a value.
+
+        Notes
+        -----
+        - Mask files are expected to have .nii.gz extension
+        - Only masks that exist at the constructed file path are loaded
+        - Progress information is printed based on verbosity level
+        - Successfully loaded mask names are stored in `self.loadedfuncmasks`
+
+        Examples
+        --------
+        >>> # Assuming self.funcmasks = [('mask1', 'mask1_file'), ('mask2', 'mask2_file')]
+        >>> # and mask files exist at self.fileroot + maskfilename + ".nii.gz"
+        >>> _loadfuncmasks()
+        >>> print(self.loadedfuncmasks)
+        ['mask1', 'mask2']
+        >>> print(self.overlays['mask1'])
+        <Overlay object at 0x...>
+        """
         self.loadedfuncmasks = []
         for maskname, maskfilename in self.funcmasks:
             if self.verbose > 1:
@@ -697,7 +1750,41 @@ class RapidtideDataset:
         if self.verbose > 1:
             print(self.loadedfuncmasks)
 
-    def _genpmasks(self, pvals=[0.05, 0.01, 0.005, 0.001]):
+    def _genpmasks(self, pvals: list[float] = [0.05, 0.01, 0.005, 0.001]) -> None:
+        """
+        Generate binary masks for specified p-value thresholds from negative log10 p-values.
+
+        This function creates binary masks based on negative log10 p-values stored in
+        self.overlays["neglog10p"]. Each mask represents regions where the negative
+        log10 p-values exceed the specified threshold.
+
+        Parameters
+        ----------
+        pvals : list of float, optional
+            List of p-value thresholds for mask generation. Default is [0.05, 0.01, 0.005, 0.001].
+            Each threshold is converted to a mask name format "p_lt_{threshold}_mask".
+
+        Returns
+        -------
+        None
+            This function modifies the instance's overlays and loadedfuncmasks attributes
+            in-place and does not return any value.
+
+        Notes
+        -----
+        - Mask names are formatted to replace "0.0" with "0p0" (e.g., "0.05" becomes "0p05")
+        - The function uses the last loaded functional mask as the base for duplication
+        - Generated masks are stored in self.overlays dictionary with corresponding names
+        - The function updates self.loadedfuncmasks with the names of newly created masks
+
+        Examples
+        --------
+        >>> _genpmasks([0.05, 0.01])
+        # Generates masks for p-values 0.05 and 0.01 based on neglog10p data
+
+        >>> _genpmasks()
+        # Generates masks for default p-values [0.05, 0.01, 0.005, 0.001]
+        """
         for thepval in pvals:
             maskname = f"p_lt_{thepval:.3f}_mask".replace("0.0", "0p0")
             nlpthresh = -np.log10(thepval)
@@ -713,7 +1800,41 @@ class RapidtideDataset:
         if self.verbose > 1:
             print(self.loadedfuncmasks)
 
-    def _loadgeommask(self):
+    def _loadgeommask(self) -> bool:
+        """
+        Load a geometric mask based on configuration settings and available files.
+
+        This function attempts to load a geometric mask either from a user-specified
+        file or from a default location based on the coordinate space and voxel size.
+        The mask is stored in `self.overlays["geommask"]` if successfully loaded.
+
+        Returns
+        -------
+        bool
+            True if a geometric mask was successfully loaded, False otherwise.
+
+        Notes
+        -----
+        - If `self.geommaskname` is set, the function attempts to load the mask from that file.
+        - If `self.coordinatespace` is "MNI152", the function searches for a default mask
+          based on the voxel size (`xsize`, `ysize`, `zsize`).
+        - The function uses the FSL directory to locate default masks when available.
+        - Verbose output is printed if `self.verbose` is greater than 1.
+
+        Examples
+        --------
+        >>> loader = SomeClass()
+        >>> loader.geommaskname = "/path/to/custom_mask.nii.gz"
+        >>> loader._loadgeommask()
+        True
+
+        >>> loader.coordinatespace = "MNI152"
+        >>> loader.xsize = 2.0
+        >>> loader.ysize = 2.0
+        >>> loader.zsize = 2.0
+        >>> loader._loadgeommask()
+        True  # if default mask is found
+        """
         if self.geommaskname is not None:
             if os.path.isfile(self.geommaskname):
                 thepath, thebase = os.path.split(self.geommaskname)
@@ -768,7 +1889,46 @@ class RapidtideDataset:
                 print("no geometric mask loaded")
             return False
 
-    def _loadanatomics(self):
+    def _loadanatomics(self) -> bool:
+        """
+        Load anatomic image data based on available files and coordinate space settings.
+
+        This method attempts to load anatomic images from various possible sources,
+        prioritizing user-specified files, high-resolution templates, MNI templates,
+        and mean-based images. The loaded image is stored in `self.overlays["anatomic"]`.
+
+        Returns
+        -------
+        bool
+            True if anatomic image was successfully loaded, False otherwise.
+
+        Notes
+        -----
+        The method checks for the following files in order:
+        1. User-specified anatomic file (`self.anatname`)
+        2. High-resolution head image: `highres_head.nii.gz`
+        3. High-resolution image: `highres.nii.gz`
+        4. MNI152 template based on resolution (`xsize`, `ysize`, `zsize`)
+        5. MNI152NLin2009cAsym template based on resolution
+        6. Mean image: `mean.nii.gz`
+        7. Mean value image: `meanvalue.nii.gz`
+        8. Described mean image: `desc-unfiltmean_map.nii.gz`
+        9. Described mean image: `desc-mean_map.nii.gz`
+
+        If `FSLDIR` environment variable is set, it is used to locate MNI152 templates
+        with 2mm resolution.
+
+        Examples
+        --------
+        >>> loader = MyLoader()
+        >>> loader.fileroot = "/path/to/data/"
+        >>> loader.coordinatespace = "MNI152"
+        >>> loader.xsize = 2.0
+        >>> loader.ysize = 2.0
+        >>> loader.zsize = 2.0
+        >>> loader._loadanatomics()
+        True
+        """
         try:
             fsldir = os.environ["FSLDIR"]
         except KeyError:
@@ -945,7 +2105,33 @@ class RapidtideDataset:
                 print("no anatomic image loaded")
             return False
 
-    def _loadgraymask(self):
+    def _loadgraymask(self) -> bool:
+        """
+        Load gray matter mask from specification.
+
+        Load a gray matter mask from the file specification stored in `self.graymaskspec`.
+        If successful, the mask is stored in `self.overlays["graymask"]` and the function
+        returns True. If no mask specification is provided or the file doesn't exist,
+        the function returns False.
+
+        Returns
+        -------
+        bool
+            True if gray matter mask was successfully loaded, False otherwise.
+
+        Notes
+        -----
+        This function checks if `self.graymaskspec` is not None and if the specified
+        file exists. If both conditions are met, it creates an Overlay object for the
+        gray mask and stores it in `self.overlays["graymask"]`. The function also
+        prints verbose messages when loading or skipping the mask.
+
+        Examples
+        --------
+        >>> loaded = self._loadgraymask()
+        >>> print(loaded)
+        True
+        """
         if self.graymaskspec is not None:
             filename, dummy = tide_io.parsefilespec(self.graymaskspec)
             if os.path.isfile(filename):
@@ -967,7 +2153,39 @@ class RapidtideDataset:
                 print("no gray mask loaded")
             return False
 
-    def _loadwhitemask(self):
+    def _loadwhitemask(self) -> bool:
+        """
+        Load white matter mask from specification if available.
+
+        This method attempts to load a white matter mask from the specification
+        stored in `self.whitemaskspec`. If the specification is valid and the
+        corresponding file exists, it creates an Overlay object for the white
+        matter mask and stores it in `self.overlays["whitemask"]`.
+
+        Parameters
+        ----------
+        self : object
+            The instance containing the white matter mask specification and
+            overlay storage.
+
+        Returns
+        -------
+        bool
+            True if white matter mask was successfully loaded, False otherwise.
+
+        Notes
+        -----
+        The method checks if `self.whitemaskspec` is not None and if the
+        specified file exists before attempting to load it. If successful,
+        the mask is stored in `self.overlays["whitemask"]` and a verbose
+        message is printed if `self.verbose` is greater than 1.
+
+        Examples
+        --------
+        >>> loaded = self._loadwhitemask()
+        >>> print(loaded)
+        True
+        """
         if self.whitemaskspec is not None:
             filename, dummy = tide_io.parsefilespec(self.whitemaskspec)
             if os.path.isfile(filename):
@@ -989,7 +2207,42 @@ class RapidtideDataset:
                 print("no white mask loaded")
             return False
 
-    def setupregressors(self):
+    def setupregressors(self) -> None:
+        """
+        Set up regressor specifications and load regressor data.
+
+        This method initializes the regressor specifications based on the BIDS format
+        and the run options, and loads the corresponding regressor data. It handles
+        various configuration parameters such as filter limits, sampling frequencies,
+        and similarity metrics, and prepares a list of regressor specifications for
+        use in subsequent processing steps.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return any value but updates the instance attributes
+            `regressors`, `regressorfilterlimits`, `fmrifreq`, `inputfreq`,
+            `inputstarttime`, `oversampfactor`, `similaritymetric`, `regressorsimcalclimits`,
+            `numberofpasses`, and `regressorspecs`.
+
+        Notes
+        -----
+        - The method reads run options from a file specified by `self.fileroot + "desc-runoptions_info"`.
+        - If `self.bidsformat` is True, the regressor files are named according to BIDS conventions.
+        - The method determines the number of passes and sets up the regressor specifications accordingly.
+        - The `regressorspecs` list contains information for loading regressors at different stages:
+          pre-filtered, post-filtered, and multiple passes, with associated file names, frequencies,
+          and time offsets.
+
+        Examples
+        --------
+        >>> setupregressors()
+        # Updates instance attributes with regressor configurations and loads data.
+        """
         # load the regressors
         self.regressors = {}
         self.therunoptions = tide_io.readoptionsfile(self.fileroot + "desc-runoptions_info")
@@ -1157,17 +2410,134 @@ class RapidtideDataset:
             ]
         self._loadregressors()
 
-    def getregressors(self):
+    def getregressors(self) -> dict:
+        """
+        Return the regressors stored in the object.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the regressors. The keys are typically
+            regressor names and the values are the corresponding regressor objects.
+
+        Notes
+        -----
+        This method provides access to the internal regressors dictionary
+        that stores all regression models used by the object.
+
+        Examples
+        --------
+        >>> model = MyRegressionModel()
+        >>> regressors = model.getregressors()
+        >>> print(regressors)
+        {'linear_reg': LinearRegression(), 'ridge_reg': Ridge()}
+        """
         return self.regressors
 
-    def setfocusregressor(self, whichregressor):
+    def setfocusregressor(self, whichregressor: str) -> None:
+        """
+        Set the focus regressor for the current instance.
+
+        This method sets the focus regressor to the specified regressor name if it exists
+        in the regressors dictionary. If the specified regressor does not exist, it defaults
+        to "prefilt".
+
+        Parameters
+        ----------
+        whichregressor : str
+            The name of the regressor to set as the focus regressor. This should be a key
+            present in the instance's regressors dictionary.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        If the specified regressor name is not found in self.regressors, the method will
+        automatically fall back to setting the focus regressor to "prefilt".
+
+        Examples
+        --------
+        >>> instance.setfocusregressor("regressor1")
+        >>> print(instance.focusregressor)
+        'regressor1'
+
+        >>> instance.setfocusregressor("nonexistent")
+        >>> print(instance.focusregressor)
+        'prefilt'
+        """
         try:
             testregressor = self.regressors[whichregressor]
             self.focusregressor = whichregressor
         except KeyError:
             self.focusregressor = "prefilt"
 
-    def setupoverlays(self):
+    def setupoverlays(self) -> None:
+        """
+        Set up and load all overlays for functional and anatomical data.
+
+        This function initializes the overlays dictionary and loads various functional
+        maps, masks, and anatomical data based on the configuration parameters such as
+        BIDS format, use of correlation outputs, and coordinate space. It also handles
+        setting TR and time offset values for the loaded maps, and loads additional
+        data such as atlases and tissue masks if applicable.
+
+        Parameters
+        ----------
+        self : object
+            The instance of the class containing this method. Expected to have the
+            following attributes:
+
+            - bidsformat : bool
+                Indicates whether the data is in BIDS format.
+            - usecorrout : bool
+                Whether to include correlation output maps.
+            - newstylenames : bool
+                Whether to use new-style naming conventions for maps.
+            - userise : bool
+                Whether to include rise time-related maps.
+            - forcetr : bool
+                Whether to force TR value for loaded maps.
+            - forceoffset : bool
+                Whether to force time offset for loaded maps.
+            - trval : float
+                The TR value to be set if `forcetr` is True.
+            - offsettime : float
+                The time offset to be set if `forceoffset` is True.
+            - verbose : int
+                Verbosity level for output messages.
+            - referencedir : str
+                Directory containing reference data such as atlases.
+            - init_LUT : bool
+                Whether to initialize lookup tables for overlays.
+            - useatlas : bool
+                Whether to load atlas data.
+            - coordinatespace : str
+                The coordinate space of the data (e.g., "MNI152", "MNI152NLin2009cAsym").
+
+        Returns
+        -------
+        None
+            This function does not return any value. It modifies the instance's
+            attributes in place.
+
+        Notes
+        -----
+        - Functional maps are loaded based on the BIDS format and naming conventions.
+        - The function dynamically builds lists of functional maps and masks depending
+          on the configuration.
+        - If an atlas is to be used and the coordinate space is compatible, it will be
+          loaded and added to the overlays.
+        - The function sets up several instance variables such as `xdim`, `ydim`, `zdim`,
+          `tdim`, `xsize`, `ysize`, `zsize`, and `tr` from the focus map.
+
+        Examples
+        --------
+        >>> setupoverlays()
+        # Loads all overlays and sets up the instance for further processing.
+        """
         # load the overlays
         self.overlays = {}
 
@@ -1397,15 +2767,92 @@ class RapidtideDataset:
         if self.verbose > 1:
             print("done")
 
-    def getoverlays(self):
+    def getoverlays(self) -> dict:
+        """
+        Return the overlays dictionary.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the overlays data.
+
+        Notes
+        -----
+        This method provides access to the internal overlays attribute.
+        The returned dictionary contains all overlay data managed by this instance.
+
+        Examples
+        --------
+        >>> overlays = obj.getoverlays()
+        >>> print(overlays)
+        {'overlay1': <OverlayObject>, 'overlay2': <OverlayObject>}
+        """
         return self.overlays
 
-    def setfocusmap(self, whichmap):
+    def setfocusmap(self, whichmap: str) -> None:
+        """
+        Set the focus map to the specified map name.
+
+        This method sets the current focus map to the specified map name if it exists
+        in the overlays dictionary. If the specified map does not exist, it defaults
+        to setting the focus map to "lagtimes".
+
+        Parameters
+        ----------
+        whichmap : str
+            The name of the map to set as the focus map. This should correspond to
+            a key in the self.overlays dictionary.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        If the specified `whichmap` is not found in `self.overlays`, the method
+        will automatically fall back to setting the focus map to "lagtimes".
+
+        Examples
+        --------
+        >>> obj.setfocusmap("temperature")
+        >>> obj.focusmap
+        'temperature'
+
+        >>> obj.setfocusmap("nonexistent")
+        >>> obj.focusmap
+        'lagtimes'
+        """
         try:
             testmap = self.overlays[whichmap]
             self.focusmap = whichmap
         except KeyError:
             self.focusmap = "lagtimes"
 
-    def setFuncMaskName(self, maskname):
+    def setFuncMaskName(self, maskname: str) -> None:
+        """
+        Set the function mask name attribute.
+
+        Parameters
+        ----------
+        maskname : str
+            The name to assign to the function mask attribute.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method assigns the provided mask name to the internal `funcmaskname` attribute
+        of the object instance.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setFuncMaskName("my_mask")
+        >>> print(obj.funcmaskname)
+        'my_mask'
+        """
         self.funcmaskname = maskname