"""Public result objects for NeuroWeave statistical analyses."""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any

import numpy as np
import pandas as pd


@dataclass
class KernelStatsResult:
    """Results of kernel-level statistical inference.

    Parameters
    ----------
    statistics : np.ndarray | None, optional
        Group-level test statistics.
    p_values : np.ndarray | None, optional
        P-value map associated with the statistics.
    metadata : dict[str, Any], optional
        Additional metadata describing the inference procedure.
    """

    statistics: np.ndarray | None = None
    p_values: np.ndarray | None = None
    metadata: dict[str, Any] = field(default_factory=dict)

    def summary(self) -> str:
        """Summarize kernel-level statistics.

        Returns
        -------
        str
            Human-readable summary of the kernel statistics.
        """

        raise NotImplementedError()

    def plot(self) -> None:
        """Plot kernel-level statistics."""

        raise NotImplementedError()

    def to_dataframe(self) -> pd.DataFrame:
        """Convert kernel statistics to a tabular representation.

        Returns
        -------
        pandas.DataFrame
            Tabular view of the kernel statistics.
        """

        raise NotImplementedError()


@dataclass
class PermutationTestResult:
    """Results of a permutation test.

    Parameters
    ----------
    observed : np.ndarray | None, optional
        Observed statistic or data summary.
    null_distribution : np.ndarray | None, optional
        Null distribution sampled under permutation.
    p_value : float | np.ndarray | None, optional
        P-value associated with the observed statistic.
    """

    observed: np.ndarray | None = None
    null_distribution: np.ndarray | None = None
    p_value: float | np.ndarray | None = None

    def summary(self) -> str:
        """Summarize permutation-test results.

        Returns
        -------
        str
            Human-readable summary of the permutation test.
        """

        raise NotImplementedError()

    def plot_null(self) -> None:
        """Plot the null distribution."""

        raise NotImplementedError()


@dataclass
class ClusterTestResult:
    """Results of a cluster-based statistical test.

    Parameters
    ----------
    clusters : list[np.ndarray]
        Cluster definitions or masks.
    cluster_p_values : np.ndarray | None, optional
        P-values associated with each detected cluster.
    stat_map : np.ndarray | None, optional
        Underlying statistic map used for clustering.
    """

    clusters: list[np.ndarray] = field(default_factory=list)
    cluster_p_values: np.ndarray | None = None
    stat_map: np.ndarray | None = None

    def summary(self) -> str:
        """Summarize cluster-based test results.

        Returns
        -------
        str
            Human-readable summary of detected clusters.
        """

        raise NotImplementedError()

    def plot_clusters(self) -> None:
        """Plot detected clusters over the statistic map."""

        raise NotImplementedError()


@dataclass
class LagwiseStatsResult:
    """Results of lag-resolved statistical inference.

    Parameters
    ----------
    lag_axis : np.ndarray | None, optional
        Lag values associated with the statistics.
    statistics : np.ndarray | None, optional
        Statistic values across lags.
    p_values : np.ndarray | None, optional
        P-values across lags.
    """

    lag_axis: np.ndarray | None = None
    statistics: np.ndarray | None = None
    p_values: np.ndarray | None = None

    def summary(self) -> str:
        """Summarize lag-wise statistics.

        Returns
        -------
        str
            Human-readable summary of lag-wise inference results.
        """

        raise NotImplementedError()

    def plot_lag_curve(self) -> None:
        """Plot a lag-resolved statistical curve."""

        raise NotImplementedError()
