nltools 0.6.0.dev0__py3-none-any.whl

nltools/algorithms/similarity.py

@@ -0,0 +1,234 @@
+"""Similarity metrics and correlation."""
+
+import itertools
+
+import numpy as np
+from scipy.spatial.distance import cdist
+from scipy.stats import rankdata
+
+from .regression import regress
+
+
+def fisher_r_to_z(r):
+    """Convert correlation coefficients to Fisher z values.
+
+    Args:
+        r (float | np.ndarray): Correlation coefficient(s).
+
+    Returns:
+        np.ndarray: Fisher z-transformed correlation(s).
+    """
+    with np.errstate(invalid="ignore"):
+        return np.arctanh(r)
+
+
+def fisher_z_to_r(z):
+    """Convert Fisher z back to a correlation coefficient.
+
+    Args:
+        z (float | np.ndarray): Fisher z value(s).
+
+    Returns:
+        np.ndarray: Correlation coefficient(s).
+    """
+    return np.tanh(z)
+
+
+# Adapted from the scikit-learn RankSVM example by Fabian Pedregosa and
+# Alexandre Gramfort (BSD licensed).
+def transform_pairwise(X, y):
+    """Transform data into pairwise differences with balanced labels for ranking.
+
+    Turns an n-class ranking problem into a two-class classification problem:
+    every pair of samples with different target values becomes one difference
+    row, and signs are flipped so that the -1 and +1 classes are balanced.
+
+    Reference: Herbrich, R., Graepel, T., & Obermayer, K. "Large Margin Rank
+    Boundaries for Ordinal Regression".
+
+    Args:
+        X (np.ndarray): Data, shape (n_samples, n_features).
+        y (np.ndarray): Target labels, shape (n_samples,) or (n_samples, 2). A
+            second column groups the samples; pairs from different groups are skipped.
+
+    Returns:
+        tuple[np.ndarray, np.ndarray]: `(X_trans, y_trans)`. `X_trans` has shape
+            (k, n_features) with one row per retained pair (k is at most
+            n_samples * (n_samples - 1) / 2; pairs are formed within groups when
+            given). `y_trans` holds the labels in {-1, +1}, shape (k,), or (k, 2)
+            with the group in the second column when `y` had two columns.
+    """
+    X = np.asarray(X)
+    y = np.asarray(y)
+    y_ndim = y.ndim
+    if y_ndim == 1:
+        y = np.c_[y, np.ones(y.shape[0])]
+
+    # Pre-allocate lists (more efficient than repeated appends)
+    X_new = []
+    y_new = []
+    y_group = []
+
+    # Use itertools.combinations (necessary for pairwise combinations)
+    # Optimize by using pre-allocated lists and vectorized sign operation
+    comb = itertools.combinations(range(X.shape[0]), 2)
+    for k, (i, j) in enumerate(comb):
+        if y[i, 0] == y[j, 0] or y[i, 1] != y[j, 1]:
+            # skip if same target or different group
+            continue
+        X_new.append(X[i] - X[j])
+        sign_val = np.sign(y[i, 0] - y[j, 0])
+        # output balanced classes
+        if sign_val != (-1) ** k:
+            sign_val = -sign_val
+            X_new[-1] = -X_new[-1]
+        y_new.append(sign_val)
+        y_group.append(y[i, 1])
+
+    # Convert to arrays efficiently
+    if len(X_new) == 0:
+        if y_ndim == 1:
+            return np.array([]).reshape(0, X.shape[1]), np.array([])
+        return np.array([]).reshape(0, X.shape[1]), np.array([]).reshape(0, 2)
+
+    X_trans = np.array(X_new)
+    if y_ndim == 1:
+        return X_trans, np.array(y_new)
+    return X_trans, np.column_stack([np.array(y_new), np.array(y_group)])
+
+
+def compute_similarity(data1, data2, metric="correlation"):
+    """Compute row-wise similarity between two data arrays.
+
+    The array engine behind `BrainData.similarity`.
+
+    Args:
+        data1 (np.ndarray): First data array, shape (n_samples1, n_features).
+        data2 (np.ndarray): Second data array, shape (n_samples2, n_features).
+        metric (str): 'correlation' (or 'pearson'), 'spearman' (or
+            'rank_correlation'), 'dot_product', or 'cosine'. Defaults to 'correlation'.
+
+    Returns:
+        np.ndarray: Similarities of shape (n_samples1, n_samples2), squeezed: a 1D
+            array when either input has a single row, a scalar when both do.
+
+    Examples:
+        ```python
+        data1 = np.random.randn(10, 100)
+        data2 = np.random.randn(5, 100)
+        sim = compute_similarity(data1, data2, metric="correlation")
+        sim.shape  # → (10, 5)
+        ```
+    """
+    # Ensure 2D arrays
+    data1 = np.atleast_2d(data1)
+    data2 = np.atleast_2d(data2)
+
+    if metric == "dot_product":
+        # Vectorized dot product
+        if data2.shape[0] == 1:
+            out = np.dot(data1, data2.T).squeeze()
+        else:
+            out = np.dot(data1, data2.T)
+    elif metric in ["pearson", "correlation"]:
+        # Use np.corrcoef (BLAS-optimized) for Pearson correlation
+        stacked = np.vstack([data1, data2])
+        corr_matrix = np.corrcoef(stacked)
+        n_data1 = data1.shape[0]
+        n_data2 = data2.shape[0]
+        # Extract correlations between data1 rows and data2 rows
+        out = corr_matrix[:n_data1, n_data1 : n_data1 + n_data2]
+        out = out.squeeze()
+    elif metric in ["spearman", "rank_correlation"]:
+        # Spearman correlation: rank-transform then use np.corrcoef
+        data1_ranked = np.apply_along_axis(rankdata, axis=1, arr=data1)
+        data2_ranked = np.apply_along_axis(rankdata, axis=1, arr=data2)
+        stacked = np.vstack([data1_ranked, data2_ranked])
+        corr_matrix = np.corrcoef(stacked)
+        n_data1 = data1.shape[0]
+        n_data2 = data2.shape[0]
+        out = corr_matrix[:n_data1, n_data1 : n_data1 + n_data2]
+        out = out.squeeze()
+    elif metric == "cosine":
+        # Use cdist with cosine metric, then convert distance to similarity
+        out = cdist(data1, data2, metric="cosine").squeeze()
+        out = 1 - out  # Convert distance to similarity
+    else:
+        raise ValueError(
+            f"metric must be one of ['correlation', 'pearson', 'spearman', "
+            f"'rank_correlation', 'dot_product', 'cosine'], got '{metric}'"
+        )
+
+    return out
+
+
+def _compute_multivariate_similarity(y, X, tail=2):
+    """Compute multivariate similarity by regressing one pattern on several.
+
+    The array engine behind `BrainData.multivariate_similarity`: predicts the
+    spatial pattern `y` from a linear combination of the columns of `X` and
+    returns the OLS coefficients, t-statistics, p-values, and residuals.
+
+    Args:
+        y (np.ndarray): Target pattern, shape (n_features,).
+        X (np.ndarray): Predictor patterns, shape (n_features, n_predictors) (the
+            transpose is accepted). An intercept column is always prepended, so
+            do not include one.
+        tail (int): 2 for two-sided p-values, 1 for an upper-tail test. Defaults to 2.
+
+    Returns:
+        dict: Keys 'beta' (coefficients, intercept first, shape (n_predictors + 1,)),
+            't' (t-statistics, same shape), 'p' (p-values, same shape), 'df'
+            (residual degrees of freedom), 'sigma' (residual standard deviation),
+            and 'residual' (residuals, shape (n_features,)).
+
+    Examples:
+        ```python
+        y = np.random.randn(100)
+        X = np.random.randn(100, 5)
+        result = _compute_multivariate_similarity(y, X)
+        result["beta"].shape  # → (6,)  5 predictors + intercept
+        ```
+    """
+    # Ensure y is 1D
+    y = np.atleast_1d(y)
+    if y.ndim > 1:
+        raise ValueError(f"y must be 1D, got shape {y.shape}")
+
+    # Ensure X is 2D: (n_features, n_predictors)
+    X = np.atleast_2d(X)
+    if X.ndim != 2:
+        raise ValueError(f"X must be 2D, got shape {X.shape}")
+
+    # Check if X needs to be transposed (handle both orientations)
+    if X.shape[0] == y.shape[0]:
+        # X is (n_features, n_predictors) - correct orientation
+        pass
+    elif X.shape[1] == y.shape[0]:
+        # X is (n_predictors, n_features) - transpose needed
+        X = X.T
+    else:
+        raise ValueError(
+            f"X must have shape (n_features, n_predictors) or (n_predictors, n_features), "
+            f"where n_features={y.shape[0]}, got shape {X.shape}"
+        )
+
+    # Add intercept (first column)
+    X_with_intercept = np.hstack([np.ones((X.shape[0], 1)), X])
+
+    b, _, t_out, p, _, res = regress(X_with_intercept, y, tail=tail)
+
+    n, p_cols = X_with_intercept.shape
+    df = n - p_cols
+    # Unbiased estimator of residual standard error: sqrt(RSS / df); correct for
+    # both intercept and intercept-free models. See GH #287.
+    sigma = float(np.sqrt(np.dot(res, res) / df))
+
+    return {
+        "beta": b,
+        "t": t_out,
+        "p": p,
+        "df": df,
+        "sigma": sigma,
+        "residual": res,
+    }

nltools/algorithms/validation.py

@@ -0,0 +1,151 @@
+"""The argument vocabulary every algorithms family shares.
+
+`tail` is spoken by inference, alignment and regression alike, and by the two
+facade methods that expose a permutation test (`Roc.summary`,
+`Adjacency.ttest`), so its validator and the p-value computation built on it
+live here rather than inside any one family.
+
+Examples:
+    ```python
+    from nltools.algorithms.validation import _validate_tail_parameter
+
+    _validate_tail_parameter(2)  # → 'two'
+    _validate_tail_parameter("invalid")  # raises ValueError
+    ```
+"""
+
+import numpy as np
+
+
+def _validate_tail_parameter(tail: int | str) -> str:
+    """Validate the public tail vocabulary and normalize to the internal form.
+
+    The public vocabulary is deliberately two-valued: the *direction* of a
+    one-tailed test is fixed by the test's convention, never chosen from the
+    data (a data-driven direction would silently halve every p-value). A fixed
+    direction across all tests is what keeps multiple-comparison correction
+    (FDR, Bonferroni) valid (GH #315).
+
+    Args:
+        tail (int | str): `2` or `'two'` (the default everywhere) for a
+            two-tailed test (`|obs|` vs `|null|`); `1` or `'one'` for a
+            one-tailed test in the test's canonical positive direction
+            (correlation/ISC/similarity > 0, mean > popmean, group1 > group2).
+            To test the negative direction, negate your data, swap the groups,
+            or flip the contrast.
+
+    Returns:
+        str: Normalized internal tail, `'two'` or `'upper'`.
+
+    Raises:
+        ValueError: If `tail` is not a valid option (including the removed
+            `'upper'`/`'lower'`/`-1` forms).
+    """
+    # One mapping table lives in `_normalize_tail_internal`; the public layer
+    # only rejects the internal-only directional forms it must not accept.
+    if tail not in (-1, "upper", "lower"):
+        try:
+            return _normalize_tail_internal(tail)
+        except ValueError:
+            pass
+    raise ValueError(
+        f"tail must be 2|'two' (two-tailed) or 1|'one' (one-tailed, the test's "
+        f"positive direction), got {tail!r}. The 'upper'/'lower'/-1 forms were "
+        "removed in v0.6.0: to test the negative direction, negate your data, "
+        "swap the groups, or flip the contrast."
+    )
+
+
+def _normalize_tail_internal(tail: int | str) -> str:
+    """Normalize a tail value to the internal 'two'/'upper'/'lower' form.
+
+    Accepts BOTH the public v0.6.0 vocabulary (2 or 'two', 1 or 'one') and the
+    internal directional forms ('upper', 'lower', -1) that forced-tail call
+    sites use directly. Public entry points must validate with the strict
+    `_validate_tail_parameter` first — this permissive form exists only so
+    `_compute_pvalue` can serve both layers.
+    """
+    if tail == 2 or tail == "two":
+        return "two"
+    if tail == 1 or tail == "one" or tail == "upper":
+        return "upper"
+    if tail == -1 or tail == "lower":
+        return "lower"
+    raise ValueError(
+        f"tail must be 2|'two', 1|'one' (or internal 'upper'/'lower'/-1), got {tail!r}"
+    )
+
+
+def _compute_pvalue(
+    obs_stat: np.ndarray,
+    null_dist: np.ndarray,
+    tail: int | str = 2,
+) -> np.ndarray:
+    """Calculate p-values from observed statistic and null distribution.
+
+    Computes the proportion of null-distribution values at least as extreme as
+    the observed statistic, with the `(count + 1) / (n_permute + 1)` correction:
+    the observed value counts as one draw, so p is never 0 and its minimum is
+    `1 / (n_permute + 1)`. Two-tailed tests compare absolute values. The fixed
+    per-tail direction keeps multiple-comparison correction (FDR, Bonferroni)
+    valid across tests (GH #315).
+
+    Args:
+        obs_stat (np.ndarray): Observed statistic(s), shape `()` for a scalar or
+            `(n_features,)` for multi-feature.
+        null_dist (np.ndarray): Null distribution from permutations, shape
+            `(n_permute,)` for a single feature or `(n_permute, n_features)`
+            for multi-feature.
+        tail (int | str): `2` or `'two'` for a two-tailed test (`|obs|` vs
+            `|null|`); `1`, `'one'`, or the internal `'upper'` for a one-tailed
+            upper test (`null >= obs`, positive effects); the internal `'lower'`
+            or `-1` for a one-tailed lower test (`null <= obs`), reserved for
+            forced-tail call sites and not part of the public vocabulary.
+
+    Returns:
+        np.ndarray: P-value(s) with the same shape as `obs_stat`.
+
+    Examples:
+        ```python
+        obs_stat = np.array([2.5])
+        null_dist = np.random.randn(1000, 1)
+        p = _compute_pvalue(obs_stat, null_dist, tail="two")
+        0 < p <= 1  # → True
+
+        # Explicit directions for forced-tail call sites
+        p_upper = _compute_pvalue(obs_stat, null_dist, tail="upper")
+        p_lower = _compute_pvalue(obs_stat, null_dist, tail="lower")
+        ```
+    """
+    tail_normalized = _normalize_tail_internal(tail)
+
+    # Ensure inputs are numpy arrays (handles Python float/int scalars)
+    obs_stat = np.asarray(obs_stat)
+    null_dist = np.asarray(null_dist)
+
+    # Handle shape differences
+    if null_dist.ndim == 1:
+        null_dist = null_dist[:, np.newaxis]
+    if obs_stat.ndim == 0:
+        obs_stat = obs_stat.reshape(1)
+    elif obs_stat.ndim == 1:
+        obs_stat = obs_stat.reshape(1, -1)
+
+    n_permute = null_dist.shape[0]
+    denom = float(n_permute) + 1.0
+
+    if tail_normalized == "upper":
+        # One-tailed upper: count how many null >= observed
+        # Tests for positive effects (H1: statistic > 0)
+        numer = np.sum(null_dist >= obs_stat, axis=0) + 1.0
+    elif tail_normalized == "lower":
+        # One-tailed lower: count how many null <= observed
+        # Tests for negative effects (H1: statistic < 0)
+        numer = np.sum(null_dist <= obs_stat, axis=0) + 1.0
+    else:  # tail_normalized == "two"
+        # Two-tailed: count how many |null| >= |observed|
+        numer = np.sum(np.abs(null_dist) >= np.abs(obs_stat), axis=0) + 1.0
+
+    p_values = numer / denom
+
+    return p_values

nltools/cross_validation.py

@@ -0,0 +1,72 @@
+"""Scikit-learn-compatible cross-validation data classes."""
+
+__all__ = ["KFoldStratified"]
+
+from sklearn.model_selection._split import _BaseKFold
+from sklearn.utils import check_random_state
+from sklearn.utils.validation import check_array
+import numpy as np
+
+
+class KFoldStratified(_BaseKFold):
+    """Stratify continuous targets across K-fold cross-validation.
+
+    Unlike the scikit-learn equivalent, this iterator stratifies continuous data.
+
+    Provides train/test indices to split data in train test sets. Samples are
+    ordered by their continuous target `y` and dealt round-robin into k folds
+    so each fold spans the full range of `y`. Each fold is then used as a
+    validation set once while the k - 1 remaining folds form the training set.
+
+    Args:
+        n_splits (int): Number of folds. Must be at least 2. Defaults to 3.
+        shuffle (bool): Whether to break ties in `y` randomly before dealing samples
+            into folds. Default False.
+        random_state (int | np.random.RandomState, optional): Seed or RandomState for
+            the tie-break shuffle. If None, use the default numpy RNG.
+    """
+
+    def __init__(self, n_splits=3, *, shuffle=False, random_state=None):
+        super().__init__(n_splits=n_splits, shuffle=shuffle, random_state=random_state)
+
+    def _make_test_folds(self, X, y=None, groups=None):
+        y_arr = np.asarray(y).ravel()
+        n = len(y_arr)
+        if self.shuffle:
+            # Sort by y (stratification) but break ties randomly so that
+            # shuffle/random_state actually vary the fold assignment. lexsort
+            # uses the last key as the primary sort, so y_arr stays primary and
+            # the random tiebreak only reorders samples that share a y value.
+            rng = check_random_state(self.random_state)
+            tiebreak = rng.permutation(n)
+            order = np.lexsort((tiebreak, y_arr))
+        else:
+            order = np.argsort(y_arr, kind="stable")
+        test_folds = np.full(n, np.nan)
+        for k in range(self.n_splits):
+            test_folds[order[np.arange(k, n, self.n_splits)]] = k
+        return test_folds
+
+    def _iter_test_masks(self, X=None, y=None, groups=None):
+        test_folds = self._make_test_folds(X, y)
+        for i in range(self.n_splits):
+            yield test_folds == i
+
+    def split(self, X, y=None, groups=None):
+        """Generate indices to split data into training and test set.
+
+        Args:
+            X (array-like): Training data of shape `(n_samples, n_features)`. Only
+                `y` is needed to generate the splits, so `np.zeros(n_samples)` works
+                as a placeholder.
+            y (array-like): Continuous target of shape `(n_samples,)`; stratification
+                is based on its ordering.
+            groups (array-like, optional): Always ignored; exists for sklearn
+                compatibility.
+
+        Yields:
+            tuple[np.ndarray, np.ndarray]: `(train, test)` — the training set indices
+                and the testing set indices for that split.
+        """
+        y = check_array(y, ensure_2d=False, dtype=None)
+        return super().split(X, y, groups)

nltools/data/__init__.py

@@ -0,0 +1,30 @@
+"""Data classes for neuroimaging analysis.
+
+`BrainData` (masked voxel data), `Adjacency` (similarity/distance matrices),
+`DesignMatrix` (regressors), the `Roc` analysis class, the
+`Simulator`/`SimulateGrid` data simulators, and the frozen result records those
+classes return (`Predict`, `BootstrapResult`, `ContrastResult`) plus the
+brain-space configuration record (`BrainSpaceConfig`).
+"""
+
+from .braindata import BrainData
+from .adjacency import Adjacency
+from .designmatrix import DesignMatrix
+from .results import BootstrapResult, Predict
+from .simulator import Simulator, SimulateGrid
+from .roc import Roc
+from nltools.models.results import ContrastResult
+from nltools.templates.config import BrainSpaceConfig
+
+__all__ = [
+    "Adjacency",
+    "BootstrapResult",
+    "BrainData",
+    "BrainSpaceConfig",
+    "ContrastResult",
+    "DesignMatrix",
+    "Predict",
+    "Roc",
+    "SimulateGrid",
+    "Simulator",
+]