API Reference

class tippingpoint.curve.MarketingReturnCurve(beta, alpha, half_saturation_k, 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).

beta

The asymptote (maximum possible return/capacity).

Type:

float

alpha

The shape parameter (>1 for S-shape, <=1 for C-shape).

Type:

float

K

The half-saturation point (spend where half of beta is reached).

Type:

float

channel_name

Name of the media channel.

Type:

str

posterior_samples

MCMC samples for alpha, beta, K, and sigma.

Type:

dict, optional

evaluate_current_budget(current_spend, target_mroas=1.0)

Provides a strategic evaluation of the current budget allocation.

Prints recommendations based on the relationship between current spend, the peak efficiency point, and the diminishing returns point.

Parameters:

• current_spend (float) – The current amount being spent.

• target_mroas (float) – The target marginal return floor. Defaults to 1.0.

classmethod fit_bayesian(spend_array, return_array, channel_name='Generic', priors=None, n_samples=2000, chains=4, burn_in=1000)

Fits a Hill Curve using Bayesian MCMC (Metropolis-Hastings).

Parameters:

• spend_array (array-like) – Historical spend data.

• return_array (array-like) – Historical return/KPI data.

• channel_name (str) – Label for the channel. Defaults to “Generic”.

• priors (dict, optional) – LogNormal priors for ‘beta’, ‘alpha’, ‘K’. Format: {‘param’: (mu, sigma)}.

• n_samples (int) – Number of samples per chain. Defaults to 2000.

• chains (int) – Number of MCMC chains. Defaults to 4.

• burn_in (int) – Number of initial samples to discard. Defaults to 1000.

Returns:

An instance of the curve fitted with posterior means.

Return type:

MarketingReturnCurve

classmethod from_historical_data(spend_array, return_array, channel_name='Generic', epochs=5000, lr=0.05)

Fits a Hill Curve to historical data using MLE (Adam optimizer).

Parameters:

• spend_array (array-like) – Historical spend data.

• return_array (array-like) – Historical return/KPI data.

• channel_name (str) – Label for the channel. Defaults to “Generic”.

• epochs (int) – Number of optimization epochs. Defaults to 5000.

• lr (float) – Learning rate for the optimizer. Defaults to 0.05.

Returns:

An instance of the curve fitted with optimized parameters.

Return type:

MarketingReturnCurve

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

Solves for the spend level where Marginal ROAS hits a specific target.

Parameters:

• target_mroas (float) – The minimum acceptable marginal return. Defaults to 1.0.

• tol (float) – Convergence tolerance for the bisection search. Defaults to 1e-5.

• max_iter (int) – Maximum iterations for the search. Defaults to 100.

Returns:

The spend amount at the diminishing returns point, or None if unreachable.

Return type:

float or None

get_minimal_marginal_cost_point()

Identifies the inflection point where marginal return peaks.

This corresponds to the spend level where efficiency is maximized (f’’(x) = 0).

Returns:

The spend amount at the inflection point.

Return type:

float

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

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

Parameters:

• target_mroas (float) – The target marginal return floor. Defaults to 1.0.

• current_spend (float, optional) – The current spend to mark on the chart.

• show_intervals (bool) – If True and posterior samples exist, plots the 90% credible interval. Defaults to True.

predict_incremental_return(spend, use_samples=False)

Calculates the total incremental return for a given spend.

Parameters:

• spend (float or array-like) – The spend amount(s) to evaluate.

• use_samples (bool) – If True, returns a distribution using posterior samples. Defaults to False.

Returns:

The predicted incremental return(s).

Return type:

float or numpy.ndarray

predict_marginal_return(spend, use_samples=False)

Calculates the first derivative (Marginal ROAS) at a given spend.

Parameters:

• spend (float or array-like) – The spend amount(s) to evaluate.

• use_samples (bool) – If True, returns a distribution using posterior samples. Defaults to False.

Returns:

The predicted marginal return(s).

Return type:

float or numpy.ndarray