nltools 0.6.0.dev0__py3-none-any.whl

nltools/algorithms/inference/validation.py

@@ -0,0 +1,282 @@
+"""Shared input validation for the inference module.
+
+One home for the argument checks the permutation, bootstrap, and matrix tests
+share, so every entry point raises the same `ValueError` for the same mistake.
+The `tail` vocabulary is wider than inference, so it lives one level up in
+`nltools.algorithms.validation`.
+
+Examples:
+    ```python
+    from nltools.algorithms.inference.validation import _validate_square_matrix
+
+    _validate_square_matrix(np.eye(3))  # → None
+    _validate_square_matrix(np.zeros((2, 3)))  # raises ValueError
+    ```
+"""
+
+import numpy as np
+
+
+def _validate_array_shape(
+    array: np.ndarray,
+    expected_ndim: int,
+    name: str = "array",
+) -> None:
+    """Validate array dimensionality.
+
+    Args:
+        array (np.ndarray): Array to validate.
+        expected_ndim (int): Expected number of dimensions.
+        name (str): Name of the array for the error message.
+
+    Raises:
+        ValueError: If the array has the wrong number of dimensions.
+    """
+    if array.ndim != expected_ndim:
+        raise ValueError(
+            f"{name} must be {expected_ndim}D, got shape {array.shape} ({array.ndim}D)"
+        )
+
+
+def _validate_array_shape_range(
+    array: np.ndarray,
+    min_ndim: int,
+    max_ndim: int,
+    name: str = "array",
+) -> None:
+    """Validate that array dimensionality falls within a range.
+
+    Args:
+        array (np.ndarray): Array to validate.
+        min_ndim (int): Minimum number of dimensions (inclusive).
+        max_ndim (int): Maximum number of dimensions (inclusive).
+        name (str): Name of the array for the error message.
+
+    Raises:
+        ValueError: If the array has the wrong number of dimensions.
+    """
+    if not (min_ndim <= array.ndim <= max_ndim):
+        raise ValueError(
+            f"{name} must be {min_ndim}D to {max_ndim}D, got shape {array.shape} "
+            f"({array.ndim}D)"
+        )
+
+
+def _validate_same_shape(
+    array1: np.ndarray,
+    array2: np.ndarray,
+    name1: str = "array1",
+    name2: str = "array2",
+) -> None:
+    """Validate that two arrays have the same shape.
+
+    Args:
+        array1 (np.ndarray): First array.
+        array2 (np.ndarray): Second array.
+        name1 (str): Name of the first array for the error message.
+        name2 (str): Name of the second array for the error message.
+
+    Raises:
+        ValueError: If the arrays have different shapes.
+    """
+    if array1.shape != array2.shape:
+        raise ValueError(
+            f"{name1} and {name2} must have same shape, "
+            f"got {array1.shape} and {array2.shape}"
+        )
+
+
+def _validate_metric_parameter(
+    metric: str,
+    allowed: list[str],
+    name: str = "metric",
+) -> None:
+    """Validate a metric name against an allowed list.
+
+    Args:
+        metric (str): Metric name to validate.
+        allowed (list[str]): Allowed metric names.
+        name (str): Name of the parameter for the error message.
+
+    Raises:
+        ValueError: If `metric` is not in `allowed`.
+    """
+    if metric not in allowed:
+        allowed_str = ", ".join(f"'{m}'" for m in allowed)
+        raise ValueError(f"{name} must be one of [{allowed_str}], got {metric!r}")
+
+
+def _validate_how_parameter(how: str) -> None:
+    """Validate the `how` parameter for matrix operations.
+
+    Args:
+        how (str): `'upper'`, `'lower'`, or `'full'`.
+
+    Raises:
+        ValueError: If `how` is not one of those values.
+    """
+    if how not in ["upper", "lower", "full"]:
+        raise ValueError(f"how must be 'upper', 'lower', or 'full', got {how!r}")
+
+
+def _validate_square_matrix(matrix: np.ndarray, name: str = "matrix") -> None:
+    """Validate that a matrix is square.
+
+    Args:
+        matrix (np.ndarray): Matrix to validate.
+        name (str): Name of the matrix for the error message.
+
+    Raises:
+        ValueError: If the matrix is not square.
+    """
+    if matrix.shape[0] != matrix.shape[1]:
+        raise ValueError(f"{name} must be square, got shape {matrix.shape}")
+
+
+def _validate_shape_compatibility(
+    X: np.ndarray,
+    y: np.ndarray,
+    X_name: str = "X",
+    y_name: str = "y",
+) -> None:
+    """Validate that X and y have the same number of samples.
+
+    Args:
+        X (np.ndarray): Feature matrix.
+        y (np.ndarray): Target vector or matrix.
+        X_name (str): Name of X for the error message.
+        y_name (str): Name of y for the error message.
+
+    Raises:
+        ValueError: If the first dimensions differ.
+    """
+    if X.shape[0] != y.shape[0]:
+        raise ValueError(
+            f"{X_name} and {y_name} must have same first dimension (n_samples), "
+            f"got {X.shape[0]} and {y.shape[0]}"
+        )
+
+
+def _validate_bootstrap_method(
+    method: str, simple_methods: list[str], fitted_methods: list[str]
+) -> None:
+    """Validate a bootstrap method name.
+
+    Args:
+        method (str): Method name to validate.
+        simple_methods (list[str]): Methods that need no fitted model.
+        fitted_methods (list[str]): Methods that require a prior `.fit()`.
+
+    Raises:
+        ValueError: If `method` is in neither list.
+    """
+    supported = simple_methods + fitted_methods
+    if method not in supported:
+        raise ValueError(
+            f"Unsupported method '{method}'. "
+            f"Supported methods: {simple_methods} (simple methods), "
+            f"{fitted_methods} (fitted model methods). "
+            f"For fitted methods, you must call .fit() first."
+        )
+
+
+def _validate_bootstrap_data(data: np.ndarray, method: str) -> None:
+    """Validate input data for bootstrapping.
+
+    Args:
+        data (np.ndarray): 1D or 2D data with at least 2 samples along axis 0.
+        method (str): Bootstrap method name (reserved for method-specific checks).
+
+    Raises:
+        ValueError: If the data is not 1D/2D or has fewer than 2 samples.
+    """
+    # Check dimensionality
+    if data.ndim not in [1, 2]:
+        raise ValueError(
+            f"Data must be 1D or 2D, got shape {data.shape}. "
+            f"For 3D+ data, you may need to reshape or select specific dimensions."
+        )
+
+    # Check number of samples
+    n_samples = data.shape[0] if data.ndim == 2 else len(data)
+    if n_samples < 2:
+        raise ValueError(
+            f"Need at least 2 samples for bootstrap, got {n_samples}. "
+            f"Bootstrap requires resampling, which needs multiple samples."
+        )
+
+
+def _validate_n_samples(n_samples: int) -> None:
+    """Reject a replicate count a bootstrap cannot be computed from.
+
+    Two replicates are the fewest a `ddof=1` standard error can be computed
+    from, so that is the hard floor. The separate quality advisory lives in
+    `_advise_on_n_samples`, in `nltools/algorithms/inference/bootstrap.py`.
+
+    Args:
+        n_samples (int): Number of bootstrap replicates.
+
+    Raises:
+        TypeError: If `n_samples` is not an integer.
+        ValueError: If `n_samples` is below 2.
+    """
+    if isinstance(n_samples, bool) or not isinstance(n_samples, (int, np.integer)):
+        raise TypeError(f"n_samples must be an integer, got {type(n_samples).__name__}")
+
+    if n_samples < 2:
+        raise ValueError(
+            f"n_samples must be at least 2, got {n_samples}. "
+            f"A bootstrap standard error needs at least two replicates. "
+            f"Recommended: n_samples >= 1000 for confidence intervals."
+        )
+
+
+def _validate_confidence_level(confidence_level: float) -> None:
+    """Validate the interval confidence level.
+
+    Args:
+        confidence_level (float): Requested level.
+
+    Raises:
+        TypeError: If `confidence_level` is not a real number.
+        ValueError: If it is not finite and strictly between zero and one.
+    """
+    if isinstance(confidence_level, bool) or not isinstance(
+        confidence_level, (int, float, np.integer, np.floating)
+    ):
+        raise TypeError(
+            f"confidence_level must be a number, got {type(confidence_level).__name__}"
+        )
+    value = float(confidence_level)
+    if not np.isfinite(value) or not 0 < value < 1:
+        raise ValueError(
+            f"confidence_level must be finite and strictly between 0 and 1, got "
+            f"{confidence_level!r}. Use 0.95 for a 95% interval."
+        )
+
+
+def _validate_memory_budget(memory_budget_gb: float | None) -> None:
+    """Validate an explicit working-memory budget.
+
+    Args:
+        memory_budget_gb (float | None): Budget in GB, or None to measure the
+            device.
+
+    Raises:
+        TypeError: If a supplied budget is not a real number.
+        ValueError: If a supplied budget is not finite and positive.
+    """
+    if memory_budget_gb is None:
+        return
+    if isinstance(memory_budget_gb, bool) or not isinstance(
+        memory_budget_gb, (int, float, np.integer, np.floating)
+    ):
+        raise TypeError(
+            f"memory_budget_gb must be a number or None, got "
+            f"{type(memory_budget_gb).__name__}"
+        )
+    value = float(memory_budget_gb)
+    if not np.isfinite(value) or value <= 0:
+        raise ValueError(
+            f"memory_budget_gb must be finite and positive, got {memory_budget_gb!r}."
+        )

nltools/algorithms/neighborhoods.py

@@ -0,0 +1,207 @@
+"""Spatial neighborhood computation for neuroimaging analyses.
+
+This module computes spatial neighborhoods (spheres) around brain voxels. It is
+designed to support searchlight analyses, ISC, and other operations that require
+iterating over local brain regions.
+
+Examples:
+    ```python
+    import nibabel as nib
+    from nltools.algorithms.neighborhoods import compute_searchlight_neighborhoods
+
+    mask = nib.load("mask.nii.gz")
+    neighborhoods = compute_searchlight_neighborhoods(mask, radius=10.0)
+
+    # Iterate over all voxels and their neighborhoods
+    for center_idx, neighbor_indices in neighborhoods.iter_neighborhoods():
+        local_data = data[:, neighbor_indices]  # data for the voxels in this sphere
+        result[center_idx] = analyze(local_data)
+    ```
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from collections.abc import Iterator
+
+import numpy as np
+from scipy import sparse
+from sklearn import neighbors
+
+from nltools.utils import _maybe_tqdm
+
+if TYPE_CHECKING:
+    from nibabel import Nifti1Image
+
+
+@dataclass(frozen=True)
+class _SphereNeighborhoods:
+    """Precomputed sphere neighborhoods for a brain mask.
+
+    This dataclass stores a sparse adjacency matrix where row i contains True
+    for all voxels within the specified radius of voxel i. It provides efficient
+    iteration over neighborhoods for searchlight-style analyses.
+
+    Attributes:
+        adjacency (sparse.csr_matrix): ``(n_voxels, n_voxels)`` matrix where
+            ``adjacency[i, j]`` is nonzero if voxel ``j`` is within the radius
+            of voxel ``i``.
+        radius (float): Radius in millimeters.
+        n_voxels (int): Number of voxels in the mask.
+        mean_size (float): Mean neighborhood size in voxels.
+        min_size (int): Smallest neighborhood size in voxels.
+        max_size (int): Largest neighborhood size in voxels.
+
+    Examples:
+        ```python
+        neighborhoods = compute_searchlight_neighborhoods(mask, radius=10.0)
+        print(f"Mean neighborhood size: {neighborhoods.mean_size:.1f} voxels")
+
+        # Get neighbors of a specific voxel
+        neighbor_idx = neighborhoods.get_neighbors(100)
+        print(f"Voxel 100 has {len(neighbor_idx)} neighbors")
+        ```
+    """
+
+    adjacency: sparse.csr_matrix
+    radius: float
+    n_voxels: int
+
+    def get_neighbors(self, voxel_idx: int) -> np.ndarray:
+        """Get indices of all voxels in the neighborhood of a given voxel.
+
+        Args:
+            voxel_idx: Index of the center voxel (0 to n_voxels-1)
+
+        Returns:
+            Array of voxel indices within radius of the center voxel
+        """
+        return self.adjacency[voxel_idx].indices
+
+    def get_neighborhood_size(self, voxel_idx: int) -> int:
+        """Get the number of voxels in a neighborhood.
+
+        Args:
+            voxel_idx: Index of the center voxel
+
+        Returns:
+            Number of voxels in the neighborhood
+        """
+        return self.adjacency[voxel_idx].nnz
+
+    def iter_neighborhoods(
+        self, *, progress_bar: bool = False
+    ) -> Iterator[tuple[int, np.ndarray]]:
+        """Iterate over all neighborhoods.
+
+        Args:
+            progress_bar: If True, wrap the iterator with a tqdm progress bar.
+
+        Yields:
+            tuple[int, np.ndarray]: ``(center_voxel_idx, neighbor_indices)`` for
+                each voxel.
+        """
+        iterator = _maybe_tqdm(
+            range(self.n_voxels),
+            progress_bar=progress_bar,
+            desc="Searchlight",
+            unit="voxels",
+        )
+
+        for i in iterator:
+            yield i, self.get_neighbors(i)
+
+    @property
+    def mean_size(self) -> float:
+        """Mean neighborhood size in voxels."""
+        return float(self.adjacency.sum() / self.n_voxels)
+
+    @property
+    def min_size(self) -> int:
+        """Minimum neighborhood size."""
+        sizes = np.diff(self.adjacency.indptr)
+        return int(sizes.min())
+
+    @property
+    def max_size(self) -> int:
+        """Maximum neighborhood size."""
+        sizes = np.diff(self.adjacency.indptr)
+        return int(sizes.max())
+
+    def __repr__(self) -> str:
+        return (
+            f"_SphereNeighborhoods(n_voxels={self.n_voxels}, "
+            f"radius={self.radius}mm, "
+            f"mean_size={self.mean_size:.1f})"
+        )
+
+
+def compute_searchlight_neighborhoods(
+    mask_img: Nifti1Image,
+    radius: float = 10.0,
+) -> _SphereNeighborhoods:
+    """Compute sphere neighborhoods for all voxels in a brain mask.
+
+    For each voxel in the mask, this function identifies all other voxels
+    within the specified radius (in millimeters).
+
+    The algorithm uses sklearn's BallTree for efficient radius queries in
+    world coordinates (mm), ensuring accurate neighborhoods regardless of
+    voxel resolution.
+
+    Args:
+        mask_img: NIfTI mask image defining the brain region
+        radius: Radius of spheres in millimeters (default: 10.0)
+
+    Returns:
+        _SphereNeighborhoods with precomputed adjacency matrix
+
+    Raises:
+        ValueError: If mask has no non-zero voxels
+
+    Examples:
+        ```python
+        import nibabel as nib
+
+        mask = nib.load("brain_mask.nii.gz")
+        neighborhoods = compute_searchlight_neighborhoods(mask, radius=8.0)
+
+        print(neighborhoods)
+        # _SphereNeighborhoods(n_voxels=50000, radius=8.0mm, mean_size=33.2)
+        ```
+    """
+    from nilearn.image.resampling import coord_transform
+
+    mask_data = mask_img.get_fdata().astype(bool)
+    affine = mask_img.affine
+
+    # Get voxel coordinates in world space (mm)
+    mask_coords_voxel = np.array(np.nonzero(mask_data)).T  # (n_voxels, 3)
+    n_voxels = mask_coords_voxel.shape[0]
+
+    if n_voxels == 0:
+        raise ValueError("Mask contains no non-zero voxels")
+
+    # Transform to world coordinates using affine
+    mask_coords_world = np.array(
+        coord_transform(
+            mask_coords_voxel[:, 0],
+            mask_coords_voxel[:, 1],
+            mask_coords_voxel[:, 2],
+            affine,
+        )
+    ).T  # (n_voxels, 3)
+
+    # Use BallTree for efficient radius queries
+    # This is the same approach used by nilearn's searchlight
+    clf = neighbors.NearestNeighbors(radius=radius, algorithm="ball_tree")
+    clf.fit(mask_coords_world)
+    adjacency = clf.radius_neighbors_graph(mask_coords_world, mode="connectivity")
+    adjacency = adjacency.tocsr()
+
+    return _SphereNeighborhoods(
+        adjacency=adjacency,
+        radius=radius,
+        n_voxels=n_voxels,
+    )