nltools 0.6.0.dev0__py3-none-any.whl

nltools/models/validation.py

@@ -0,0 +1,26 @@
+"""The one validation check the nltools estimators share.
+
+`_Glm` and `_Ridge` are independent estimators with different input contracts, so
+they share this small private function instead of a common base class.
+"""
+
+from __future__ import annotations
+
+from sklearn.exceptions import NotFittedError
+
+
+def _check_is_fitted(model: object) -> None:
+    """Raise if `model` has not been fitted yet.
+
+    Args:
+        model (object): Estimator carrying an `is_fitted_` flag.
+
+    Raises:
+        NotFittedError: If the model has not been fitted yet. `NotFittedError`
+            subclasses both `ValueError` and `AttributeError`.
+    """
+    if not model.is_fitted_:
+        raise NotFittedError(
+            f"This {type(model).__name__} instance is not fitted yet. "
+            "Call 'fit' with appropriate arguments before using this estimator."
+        )

nltools/plotting/__init__.py

@@ -0,0 +1,32 @@
+"""nltools.plotting — visualization utilities for neuroimaging analysis.
+
+`component_viewer` is the one function users call directly. Everything else
+here is the drawing internal behind a data-class method — `BrainData.plot_surf`,
+`Roc.plot`, `Adjacency.plot_silhouette` and friends — organized into focused
+submodules:
+
+- **brain**: surface plots and flatmaps
+- **adjacency**: adjacency matrix visualizations (stacked, silhouette, distance)
+- **prediction**: model output plots (ROC, decision margin, regression, probability)
+- **decomposition**: ICA/PCA component viewer
+"""
+
+from .brain import (  # noqa: F401
+    _plot_surf,
+    _plot_flatmap,
+)
+from .adjacency import (  # noqa: F401
+    _plot_stacked_adjacency,
+    _plot_mean_label_distance,
+    _plot_between_label_distance,
+    _plot_silhouette,
+)
+from .prediction import (  # noqa: F401
+    _plot_predicted_versus_actual,
+    _plot_decision_margin,
+    _plot_class_probability,
+    _plot_roc,
+)
+from .decomposition import component_viewer
+
+__all__ = ["component_viewer"]

nltools/plotting/adjacency.py

@@ -0,0 +1,421 @@
+"""Adjacency matrix visualization — stacked plots, distance, and silhouette."""
+
+import matplotlib.pyplot as plt
+import numpy as np
+import polars as pl
+import seaborn as sns
+
+from nltools.algorithms.inference import (
+    one_sample_permutation_test,
+    two_sample_permutation_test,
+)
+
+
+def _polars_to_pandas(df):
+    """Convert a polars DataFrame to pandas without requiring pyarrow."""
+    import pandas as pd
+
+    return pd.DataFrame(df.to_dict(as_series=False))
+
+
+def _as_square_ndarray(distance):
+    """Accept np.ndarray, polars DataFrame, or pandas DataFrame and return a square float ndarray."""
+    if isinstance(distance, np.ndarray):
+        arr = distance
+    elif isinstance(distance, pl.DataFrame):
+        arr = distance.to_numpy()
+    elif hasattr(distance, "values") and hasattr(distance, "shape"):
+        arr = np.asarray(distance.values)
+    else:
+        arr = np.asarray(distance)
+    if arr.ndim != 2 or arr.shape[0] != arr.shape[1]:
+        raise ValueError(f"distance must be a square matrix; got shape {arr.shape}")
+    return arr.astype(float)
+
+
+def _within_between_values(distance_arr, labels_arr, label):
+    """Return (within, between) 1-D arrays for one label."""
+    mask_in = labels_arr == label
+    block = distance_arr[np.ix_(mask_in, mask_in)]
+    within = block[np.triu_indices(mask_in.sum(), k=1)]
+    between = distance_arr[np.ix_(mask_in, ~mask_in)].ravel()
+    return within, between
+
+
+def _stacked_adjacency_matrix(adjacency1, adjacency2, normalize=True):
+    """Build the stacked matrix with adjacency1 in the upper triangle, adjacency2 lower.
+
+    The mapping is fixed regardless of `normalize` so toggling normalization never
+    swaps which input appears in which triangle. When `normalize` is True each
+    triangle is mean-centered and scaled by the max absolute triangle value (guarded
+    against a zero max) so the two datasets share a comparable range.
+
+    Args:
+        adjacency1: Adjacency instance rendered in the upper triangle.
+        adjacency2: Adjacency instance rendered in the lower triangle.
+        normalize: Mean-center and scale each triangle before stacking. Default True.
+
+    Returns:
+        Square np.ndarray with the two triangles combined.
+    """
+    if normalize:
+        upper_src = (adjacency1 - adjacency1.mean()).squareform()
+        lower_src = (adjacency2 - adjacency2.mean()).squareform()
+    else:
+        upper_src = adjacency1.squareform()
+        lower_src = adjacency2.squareform()
+
+    upper = np.triu(upper_src, k=1)
+    lower = np.tril(lower_src, k=-1)
+
+    if normalize:
+        upper_scale = np.max(np.abs(upper))
+        lower_scale = np.max(np.abs(lower))
+        if upper_scale > 0:
+            upper = upper / upper_scale
+        if lower_scale > 0:
+            lower = lower / lower_scale
+
+    return upper + lower
+
+
+def _plot_stacked_adjacency(adjacency1, adjacency2, normalize=True, **kwargs):
+    """Create stacked adjacency to illustrate similarity.
+
+    `adjacency1` is drawn in the upper triangle and `adjacency2` in the lower,
+    consistently whether or not `normalize` is set.
+
+    Args:
+        adjacency1 (Adjacency): Adjacency instance shown in the upper triangle.
+        adjacency2 (Adjacency): Adjacency instance shown in the lower triangle.
+        normalize (bool): Normalize matrices before stacking. Default True.
+        **kwargs (dict): Forwarded to `seaborn.heatmap`.
+
+    Returns:
+        matplotlib.axes.Axes: Axes holding the stacked heatmap.
+    """
+    from nltools.data import Adjacency
+
+    if not isinstance(adjacency1, Adjacency) or not isinstance(adjacency2, Adjacency):
+        raise ValueError("This function requires Adjacency() instances as input.")
+
+    dist = _stacked_adjacency_matrix(adjacency1, adjacency2, normalize=normalize)
+    return sns.heatmap(
+        dist, xticklabels=False, yticklabels=False, square=True, **kwargs
+    )
+
+
+def _plot_mean_label_distance(
+    distance,
+    labels,
+    *,
+    ax=None,
+    permutation_test=False,
+    n_permute=5000,
+    fontsize=18,
+    **kwargs,
+):
+    """Violin plot of within- vs between-label distances.
+
+    Args:
+        distance (np.ndarray | pl.DataFrame | pd.DataFrame): Square pairwise distance
+            matrix.
+        labels (array-like): Group label for each row/column (length N).
+        ax (matplotlib.axes.Axes, optional): Axis to draw on.
+        permutation_test (bool): If True, run a two-sample permutation test per group.
+            Default False.
+        n_permute (int): Number of permutations. Default 5000.
+        fontsize (int): Font size for the axis label and title. Default 18.
+        **kwargs (dict): Forwarded to `seaborn.violinplot`.
+
+    Returns:
+        pl.DataFrame | tuple[pl.DataFrame, dict]: A long-format frame with columns
+            `Distance`, `Type`, `Group`. If `permutation_test=True`, a tuple
+            `(long_df, stats)` where `stats` maps each group label to its
+            permutation-test result.
+    """
+    arr = _as_square_ndarray(distance)
+    labels_arr = np.asarray(labels)
+    if labels_arr.shape[0] != arr.shape[0]:
+        raise ValueError("Labels must be same length as distance matrix")
+
+    rows = []
+    for group in np.unique(labels_arr):
+        within, between = _within_between_values(arr, labels_arr, group)
+        rows.append(
+            pl.DataFrame(
+                {"Distance": within, "Type": ["Within"] * len(within), "Group": group}
+            )
+        )
+        rows.append(
+            pl.DataFrame(
+                {
+                    "Distance": between,
+                    "Type": ["Between"] * len(between),
+                    "Group": group,
+                }
+            )
+        )
+    out = pl.concat(rows, how="vertical")
+
+    f = sns.violinplot(
+        x="Group",
+        y="Distance",
+        hue="Type",
+        data=_polars_to_pandas(out),
+        split=True,
+        inner="quartile",
+        palette={"Within": "lightskyblue", "Between": "red"},
+        ax=ax,
+        **kwargs,
+    )
+    f.set_ylabel("Average Distance", fontsize=fontsize)
+    f.set_title("Average Group Distance", fontsize=fontsize)
+
+    if permutation_test:
+        stats = {}
+        for group in np.unique(labels_arr):
+            within = out.filter(
+                (pl.col("Group") == group) & (pl.col("Type") == "Within")
+            )["Distance"].to_numpy()
+            between = out.filter(
+                (pl.col("Group") == group) & (pl.col("Type") == "Between")
+            )["Distance"].to_numpy()
+            stats[str(group)] = two_sample_permutation_test(
+                within, between, n_permute=n_permute
+            )
+        return out, stats
+    return out
+
+
+def _plot_between_label_distance(
+    distance,
+    labels,
+    *,
+    ax=None,
+    permutation_test=True,
+    n_permute=5000,
+    **kwargs,
+):
+    """Heatmap of average pairwise distance between every label pair.
+
+    Args:
+        distance (np.ndarray | pl.DataFrame | pd.DataFrame): Square pairwise distance
+            matrix.
+        labels (array-like): Group label for each row/column (length N).
+        ax (matplotlib.axes.Axes, optional): Axis to draw on.
+        permutation_test (bool): If True, also compute mean-difference and p-value
+            matrices. Default True.
+        n_permute (int): Number of permutations. Default 5000.
+        **kwargs (dict): Forwarded to `seaborn.heatmap`.
+
+    Returns:
+        tuple[pl.DataFrame, ...]: `(long_df, within_mean_df)` without
+            `permutation_test`, or `(long_df, within_mean_df, mean_diff_df, p_df)`
+            with it. All frames are polars DataFrames. `long_df` has columns
+            `Distance`, `Group`, `Comparison`. The three square-matrix-like frames are
+            long format with columns `label1`, `label2`, and a value column so they
+            can be pivoted to a matrix if needed.
+    """
+    arr = _as_square_ndarray(distance)
+    labels_arr = np.asarray(labels)
+    if labels_arr.shape[0] != arr.shape[0]:
+        raise ValueError("Labels must be same length as distance matrix")
+
+    unique = np.unique(labels_arr)
+
+    long_rows = []
+    for i in unique:
+        mask_i = labels_arr == i
+        for j in unique:
+            mask_j = labels_arr == j
+            if i == j:
+                vals = arr[np.ix_(mask_i, mask_i)][np.triu_indices(mask_i.sum(), k=1)]
+            else:
+                vals = arr[np.ix_(mask_i, mask_j)].ravel()
+            long_rows.append(
+                pl.DataFrame(
+                    {
+                        "Distance": vals,
+                        "Group": i,
+                        "Comparison": j,
+                    }
+                )
+            )
+    long_df = pl.concat(long_rows, how="vertical")
+
+    within_mean_df = (
+        long_df.group_by(["Group", "Comparison"])
+        .agg(pl.col("Distance").mean().alias("mean_distance"))
+        .rename({"Group": "label1", "Comparison": "label2"})
+    )
+
+    if ax is None:
+        _, ax = plt.subplots(1)
+
+    within_matrix = _long_to_matrix(
+        within_mean_df, "label1", "label2", "mean_distance", unique
+    )
+
+    if permutation_test:
+        mean_diff_rows = []
+        p_rows = []
+        for i in unique:
+            within_i = long_df.filter(
+                (pl.col("Group") == i) & (pl.col("Comparison") == i)
+            )["Distance"].to_numpy()
+            for j in unique:
+                between_ij = long_df.filter(
+                    (pl.col("Group") == i) & (pl.col("Comparison") == j)
+                )["Distance"].to_numpy()
+                if i == j or len(within_i) == 0 or len(between_ij) == 0:
+                    mean_diff_rows.append({"label1": i, "label2": j, "mean_diff": 0.0})
+                    p_rows.append({"label1": i, "label2": j, "p": 1.0})
+                    continue
+                s = two_sample_permutation_test(
+                    within_i, between_ij, n_permute=n_permute
+                )
+                mean_diff_rows.append(
+                    {"label1": i, "label2": j, "mean_diff": float(s["mean_diff"])}
+                )
+                p_rows.append({"label1": i, "label2": j, "p": float(s["p"])})
+        mean_diff_df = pl.DataFrame(mean_diff_rows)
+        p_df = pl.DataFrame(p_rows)
+
+        mean_diff_matrix = _long_to_matrix(
+            mean_diff_df, "label1", "label2", "mean_diff", unique
+        )
+        p_matrix = _long_to_matrix(p_df, "label1", "label2", "p", unique)
+
+        sns.heatmap(mean_diff_matrix, ax=ax, square=True, **kwargs)
+        sns.heatmap(
+            mean_diff_matrix,
+            mask=p_matrix > 0.05,
+            square=True,
+            linewidth=2,
+            annot=True,
+            ax=ax,
+            cbar=False,
+        )
+        return long_df, within_mean_df, mean_diff_df, p_df
+
+    sns.heatmap(within_matrix, ax=ax, square=True, **kwargs)
+    return long_df, within_mean_df
+
+
+def _long_to_matrix(long_df, row_col, col_col, value_col, order):
+    """Pivot a long-format polars frame into a numpy matrix using *order* for row/col order."""
+    wide = long_df.pivot(
+        values=value_col, index=row_col, on=col_col, aggregate_function="first"
+    )
+    out = np.zeros((len(order), len(order)), dtype=float)
+    wide_dict = {row[row_col]: row for row in wide.iter_rows(named=True)}
+    for i, r in enumerate(order):
+        row = wide_dict.get(r, {})
+        for j, c in enumerate(order):
+            val = row.get(c)
+            out[i, j] = float(val) if val is not None else 0.0
+    return out
+
+
+def _plot_silhouette(
+    distance,
+    labels,
+    *,
+    ax=None,
+    permutation_test=True,
+    n_permute=5000,
+    colors=None,
+    figsize=(6, 4),
+):
+    """Silhouette plot indicating between- vs within-label distance.
+
+    Uses the simplified silhouette definition from the original nltools
+    implementation: within(i) = mean distance to other points in the same
+    cluster; between(i) = mean distance to all points in other clusters
+    (not the strict Rousseeuw min-over-clusters). Score is
+    (between - within) / max(between, within).
+
+    Args:
+        distance (np.ndarray | pl.DataFrame | pd.DataFrame): Square pairwise distance
+            matrix.
+        labels (array-like): Cluster label for each row/column (length N).
+        ax (matplotlib.axes.Axes, optional): Axis to draw on.
+        permutation_test (bool): If True, run a one-sample permutation test per cluster
+            on positive-mean silhouette scores. Default True.
+        n_permute (int): Number of permutations. Default 5000.
+        colors (list, optional): RGB triplets, one per cluster. Default: seaborn
+            `'hls'` palette.
+        figsize (tuple): Figure size. Default (6, 4).
+
+    Returns:
+        pl.DataFrame: Frame with columns `label` and `mean_silhouette`. If
+            `permutation_test` is True, adds a `p` column (1.0 for clusters with
+            non-positive mean).
+    """
+    arr = _as_square_ndarray(distance)
+    labels_arr = np.asarray(labels)
+    if labels_arr.shape[0] != arr.shape[0]:
+        raise ValueError("Labels must be same length as distance matrix")
+
+    unique = np.unique(labels_arr)
+    n_clusters = len(unique)
+    n = arr.shape[0]
+
+    if colors is None:
+        colors = sns.color_palette("hls", n_clusters)
+
+    sil = np.zeros(n, dtype=float)
+    for idx in range(n):
+        same = (labels_arr == labels_arr[idx]) & (np.arange(n) != idx)
+        other = labels_arr != labels_arr[idx]
+        within_mean = arr[idx, same].mean() if same.any() else 0.0
+        between_mean = arr[idx, other].mean() if other.any() else 0.0
+        denom = max(within_mean, between_mean)
+        sil[idx] = (between_mean - within_mean) / denom if denom > 0 else 0.0
+
+    with sns.axes_style("white"):
+        if ax is None:
+            _, ax = plt.subplots(1, figsize=figsize)
+
+    x_lower = 10
+    label_x_positions = []
+    for ci, cluster in enumerate(unique):
+        cluster_vals = np.sort(sil[labels_arr == cluster])
+        size = cluster_vals.shape[0]
+        x_upper = x_lower + size
+        color = colors[ci]
+        with sns.axes_style("white"):
+            plt.fill_between(
+                np.arange(x_lower, x_upper),
+                0,
+                cluster_vals,
+                facecolor=color,
+                edgecolor=color,
+            )
+        label_x_positions.append(np.mean([x_lower, x_upper]))
+        x_lower = x_upper + 3
+
+    ax.set_xticks(label_x_positions)
+    ax.set_xticklabels(unique)
+    ax.set_title("Silhouettes", fontsize=18)
+    ax.set_xlim([5, 10 + n + n_clusters * 3])
+
+    rows = []
+    for cluster in unique:
+        cluster_vals = sil[labels_arr == cluster]
+        rows.append({"label": cluster, "mean_silhouette": float(cluster_vals.mean())})
+    out = pl.DataFrame(rows)
+
+    if permutation_test:
+        p_values = []
+        for cluster in unique:
+            cluster_vals = sil[labels_arr == cluster]
+            if cluster_vals.mean() > 0:
+                stats = one_sample_permutation_test(cluster_vals, n_permute=n_permute)
+                p_values.append(float(stats["p"]))
+            else:
+                p_values.append(1.0)
+        out = out.with_columns(pl.Series("p", p_values))
+
+    return out