subset-mixture-model 0.1.2__tar.gz → 0.2.0__tar.gz

subset_mixture_model-0.2.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: subset-mixture-model
+Version: 0.2.0
+Summary: Interpretable empirical-Bayes aggregation of partition estimators for categorical regression
+Author-email: Aaron John Danielson <aaron.danielson@austin.utexas.edu>
+License: MIT
+Project-URL: Repository, https://github.com/aaronjdanielson/subset-mixture-model
+Keywords: interpretable machine learning,categorical features,empirical Bayes,uncertainty quantification,mixture model
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.11
+Provides-Extra: experiments
+Requires-Dist: matplotlib>=3.7; extra == "experiments"
+Requires-Dist: seaborn>=0.12; extra == "experiments"
+Requires-Dist: joblib>=1.3; extra == "experiments"
+Requires-Dist: scikit-learn>=1.3; extra == "experiments"
+Requires-Dist: lightgbm>=4.0; extra == "experiments"
+Requires-Dist: ngboost>=0.4; extra == "experiments"
+Requires-Dist: mapie>=0.6; extra == "experiments"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# Subset Mixture Model (SMM)
+
+[![PyPI version](https://badge.fury.io/py/subset-mixture-model.svg)](https://pypi.org/project/subset-mixture-model/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**SMM** is an interpretable, uncertainty-aware regression method for data with
+categorical features. It learns a global convex mixture over *subset-induced
+partition estimators*—one per non-empty feature subset—and returns a full
+predictive distribution together with a transparent account of *why* each
+prediction has the value and the uncertainty it does.
+
+Version 0.2 upgrades the method to be genuinely probabilistic:
+
+- **Cross-fitted weights** — subset cell means are multiway target encodings, so
+  the mixture weights are learned on out-of-fold statistics to avoid target
+  leakage (small, high-order cells no longer get to memorize the response).
+- **Conjugate Student-t cells** — each cell uses a Normal-Inverse-Gamma
+  posterior, so its predictive component is a Student-t that widens and grows
+  heavy tails in sparse cells (the plug-in Gaussian is the large-sample limit).
+- **Exact mixture inference** — NLL, CDF, central intervals (by bisection) and
+  CRPS are computed exactly from the mixture of Student-t components.
+- **Four-part predictive variance** — within-cell noise, cell-estimation
+  uncertainty, subset-resolution disagreement, and weight uncertainty (Laplace).
+- **Interpretation as diagnostics** — the learned weights are summarized by
+  entropy, effective number of subsets, order-level mass, and concentration,
+  rather than claimed to be a sparse ANOVA decomposition.
+
+---
+
+## Installation
+
+```bash
+pip install subset-mixture-model
+```
+
+Import as `smm`:
+
+```python
+import smm
+```
+
+Requires `torch>=2.0`, `numpy`, `pandas`, `scipy`. `plot_calibration` also needs
+`matplotlib`.
+
+---
+
+## Quickstart
+
+```python
+import numpy as np
+import pandas as pd
+from smm import SMM
+
+# --- synthetic data: a main effect (region) + an interaction (season x tier) ---
+rng = np.random.default_rng(0)
+N = 2000
+region = rng.integers(0, 2, N)
+season = rng.integers(0, 3, N)
+tier   = rng.integers(0, 2, N)
+y = 5.0 * region + 3.0 * (season == 1) * tier + rng.normal(0, 2.0, N)
+df = pd.DataFrame({"region": region, "season": season, "tier": tier, "y": y})
+
+train, val, test = df[:1400], df[1400:1700], df[1700:]
+FEATURES, TARGET = ["region", "season", "tier"], "y"
+
+# --- fit: cross-fitted weights + conjugate Student-t cells + Laplace UQ ---
+model = SMM(FEATURES, TARGET, kappa0=1.0, lam=0.5).fit(train, val)
+
+# --- point prediction and a full predictive distribution ---
+mean = model.predict(test)
+mean, std = model.predict_with_uncertainty(test)
+lo, hi = model.interval(test, level=0.95)          # exact mixture interval
+
+y_test = test[TARGET].values
+print("RMSE :", np.sqrt(np.mean((mean - y_test) ** 2)).round(3))
+print("NLL  :", round(model.nll(test, y_test), 3))
+print("CRPS :", round(model.crps(test, y_test), 3))
+print("cov95:", round(float(((y_test >= lo) & (y_test <= hi)).mean()), 3))
+```
+
+### Why this prediction? Uncertainty decomposition
+
+```python
+mean, std, aleatoric_std, epistemic_std = model.predict_with_uncertainty(
+    test, return_components=True
+)
+# std**2 == aleatoric**2 + epistemic**2  (within-cell noise vs. everything else)
+```
+
+### Which interactions matter? Global diagnostics
+
+```python
+print(model.weight_table(top_k=5))     # subsets ranked by learned weight
+print(model.diagnostics())             # H, N_eff, HHI, order-level mass M_k
+```
+
+`diagnostics()` returns the concentration of the weight distribution. Diffuse
+weights (large `N_eff`) are an honest signal that *no* sparse subset explanation
+dominates—prediction draws on many comparable resolutions—while concentrated
+weights identify a few dominant interactions.
+
+### Why *this* prediction? Local contributions
+
+```python
+row = test.iloc[[0]]
+print(model.explain(row))     # per-subset contributions; they sum to the prediction
+```
+
+---
+
+## What the model gives you
+
+| Method | Returns |
+|---|---|
+| `SMM(features, target, ...)` | estimator; key knobs `kappa0` (shrinkage), `alpha0`,`lam` (order-aware prior), `K` (folds), `mode` (`"nig"`/`"plugin"`), `max_order` |
+| `.fit(df, val_df=None)` | cross-fit → optimize weights (early-stop on `val_df`) → Laplace |
+| `.predict(df)` | predictive mean |
+| `.predict_with_uncertainty(df, return_components=)` | mean, std [, aleatoric, epistemic] |
+| `.nll / .crps` | exact mixture proper scores |
+| `.interval(df, level)` | exact central interval via bisection on the mixture CDF |
+| `.weight_table / .diagnostics / .explain` | interpretability outputs |
+
+Lower-level building blocks are also exported: `SubsetMaker`, `crossfit_components`,
+`SubsetMixturePredictor`, `compute_posterior_covariance`, `predict_with_uncertainty`,
+`NIGPrior`, `weight_table`, `weight_diagnostics`, `calibration_stats`.
+
+To reproduce the first-version plug-in behavior, use
+`SMM(..., mode="plugin", cross_fit=False, kappa0=0)`.
+
+---
+
+## Method summary
+
+For each non-empty feature subset *s*, SMM groups the training data by the values
+of *s* and models each resulting cell with a conjugate Normal-Inverse-Gamma
+posterior, giving a Student-t predictive component. A single global simplex
+weight vector π over all subsets is learned by MAP under an (optionally
+order-aware) Dirichlet prior, using out-of-fold cell statistics. The predictive
+distribution is the mixture ∑ₛ πₛ · tₛ, and uncertainty in π is propagated by a
+Laplace approximation in the low-dimensional logit space.
+
+SMM is intended for problems whose predictive structure is concentrated in a
+modest number of naturally categorical features (full powerset for *D ≤ 8*;
+order-restricted for larger *D*). It is a transparent, uncertainty-aware
+alternative to gradient-boosted trees in that regime, not a general replacement.
+
+---
+
+## Citation
+
+```bibtex
+@article{danielson2026smm,
+  title   = {Subset Mixture Models: Interpretable Probabilistic Aggregation
+             of Partition Estimators for Categorical Regression},
+  author  = {Danielson, Aaron John},
+  journal = {Under review},
+  year    = {2026},
+}
+```
+
+## License
+
+MIT © Aaron John Danielson

subset_mixture_model-0.2.0/README.md

@@ -0,0 +1,163 @@
+# Subset Mixture Model (SMM)
+
+[![PyPI version](https://badge.fury.io/py/subset-mixture-model.svg)](https://pypi.org/project/subset-mixture-model/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**SMM** is an interpretable, uncertainty-aware regression method for data with
+categorical features. It learns a global convex mixture over *subset-induced
+partition estimators*—one per non-empty feature subset—and returns a full
+predictive distribution together with a transparent account of *why* each
+prediction has the value and the uncertainty it does.
+
+Version 0.2 upgrades the method to be genuinely probabilistic:
+
+- **Cross-fitted weights** — subset cell means are multiway target encodings, so
+  the mixture weights are learned on out-of-fold statistics to avoid target
+  leakage (small, high-order cells no longer get to memorize the response).
+- **Conjugate Student-t cells** — each cell uses a Normal-Inverse-Gamma
+  posterior, so its predictive component is a Student-t that widens and grows
+  heavy tails in sparse cells (the plug-in Gaussian is the large-sample limit).
+- **Exact mixture inference** — NLL, CDF, central intervals (by bisection) and
+  CRPS are computed exactly from the mixture of Student-t components.
+- **Four-part predictive variance** — within-cell noise, cell-estimation
+  uncertainty, subset-resolution disagreement, and weight uncertainty (Laplace).
+- **Interpretation as diagnostics** — the learned weights are summarized by
+  entropy, effective number of subsets, order-level mass, and concentration,
+  rather than claimed to be a sparse ANOVA decomposition.
+
+---
+
+## Installation
+
+```bash
+pip install subset-mixture-model
+```
+
+Import as `smm`:
+
+```python
+import smm
+```
+
+Requires `torch>=2.0`, `numpy`, `pandas`, `scipy`. `plot_calibration` also needs
+`matplotlib`.
+
+---
+
+## Quickstart
+
+```python
+import numpy as np
+import pandas as pd
+from smm import SMM
+
+# --- synthetic data: a main effect (region) + an interaction (season x tier) ---
+rng = np.random.default_rng(0)
+N = 2000
+region = rng.integers(0, 2, N)
+season = rng.integers(0, 3, N)
+tier   = rng.integers(0, 2, N)
+y = 5.0 * region + 3.0 * (season == 1) * tier + rng.normal(0, 2.0, N)
+df = pd.DataFrame({"region": region, "season": season, "tier": tier, "y": y})
+
+train, val, test = df[:1400], df[1400:1700], df[1700:]
+FEATURES, TARGET = ["region", "season", "tier"], "y"
+
+# --- fit: cross-fitted weights + conjugate Student-t cells + Laplace UQ ---
+model = SMM(FEATURES, TARGET, kappa0=1.0, lam=0.5).fit(train, val)
+
+# --- point prediction and a full predictive distribution ---
+mean = model.predict(test)
+mean, std = model.predict_with_uncertainty(test)
+lo, hi = model.interval(test, level=0.95)          # exact mixture interval
+
+y_test = test[TARGET].values
+print("RMSE :", np.sqrt(np.mean((mean - y_test) ** 2)).round(3))
+print("NLL  :", round(model.nll(test, y_test), 3))
+print("CRPS :", round(model.crps(test, y_test), 3))
+print("cov95:", round(float(((y_test >= lo) & (y_test <= hi)).mean()), 3))
+```
+
+### Why this prediction? Uncertainty decomposition
+
+```python
+mean, std, aleatoric_std, epistemic_std = model.predict_with_uncertainty(
+    test, return_components=True
+)
+# std**2 == aleatoric**2 + epistemic**2  (within-cell noise vs. everything else)
+```
+
+### Which interactions matter? Global diagnostics
+
+```python
+print(model.weight_table(top_k=5))     # subsets ranked by learned weight
+print(model.diagnostics())             # H, N_eff, HHI, order-level mass M_k
+```
+
+`diagnostics()` returns the concentration of the weight distribution. Diffuse
+weights (large `N_eff`) are an honest signal that *no* sparse subset explanation
+dominates—prediction draws on many comparable resolutions—while concentrated
+weights identify a few dominant interactions.
+
+### Why *this* prediction? Local contributions
+
+```python
+row = test.iloc[[0]]
+print(model.explain(row))     # per-subset contributions; they sum to the prediction
+```
+
+---
+
+## What the model gives you
+
+| Method | Returns |
+|---|---|
+| `SMM(features, target, ...)` | estimator; key knobs `kappa0` (shrinkage), `alpha0`,`lam` (order-aware prior), `K` (folds), `mode` (`"nig"`/`"plugin"`), `max_order` |
+| `.fit(df, val_df=None)` | cross-fit → optimize weights (early-stop on `val_df`) → Laplace |
+| `.predict(df)` | predictive mean |
+| `.predict_with_uncertainty(df, return_components=)` | mean, std [, aleatoric, epistemic] |
+| `.nll / .crps` | exact mixture proper scores |
+| `.interval(df, level)` | exact central interval via bisection on the mixture CDF |
+| `.weight_table / .diagnostics / .explain` | interpretability outputs |
+
+Lower-level building blocks are also exported: `SubsetMaker`, `crossfit_components`,
+`SubsetMixturePredictor`, `compute_posterior_covariance`, `predict_with_uncertainty`,
+`NIGPrior`, `weight_table`, `weight_diagnostics`, `calibration_stats`.
+
+To reproduce the first-version plug-in behavior, use
+`SMM(..., mode="plugin", cross_fit=False, kappa0=0)`.
+
+---
+
+## Method summary
+
+For each non-empty feature subset *s*, SMM groups the training data by the values
+of *s* and models each resulting cell with a conjugate Normal-Inverse-Gamma
+posterior, giving a Student-t predictive component. A single global simplex
+weight vector π over all subsets is learned by MAP under an (optionally
+order-aware) Dirichlet prior, using out-of-fold cell statistics. The predictive
+distribution is the mixture ∑ₛ πₛ · tₛ, and uncertainty in π is propagated by a
+Laplace approximation in the low-dimensional logit space.
+
+SMM is intended for problems whose predictive structure is concentrated in a
+modest number of naturally categorical features (full powerset for *D ≤ 8*;
+order-restricted for larger *D*). It is a transparent, uncertainty-aware
+alternative to gradient-boosted trees in that regime, not a general replacement.
+
+---
+
+## Citation
+
+```bibtex
+@article{danielson2026smm,
+  title   = {Subset Mixture Models: Interpretable Probabilistic Aggregation
+             of Partition Estimators for Categorical Regression},
+  author  = {Danielson, Aaron John},
+  journal = {Under review},
+  year    = {2026},
+}
+```
+
+## License
+
+MIT © Aaron John Danielson

{subset_mixture_model-0.1.2 → subset_mixture_model-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "subset-mixture-model"
-version = "0.1.2"
+version = "0.2.0"
 description = "Interpretable empirical-Bayes aggregation of partition estimators for categorical regression"
 readme = "README.md"
 license = { text = "MIT" }
@@ -33,7 +33,6 @@ dependencies = [
   "torch>=2.0",
   "numpy>=1.24",
   "pandas>=2.0",
-  "scikit-learn>=1.3",
   "scipy>=1.11",
 ]
 
@@ -42,6 +41,7 @@ experiments = [
   "matplotlib>=3.7",
   "seaborn>=0.12",
   "joblib>=1.3",
+  "scikit-learn>=1.3",
   "lightgbm>=4.0",
   "ngboost>=0.4",
   "mapie>=0.6",

{subset_mixture_model-0.1.2 → subset_mixture_model-0.2.0}/smm/__init__.py

@@ -1,5 +1,17 @@
+"""Subset Mixture Model (SMM): interpretable probabilistic aggregation of
+subset-induced partition estimators for categorical regression."""
+
+from .cells import NIGPrior
 from .subset_maker import SubsetMaker
-from .model import SubsetWeightsModel, SubsetDataset, subset_mixture_neg_log_posterior, subset_mixture_mse
+from .model import (
+    SubsetWeightsModel,
+    SubsetDataset,
+    ComponentDataset,
+    order_aware_alpha,
+    subset_mixture_neg_log_posterior,
+    subset_mixture_mse,
+)
+from .crossfit import crossfit_components
 from .predictor import SubsetMixturePredictor
 from .laplace import (
     compute_posterior_covariance,
@@ -8,18 +20,27 @@ from .laplace import (
 )
 from .diagnostics import (
     weight_table,
+    weight_diagnostics,
     explain_prediction,
     calibration_stats,
     plot_calibration,
 )
+from .smm import SMM
 
 __all__ = [
+    # High-level estimator
+    "SMM",
+    # Cells / prior
+    "NIGPrior",
     # Core
     "SubsetMaker",
     "SubsetWeightsModel",
     "SubsetDataset",
+    "ComponentDataset",
+    "order_aware_alpha",
     "subset_mixture_neg_log_posterior",
     "subset_mixture_mse",
+    "crossfit_components",
     "SubsetMixturePredictor",
     # Uncertainty
     "compute_posterior_covariance",
@@ -27,6 +48,7 @@ __all__ = [
     "coverage",
     # Diagnostics
     "weight_table",
+    "weight_diagnostics",
     "explain_prediction",
     "calibration_stats",
     "plot_calibration",

subset_mixture_model-0.2.0/smm/cells.py

@@ -0,0 +1,183 @@
+"""
+Conjugate Normal-Inverse-Gamma (NIG) cell model and Student-t component math.
+
+This module implements the principled cell model of the Subset Mixture Model
+(SMM). Each subset cell is modeled as Gaussian data with a Normal-Inverse-Gamma
+prior on (mu, sigma^2); the posterior predictive of a new response in the cell
+is Student-t (Theorem "Student-t posterior predictive" in the paper):
+
+    (mu, sigma^2) ~ NIG(m0, kappa0, a0, b0)
+    posterior     NIG(m_n, kappa_n, a_n, b_n) given (n, ybar, S)
+    predictive    t_{2 a_n}( m_n,  b_n (kappa_n + 1) / (a_n kappa_n) )
+
+with sufficient statistics
+    n    = cell size,
+    ybar = cell mean,
+    S    = sum of squared deviations = sum_i (y_i - ybar)^2.
+
+The plug-in Gaussian component of the first version of the method is recovered
+as the limit kappa0 -> 0, a0, b0 -> 0 (see `plugin_limit`), which this module
+supports so the plug-in path remains reachable as an ablation.
+
+Empirical-Bayes hyperparameters (default): match the prior to the global
+marginal moments of the target,
+    m0 = global mean,
+    a0 = 2                      (weakly informative; finite prior variance),
+    b0 = (a0 - 1) * global_var  = global_var   (so E[sigma^2] = global_var),
+    kappa0 = shrinkage strength (the one substantive hyperparameter).
+"""
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+import torch
+
+
+# --------------------------------------------------------------------------- #
+#  Hyperparameters
+# --------------------------------------------------------------------------- #
+@dataclass
+class NIGPrior:
+    """Normal-Inverse-Gamma prior hyperparameters (m0, kappa0, a0, b0)."""
+
+    m0: float
+    kappa0: float
+    a0: float
+    b0: float
+
+    @classmethod
+    def empirical_bayes(cls, y, kappa0: float = 1.0, a0: float = 2.0):
+        """
+        Build an empirical-Bayes prior by moment-matching the global marginal.
+
+        E[sigma^2] = b0 / (a0 - 1) = Var(y)  ->  b0 = (a0 - 1) * Var(y).
+        The prior mean m0 is the global mean of y. `kappa0` (the prior
+        pseudo-count / shrinkage strength) is the one substantive knob.
+        """
+        y = np.asarray(y, dtype=float)
+        y = y[~np.isnan(y)]
+        global_mean = float(y.mean())
+        global_var = float(y.var(ddof=0))
+        if not np.isfinite(global_var) or global_var <= 0:
+            global_var = 1.0
+        if a0 <= 1.0:
+            raise ValueError("a0 must be > 1 for a finite prior variance.")
+        b0 = (a0 - 1.0) * global_var
+        return cls(m0=global_mean, kappa0=float(kappa0), a0=float(a0), b0=b0)
+
+
+# --------------------------------------------------------------------------- #
+#  Conjugate update  (n, ybar, S)  ->  posterior  ->  Student-t predictive
+# --------------------------------------------------------------------------- #
+def nig_posterior(n, ybar, S, prior: NIGPrior):
+    """
+    Conjugate NIG update. Accepts scalars or numpy arrays (vectorized over cells).
+
+    Returns (m_n, kappa_n, a_n, b_n) with the paper's formulas:
+        kappa_n = kappa0 + n
+        m_n     = (kappa0 m0 + n ybar) / (kappa0 + n)
+        a_n     = a0 + n / 2
+        b_n     = b0 + S/2 + (kappa0 n) / (2 (kappa0 + n)) (ybar - m0)^2
+    """
+    n = np.asarray(n, dtype=float)
+    ybar = np.asarray(ybar, dtype=float)
+    S = np.asarray(S, dtype=float)
+
+    kappa_n = prior.kappa0 + n
+    m_n = (prior.kappa0 * prior.m0 + n * ybar) / kappa_n
+    a_n = prior.a0 + n / 2.0
+    denom = np.where(kappa_n > 0, 2.0 * kappa_n, 1.0)
+    b_n = (
+        prior.b0
+        + 0.5 * S
+        + (prior.kappa0 * n) / denom * (ybar - prior.m0) ** 2
+    )
+    return m_n, kappa_n, a_n, b_n
+
+
+def student_t_params(n, ybar, S, prior: NIGPrior):
+    """
+    Posterior-predictive Student-t parameters for each cell.
+
+    Returns a dict of numpy arrays:
+        loc   = m_n                                  (location)
+        scale2 = b_n (kappa_n + 1) / (a_n kappa_n)    (squared scale, tau^2)
+        df    = 2 a_n                                (degrees of freedom, nu)
+    plus the two moment pieces used by the four-part variance decomposition:
+        e_sigma2 = b_n / (a_n - 1)                   E[sigma^2 | D]  (within-cell)
+        var_mu   = b_n / (kappa_n (a_n - 1))         Var(mu | D)     (cell-estimation)
+    """
+    m_n, kappa_n, a_n, b_n = nig_posterior(n, ybar, S, prior)
+    scale2 = b_n * (kappa_n + 1.0) / (a_n * kappa_n)
+    df = 2.0 * a_n
+    e_sigma2 = b_n / (a_n - 1.0)
+    var_mu = b_n / (kappa_n * (a_n - 1.0))
+    return {
+        "loc": m_n,
+        "scale2": scale2,
+        "df": df,
+        "e_sigma2": e_sigma2,
+        "var_mu": var_mu,
+    }
+
+
+def plugin_params(ybar, var, eps: float = 1e-9):
+    """
+    Plug-in Gaussian component parameters (the first-version ablation).
+
+    A Gaussian is a Student-t with df = inf; we return a large finite df so the
+    same Student-t code path evaluates it. loc = ybar, scale2 = var.
+    """
+    ybar = np.asarray(ybar, dtype=float)
+    var = np.asarray(var, dtype=float)
+    scale2 = np.maximum(var, eps)
+    return {
+        "loc": ybar,
+        "scale2": scale2,
+        "df": np.full_like(ybar, 1e8),
+        "e_sigma2": scale2,
+        "var_mu": np.zeros_like(ybar),  # plug-in omits cell-estimation error
+    }
+
+
+# --------------------------------------------------------------------------- #
+#  Student-t density / cdf  (torch for training, numpy for inference)
+# --------------------------------------------------------------------------- #
+def student_t_logpdf(y, loc, scale2, df):
+    """
+    Log density of a location-scale Student-t, elementwise (torch).
+
+    log t_nu(y | loc, s^2) =
+        lgamma((nu+1)/2) - lgamma(nu/2) - 0.5 log(nu pi s^2)
+        - (nu+1)/2 * log(1 + (y-loc)^2 / (nu s^2)).
+    """
+    z2 = (y - loc) ** 2 / scale2
+    half_df = 0.5 * df
+    return (
+        torch.lgamma(half_df + 0.5)
+        - torch.lgamma(half_df)
+        - 0.5 * torch.log(df * math.pi * scale2)
+        - (half_df + 0.5) * torch.log1p(z2 / df)
+    )
+
+
+def student_t_logpdf_np(y, loc, scale2, df):
+    """Numpy version of `student_t_logpdf` (for inference / scoring)."""
+    from scipy.special import gammaln
+
+    z2 = (y - loc) ** 2 / scale2
+    half_df = 0.5 * df
+    return (
+        gammaln(half_df + 0.5)
+        - gammaln(half_df)
+        - 0.5 * np.log(df * np.pi * scale2)
+        - (half_df + 0.5) * np.log1p(z2 / df)
+    )
+
+
+def student_t_cdf_np(y, loc, scale2, df):
+    """CDF of a location-scale Student-t (numpy, via scipy)."""
+    from scipy.stats import t as _t
+
+    return _t.cdf((y - loc) / np.sqrt(scale2), df=df)