API Reference

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

Model Interface

class tippingpoint.models.MarketingReturnCurve(beta, alpha, half_saturation_k, theta=0.0, channel_name='Generic', posterior_samples=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 geometric adstock decay 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)

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)

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

get_minimal_marginal_cost_point()

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)

predict_marginal_return(spend, use_samples=False)

summary()

update_loss(loss)

Return type:

None

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

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^alpha) / (K^alpha + x^alpha).

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.