📈 Murphet — Making Prophet a Beta (Pun Intended!)

A Stan-powered time-series model that never breaks the 0-1 bounds while delivering more accurate forecasts than Prophet for rates and probabilities.

Your conversion rates deserve better than to be treated like stock prices!

🚀 Prophet, but Better for Bounded Data

Prophet is great, but it wasn't built for churn rates, conversion percentages, or hotel occupancy. Murphet was.

When forecasting rates, the last thing you want is predictions that break the logical 0-1 bounds. But that's exactly what happens with vanilla Prophet when forecasting:

• Conversion rates
• Churn probabilities
• Occupancy percentages
• Click-through rates
• Any metric bounded between 0 and 1

Murphet fixes this with a Beta likelihood that respects these natural boundaries while providing more accurate forecasts. It's Prophet's smarter cousin - specifically designed for the data you're actually working with.

1 · Why Choose Murphet?

2 · Installation in Seconds

pip install murphet              # wheels include pre-compiled Stan models

Requirements

• Python >= 3.8 & CmdStanPy >= 1.0 (auto-installed)
• A recent CmdStan toolchain (gcc/clang) — cmdstanpy.install_cmdstan() will fetch it.

3 · Quick Start (Just 10 Lines!)

import pandas as pd, numpy as np
from murphet import fit_churn_model

df = pd.read_csv("churn_data.csv")        # cols: ds, y  (0<y<1)
df["ds"] = pd.to_datetime(df["ds"])
df["t"]  = np.arange(len(df))             # integer index

mod = fit_churn_model(
        t              = df["t"],
        y              = df["y"],
        periods        = 12, num_harmonics = 3,    # yearly seasonality
        n_changepoints = 4,
        likelihood     = "beta",                   # default & safest
        inference      = "nuts",                   # full posterior
      )

future_t = np.arange(len(df), len(df)+6)
fcst     = mod.predict(future_t)

4 · Model Architecture

Murphet combines the best of structural time series modeling with modern Bayesian methods:

Advanced Features

5 · Real-World Performance

Hong Kong Hotel Occupancy Rates (2020-2025)

U.S. Retail Inventories-to-Sales Ratio

Residual Diagnostics

Murphet's AR(1) and heteroscedastic components virtually eliminate autocorrelation structures that Prophet leaves behind.

6 · Choosing the Right Model Head

Simply set likelihood="gaussian" to switch; all other API calls remain identical.

7 · API Reference

Key Parameters

# Seasonality configuration
periods            # Length of seasonal periods (e.g., 12 for monthly data with yearly seasonality)
num_harmonics      # Number of Fourier terms per period (higher = more flexible seasonality)
season_scale       # Prior scale for seasonal components (0.3-2.0 recommended)

# Trend configuration
n_changepoints     # Number of potential trend changes (Prophet default heuristic = 0.2 * N)
delta_scale        # Prior scale for changepoint magnitudes (0.01-0.6 range)
gamma_scale        # Steepness of changepoint transitions (1.0-10.0 range)

# Inference options
likelihood         # "beta" (default) or "gaussian"
inference          # "map" (fastest), "advi" (quick uncertainty), or "nuts" (most accurate)

8 · Coming Soon

• Holiday regressors (Prophet style)
• Automatic plotting functionality
• Performance optimizations for long MCMC chains
• Integration with Prophet ecosystem tools

9 · For Academic Use

If you use Murphet in academic work, please cite:

Murphy, S. (2025). Murphet: A Bayesian Time-Series Model for Bounded Rates.
https://github.com/halsted312/murphet

10 · Get Started Today

Don't let your bounded metrics be forecasted with unbounded models. Murphet brings the power of Bayesian modeling to your rates and proportions with an easy-to-use API that feels just like Prophet.

# It's as simple as:
from murphet import fit_churn_model

model = fit_churn_model(t=time_index, y=bounded_values)
forecast = model.predict(future_time_points)

Check out the documentation →