statgpu 0.1.0__py3-none-any.whl

statgpu/inference/_results.py

@@ -0,0 +1,265 @@
+"""Shared inference result containers.
+
+These classes are intentionally lightweight.  They describe how inference
+results are carried, serialized, and synchronized back to estimator attributes;
+model-specific inference algorithms live in the model/helper modules.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Sequence
+
+import numpy as np
+
+
+def _to_numpy_or_none(value):
+    if value is None:
+        return None
+    return np.asarray(value)
+
+
+def _serializable(value):
+    if value is None:
+        return None
+    arr = np.asarray(value)
+    if arr.ndim == 0:
+        return arr.item()
+    return arr.tolist()
+
+
+@dataclass
+class BaseInferenceResult:
+    """Base class for model inference results."""
+
+    method: str
+    feature_names: Optional[Sequence[str]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def apply_to(self, estimator):
+        """Attach this result object to an estimator."""
+        estimator._inference_result = self
+        return estimator
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "result_type": self.__class__.__name__,
+            "method": self.method,
+            "feature_names": list(self.feature_names) if self.feature_names is not None else None,
+            "metadata": dict(self.metadata),
+        }
+
+    def to_dataframe(self):
+        try:
+            import pandas as pd
+        except ImportError as exc:
+            raise ImportError("pandas is required for to_dataframe()") from exc
+        return pd.DataFrame([self.to_dict()])
+
+
+@dataclass
+class ParameterInferenceResult(BaseInferenceResult):
+    """Parameter-level inference result.
+
+    This class only promises per-parameter estimates/statistics.  It does not
+    imply a joint Wald test or a complete precision matrix.
+    """
+
+    params: Any = None
+    bse: Any = None
+    statistic: Any = None
+    statistic_name: str = "statistic"
+    pvalues: Any = None
+    conf_int: Any = None
+    cov_type: Optional[str] = None
+    distribution: Optional[str] = None
+    df: Optional[float] = None
+
+    def __post_init__(self):
+        self.params = _to_numpy_or_none(self.params)
+        self.bse = _to_numpy_or_none(self.bse)
+        self.statistic = _to_numpy_or_none(self.statistic)
+        self.pvalues = _to_numpy_or_none(self.pvalues)
+        self.conf_int = _to_numpy_or_none(self.conf_int)
+
+    def apply_to(self, estimator):
+        super().apply_to(estimator)
+        estimator._params = None if self.params is None else np.asarray(self.params).copy()
+        estimator._bse = None if self.bse is None else np.asarray(self.bse).copy()
+        if self.statistic is not None:
+            stat = np.asarray(self.statistic).copy()
+            if self.statistic_name == "z":
+                estimator._zvalues = stat
+                if hasattr(estimator, "_tvalues"):
+                    estimator._tvalues = None
+            elif self.statistic_name == "t":
+                estimator._tvalues = stat
+                if hasattr(estimator, "_zvalues"):
+                    estimator._zvalues = None
+            else:
+                estimator._statistic = stat
+                if hasattr(estimator, "_zvalues"):
+                    estimator._zvalues = None
+        estimator._pvalues = None if self.pvalues is None else np.asarray(self.pvalues).copy()
+        estimator._conf_int = None if self.conf_int is None else np.asarray(self.conf_int).copy()
+        return estimator
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = super().to_dict()
+        data.update(
+            {
+                "params": _serializable(self.params),
+                "bse": _serializable(self.bse),
+                "statistic": _serializable(self.statistic),
+                "statistic_name": self.statistic_name,
+                "pvalues": _serializable(self.pvalues),
+                "conf_int": _serializable(self.conf_int),
+                "cov_type": self.cov_type,
+                "distribution": self.distribution,
+                "df": self.df,
+            }
+        )
+        return data
+
+    def to_dataframe(self):
+        try:
+            import pandas as pd
+        except ImportError as exc:
+            raise ImportError("pandas is required for to_dataframe()") from exc
+
+        params = np.asarray(self.params)
+        if params.ndim != 1:
+            raise ValueError("to_dataframe() is only supported for one-dimensional parameter results.")
+        names = (
+            list(self.feature_names)
+            if self.feature_names is not None
+            else [f"param_{i}" for i in range(params.shape[0])]
+        )
+        data = {
+            "term": names,
+            "estimate": params,
+        }
+        if self.bse is not None:
+            data["std_error"] = np.asarray(self.bse)
+        if self.statistic is not None:
+            data[self.statistic_name] = np.asarray(self.statistic)
+        if self.pvalues is not None:
+            data["pvalue"] = np.asarray(self.pvalues)
+        if self.conf_int is not None:
+            ci = np.asarray(self.conf_int)
+            data["conf_low"] = ci[:, 0]
+            data["conf_high"] = ci[:, 1]
+        return pd.DataFrame(data)
+
+
+@dataclass
+class GaussianInferenceResult(ParameterInferenceResult):
+    """Gaussian linear-model parameter inference result."""
+
+    method: str = "classical"
+    statistic_name: str = "t"
+    distribution: Optional[str] = "t"
+
+    @property
+    def tvalues(self):
+        return self.statistic
+
+
+@dataclass
+class DebiasedInferenceResult(ParameterInferenceResult):
+    """Placeholder result type for debiased parameter inference."""
+
+    method: str = "debiased"
+    statistic_name: str = "z"
+    distribution: Optional[str] = "normal"
+    precision_method: Optional[str] = None
+    simultaneous_conf_int: Any = None
+    simultaneous_method: Optional[str] = None
+    simultaneous_alpha: Optional[float] = None
+    simultaneous_n_bootstrap: Optional[int] = None
+    simultaneous_critical_value: Optional[float] = None
+    simultaneous_target_mask: Any = None
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.simultaneous_conf_int = _to_numpy_or_none(self.simultaneous_conf_int)
+        self.simultaneous_target_mask = _to_numpy_or_none(self.simultaneous_target_mask)
+
+    def apply_to(self, estimator):
+        super().apply_to(estimator)
+        if self.statistic is not None:
+            stat = np.asarray(self.statistic).copy()
+            estimator._zvalues = stat
+            # Existing Lasso summary code displays debiased z-statistics through
+            # the legacy _tvalues slot.
+            estimator._tvalues = stat
+        if self.simultaneous_conf_int is not None:
+            estimator._conf_int_simultaneous = np.asarray(self.simultaneous_conf_int).copy()
+            estimator._simultaneous_enabled = True
+            estimator._simultaneous_method = self.simultaneous_method
+            estimator._simultaneous_alpha = self.simultaneous_alpha
+            estimator._simultaneous_n_bootstrap = self.simultaneous_n_bootstrap
+            estimator._simultaneous_critical_value = self.simultaneous_critical_value
+            estimator._simultaneous_target_mask = (
+                None
+                if self.simultaneous_target_mask is None
+                else np.asarray(self.simultaneous_target_mask).copy()
+            )
+        return estimator
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = super().to_dict()
+        data["precision_method"] = self.precision_method
+        data.update(
+            {
+                "simultaneous_conf_int": _serializable(self.simultaneous_conf_int),
+                "simultaneous_method": self.simultaneous_method,
+                "simultaneous_alpha": self.simultaneous_alpha,
+                "simultaneous_n_bootstrap": self.simultaneous_n_bootstrap,
+                "simultaneous_critical_value": self.simultaneous_critical_value,
+                "simultaneous_target_mask": _serializable(self.simultaneous_target_mask),
+            }
+        )
+        return data
+
+
+@dataclass
+class OracleActiveSetInferenceResult(ParameterInferenceResult):
+    """Placeholder result type for active-set/oracle-style inference."""
+
+    method: str = "active_set"
+    statistic_name: str = "z"
+    distribution: Optional[str] = "normal"
+    active_set: Any = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = super().to_dict()
+        data["active_set"] = _serializable(self.active_set)
+        return data
+
+
+@dataclass
+class ResamplingInferenceResult(BaseInferenceResult):
+    """Placeholder result type for bootstrap/permutation-style inference."""
+
+    samples: Any = None
+    observed: Any = None
+    confidence_interval: Any = None
+    pvalue: Optional[float] = None
+
+    def __post_init__(self):
+        self.samples = _to_numpy_or_none(self.samples)
+        self.observed = _to_numpy_or_none(self.observed)
+        self.confidence_interval = _to_numpy_or_none(self.confidence_interval)
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = super().to_dict()
+        data.update(
+            {
+                "samples": _serializable(self.samples),
+                "observed": _serializable(self.observed),
+                "confidence_interval": _serializable(self.confidence_interval),
+                "pvalue": self.pvalue,
+            }
+        )
+        return data

statgpu/linear_model/__init__.py

@@ -0,0 +1,75 @@
+"""
+Linear models for regression and classification.
+"""
+
+# Wrappers (basic model classes)
+from .wrappers import (
+    LinearRegression,
+    Ridge,
+    Lasso,
+    ElasticNet,
+    AdaptiveLasso,
+    SCADRegression,
+    MCPRegression,
+    LogisticRegression,
+    GammaRegression,
+    PoissonRegression,
+    InverseGaussianRegression,
+    NegativeBinomialRegression,
+    TweedieRegression,
+)
+
+# GLM base
+from ._glm_base import GeneralizedLinearModel, OrderedGeneralizedLinearModel
+
+# Penalized models
+from .penalized import PenalizedGeneralizedLinearModel
+from .penalized._penalized_linear import PenalizedLinearRegression
+from .penalized._penalized_logistic import PenalizedLogisticRegression
+from .penalized._penalized_poisson import PenalizedPoissonRegression
+from .penalized._penalized_gamma import PenalizedGammaRegression
+from .penalized._penalized_inverse_gaussian import PenalizedInverseGaussianRegression
+from .penalized._penalized_negative_binomial import PenalizedNegativeBinomialRegression
+from .penalized._penalized_tweedie import PenalizedTweedieRegression
+
+# CV models
+from .cv import LassoCV, RidgeCV, ElasticNetCV, LogisticRegressionCV
+from .penalized._penalized_cv import PenalizedGLM_CV, ApproximateCVWarning
+
+# Ordered models
+from ._ordered_logit import OrderedLogitRegression
+from ._ordered_probit import OrderedProbitRegression
+
+__all__ = [
+    'LinearRegression',
+    'LogisticRegression',
+    'LogisticRegressionCV',
+    'PoissonRegression',
+    'GammaRegression',
+    'InverseGaussianRegression',
+    'NegativeBinomialRegression',
+    'TweedieRegression',
+    'GeneralizedLinearModel',
+    'OrderedGeneralizedLinearModel',
+    'PenalizedGeneralizedLinearModel',
+    'PenalizedGLM_CV',
+    'PenalizedLinearRegression',
+    'PenalizedLogisticRegression',
+    'PenalizedPoissonRegression',
+    'PenalizedGammaRegression',
+    'PenalizedInverseGaussianRegression',
+    'PenalizedNegativeBinomialRegression',
+    'PenalizedTweedieRegression',
+    'AdaptiveLasso',
+    'SCADRegression',
+    'MCPRegression',
+    'Ridge',
+    'RidgeCV',
+    'Lasso',
+    'LassoCV',
+    'ElasticNet',
+    'ElasticNetCV',
+    'OrderedLogitRegression',
+    'OrderedProbitRegression',
+    'ApproximateCVWarning',
+]

statgpu/linear_model/_gaussian_inference.py

@@ -0,0 +1,306 @@
+"""Shared Gaussian linear-model inference helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+from scipy import stats
+
+from statgpu.backends import _to_numpy
+from statgpu.inference._results import GaussianInferenceResult
+
+
+@dataclass
+class GaussianFitState:
+    X_design: np.ndarray
+    y: np.ndarray
+    resid: np.ndarray
+    scale: np.ndarray | float
+    nobs: int
+    df_resid: int
+    params: np.ndarray
+
+
+def validate_cov_type(cov_type: str) -> str:
+    """Validate and normalize cov_type. Preserves string identity for sklearn clone()."""
+    _ct = str(cov_type).lower()
+    if _ct not in ("nonrobust", "hc0", "hc1", "hc2", "hc3", "hac"):
+        raise ValueError(
+            "cov_type must be one of: 'nonrobust', 'hc0', 'hc1', 'hc2', 'hc3', 'hac'"
+        )
+    return cov_type if str(cov_type) == _ct else _ct
+
+
+def validate_hac_maxlags(hac_maxlags: Optional[int]) -> Optional[int]:
+    if hac_maxlags is not None and int(hac_maxlags) < 0:
+        raise ValueError("hac_maxlags must be a non-negative integer or None")
+    return None if hac_maxlags is None else int(hac_maxlags)
+
+
+def resolve_hac_maxlags(n_obs: int, hac_maxlags: Optional[int]) -> int:
+    if n_obs <= 1:
+        return 0
+    if hac_maxlags is None:
+        maxlags = int(np.floor(4.0 * (n_obs / 100.0) ** (2.0 / 9.0)))
+    else:
+        maxlags = int(hac_maxlags)
+    return max(0, min(maxlags, n_obs - 1))
+
+
+def build_gaussian_fit_state(X, y, coef, intercept, fit_intercept: bool) -> GaussianFitState:
+    X_np = np.asarray(_to_numpy(X), dtype=float)
+    y_np = np.asarray(_to_numpy(y), dtype=float)
+    if y_np.ndim == 2 and y_np.shape[1] == 1:
+        y_np = y_np.ravel()
+
+    coef_np = np.asarray(coef, dtype=float)
+    intercept_np = np.asarray(intercept, dtype=float)
+    if fit_intercept:
+        X_design = np.column_stack([np.ones(X_np.shape[0], dtype=X_np.dtype), X_np])
+        if coef_np.ndim == 1:
+            params = np.concatenate([[float(intercept_np)], coef_np])
+        else:
+            params = np.vstack([intercept_np.reshape(1, -1), coef_np])
+    else:
+        X_design = X_np
+        params = coef_np.copy()
+
+    y_pred = X_np @ coef_np
+    if fit_intercept:
+        y_pred = y_pred + intercept_np
+    resid = y_np - y_pred
+    nobs = X_design.shape[0]
+    df_resid = nobs - X_design.shape[1]
+    rss = np.sum(resid ** 2, axis=0)
+    scale = rss / df_resid if df_resid > 0 else np.full_like(rss, np.nan, dtype=float)
+    if np.ndim(scale) == 0:
+        scale = float(scale)
+    return GaussianFitState(
+        X_design=X_design,
+        y=y_np,
+        resid=resid,
+        scale=scale,
+        nobs=nobs,
+        df_resid=df_resid,
+        params=params,
+    )
+
+
+def _hac_meat_numpy(scores: np.ndarray, maxlags: int) -> np.ndarray:
+    n = scores.shape[0]
+    meat = scores.T @ scores
+    for lag in range(1, maxlags + 1):
+        weight = 1.0 - lag / (maxlags + 1.0)
+        gamma = scores[lag:].T @ scores[:-lag]
+        meat += weight * (gamma + gamma.T)
+    return meat
+
+
+def robust_covariance_numpy(
+    X: np.ndarray,
+    resid: np.ndarray,
+    bread_inv: np.ndarray,
+    cov_type: str,
+    hac_maxlags: Optional[int] = None,
+) -> np.ndarray:
+    cov_type = validate_cov_type(cov_type)
+    n, k = X.shape
+    resid = np.asarray(resid, dtype=float)
+
+    if cov_type == "hac":
+        scores = X * resid[:, None]
+        maxlags = resolve_hac_maxlags(n, hac_maxlags)
+        meat = _hac_meat_numpy(scores, maxlags)
+        return bread_inv @ meat @ bread_inv
+
+    leverage = None
+    if cov_type in ("hc2", "hc3"):
+        leverage = np.sum(X * (X @ bread_inv), axis=1)
+        leverage = np.clip(leverage, 0.0, 1.0 - 1e-12)
+
+    if cov_type == "hc2":
+        omega = resid ** 2 / np.maximum(1.0 - leverage, 1e-12)
+    elif cov_type == "hc3":
+        omega = resid ** 2 / np.maximum((1.0 - leverage) ** 2, 1e-12)
+    else:
+        omega = resid ** 2
+
+    meat = X.T @ (X * omega[:, None])
+    if cov_type == "hc1" and n > k:
+        meat *= n / (n - k)
+    return bread_inv @ meat @ bread_inv
+
+
+def robust_covariance_gpu(X, resid, bread_inv, cov_type, xp, hac_maxlags=None):
+    """GPU-native robust/HAC covariance (CuPy or Torch)."""
+    cov_type = validate_cov_type(cov_type)
+    n, k = X.shape
+
+    if cov_type == "hac":
+        scores = X * resid[:, None]
+        maxlags = resolve_hac_maxlags(n, hac_maxlags)
+        meat = _hac_meat_gpu(scores, maxlags, xp)
+        return bread_inv @ meat @ bread_inv
+
+    leverage = None
+    if cov_type in ("hc2", "hc3"):
+        leverage = xp.sum(X * (X @ bread_inv), axis=1)
+        leverage = xp.clip(leverage, 0.0, 1.0 - 1e-12)
+
+    if cov_type == "hc2":
+        omega = resid ** 2 / xp.clip(1.0 - leverage, 1e-12, None)
+    elif cov_type == "hc3":
+        omega = resid ** 2 / xp.clip((1.0 - leverage) ** 2, 1e-12, None)
+    else:
+        omega = resid ** 2
+
+    meat = X.T @ (X * omega[:, None])
+    if cov_type == "hc1" and n > k:
+        meat = meat * (n / (n - k))
+    return bread_inv @ meat @ bread_inv
+
+
+def _hac_meat_gpu(scores, maxlags, xp):
+    """GPU-native Bartlett-kernel HAC meat."""
+    meat = scores.T @ scores
+    for lag in range(1, maxlags + 1):
+        weight = 1.0 - lag / (maxlags + 1.0)
+        gamma = scores[lag:].T @ scores[:-lag]
+        meat = meat + weight * (gamma + gamma.T)
+    return meat
+
+
+def compute_gaussian_inference(
+    X_design,
+    params,
+    resid,
+    scale,
+    df_resid: int,
+    cov_type: str,
+    hac_maxlags: Optional[int] = None,
+    ridge_alpha: float = 0.0,
+    alpha: float = 0.05,
+    ridge_penalize_intercept: Optional[bool] = None,
+) -> Optional[GaussianInferenceResult]:
+    if X_design is None or scale is None:
+        return None
+    scale_arr = np.asarray(scale, dtype=float)
+    if np.any(np.isnan(scale_arr)):
+        return None
+
+    X = np.asarray(_to_numpy(X_design), dtype=float)
+    params_arr = np.asarray(_to_numpy(params), dtype=float)
+    resid_arr = np.asarray(_to_numpy(resid), dtype=float)
+    n, k = X.shape
+    XtX = X.T @ X
+    penalty_diag = np.zeros(k, dtype=float)
+    if ridge_alpha:
+        penalty_diag[:] = float(ridge_alpha)
+        if ridge_penalize_intercept is None:
+            unpenalized_intercept = k > 0 and np.allclose(X[:, 0], X[0, 0])
+        else:
+            unpenalized_intercept = k > 0 and not bool(ridge_penalize_intercept)
+        if unpenalized_intercept:
+            penalty_diag[0] = 0.0
+    bread = XtX + np.diag(penalty_diag)
+    try:
+        bread_inv = np.linalg.inv(bread)
+    except np.linalg.LinAlgError:
+        bread_inv = np.linalg.pinv(bread)
+
+    if params_arr.ndim == 2:
+        n_targets = params_arr.shape[1]
+        bse_out = np.empty_like(params_arr)
+        t_out = np.empty_like(params_arr)
+        p_out = np.empty_like(params_arr)
+        ci_out = np.empty((params_arr.shape[0], n_targets, 2), dtype=float)
+        for j in range(n_targets):
+            result = compute_gaussian_inference(
+                X,
+                params_arr[:, j],
+                resid_arr[:, j],
+                scale_arr.reshape(-1)[j],
+                df_resid,
+                cov_type,
+                hac_maxlags=hac_maxlags,
+                ridge_alpha=ridge_alpha,
+                alpha=alpha,
+                ridge_penalize_intercept=ridge_penalize_intercept,
+            )
+            if result is None:
+                return None
+            bse_out[:, j] = result.bse
+            t_out[:, j] = result.tvalues
+            p_out[:, j] = result.pvalues
+            ci_out[:, j, :] = result.conf_int
+        method = "classical" if validate_cov_type(cov_type) == "nonrobust" else "sandwich"
+        distribution = "t" if validate_cov_type(cov_type) == "nonrobust" else "normal"
+        return GaussianInferenceResult(
+            params=params_arr,
+            bse=bse_out,
+            statistic=t_out,
+            pvalues=p_out,
+            conf_int=ci_out,
+            cov_type=cov_type,
+            distribution=distribution,
+            df=df_resid,
+            method=method,
+            metadata={"ridge_alpha": float(ridge_alpha), "alpha": float(alpha)},
+        )
+
+    cov_type = validate_cov_type(cov_type)
+    if cov_type == "nonrobust":
+        if ridge_alpha:
+            cov_params = float(scale_arr) * (bread_inv @ XtX @ bread_inv)
+        else:
+            cov_params = float(scale_arr) * bread_inv
+        bse = np.sqrt(np.diag(cov_params))
+        tvalues = params_arr / (bse + 1e-30)
+        pvalues = 2 * (1 - stats.t.cdf(np.abs(tvalues), df_resid))
+        t_crit = stats.t.ppf(1 - alpha / 2, df_resid)
+        conf_int = np.column_stack([
+            params_arr - t_crit * bse,
+            params_arr + t_crit * bse,
+        ])
+        return GaussianInferenceResult(
+            params=params_arr,
+            bse=bse,
+            statistic=tvalues,
+            pvalues=pvalues,
+            conf_int=conf_int,
+            cov_type=cov_type,
+            distribution="t",
+            df=df_resid,
+            method="classical",
+            metadata={"ridge_alpha": float(ridge_alpha), "alpha": float(alpha)},
+        )
+
+    cov_params = robust_covariance_numpy(
+        X,
+        resid_arr,
+        bread_inv,
+        cov_type,
+        hac_maxlags=hac_maxlags,
+    )
+    bse = np.sqrt(np.maximum(np.diag(cov_params), 0.0))
+    tvalues = params_arr / (bse + 1e-30)
+    pvalues = 2 * (1 - stats.norm.cdf(np.abs(tvalues)))
+    z_crit = stats.norm.ppf(1 - alpha / 2)
+    conf_int = np.column_stack([
+        params_arr - z_crit * bse,
+        params_arr + z_crit * bse,
+    ])
+    return GaussianInferenceResult(
+        params=params_arr,
+        bse=bse,
+        statistic=tvalues,
+        pvalues=pvalues,
+        conf_int=conf_int,
+        cov_type=cov_type,
+        distribution="normal",
+        df=df_resid,
+        method="sandwich",
+        metadata={"ridge_alpha": float(ridge_alpha), "alpha": float(alpha)},
+    )