API Reference

This section documents the public API of the Tipping Point module.

Single-Channel Model Interface

class tippingpoint.models.MarketingReturnCurve(beta, alpha, half_saturation_k, theta=0.0, channel_name='Generic', posterior_samples=None, baseline=0.0, adstock_type='geometric', adstock_params=None)

Bases: object

A marketing intelligence tool to determine inflection points of a media response curve.

Based on the Hill Function (Google Meridian methodology), this tool identifies the Minimal Marginal Cost Point (peak efficiency) and the Point of Diminishing Returns (profitability floor).

adstock_spend(spend_timeline)

Applies the model’s fitted adstock decay (geometric or Weibull) to a timeline of spends.

calculate_tipping_points()

Pre-computes and caches key strategic inflection points.

evaluate_current_budget(current_spend, target_mroas=1.0)

classmethod fit_bayesian(spend_array, return_array, channel_name='Generic', priors=None, n_samples=2000, chains=4, burn_in=1000, adstock_type='none', adstock_bounds=None, adstock_fixed_days=None, calibration_experiments=None, fit_baseline=False)

classmethod from_historical_data(spend_array, return_array, channel_name='Generic', epochs=5000, lr=0.05, adstock_type='none', adstock_bounds=None, adstock_fixed_days=None, fit_baseline=False)

get_diminishing_returns_point(target_mroas=1.0, tol=1e-05, max_iter=100, warn_unreachable=True)

get_minimal_marginal_cost_point()

get_optimal_scaling_window(target_mroas=1.0)

Returns the tuple (min_spend, max_spend) defining the optimal scaling zone.

launch_dashboard()

Launches the interactive dashboard for this specific model instance.

property max_efficiency_point

property max_profit_point

plot_response_curve(target_mroas=1.0, current_spend=None, show_intervals=True, scatter=None, show=True)

predict_incremental_return(spend, use_samples=False, include_baseline=False)

predict_marginal_return(spend, use_samples=False)

summary()

update_loss(loss_val)

Hierarchical Multi-Channel MMM

class tippingpoint.mmm.MultiChannelMMM(channels, baseline=0.0, loss=0.0, posterior_samples=None)

Bases: object

Meridian-Lite Hierarchical Bayesian Marketing Mix Model.

Jointly estimates:

Y_t = Baseline + sum_{m=1}^M Hill_m(Adstock_m(S_{m, 1:t})) + eps_t

Key Capabilities:

• Hierarchical Bayesian Partial Pooling across channels & geos.

• Joint simultaneous estimation of Carryover Adstock (theta), Hill Saturation (alpha, K), and Channel Return Coefficients (beta).

• Prevents cross-channel double-counting and omitted variable bias.

• Experimental calibration (lift studies, geo experiments) integration.

• Historical contribution decomposition, Share of Return, ROI with 90% credible intervals.

• Direct integration with PortfolioAllocator for global budget optimization.

decompose_historical_contributions(spend_data, return_array=None)

Computes comprehensive historical attribution, share of spend vs return, and channel ROI.

Returns:

• ‘contributions_df’: pd.DataFrame with time-series breakdown of Baseline and all channels.

• ’summary_table’: pd.DataFrame with Channel, Total Spend, Total Contribution,

  Share of Spend (%), Share of Return (%), ROI, and current mROAS.

• ’total_predicted’: np.ndarray of total model predictions.

Return type:

dict containing

classmethod fit_bayesian(spend_data, return_array, channel_names=None, n_samples=2000, chains=4, burn_in=1000, fit_baseline=True, hierarchical=True, adstock_types=None, adstock_bounds=None, adstock_fixed_days=None, calibration_experiments=None)

Fits a Meridian-lite Hierarchical Bayesian Marketing Mix Model.

classmethod fit_hierarchical_bayesian(spend_data, return_array, channel_names=None, n_samples=2000, chains=4, burn_in=1000, fit_baseline=True, hierarchical=True, adstock_types=None, adstock_bounds=None, adstock_fixed_days=None, calibration_experiments=None)

Fits a Meridian-lite Hierarchical Bayesian Marketing Mix Model.

classmethod from_historical_data(spend_data, return_array, channel_names=None, epochs=5000, lr=0.05, fit_baseline=True, adstock_types=None, adstock_bounds=None, adstock_fixed_days=None)

Fits a joint multi-channel MMM using Gradient Descent (MLE / Tinygrad Adam).

get_allocator()

Returns a PortfolioAllocator configured with all fitted channel models.

predict_channel_contributions(spend_dict, use_samples=False)

Decomposes response into individual channel incremental contributions and baseline.

Supports both single-period scalar spend queries and multi-period time-series arrays.

predict_total_return(spend_dict, use_samples=False)

Predicts total response (baseline + all channel responses) given a dictionary of channel spends.

Supports both single-period scalars and multi-period 1D numpy arrays.

summary()

Returns a dictionary summarizing all channel curves, baseline, and MCMC diagnostics.

tippingpoint.mmm.fit_multichannel_bayesian_mcmc(spend_data, return_array, channel_names=None, n_samples=2000, chains=4, burn_in=1000, fit_baseline=True, hierarchical=True, adstock_types=None, adstock_bounds=None, adstock_fixed_days=None, calibration_experiments=None)

Fits a Meridian-lite Hierarchical Bayesian Marketing Mix Model.

Features:

1. Hierarchical shrinkage (partial pooling) across channels for capacity (beta), S-curve steepness (alpha), half-saturation (K), and carryover decay (theta).

2. Optional Geo-level hierarchical partial pooling when geo/regional data is provided.

3. Joint simultaneous MCMC estimation of carryover adstock, Hill saturation, baseline, and channel coefficients in transformed unconstrained parameter space.

4. Experimental lift calibration seamlessly integrated into the joint log-likelihood.

5. Convergence diagnostics including Gelman-Rubin R-hat and acceptance rates.

tippingpoint.mmm.fit_multichannel_gradient(spend_data, return_array, channel_names=None, epochs=5000, lr=0.05, fit_baseline=True, adstock_types=None, adstock_bounds=None, adstock_fixed_days=None)

Fits a joint Multi-Channel Marketing Mix Model using Gradient Descent (Tinygrad Adam).

tippingpoint.mmm.fit_multichannel_hierarchical_bayesian(spend_data, return_array, channel_names=None, n_samples=2000, chains=4, burn_in=1000, fit_baseline=True, hierarchical=True, adstock_types=None, adstock_bounds=None, adstock_fixed_days=None, calibration_experiments=None)

Fits a Meridian-lite Hierarchical Bayesian Marketing Mix Model.

Features:

1. Hierarchical shrinkage (partial pooling) across channels for capacity (beta), S-curve steepness (alpha), half-saturation (K), and carryover decay (theta).

2. Optional Geo-level hierarchical partial pooling when geo/regional data is provided.

3. Joint simultaneous MCMC estimation of carryover adstock, Hill saturation, baseline, and channel coefficients in transformed unconstrained parameter space.

4. Experimental lift calibration seamlessly integrated into the joint log-likelihood.

5. Convergence diagnostics including Gelman-Rubin R-hat and acceptance rates.

Portfolio Optimization

class tippingpoint.portfolio.PortfolioAllocator(models)

Bases: object

Optimizes budget allocation across multiple MarketingReturnCurve models.

allocate_budget(total_budget, channel_bounds=None)

Finds the optimal spend distribution to maximize total return.

Parameters:

• total_budget (float) – Total budget to allocate.

• channel_bounds (dict, optional) – Dictionary of (min_spend, max_spend) bounds keyed by channel_name.

Returns:

The optimal allocation, marginal ROAS, and expected return.

Return type:

dict

Fitting Engines

tippingpoint.fitting.gradient.fit_mle_gradient(spend_array, return_array, epochs=5000, lr=0.05, adstock_type='none', adstock_bounds=None, adstock_fixed_days=None, fit_baseline=False)

Fits a Hill Curve to historical data using MLE (Adam optimizer), with optional adstock and baseline.

tippingpoint.fitting.gradient.tinygrad_geometric_adstock(spend, theta)

Applies geometric adstock decay in Tinygrad (vectorized Toeplitz weights).

tippingpoint.fitting.bayesian.fit_bayesian_mcmc(spend_array, return_array, channel_name='Generic', priors=None, n_samples=2000, chains=4, burn_in=1000, adstock_type='none', adstock_bounds=None, adstock_fixed_days=None, calibration_experiments=None, fit_baseline=False)

Fits a Hill Curve using Bayesian MCMC (Metropolis-Hastings in transformed space) with optional adstock, baseline, and experimental calibration.

Mathematical Core

tippingpoint.math.days_to_theta(days)

Converts half-life in days/periods to geometric decay rate theta.

Formula: theta = 0.5 ** (1 / days)

tippingpoint.math.geometric_adstock(spend, theta)

Applies geometric adstock decay to a spend array.

Formula: S_t_adstocked = S_t + theta * S_{t-1_adstocked}

tippingpoint.math.get_inflection_point(alpha, K)

Calculates the inflection point where marginal return peaks (f’’(x) = 0).

tippingpoint.math.hill_first_derivative(spend, beta, alpha, K)

Calculates the first derivative of the Hill Function (Marginal ROAS).

tippingpoint.math.hill_function(spend, beta, alpha, K)

Calculates the Hill Function value: f(x) = (beta * (x/K)^alpha) / (1 + (x/K)^alpha).

tippingpoint.math.weibull_adstock(spend, shape, scale, adstock_type='pdf', max_lag=None)

Applies Weibull adstock transformation (PDF or CDF decay).

Parameters:

• spend (array-like) – 1D array of media spend over time.

• shape (float) – Weibull shape parameter (k > 0). If k > 1, peak effect is delayed.

• scale (float) – Weibull scale parameter (lambda > 0), controls decay duration.

• adstock_type (str) – ‘pdf’ (peaked/delayed decay) or ‘cdf’ (cumulative retention).

• max_lag (int, optional) – Maximum lag window. Defaults to full length of spend.

Returns:

Adstocked effective spend array.

Return type:

np.ndarray

Visualization

class tippingpoint.viz.CurveVisualizer

Bases: object

Handles visualization for media response curves.

G_BLUE = '#4285F4'

G_GRAY = '#5F6368'

G_GREEN = '#34A853'

G_LIGHT_GRAY = '#F8F9FA'

G_RED = '#EA4335'

G_YELLOW = '#FBBC04'

classmethod plot_response_curve(model, target_mroas=1.0, current_spend=None, show_intervals=True, scatter=None)

Generates a visualization of the media response and marginal return curves.