nltools 0.6.0.dev0__py3-none-any.whl

nltools/data/results.py

@@ -0,0 +1,291 @@
+"""Structural result records returned by decoding and resampling operations."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import asdict as dataclass_asdict
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generic
+
+import numpy as np
+
+from nltools.models.results import Payload
+
+if TYPE_CHECKING:
+    from .braindata import BrainData
+
+
+#: Fields that may be populated for each spatial scale, and the subset that
+#: every result of that scale must carry. Anything outside `permitted` must be
+#: `None`, so an invalid field combination cannot be constructed.
+_MODE_FIELDS = {
+    "whole_brain": {
+        "required": ("predictions", "cv_folds", "scores", "estimator", "weight_map"),
+        "optional": ("classes",),
+    },
+    "roi": {
+        "required": ("scores", "roi_labels", "score_map", "weight_map"),
+        "optional": ("classes",),
+    },
+    "searchlight": {
+        "required": ("score_map",),
+        "optional": ("classes",),
+    },
+}
+
+#: Fields that describe the call itself rather than one spatial scale's output.
+#: They always carry a value, including a `scoring` of `None`, so they are exempt
+#: from both the per-mode "None means not applicable" rule and the None filter in
+#: `available` and `asdict`.
+_MODE_INDEPENDENT_FIELDS = ("spatial_scale", "scoring")
+
+
+def _fold_mean(scores, axis=None):
+    """Reduce fold scores to their cross-fold mean, ignoring failed folds.
+
+    `Predict.mean_score` and the ROI runner's painted `score_map` must report the
+    same number for the same parcel, so both call this one reduction.
+    """
+    return np.nanmean(scores, axis=axis)
+
+
+@dataclass(frozen=True)
+class Predict:
+    """Frozen structural record for `BrainData.predict` decoding results.
+
+    ``spatial_scale`` is the discriminator: it decides which fields carry a
+    value and which stay ``None``. Construction validates that combination, so
+    an empty or mixed-mode record cannot exist; the shapes within it are the
+    producer's responsibility. Field bindings cannot be rebound, but the
+    payloads they hold remain usable, and the record takes independent
+    ownership of every array, brain map, and estimator it stores.
+
+    **Brain-space outputs are `BrainData` objects**, not raw arrays, so
+    ``result.weight_map.plot()`` works directly (``.data`` gives the array).
+    Non-spatial fields are numpy.
+
+    **Populated by `spatial_scale`.** ``'whole_brain'``: ``predictions``,
+    ``cv_folds``, ``scores``, ``estimator``, ``weight_map``. ``'roi'``:
+    ``scores``, ``roi_labels``, ``score_map``, ``weight_map``.
+    ``'searchlight'``: ``score_map``. ``classes`` accompanies any classifier;
+    ``scoring`` records the caller's scoring specification in every mode.
+
+    **Why the all-data fit is the canonical map.** The mean of per-fold
+    ``coef_`` vectors corresponds to no actual fitted estimator (each fold saw
+    a different subset), and fits on overlapping training folds are not
+    independent uncertainty samples. The record therefore exposes one
+    coefficient map, from the estimator refitted on all observations after
+    cross-validation: cross-validation gives the honest *score*, the refit
+    gives the publishable *map*.
+
+    Attributes:
+        spatial_scale (str): ``'whole_brain'``, ``'roi'``, or
+            ``'searchlight'``.
+        scoring (str | callable | None): The scoring specification the caller
+            passed. ``None`` records that the estimator's own ``score`` method
+            was used; it does not by itself name that method's metric.
+        classes (ndarray | None): Classifier class labels, ``(n_classes,)``.
+            ``None`` for regression.
+        predictions (ndarray | None): Out-of-fold predictions, one per row,
+            ``(n_samples,)`` (whole-brain only).
+        cv_folds (ndarray | None): Fold index per row, ``(n_samples,)``
+            (whole-brain only).
+        scores (ndarray | None): Per-fold score — ``(n_folds,)`` for
+            whole-brain, ``(n_folds, n_rois)`` for ROI.
+        estimator (Any): The all-data fitted sklearn estimator (whole-brain
+            only); use it to ``.predict()`` on new data.
+        weight_map (BrainData | None): Coefficients of the estimator refit on
+            all data, ``(n_voxels,)`` or ``(n_classes, n_voxels)`` for
+            multiclass — one map for regression and binary classification, one
+            map per class in ``classes`` order for multiclass. For ROI, each
+            parcel's coefficients are written into its voxels (NaN outside
+            parcels); magnitudes are not comparable across parcels.
+        roi_labels (ndarray | None): Atlas integer ids, ``(n_rois,)``, in the
+            order of the ``scores`` parcel axis (ROI only).
+        score_map (BrainData | None): ``(n_voxels,)`` map of cross-validated
+            scores — for ROI, every voxel of parcel *i* holds that parcel's
+            mean fold score (NaN outside parcels); for searchlight, the
+            sphere-centered mean fold score at each voxel.
+        mean_score (float | ndarray): Mean of ``scores`` across folds, computed
+            on demand — a float for whole-brain, ``(n_rois,)`` for ROI.
+            Accessing it on a searchlight result raises `AttributeError`.
+        std_score (float | ndarray): Standard deviation of ``scores`` across
+            folds, in ``mean_score``'s form and with the same searchlight rule.
+
+    Note:
+        Encoding-model timeseries prediction (``bd.predict(X=...)``) returns a
+        `BrainData` directly rather than a `Predict` — the natural container
+        for a voxel timeseries.
+    """
+
+    spatial_scale: str
+    scoring: Any = None
+    classes: np.ndarray | None = None
+    predictions: np.ndarray | None = None
+    cv_folds: np.ndarray | None = None
+    scores: np.ndarray | None = None
+    estimator: Any = None
+    weight_map: BrainData | None = None
+    roi_labels: np.ndarray | None = None
+    score_map: BrainData | None = None
+
+    def __post_init__(self):
+        """Validate the field combination, then take ownership."""
+        self._validate_mode()
+        for name in self.__dataclass_fields__:
+            if name in _MODE_INDEPENDENT_FIELDS:
+                # A scoring name or callable is the caller's specification, not
+                # a payload the record owns; copying a callable scorer would
+                # change what `scoring` reports.
+                continue
+            value = getattr(self, name)
+            if value is not None:
+                object.__setattr__(self, name, deepcopy(value))
+
+    def _validate_mode(self) -> None:
+        """Require exactly the fields the spec's shape table lists for this scale."""
+        if self.spatial_scale not in _MODE_FIELDS:
+            raise ValueError(
+                f"spatial_scale must be one of {sorted(_MODE_FIELDS)}; "
+                f"got {self.spatial_scale!r}."
+            )
+        mode = _MODE_FIELDS[self.spatial_scale]
+        permitted = set(mode["required"]) | set(mode["optional"])
+        for name in mode["required"]:
+            if getattr(self, name) is None:
+                raise ValueError(
+                    f"{name} is required for spatial_scale="
+                    f"{self.spatial_scale!r} and cannot be None."
+                )
+        for name in self.__dataclass_fields__:
+            if name in _MODE_INDEPENDENT_FIELDS or name in permitted:
+                continue
+            if getattr(self, name) is not None:
+                raise ValueError(
+                    f"{name} does not apply to spatial_scale="
+                    f"{self.spatial_scale!r} and must be None. That scale "
+                    f"populates {sorted(permitted)}."
+                )
+
+    @property
+    def mean_score(self):
+        """Mean score across folds — a float for whole-brain, per parcel for ROI."""
+        return self._summarize(_fold_mean, "mean_score")
+
+    @property
+    def std_score(self):
+        """Score standard deviation across folds, in `mean_score`'s form."""
+        return self._summarize(np.nanstd, "std_score")
+
+    def _summarize(self, reduction, name: str):
+        """Derive one cross-fold summary from `scores`."""
+        if self.spatial_scale == "searchlight":
+            raise AttributeError(
+                f"{name} does not exist for a searchlight result: searchlight "
+                f"stores its cross-fold mean directly in score_map, with one "
+                f"value per sphere center."
+            )
+        if self.spatial_scale == "roi":
+            return reduction(self.scores, axis=0)
+        return float(reduction(self.scores))
+
+    def __setstate__(self, state):
+        """Restore a pickled record, rejecting one written by an older nltools.
+
+        Unpickling is the only path that bypasses `__post_init__`, and joblib
+        caches (the tutorials memoize `predict` results) are full of pickles. An
+        old record's fields are disjoint enough to detect, and without this check
+        its `score_map` would silently read as the class default `None`.
+        """
+        if "spatial_scale" not in state or set(state) - set(self.__dataclass_fields__):
+            raise ValueError(
+                "This Predict was pickled by an older nltools and cannot be "
+                "restored: its field set predates the spatial_scale "
+                "discriminator. Clear the cache (for the tutorials, "
+                "`uv run poe tutorials-clean-cache`) and rerun."
+            )
+        self.__dict__.update(state)
+
+    def available(self) -> list:
+        """Return names of the fields this result carries (excludes private).
+
+        `spatial_scale` and `scoring` always count: a `scoring` of `None` records
+        that the estimator's own `score` method was used, which is a value, not an
+        absent field.
+        """
+        return [
+            field_name
+            for field_name in self.__dataclass_fields__
+            if not field_name.startswith("_") and self._is_reported(field_name)
+        ]
+
+    def _is_reported(self, field_name: str) -> bool:
+        """Whether a field appears in `available` and the default `asdict`."""
+        return (
+            field_name in _MODE_INDEPENDENT_FIELDS
+            or getattr(self, field_name) is not None
+        )
+
+    def asdict(self, include_none: bool = False) -> dict:
+        """Convert to dictionary.
+
+        Args:
+            include_none: If True, include every field that does not apply to
+                this spatial scale, whose value is None. `spatial_scale` and
+                `scoring` are always included. Private fields (starting with _)
+                are always excluded.
+
+        Returns:
+            Dictionary of field names to values.
+        """
+        full_dict = dataclass_asdict(self)
+        filtered = {k: v for k, v in full_dict.items() if not k.startswith("_")}
+        if not include_none:
+            filtered = {k: v for k, v in filtered.items() if self._is_reported(k)}
+        return filtered
+
+
+@dataclass(frozen=True)
+class BootstrapResult(Generic[Payload]):
+    """Frozen record of one bootstrap statistic's estimate and uncertainty.
+
+    The single result structure every supported `bootstrap` statistic returns.
+    Its payload is whatever the producer works in: `BrainData` for the
+    `BrainData` facade, `Adjacency` for the `Adjacency` facade. The four
+    summary payloads share one data shape.
+
+    Field bindings cannot be rebound. The payloads stay usable, but the record
+    takes independent ownership of each one, so mutating a returned payload
+    never reaches the source object or a sibling payload.
+
+    The record deliberately exposes no replicate mean and no `z`, `p`, or
+    `tail` output: those need a separately defined bootstrap hypothesis test.
+    For a normal-approximation stand-in, users compute it themselves from
+    `estimate` and `standard_error`.
+
+    Attributes:
+        estimate (Payload): The statistic evaluated once on the original full
+            sample — not the mean of the replicates.
+        standard_error (Payload): Elementwise standard deviation of the
+            bootstrap replicates, with `ddof=1`.
+        ci_lower (Payload): Lower bound of the central percentile interval at
+            the requested `confidence_level`.
+        ci_upper (Payload): Upper bound of that interval. The bounds are
+            elementwise marginal: the nominal level applies separately to each
+            voxel, feature, or test row, with no simultaneous-coverage claim.
+        samples (np.ndarray | None): Every replicate, bootstrap axis first,
+            when `return_samples=True`; `None` otherwise.
+    """
+
+    estimate: Payload
+    standard_error: Payload
+    ci_lower: Payload
+    ci_upper: Payload
+    samples: np.ndarray | None = None
+
+    def __post_init__(self):
+        """Take independent ownership of every payload the record stores."""
+        for name in self.__dataclass_fields__:
+            value = getattr(self, name)
+            if value is not None:
+                object.__setattr__(self, name, deepcopy(value))

nltools/data/roc/__init__.py

@@ -0,0 +1,398 @@
+"""ROC (Receiver Operating Characteristic) analysis for single-interval classification.
+
+These tools provide the ability to quickly run receiver operating characteristic
+analyses on the output of machine-learning models applied to imaging data.
+"""
+
+import numpy as np
+from nltools.plotting import _plot_roc
+from scipy.stats import norm, binomtest
+from sklearn.metrics import auc
+from copy import deepcopy
+
+
+class Roc:
+    """Compute receiver operating characteristic curves for single-interval or forced-choice classification.
+
+    The Roc class is based on Tor Wager's Matlab roc_plot.m function and
+    allows a user to easily run different types of receiver operator
+    characteristic curves.  For example, one might be interested in single
+    interval or forced choice.
+
+    Args:
+        input_values (array-like): 1-D continuous decision values, one per observation.
+        binary_outcome (array-like): Boolean class label per observation.
+        method (str): Threshold-selection variant, naming what the chosen
+            threshold maximizes or minimizes: `'optimal_overall'` maximizes the
+            number of correct classifications, so the larger class dominates;
+            `'optimal_balanced'` maximizes balanced accuracy, the mean of
+            sensitivity and specificity, weighting the two classes equally;
+            `'minimum_sdt_bias'` minimizes the signal-detection response bias
+            `c`, which places the threshold midway between the two classes'
+            estimated distributions. With equal class sizes the first two often
+            agree.
+        forced_choice (array-like, optional): Subject id per observation for
+            forced-choice classification (each subject contributes one positive and
+            one negative observation).
+
+    Attributes:
+        input_values (np.ndarray): Decision values.
+        binary_outcome (np.ndarray): Boolean labels.
+        method (str): Configured threshold-selection variant. Set at construction;
+            `calculate`'s `method=` argument reads this as its default and never
+            writes back to it, so an explicit override passed to `calculate` only
+            affects that call.
+        forced_choice (np.ndarray | None): Subject ids for forced-choice classification.
+        criterion_values (np.ndarray): Thresholds at which `tpr`/`fpr` were evaluated;
+            set by `calculate`.
+        tpr (np.ndarray): True positive rate per criterion value; set by `calculate`.
+        fpr (np.ndarray): False positive rate per criterion value; set by `calculate`.
+        auc (float): Area under the ROC curve; set by `calculate`.
+        class_thr (float): Selected classification threshold; set by `calculate`.
+        sensitivity (float): Sensitivity at `class_thr`; set by `calculate`.
+        specificity (float): Specificity at `class_thr`; set by `calculate`.
+        ppv (float): Positive predictive value at `class_thr`; set by `calculate`.
+        accuracy (float): Classification accuracy; set by `calculate`.
+        accuracy_se (float): Standard error of the accuracy; set by `calculate`.
+        accuracy_p (BinomTestResult): `scipy.stats.binomtest` result comparing accuracy
+            against chance (read `.pvalue`); set by `calculate`.
+        tpr_smooth (np.ndarray): Gaussian-model true positive rate curve; set by
+            `plot(method='gaussian')`. Never read by `calculate`.
+        fpr_smooth (np.ndarray): Gaussian-model false positive rate curve; set by
+            `plot(method='gaussian')`. Never read by `calculate`.
+        aucn (float): Area under the Gaussian-model curve (`tpr_smooth`/`fpr_smooth`);
+            set by `plot(method='gaussian')`. Never read by `calculate`.
+        gaussian_sensitivity (float): Gaussian-model sensitivity estimate for
+            forced-choice data; set by `plot(method='gaussian')`. Never read by
+            `calculate`.
+        gaussian_specificity (float): Gaussian-model specificity estimate for
+            forced-choice data; set by `plot(method='gaussian')`. Never read by
+            `calculate`.
+        gaussian_ppv (float): Gaussian-model positive predictive value for
+            forced-choice data; set by `plot(method='gaussian')`. Never read by
+            `calculate`.
+        gaussian_auc (float): Gaussian-model area under the curve for forced-choice
+            data; set by `plot(method='gaussian')`. Never read by `calculate`.
+    """
+
+    def __init__(
+        self,
+        *,
+        input_values=None,
+        binary_outcome=None,
+        method="optimal_overall",
+        forced_choice=None,
+    ):
+        if len(input_values) != len(binary_outcome):
+            raise ValueError(
+                "Data Problem: input_value and binary_outcomeare different lengths."
+            )
+
+        binary_outcome = np.asarray(binary_outcome).astype(bool).flatten()
+        if binary_outcome.all() or not binary_outcome.any():
+            raise ValueError(
+                "Data Problem: binary_outcome must contain both positive and "
+                "negative cases (True and False)."
+            )
+
+        valid_methods = ["optimal_overall", "optimal_balanced", "minimum_sdt_bias"]
+        if method not in valid_methods:
+            raise ValueError(
+                "method must be ['optimal_overall', "
+                "'optimal_balanced','minimum_sdt_bias']"
+            )
+
+        self.input_values = np.array(input_values)
+        self.method = deepcopy(method)
+        self.forced_choice = deepcopy(forced_choice)
+        self.binary_outcome = binary_outcome
+
+    def calculate(
+        self,
+        *,
+        input_values=None,
+        binary_outcome=None,
+        criterion_values=None,
+        method=None,
+        forced_choice=None,
+        balanced_acc=False,
+        tail=2,
+    ):
+        """Calculate ROC metrics and store them on the instance.
+
+        Args:
+            input_values (array-like, optional): 1-D continuous decision values, one
+                per observation. Defaults to the values given at construction.
+            binary_outcome (array-like, optional): Boolean class label per
+                observation. Defaults to the labels given at construction.
+            criterion_values (array-like, optional): Thresholds at which to evaluate
+                `fpr` and `tpr`. Defaults to a dense grid over the range of
+                `input_values`.
+            method (str, optional): Threshold-selection variant, one of
+                `'optimal_overall'` (maximize correct classifications),
+                `'optimal_balanced'` (maximize balanced accuracy, the mean of
+                sensitivity and specificity), or `'minimum_sdt_bias'` (minimize
+                signal-detection response bias).
+                Defaults to `None`, which uses the instance's configured `method`
+                (set at construction, or by assigning `self.method` directly). An
+                explicit value overrides the configured `method` for this call only
+                and does not change `self.method`.
+            forced_choice (array-like, optional): Subject id per observation for
+                forced-choice classification.
+            balanced_acc (bool): Report balanced accuracy (mean of sensitivity and
+                specificity) instead of overall accuracy. Only affects the accuracy
+                estimate, not the p-value or the threshold used for
+                sensitivity/specificity.
+            tail (int | str): `2`/`'two'` for two-tailed (default); `1`/`'one'` for
+                one-tailed (accuracy > chance) in the binomial test for `accuracy_p`.
+        """
+        from nltools.algorithms.validation import _validate_tail_parameter
+
+        binom_alternative = (
+            "two-sided" if _validate_tail_parameter(tail) == "two" else "greater"
+        )
+
+        if input_values is not None:
+            self.input_values = np.array(input_values)
+
+        if binary_outcome is not None:
+            self.binary_outcome = np.asarray(binary_outcome).astype(bool).flatten()
+
+        # Create Criterion Values
+        if criterion_values is not None:
+            self.criterion_values = deepcopy(criterion_values)
+        else:
+            self.criterion_values = np.linspace(
+                np.min(self.input_values.squeeze()),
+                np.max(self.input_values.squeeze()),
+                num=50 * len(self.binary_outcome),
+            )
+
+        if forced_choice is not None:
+            self.forced_choice = deepcopy(forced_choice)
+
+        if self.forced_choice is not None:
+            sub_idx = np.unique(self.forced_choice)
+            if len(sub_idx) != len(self.binary_outcome) / 2:
+                raise ValueError(
+                    "Make sure that subject ids are correct for 'forced_choice'."
+                )
+            if len(
+                set(sub_idx).union(
+                    set(np.array(self.forced_choice)[self.binary_outcome])
+                )
+            ) != len(sub_idx):
+                raise ValueError("Issue with forced_choice subject labels.")
+            if len(
+                set(sub_idx).union(
+                    set(np.array(self.forced_choice)[~self.binary_outcome])
+                )
+            ) != len(sub_idx):
+                raise ValueError("Issue with forced_choice subject labels.")
+            for sub in sub_idx:
+                sub_mn = (
+                    self.input_values[
+                        (self.forced_choice == sub) & (self.binary_outcome)
+                    ]
+                    + self.input_values[
+                        (self.forced_choice == sub) & (~self.binary_outcome)
+                    ]
+                )[0] / 2
+                self.input_values[
+                    (self.forced_choice == sub) & (self.binary_outcome)
+                ] = (
+                    self.input_values[
+                        (self.forced_choice == sub) & (self.binary_outcome)
+                    ][0]
+                    - sub_mn
+                )
+                self.input_values[
+                    (self.forced_choice == sub) & (~self.binary_outcome)
+                ] = (
+                    self.input_values[
+                        (self.forced_choice == sub) & (~self.binary_outcome)
+                    ][0]
+                    - sub_mn
+                )
+            self.class_thr = 0
+
+        # Calculate true positive and false positive rate
+        self.tpr = np.zeros(self.criterion_values.shape)
+        self.fpr = np.zeros(self.criterion_values.shape)
+        for i, x in enumerate(self.criterion_values):
+            wh = self.input_values >= x
+            self.tpr[i] = np.sum(wh[self.binary_outcome]) / np.sum(self.binary_outcome)
+            self.fpr[i] = np.sum(wh[~self.binary_outcome]) / np.sum(
+                ~self.binary_outcome
+            )
+        self.n_true = np.sum(self.binary_outcome)
+        self.n_false = np.sum(~self.binary_outcome)
+        self.auc = auc(self.fpr, self.tpr)
+
+        # Get criterion threshold. An explicit method= overrides the instance's
+        # configured self.method for this call only; self.method itself is left
+        # untouched so a later bare calculate() reverts to it (q31x fvgk #12).
+        if self.forced_choice is None:
+            resolved_method = self.method if method is None else method
+            if resolved_method == "optimal_balanced":
+                # Balanced accuracy is the mean of sensitivity and specificity.
+                # Averaging tpr with fpr instead maximizes at the lowest
+                # criterion value, where everything is called positive.
+                balanced_accuracy = (self.tpr + (1 - self.fpr)) / 2
+                self.class_thr = self.criterion_values[np.argmax(balanced_accuracy)]
+            elif resolved_method == "optimal_overall":
+                n_corr_t = self.tpr * self.n_true
+                n_corr_f = (1 - self.fpr) * self.n_false
+                sm = n_corr_t + n_corr_f
+                self.class_thr = self.criterion_values[np.argmax(sm)]
+            elif resolved_method == "minimum_sdt_bias":
+                # Calculate  MacMillan and Creelman 2005 Response Bias (c_bias)
+                c_bias = (
+                    norm.ppf(np.maximum(0.0001, np.minimum(0.9999, self.tpr)))
+                    + norm.ppf(np.maximum(0.0001, np.minimum(0.9999, self.fpr)))
+                ) / float(2)
+                self.class_thr = self.criterion_values[np.argmin(abs(c_bias))]
+
+        # Calculate output
+        self.false_positive = (self.input_values >= self.class_thr) & (
+            ~self.binary_outcome
+        )
+        self.false_negative = (self.input_values < self.class_thr) & (
+            self.binary_outcome
+        )
+        self.misclass = (self.false_negative) | (self.false_positive)
+        self.true_positive = (self.binary_outcome) & (~self.misclass)
+        self.true_negative = (~self.binary_outcome) & (~self.misclass)
+        self.sensitivity = (
+            np.sum(self.input_values[self.binary_outcome] >= self.class_thr)
+            / self.n_true
+        )
+        self.specificity = (
+            1
+            - np.sum(self.input_values[~self.binary_outcome] >= self.class_thr)
+            / self.n_false
+        )
+        self.ppv = np.sum(self.true_positive) / (
+            np.sum(self.true_positive) + np.sum(self.false_positive)
+        )
+        if self.forced_choice is not None:
+            self.true_positive = self.true_positive[self.binary_outcome]
+            self.true_negative = self.true_negative[~self.binary_outcome]
+            self.false_negative = self.false_negative[self.binary_outcome]
+            self.false_positive = self.false_positive[~self.binary_outcome]
+            self.misclass = (self.false_positive) | (self.false_negative)
+
+        # Calculate Accuracy
+        if balanced_acc:
+            self.accuracy = np.mean(
+                [self.sensitivity, self.specificity]
+            )  # See Brodersen, Ong, Stephan, Buhmann (2010)
+        else:
+            self.accuracy = 1 - np.mean(self.misclass)
+
+        # Calculate p-Value using binomial test (can add hierarchical version of binomial test)
+        self.n = len(self.misclass)
+        self.accuracy_p = binomtest(
+            int(np.sum(~self.misclass)), self.n, p=0.5, alternative=binom_alternative
+        )
+        p = np.mean(~self.misclass)
+        self.accuracy_se = np.sqrt(p * (1 - p) / self.n)
+
+    def plot(self, *, method="gaussian", balanced_acc=False):
+        """Create a ROC plot.
+
+        Runs `calculate` first, then plots either a Gaussian-smoothed ROC curve fit
+        to the decision values or the observed empirical curve. The underlying
+        `calculate` call re-runs with the instance's configured `method` (it never
+        overrides the threshold rule), and the Gaussian-model curve estimates are
+        stored on their own attributes rather than overwriting `calculate`'s
+        `sensitivity`, `specificity`, `ppv`, and `auc`.
+
+        Args:
+            method (str): Type of plot, `'gaussian'` or `'observed'`.
+            balanced_acc (bool): Passed to `calculate`; report balanced accuracy.
+
+        Returns:
+            matplotlib.figure.Figure: The ROC figure.
+
+        Note:
+            For `method='gaussian'` on forced-choice data, this also sets
+            `gaussian_sensitivity`, `gaussian_specificity`, `gaussian_ppv`, and
+            `gaussian_auc` from the fitted Gaussian model. For `method='gaussian'`
+            on either kind of data, it also sets `tpr_smooth`, `fpr_smooth`, and
+            `aucn` (the smoothed curve and its AUC). None of these attributes are
+            read by `calculate`.
+        """
+
+        self.calculate(balanced_acc=balanced_acc)  # Calculate ROC parameters
+
+        if method == "gaussian":
+            if self.forced_choice is not None:
+                sub_idx = np.unique(self.forced_choice)
+                diff_scores = []
+                for sub in sub_idx:
+                    diff_scores.append(
+                        self.input_values[
+                            (self.forced_choice == sub) & (self.binary_outcome)
+                        ][0]
+                        - self.input_values[
+                            (self.forced_choice == sub) & (~self.binary_outcome)
+                        ][0]
+                    )
+                diff_scores = np.array(diff_scores)
+                mn_diff = np.mean(diff_scores)
+                d = mn_diff / np.std(diff_scores)
+                pooled_sd = np.std(diff_scores) / np.sqrt(2)
+                d_a_model = mn_diff / pooled_sd
+
+                expected_acc = 1 - norm.cdf(0, d, 1)
+                self.gaussian_sensitivity = expected_acc
+                self.gaussian_specificity = expected_acc
+                self.gaussian_ppv = self.gaussian_sensitivity / (
+                    self.gaussian_sensitivity + 1 - self.gaussian_specificity
+                )
+                self.gaussian_auc = norm.cdf(d_a_model / np.sqrt(2))
+
+                x = np.arange(-3, 3, 0.1)
+                self.tpr_smooth = 1 - norm.cdf(x, d, 1)
+                self.fpr_smooth = 1 - norm.cdf(x, -d, 1)
+            else:
+                mn_true = np.mean(self.input_values[self.binary_outcome])
+                mn_false = np.mean(self.input_values[~self.binary_outcome])
+                var_true = np.var(self.input_values[self.binary_outcome])
+                var_false = np.var(self.input_values[~self.binary_outcome])
+                pooled_sd = np.sqrt(
+                    (var_true * (self.n_true - 1) + var_false * (self.n_false - 1))
+                    / (self.n_true + self.n_false - 2)
+                )
+                d = (mn_true - mn_false) / pooled_sd
+                z_true = mn_true / pooled_sd
+                z_false = mn_false / pooled_sd
+
+                x = np.arange(z_false - 3, z_true + 3, 0.1)
+                self.tpr_smooth = 1 - (norm.cdf(x, z_true, 1))
+                self.fpr_smooth = 1 - (norm.cdf(x, z_false, 1))
+
+            self.aucn = auc(self.fpr_smooth, self.tpr_smooth)
+            fig = _plot_roc(self.fpr_smooth, self.tpr_smooth)
+
+        elif method == "observed":
+            fig = _plot_roc(self.fpr, self.tpr)
+        else:
+            raise ValueError("method must be 'gaussian' or 'observed'")
+        return fig
+
+    def summary(self):
+        """Display a formatted summary of ROC analysis."""
+
+        print("------------------------")
+        print(".:ROC Analysis Summary:.")
+        print("------------------------")
+        print("{:20s}".format("Accuracy:") + f"{self.accuracy:.2f}")
+        print("{:20s}".format("Accuracy SE:") + f"{self.accuracy_se:.2f}")
+        print("{:20s}".format("Accuracy p-value:") + f"{self.accuracy_p.pvalue:.2f}")
+        print("{:20s}".format("Sensitivity:") + f"{self.sensitivity:.2f}")
+        print("{:20s}".format("Specificity:") + f"{self.specificity:.2f}")
+        print("{:20s}".format("AUC:") + f"{self.auc:.2f}")
+        print("{:20s}".format("PPV:") + f"{self.ppv:.2f}")
+        print("------------------------")