prophet-laplace 0.0.1__tar.gz

prophet_laplace-0.0.1/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 Peter Cotton

prophet_laplace-0.0.1/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: prophet-laplace
+Version: 0.0.1
+Summary: Prophet in a laplace sandwich: same API, calibrated densities
+Author: Peter Cotton
+License: MIT
+Project-URL: Homepage, https://github.com/microprediction/prophet-laplace
+Project-URL: Repository, https://github.com/microprediction/prophet-laplace
+Project-URL: Sandwich explainer, https://skaters.microprediction.org/sandwich.html
+Keywords: prophet,forecasting,calibration,time-series,skaters,laplace
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: prophet>=1.1
+Requires-Dist: skaters>=0.13.0
+Requires-Dist: pandas
+Dynamic: license-file
+
+# prophet-laplace
+
+*"He's not the messiah. He's a very naughty boy."* ([why](https://medium.com/geekculture/is-facebooks-prophet-the-time-series-messiah-or-just-a-very-naughty-boy-8b71b136bc8c)) *This package makes him useful anyway.*
+
+Prophet in a laplace sandwich: same API, calibrated densities.
+
+```python
+from prophet_laplace import SandwichedProphet
+
+m = SandwichedProphet(k=30)          # accepts Prophet's kwargs too
+m.fit(df)                            # ds, y (+ regressors as usual)
+fc = m.predict(future)               # yhat / yhat_lower / yhat_upper,
+                                     # mapped back exactly
+```
+
+## What it does
+
+`SandwichedProphet` fits Prophet in the z-coordinates of a
+[skaters](https://github.com/microprediction/skaters) laplace forecaster
+(the Rosenblatt transform of each observation under the predictive issued
+for it) and maps every forecast back through the exact inverse. Prophet
+keeps its calendar decomposition, holidays, and extra regressors; the
+sandwich supplies the volatility clock, repeated-value handling, and
+tails whose stated probabilities come true.
+
+## Why
+
+Measured on 921 non-price FRED series under a pre-registered protocol
+(statements, frozen universe, and results in the skaters repository):
+
+|            | median one-step LL vs laplace | family-weighted (120 families) |
+|------------|------------------------------|-------------------------------|
+| Prophet raw | -0.755 nats | -4.60 nats |
+| Prophet sandwiched | **-0.020 nats** | **-0.025 nats** |
+
+The sandwich closes 97% of Prophet's density gap without retraining
+anything. `predictive(step, z_mu, z_sigma)` exposes the full y-space
+density (logpdf, cdf, quantile) for scoring and risk use.
+
+The same construction lifts other forecasters and detectors too:
+[skaters.microprediction.org/sandwich.html](https://skaters.microprediction.org/sandwich.html).
+
+## Status
+
+v0: future frames only, horizons past `k` reuse the k-step transport
+(disclosed approximation). The goal is to demonstrate interoperability,
+then propose the option upstream.

prophet_laplace-0.0.1/README.md

@@ -0,0 +1,47 @@
+# prophet-laplace
+
+*"He's not the messiah. He's a very naughty boy."* ([why](https://medium.com/geekculture/is-facebooks-prophet-the-time-series-messiah-or-just-a-very-naughty-boy-8b71b136bc8c)) *This package makes him useful anyway.*
+
+Prophet in a laplace sandwich: same API, calibrated densities.
+
+```python
+from prophet_laplace import SandwichedProphet
+
+m = SandwichedProphet(k=30)          # accepts Prophet's kwargs too
+m.fit(df)                            # ds, y (+ regressors as usual)
+fc = m.predict(future)               # yhat / yhat_lower / yhat_upper,
+                                     # mapped back exactly
+```
+
+## What it does
+
+`SandwichedProphet` fits Prophet in the z-coordinates of a
+[skaters](https://github.com/microprediction/skaters) laplace forecaster
+(the Rosenblatt transform of each observation under the predictive issued
+for it) and maps every forecast back through the exact inverse. Prophet
+keeps its calendar decomposition, holidays, and extra regressors; the
+sandwich supplies the volatility clock, repeated-value handling, and
+tails whose stated probabilities come true.
+
+## Why
+
+Measured on 921 non-price FRED series under a pre-registered protocol
+(statements, frozen universe, and results in the skaters repository):
+
+|            | median one-step LL vs laplace | family-weighted (120 families) |
+|------------|------------------------------|-------------------------------|
+| Prophet raw | -0.755 nats | -4.60 nats |
+| Prophet sandwiched | **-0.020 nats** | **-0.025 nats** |
+
+The sandwich closes 97% of Prophet's density gap without retraining
+anything. `predictive(step, z_mu, z_sigma)` exposes the full y-space
+density (logpdf, cdf, quantile) for scoring and risk use.
+
+The same construction lifts other forecasters and detectors too:
+[skaters.microprediction.org/sandwich.html](https://skaters.microprediction.org/sandwich.html).
+
+## Status
+
+v0: future frames only, horizons past `k` reuse the k-step transport
+(disclosed approximation). The goal is to demonstrate interoperability,
+then propose the option upstream.

prophet_laplace-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "prophet-laplace"
+version = "0.0.1"
+description = "Prophet in a laplace sandwich: same API, calibrated densities"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [{name = "Peter Cotton"}]
+keywords = ["prophet", "forecasting", "calibration", "time-series", "skaters", "laplace"]
+dependencies = ["prophet>=1.1", "skaters>=0.13.0", "pandas"]
+
+[project.urls]
+Homepage = "https://github.com/microprediction/prophet-laplace"
+Repository = "https://github.com/microprediction/prophet-laplace"
+"Sandwich explainer" = "https://skaters.microprediction.org/sandwich.html"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

prophet_laplace-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

prophet_laplace-0.0.1/src/prophet_laplace/__init__.py

@@ -0,0 +1,18 @@
+"""prophet-laplace: Prophet in a laplace sandwich.
+
+Same Prophet API, calibrated densities. A SandwichedProphet fits Prophet
+in the z-coordinates of a laplace forecaster (the Rosenblatt transform of
+each observation under the predictive issued for it) and maps every
+forecast back through the exact inverse. Prophet keeps its calendar
+machinery, holidays, and extra regressors; the sandwich supplies the
+volatility clock, the lattice handling, and tails that keep their stated
+rates.
+
+Measured on 921 non-price FRED series (pre-registered, see the skaters
+repository): raw Prophet trails laplace by 0.76 nats median one-step
+log-likelihood (family-weighted 4.6); sandwiched, the gap is 0.02.
+"""
+from prophet_laplace.sandwich import SandwichedProphet
+
+__all__ = ["SandwichedProphet"]
+__version__ = "0.0.1"

prophet_laplace-0.0.1/src/prophet_laplace/sandwich.py

@@ -0,0 +1,116 @@
+"""The sandwich: laplace transform in front, Prophet inside, exact inverse behind."""
+from __future__ import annotations
+
+import math
+
+import pandas as pd
+
+from skaters import laplace
+from skaters.tails import _phi_inv
+
+_EPS = 1e-12
+_SQRT2 = math.sqrt(2.0)
+
+
+def _phi(z: float) -> float:
+    return 0.5 * math.erfc(-z / _SQRT2)
+
+
+class _Predictive:
+    """A y-space predictive assembled from Prophet's z-space Gaussian and
+    laplace's h-step transport, with exact change-of-variables accounting."""
+
+    def __init__(self, transport, z_mu: float, z_sigma: float):
+        self._t = transport
+        self._mu = z_mu
+        self._sd = max(z_sigma, 1e-9)
+
+    def quantile(self, p: float) -> float:
+        z = self._mu + self._sd * _phi_inv(min(max(p, _EPS), 1.0 - _EPS))
+        u = min(max(_phi(z), _EPS), 1.0 - _EPS)
+        return self._t.quantile(u)
+
+    def logpdf(self, y: float) -> float:
+        u = min(max(self._t.cdf(y), _EPS), 1.0 - _EPS)
+        z = _phi_inv(u)
+        r = (z - self._mu) / self._sd
+        log_fz = -0.5 * r * r - math.log(self._sd) - 0.5 * math.log(2 * math.pi)
+        log_phi = -0.5 * z * z - 0.5 * math.log(2 * math.pi)
+        return log_fz + self._t.logpdf(y) - log_phi
+
+    def cdf(self, y: float) -> float:
+        u = min(max(self._t.cdf(y), _EPS), 1.0 - _EPS)
+        z = _phi_inv(u)
+        return _phi((z - self._mu) / self._sd)
+
+
+class SandwichedProphet:
+    """Drop-in Prophet with laplace-sandwiched coordinates.
+
+    Prophet keeps its API, calendar machinery, holidays, and extra
+    regressors; it just operates in the z-coordinates of a laplace
+    forecaster (the Rosenblatt transform of each observation under the
+    predictive issued for it), and every forecast maps back through the
+    exact inverse.
+
+    ``k`` is the forecast horizon in observations; ``predict`` supports
+    future frames up to k steps past the training data (rows beyond k
+    reuse the k-step transport, a disclosed approximation).
+    """
+
+    def __init__(self, k: int = 1, **prophet_kwargs):
+        from prophet import Prophet
+        self.k = int(k)
+        prophet_kwargs.setdefault("interval_width", 0.6827)
+        self._m = Prophet(**prophet_kwargs)
+        self._interval_z = 1.0          # 0.6827 central interval = +-1 sd
+        self._fitted = False
+        self._pending = None            # k-step transport past training end
+
+    def add_regressor(self, name: str, **kw) -> "SandwichedProphet":
+        self._m.add_regressor(name, **kw)
+        return self
+
+    def fit(self, df: pd.DataFrame, **fit_kwargs) -> "SandwichedProphet":
+        f = laplace(self.k)
+        state = None
+        pend = None                     # dists issued for the arriving y
+        zs = []
+        for y in df["y"].astype(float).tolist():
+            if pend is None:
+                zs.append(0.0)
+            else:
+                u = min(max(pend[0].cdf(y), _EPS), 1.0 - _EPS)
+                zs.append(_phi_inv(u))
+            pend, state = f(y, state)
+        self._pending = pend            # transport for steps 1..k ahead
+        zdf = df.copy()
+        zdf["y"] = zs
+        self._m.fit(zdf, **fit_kwargs)
+        self._last_ds = pd.to_datetime(df["ds"]).max()
+        self._fitted = True
+        return self
+
+    def _transport(self, step: int):
+        return self._pending[min(step, self.k) - 1]
+
+    def predictive(self, step: int, z_mu: float, z_sigma: float) -> _Predictive:
+        return _Predictive(self._transport(step), z_mu, z_sigma)
+
+    def predict(self, future: pd.DataFrame) -> pd.DataFrame:
+        assert self._fitted, "call fit first"
+        ds = pd.to_datetime(future["ds"])
+        assert (ds > self._last_ds).all(), (
+            "sandwich v0 maps future rows only; pass a frame strictly "
+            "after the training data")
+        fc = self._m.predict(future)
+        sds = ((fc["yhat_upper"] - fc["yhat_lower"]) / 2.0
+               / self._interval_z).clip(lower=1e-9)
+        out = fc.copy()
+        for i in range(len(fc)):
+            pred = self.predictive(i + 1, float(fc["yhat"].iloc[i]),
+                                   float(sds.iloc[i]))
+            out.loc[out.index[i], "yhat"] = pred.quantile(0.5)
+            out.loc[out.index[i], "yhat_lower"] = pred.quantile(0.5 - 0.6827 / 2)
+            out.loc[out.index[i], "yhat_upper"] = pred.quantile(0.5 + 0.6827 / 2)
+        return out

prophet_laplace-0.0.1/src/prophet_laplace.egg-info/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: prophet-laplace
+Version: 0.0.1
+Summary: Prophet in a laplace sandwich: same API, calibrated densities
+Author: Peter Cotton
+License: MIT
+Project-URL: Homepage, https://github.com/microprediction/prophet-laplace
+Project-URL: Repository, https://github.com/microprediction/prophet-laplace
+Project-URL: Sandwich explainer, https://skaters.microprediction.org/sandwich.html
+Keywords: prophet,forecasting,calibration,time-series,skaters,laplace
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: prophet>=1.1
+Requires-Dist: skaters>=0.13.0
+Requires-Dist: pandas
+Dynamic: license-file
+
+# prophet-laplace
+
+*"He's not the messiah. He's a very naughty boy."* ([why](https://medium.com/geekculture/is-facebooks-prophet-the-time-series-messiah-or-just-a-very-naughty-boy-8b71b136bc8c)) *This package makes him useful anyway.*
+
+Prophet in a laplace sandwich: same API, calibrated densities.
+
+```python
+from prophet_laplace import SandwichedProphet
+
+m = SandwichedProphet(k=30)          # accepts Prophet's kwargs too
+m.fit(df)                            # ds, y (+ regressors as usual)
+fc = m.predict(future)               # yhat / yhat_lower / yhat_upper,
+                                     # mapped back exactly
+```
+
+## What it does
+
+`SandwichedProphet` fits Prophet in the z-coordinates of a
+[skaters](https://github.com/microprediction/skaters) laplace forecaster
+(the Rosenblatt transform of each observation under the predictive issued
+for it) and maps every forecast back through the exact inverse. Prophet
+keeps its calendar decomposition, holidays, and extra regressors; the
+sandwich supplies the volatility clock, repeated-value handling, and
+tails whose stated probabilities come true.
+
+## Why
+
+Measured on 921 non-price FRED series under a pre-registered protocol
+(statements, frozen universe, and results in the skaters repository):
+
+|            | median one-step LL vs laplace | family-weighted (120 families) |
+|------------|------------------------------|-------------------------------|
+| Prophet raw | -0.755 nats | -4.60 nats |
+| Prophet sandwiched | **-0.020 nats** | **-0.025 nats** |
+
+The sandwich closes 97% of Prophet's density gap without retraining
+anything. `predictive(step, z_mu, z_sigma)` exposes the full y-space
+density (logpdf, cdf, quantile) for scoring and risk use.
+
+The same construction lifts other forecasters and detectors too:
+[skaters.microprediction.org/sandwich.html](https://skaters.microprediction.org/sandwich.html).
+
+## Status
+
+v0: future frames only, horizons past `k` reuse the k-step transport
+(disclosed approximation). The goal is to demonstrate interoperability,
+then propose the option upstream.

prophet_laplace-0.0.1/src/prophet_laplace.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/prophet_laplace/__init__.py
+src/prophet_laplace/sandwich.py
+src/prophet_laplace.egg-info/PKG-INFO
+src/prophet_laplace.egg-info/SOURCES.txt
+src/prophet_laplace.egg-info/dependency_links.txt
+src/prophet_laplace.egg-info/requires.txt
+src/prophet_laplace.egg-info/top_level.txt
+tests/test_sandwich.py

prophet_laplace-0.0.1/src/prophet_laplace.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

prophet_laplace-0.0.1/src/prophet_laplace.egg-info/requires.txt

@@ -0,0 +1,3 @@
+prophet>=1.1
+skaters>=0.13.0
+pandas

prophet_laplace-0.0.1/src/prophet_laplace.egg-info/top_level.txt

@@ -0,0 +1 @@
+prophet_laplace

prophet_laplace-0.0.1/tests/test_sandwich.py

@@ -0,0 +1,50 @@
+import math
+import random
+
+import pandas as pd
+import pytest
+
+from prophet_laplace import SandwichedProphet
+
+
+def _df(n=400, seed=3):
+    rng = random.Random(seed)
+    ds = pd.date_range("2020-01-01", periods=n, freq="D")
+    lvl, ys = 0.0, []
+    for t in range(n):
+        vol = 2.0 if (t // 60) % 2 else 0.5
+        lvl += rng.gauss(0, vol)
+        ys.append(lvl + 3.0 * math.sin(2 * math.pi * t / 7))
+    return pd.DataFrame({"ds": ds, "y": ys})
+
+
+def test_fit_predict_roundtrip():
+    df = _df()
+    m = SandwichedProphet(k=5).fit(df)
+    future = pd.DataFrame(
+        {"ds": pd.date_range(df["ds"].max() + pd.Timedelta(days=1),
+                             periods=5, freq="D")})
+    fc = m.predict(future)
+    assert len(fc) == 5
+    assert (fc["yhat_lower"] <= fc["yhat"]).all()
+    assert (fc["yhat"] <= fc["yhat_upper"]).all()
+    assert fc["yhat"].abs().max() < 1e6
+
+
+def test_predictive_density_is_wellformed():
+    df = _df()
+    m = SandwichedProphet(k=1).fit(df)
+    pred = m.predictive(1, 0.0, 1.0)
+    qs = [pred.quantile(p) for p in (0.01, 0.25, 0.5, 0.75, 0.99)]
+    assert all(b >= a for a, b in zip(qs, qs[1:]))
+    y0 = qs[2]
+    assert math.isfinite(pred.logpdf(y0))
+    assert 0.0 <= pred.cdf(y0) <= 1.0
+    assert abs(pred.cdf(qs[1]) - 0.25) < 0.05
+
+
+def test_past_frames_rejected():
+    df = _df()
+    m = SandwichedProphet(k=1).fit(df)
+    with pytest.raises(AssertionError):
+        m.predict(df[["ds"]].tail(3))