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

rapidtide/voxelData.py

@@ -17,8 +17,10 @@
 #
 #
 import copy
+from typing import Any
 
 import numpy as np
+from numpy.typing import NDArray
 from tqdm import tqdm
 
 import rapidtide.filter as tide_filt
@@ -40,11 +42,41 @@ class dataVolume:
 
     def __init__(
         self,
-        shape,
-        shared=False,
-        dtype=np.float64,
-        thepid=0,
-    ):
+        shape: tuple,
+        shared: bool = False,
+        dtype: type = np.float64,
+        thepid: int = 0,
+    ) -> None:
+        """
+        Initialize a data container with specified shape and properties.
+
+        Parameters
+        ----------
+        shape : tuple
+            The shape of the data array. Must be either 3D (x, y, z) or 4D (x, y, z, t).
+        shared : bool, optional
+            Whether to create a shared memory array, by default False
+        dtype : type, optional
+            Data type of the array, by default np.float64
+        thepid : int, optional
+            Process ID for naming shared memory, by default 0
+
+        Returns
+        -------
+        None
+            This method initializes the object in-place and does not return a value.
+
+        Notes
+        -----
+        The function automatically determines the number of dimensions based on the shape tuple length.
+        For 3D shapes, timepoints is set to 1. For 4D shapes, timepoints is set to the fourth dimension.
+        Invalid shapes will trigger a print statement with the error message.
+
+        Examples
+        --------
+        >>> data_container = DataContainer((64, 64, 32))
+        >>> data_container = DataContainer((64, 64, 32, 10), shared=True, dtype=np.float32)
+        """
         if len(shape) == 3:
             self.xsize = int(shape[0])
             self.ysize = int(shape[1])
@@ -64,24 +96,131 @@ class dataVolume:
         self.data, self.data_shm = tide_util.allocarray(
             shape, self.dtype, shared=shared, name=f"filtereddata_{thepid}"
         )
-        return self.data
 
-    def byvol(self):
+    def byvol(self) -> NDArray:
+        """
+        Return the data array.
+
+        Returns
+        -------
+        NDArray
+            The underlying data array stored in the object.
+
+        Notes
+        -----
+        This method provides direct access to the internal data array.
+        The returned array is a view of the original data and modifications
+        to it will affect the original object.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> data = obj.byvol()
+        >>> print(data.shape)
+        (100, 50)
+        """
         return self.data
 
-    def byslice(self):
+    def byslice(self) -> NDArray:
+        """
+        Reshape data by slices for 2D processing.
+
+        Reshapes the internal data array to facilitate 2D processing operations
+        by combining the x and y dimensions while preserving slice information.
+
+        Parameters
+        ----------
+        self : object
+            The instance containing the data to be reshaped. Expected to have
+            attributes: dimensions (int), data (array-like), xsize (int),
+            ysize (int), and numslices (int).
+
+        Returns
+        -------
+        NDArray
+            Reshaped array with dimensions (xsize * ysize, -1). For 3D data,
+            the shape becomes (xsize * ysize, -1). For 4D data, the shape becomes
+            (xsize * ysize, numslices, -1).
+
+        Notes
+        -----
+        This function is useful for preparing data for 2D processing operations
+        where the spatial dimensions need to be flattened while maintaining
+        temporal or spectral slice information.
+
+        Examples
+        --------
+        >>> # For 3D data with shape (100, 100, 50)
+        >>> result = obj.byslice()
+        >>> # Result shape: (10000, 50)
+        >>>
+        >>> # For 4D data with shape (50, 50, 10, 20)
+        >>> result = obj.byslice()
+        >>> # Result shape: (2500, 10, 20)
+        """
         if self.dimensions == 3:
             return self.data.reshape(self.xsize * self.ysize, -1)
         else:
             return self.data.reshape(self.xsize * self.ysize, self.numslices, -1)
 
-    def byvoxel(self):
+    def byvoxel(self) -> NDArray:
+        """
+        Reshape data to voxel format based on dimensions.
+
+        Returns
+        -------
+        NDArray
+            Reshaped array where each row represents a voxel. For 3D data, returns
+            a 1D array of shape (numspatiallocs,). For non-3D data, returns a 2D array
+            of shape (numspatiallocs, -1).
+
+        Notes
+        -----
+        This method reshapes the internal ``data`` attribute to a voxel-based
+        structure. The ``numspatiallocs`` attribute determines the first dimension
+        of the output array, while the second dimension is determined by the
+        remaining data dimensions.
+
+        Examples
+        --------
+        >>> # For 3D data
+        >>> result = obj.byvoxel()
+        >>> print(result.shape)
+        (1000,)  # where 1000 = numspatiallocs
+
+        >>> # For 2D data
+        >>> result = obj.byvoxel()
+        >>> print(result.shape)
+        (1000, 5)  # where 1000 = numspatiallocs, 5 = remaining dimensions
+        """
         if self.dimensions == 3:
             return self.data.reshape(self.numspatiallocs)
         else:
             return self.data.reshape(self.numspatiallocs, -1)
 
-    def destroy(self):
+    def destroy(self) -> None:
+        """
+        Clean up and destroy the object's resources.
+
+        This method releases the internal data storage and performs cleanup of
+        shared memory resources if they exist.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        The method first deletes the internal `data` attribute, then checks if
+        `data_shm` (shared memory) exists and performs cleanup if it does.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.destroy()
+        >>> # Object resources have been cleaned up
+        """
         del self.data
         if self.data_shm is not None:
             tide_util.cleanup_shm(self.data_shm)
@@ -116,16 +255,90 @@ class VoxelData:
 
     def __init__(
         self,
-        filename,
-        timestep=0.0,
-        validstart=None,
-        validend=None,
-    ):
+        filename: str,
+        timestep: float = 0.0,
+        validstart: int | None = None,
+        validend: int | None = None,
+    ) -> None:
+        """
+        Initialize the object with filename and optional data reading parameters.
+
+        Parameters
+        ----------
+        filename : str
+            Path to the data file to be read.
+        timestep : float, optional
+            Time step for data processing, default is 0.0.
+        validstart : int, optional
+            Starting index for valid data range, default is None (all data).
+        validend : int, optional
+            Ending index for valid data range, default is None (all data).
+
+        Returns
+        -------
+        None
+            This method initializes the object and reads data but does not return any value.
+
+        Notes
+        -----
+        This method calls `readdata()` internally with the provided parameters to load
+        and process the data from the specified file.
+
+        Examples
+        --------
+        >>> obj = MyClass("data.txt")
+        >>> obj = MyClass("data.txt", timestep=0.1, validstart=10, validend=100)
+        """
 
         self.filename = filename
         self.readdata(timestep, validstart, validend)
 
-    def readdata(self, timestep, validstart, validend):
+    def readdata(self, timestep: float, validstart: int | None, validend: int | None) -> None:
+        """
+        Load and process data from a file based on its type (NIfTI, CIFTI, or text).
+
+        This function loads data using `self.load()` and determines the file type
+        (NIfTI, CIFTI, or text) to set appropriate attributes such as dimensions,
+        timepoints, and spatial locations. It also handles time-related parameters
+        like `timestep` and `toffset`, and sets valid time ranges.
+
+        Parameters
+        ----------
+        timestep : float
+            The time step size (in seconds) for the data. If <= 0.0, the function
+            will attempt to infer it from the file metadata (except for text files,
+            which require this to be explicitly set).
+        validstart : int, optional
+            The starting index of the valid time range. If None, defaults to the
+            beginning of the data.
+        validend : int, optional
+            The ending index of the valid time range. If None, defaults to the end
+            of the data.
+
+        Returns
+        -------
+        None
+            This function does not return a value but updates the instance attributes
+            of `self` based on the loaded data and parameters.
+
+        Notes
+        -----
+        - For text files, `timestep` must be provided explicitly; otherwise, a
+          `ValueError` is raised.
+        - For CIFTI files, the `timestep` is hardcoded to 0.72 seconds as a temporary
+          workaround until full XML parsing is implemented.
+        - The function sets various internal attributes such as `xsize`, `ysize`,
+          `numslices`, `timepoints`, `numspatiallocs`, and `nativespaceshape`
+          depending on the file type.
+
+        Examples
+        --------
+        >>> readdata(timestep=1.0, validstart=0, validend=100)
+        # Loads data with a 1-second timestep and valid time range from 0 to 100.
+
+        >>> readdata(timestep=0.0, validstart=None, validend=None)
+        # Loads data and infers timestep from file metadata (if not text).
+        """
         # load the data
         self.load()
 
@@ -193,7 +406,54 @@ class VoxelData:
         self.setvalidtimes(validstart, validend)
         self.resident = True
 
-    def copyheader(self, numtimepoints=None, tr=None, toffset=None):
+    def copyheader(
+        self,
+        numtimepoints: int | None = None,
+        tr: float | None = None,
+        toffset: float | None = None,
+    ) -> Any | None:
+        """
+        Copy and modify header information for neuroimaging files.
+
+        This method creates a deep copy of the current header and modifies specific
+        dimensions and parameters based on the file type (CIFTI or other formats).
+        For text files, returns None immediately. For CIFTI files, modifies time and
+        space dimensions. For other file types, updates time dimensions and related
+        parameters.
+
+        Parameters
+        ----------
+        numtimepoints : int, optional
+            Number of time points to set in the header. If None, time dimension
+            remains unchanged for non-CIFTI files.
+        tr : float, optional
+            Repetition time (TR) to set in the header. If None, TR remains unchanged.
+        toffset : float, optional
+            Time offset to set in the header. If None, time offset remains unchanged.
+
+        Returns
+        -------
+        dict or None
+            Modified header dictionary for non-text files, or None for text files.
+            Returns None if the file type is "text".
+
+        Notes
+        -----
+        For CIFTI files:
+            - Time dimension is updated to numtimepoints
+            - Space dimension is set to self.numspatiallocs
+        For other file types:
+            - Time dimension is updated to numtimepoints (index 4)
+            - Dimension index 0 is updated based on numtimepoints (4 for >1, 3 for 1)
+            - TR is set in pixdim[4] if provided
+            - Time offset is set in toffset if provided
+
+        Examples
+        --------
+        >>> header = obj.copyheader(numtimepoints=100, tr=2.0)
+        >>> header = obj.copyheader(toffset=-5.0)
+        >>> header = obj.copyheader()
+        """
         if self.filetype == "text":
             return None
         else:
@@ -217,18 +477,127 @@ class VoxelData:
                     thisheader["pixdim"][4] = tr
             return thisheader
 
-    def getsizes(self):
+    def getsizes(self) -> tuple[float, float, float, float]:
+        """
+        Return the dimensions and spacing parameters of the data structure.
+
+        Returns
+        -------
+        tuple[float, float, float, float]
+            A tuple containing four float values in order:
+            - xdim: x-dimension size
+            - ydim: y-dimension size
+            - slicethickness: thickness of each slice
+            - timestep: time step between measurements
+
+        Notes
+        -----
+        This method provides access to the fundamental spatial and temporal
+        parameters of the data structure. The returned values represent the
+        physical dimensions and spacing characteristics that define the
+        coordinate system of the data.
+
+        Examples
+        --------
+        >>> sizes = obj.getsizes()
+        >>> print(sizes)
+        (100.0, 100.0, 1.0, 0.1)
+        >>> x_size, y_size, slice_thick, time_step = obj.getsizes()
+        """
         return self.xdim, self.ydim, self.slicethickness, self.timestep
 
-    def getdims(self):
+    def getdims(self) -> tuple[int, int, int, int]:
+        """
+        Return the dimensions of the data structure.
+
+        Returns
+        -------
+        tuple[int, int, int, int]
+            A tuple containing four integers representing:
+            - xsize: width dimension
+            - ysize: height dimension
+            - numslices: number of slices
+            - timepoints: number of time points
+
+        Notes
+        -----
+        This method provides access to the fundamental spatial and temporal dimensions
+        of the data structure. The returned tuple follows the order (x, y, slices, time).
+
+        Examples
+        --------
+        >>> dims = obj.getdims()
+        >>> print(dims)
+        (640, 480, 32, 100)
+        >>> x, y, slices, time = obj.getdims()
+        >>> print(f"Data shape: {x} x {y} x {slices} x {time}")
+        Data shape: 640 x 480 x 32 x 100
+        """
         return self.xsize, self.ysize, self.numslices, self.timepoints
 
-    def unload(self):
+    def unload(self) -> None:
+        """
+        Unload Nim data and clean up resources.
+
+        This method removes the Nim data and Nim object references from the instance
+        and marks the instance as not resident in memory.
+
+        Notes
+        -----
+        This method should be called to properly clean up resources when the Nim
+        data is no longer needed. The method deletes the internal references to
+        ``nim_data`` and ``nim`` objects and sets the ``resident`` flag to ``False``.
+
+        Examples
+        --------
+        >>> instance = MyClass()
+        >>> instance.load()  # Load some data
+        >>> instance.unload()  # Clean up resources
+        >>> instance.resident
+        False
+        """
         del self.nim_data
         del self.nim
         self.resident = False
 
-    def load(self):
+    def load(self) -> None:
+        """
+        Load data from file based on file type detection.
+
+        This method loads data from the specified filename, automatically detecting
+        whether the file is text, CIFTI, or NIFTI format. The loaded data is stored
+        in instance variables for subsequent processing.
+
+        Parameters
+        ----------
+        self : object
+            The instance of the class containing this method. Expected to have
+            attributes: filename (str), filetype (str or None), and various data
+            storage attributes (nim_data, nim, cifti_hdr, nim_hdr, thedims, thesizes).
+
+        Returns
+        -------
+        None
+            This method does not return any value but updates instance attributes
+            with loaded data.
+
+        Notes
+        -----
+        - If filetype is not None, the method prints "reloading non-resident data"
+        - For text files, data is read using tide_io.readvecs()
+        - For CIFTI files, data is read using tide_io.readfromcifti() and stored
+          in multiple attributes including cifti_hdr and nim_hdr
+        - For NIFTI files, data is read using tide_io.readfromnifti() and stored
+          in nim, nim_data, nim_hdr, thedims, and thesizes attributes
+        - The method sets self.resident = True upon successful completion
+
+        Examples
+        --------
+        >>> loader = DataContainer()
+        >>> loader.filename = "data.nii.gz"
+        >>> loader.load()
+        loading data from data.nii.gz
+        """
         if self.filetype is not None:
             print("reloading non-resident data")
         else:
@@ -255,7 +624,41 @@ class VoxelData:
                 )
         self.resident = True
 
-    def setvalidtimes(self, validstart, validend):
+    def setvalidtimes(self, validstart: int | None, validend: int | None) -> None:
+        """
+        Set valid time points for the object based on start and end indices.
+
+        This method configures the valid time range for the object by setting
+        `validstart` and `validend` attributes. It also calculates the number of
+        real time points and updates the native fMRI shape based on the file type.
+
+        Parameters
+        ----------
+        validstart : int, optional
+            The starting index of valid time points. If None, defaults to 0.
+        validend : int, optional
+            The ending index of valid time points. If None, defaults to
+            `self.timepoints - 1`.
+
+        Returns
+        -------
+        None
+            This method modifies the object's attributes in-place and does not return anything.
+
+        Notes
+        -----
+        The method calculates `realtimepoints` as `validend - validstart + 1`.
+        The `nativefmrishape` is updated based on the `filetype` attribute:
+        - "nifti": (xsize, ysize, numslices, realtimepoints)
+        - "cifti": (1, 1, 1, realtimepoints, numspatiallocs)
+        - else: (xsize, realtimepoints)
+
+        Examples
+        --------
+        >>> obj.setvalidtimes(5, 15)
+        >>> obj.setvalidtimes(None, 10)
+        >>> obj.setvalidtimes(0, None)
+        """
         if validstart is None:
             self.validstart = 0
         else:
@@ -272,16 +675,96 @@ class VoxelData:
         else:
             self.nativefmrishape = (self.xsize, self.realtimepoints)
 
-    def setvalidvoxels(self, validvoxels):
+    def setvalidvoxels(self, validvoxels: NDArray) -> None:
+        """
+        Set the valid voxels for the object.
+
+        Parameters
+        ----------
+        validvoxels : numpy.ndarray
+            Array containing the valid voxel coordinates. The first dimension
+            represents the number of valid spatial locations.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method updates two attributes:
+        - `self.validvoxels`: Stores the provided valid voxel array
+        - `self.numvalidspatiallocs`: Stores the number of valid spatial locations
+          (derived from the shape of the validvoxels array)
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> voxels = np.array([[0, 0, 0], [1, 1, 1], [2, 2, 2]])
+        >>> obj.setvalidvoxels(voxels)
+        >>> print(obj.numvalidspatiallocs)
+        3
+        """
         self.validvoxels = validvoxels
         self.numvalidspatiallocs = np.shape(self.validvoxels)[0]
 
-    def byvol(self):
+    def byvol(self) -> NDArray:
+        """
+        Return the nim_data array from the object.
+
+        If the object is not resident, it will be loaded first.
+
+        Returns
+        -------
+        NDArray
+            The nim_data array stored in the object.
+
+        Notes
+        -----
+        This method checks if the object is resident and loads it if necessary
+        before returning the nim_data array.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> data = obj.byvol()
+        >>> print(data.shape)
+        (100, 100)
+        """
         if not self.resident:
             self.load()
         return self.nim_data
 
-    def byvoltrimmed(self):
+    def byvoltrimmed(self) -> NDArray:
+        """
+        Return data with volume trimming applied based on valid time range.
+
+        This method returns the neuroimaging data with temporal dimensions trimmed
+        according to the valid start and end indices. The behavior varies depending
+        on the file type and dimensions of the data.
+
+        Returns
+        -------
+        NDArray
+            Trimmed neuroimaging data array. For NIfTI files with 4D data or
+            CIFTI/text files, returns data with shape (X, Y, Z, T) where T is
+            the trimmed temporal dimension. For other file types, returns data
+            with shape (X, Y, Z) or (X, T) depending on the data structure.
+
+        Notes
+        -----
+        - If the data is not resident in memory, it will be loaded automatically
+        - For NIfTI files with 4D data, CIFTI files, or text files, the temporal
+          dimension is trimmed using self.validstart and self.validend
+        - For other file types, only the temporal dimension is trimmed
+        - The validend index is inclusive in the returned data
+
+        Examples
+        --------
+        >>> data = obj.byvoltrimmed()
+        >>> print(data.shape)
+        (64, 64, 32, 100)  # For 4D NIfTI data with 100 valid time points
+        """
         if not self.resident:
             self.load()
         if self.filetype == "nifti":
@@ -292,19 +775,106 @@ class VoxelData:
         else:
             return self.nim_data[:, self.validstart : self.validend + 1]
 
-    def byvoxel(self):
+    def byvoxel(self) -> NDArray:
+        """
+        Reshape data by voxel across spatial locations.
+
+        This method reshapes the trimmed volume data to organize it by voxel
+        across all spatial locations. The output format depends on the
+        file type and dimensions of the data.
+
+        Returns
+        -------
+        NDArray
+            Reshaped array where each row represents a voxel and columns
+            represent time points or other dimensions. For 4D data or
+            CIFTI/text files, the shape is (numspatiallocs, -1), otherwise
+            (numspatiallocs,).
+
+        Notes
+        -----
+        - For 4D data, CIFTI files, or text files, the result is reshaped to
+          have an additional dimension for time points or other temporal
+          dimensions
+        - For other file types, the result is reshaped to a 2D array with
+          shape (numspatiallocs,)
+
+        Examples
+        --------
+        >>> data = MyDataClass()
+        >>> voxel_data = data.byvoxel()
+        >>> print(voxel_data.shape)
+        (numspatiallocs, num_timepoints)
+        """
         if self.dimensions == 4 or self.filetype == "cifti" or self.filetype == "text":
             return self.byvoltrimmed().reshape(self.numspatiallocs, -1)
         else:
             return self.byvoltrimmed().reshape(self.numspatiallocs)
 
-    def byslice(self):
+    def byslice(self) -> NDArray:
+        """
+        Reshape data by slice dimensions.
+
+        Reshapes the data returned by `byvoltrimmed()` to organize data by slice
+        locations and slices. The output format depends on the file type and
+        dimensions of the data.
+
+        Returns
+        -------
+        NDArray
+            Reshaped array with dimensions (numslicelocs, numslices, -1) for
+            CIFTI or text files, or (numslicelocs, numslices) for other file types.
+
+        Notes
+        -----
+        This method is particularly useful for organizing volumetric data by
+        slice locations and slices. For CIFTI and text file types, the last
+        dimension is automatically expanded to accommodate additional data
+        dimensions.
+
+        Examples
+        --------
+        >>> data = MyClass()
+        >>> result = data.byslice()
+        >>> print(result.shape)
+        (10, 20, 100)  # for CIFTI/text files
+        >>> print(result.shape)
+        (10, 20)       # for other file types
+        """
         if self.dimensions == 4 or self.filetype == "cifti" or self.filetype == "text":
             return self.byvoltrimmed().reshape(self.numslicelocs, self.numslices, -1)
         else:
             return self.byvoltrimmed().reshape(self.numslicelocs, self.numslices)
 
-    def validdata(self):
+    def validdata(self) -> NDArray:
+        """
+        Return valid voxel data based on validvoxels mask.
+
+        If validvoxels is None, returns all voxel data. Otherwise, returns
+        only the subset of voxel data indicated by the validvoxels mask.
+
+        Returns
+        -------
+        NDArray
+            Array containing voxel data. If validvoxels is None, returns
+            all voxel data from byvoxel() method. If validvoxels is not None,
+            returns subset of voxel data filtered by validvoxels mask.
+
+        Notes
+        -----
+        This method relies on the byvoxel() method to generate the base
+        voxel data array and applies filtering based on the validvoxels
+        attribute if it exists.
+
+        Examples
+        --------
+        >>> # Get all voxel data
+        >>> data = obj.validdata()
+        >>>
+        >>> # Get filtered voxel data
+        >>> obj.validvoxels = [0, 1, 2, 5, 10]
+        >>> data = obj.validdata()
+        """
         if self.validvoxels is None:
             return self.byvoxel()
         else:
@@ -318,14 +888,67 @@ class VoxelData:
 
     def smooth(
         self,
-        gausssigma,
-        brainmask=None,
-        graymask=None,
-        whitemask=None,
-        premask=False,
-        premasktissueonly=False,
-        showprogressbar=False,
-    ):
+        gausssigma: float,
+        brainmask: NDArray | None = None,
+        graymask: NDArray | None = None,
+        whitemask: NDArray | None = None,
+        premask: bool = False,
+        premasktissueonly: bool = False,
+        showprogressbar: bool = False,
+    ) -> float:
+        """
+        Apply Gaussian spatial smoothing to the data.
+
+        This function applies a Gaussian spatial filter to the data, with optional
+        pre-masking of brain or tissue regions. For CIFTI and text file types, the
+        smoothing is skipped by setting `gausssigma` to 0.0. If `gausssigma` is less
+        than 0.0, it is automatically set to the mean of the image dimensions divided
+        by 2.0.
+
+        Parameters
+        ----------
+        gausssigma : float
+            Standard deviation for the Gaussian kernel. If less than 0.0, it is
+            automatically calculated as the mean of image dimensions divided by 2.0.
+        brainmask : NDArray | None, optional
+            Binary mask for the brain region. Required if `premask` is True and
+            `premasktissueonly` is False.
+        graymask : NDArray | None, optional
+            Binary mask for gray matter. Required if `premask` is True and
+            `premasktissueonly` is True.
+        whitemask : NDArray | None, optional
+            Binary mask for white matter. Required if `premask` is True and
+            `premasktissueonly` is True.
+        premask : bool, optional
+            If True, applies the mask before smoothing. Default is False.
+        premasktissueonly : bool, optional
+            If True, applies the mask only to gray and white matter. Requires
+            `graymask` and `whitemask` to be provided. Default is False.
+        showprogressbar : bool, optional
+            If True, displays a progress bar during processing. Default is False.
+
+        Returns
+        -------
+        float
+            The actual `gausssigma` value used for smoothing.
+
+        Notes
+        -----
+        - For CIFTI and text file types, smoothing is skipped.
+        - The function modifies `self.nim_data` in-place.
+        - If `premask` is True, the mask is applied to the timepoints specified by
+          `self.validstart` to `self.validend`.
+
+        Examples
+        --------
+        >>> # Apply smoothing with automatic sigma
+        >>> smooth(-1.0)
+        1.5
+
+        >>> # Apply smoothing with a custom sigma and pre-mask
+        >>> smooth(2.0, brainmask=mask, premask=True)
+        2.0
+        """
         # do spatial filtering if requested
         if self.filetype == "cifti" or self.filetype == "text":
             gausssigma = 0.0
@@ -379,7 +1002,31 @@ class VoxelData:
                 )
         return gausssigma
 
-    def summarize(self):
+    def summarize(self) -> None:
+        """
+        Print a comprehensive summary of voxel data properties.
+
+        This method outputs detailed information about the voxel data structure,
+        including image dimensions, spatial properties, temporal characteristics,
+        and file metadata. The summary includes both geometric and temporal
+        parameters that define the voxel space and data organization.
+
+        Notes
+        -----
+        The method prints to standard output and does not return any value.
+        All attributes are accessed from the instance and displayed in a
+        formatted manner for easy inspection of the data structure.
+
+        Examples
+        --------
+        >>> obj.summarize()
+        Voxel data summary:
+            self.nim=...
+            self.nim_data.shape=...
+            self.nim_hdr=...
+            self.nim_affine=...
+            ...
+        """
         print("Voxel data summary:")
         print(f"\t{self.nim=}")
         print(f"\t{self.nim_data.shape=}")