deepcausalmmm.postprocess.response_curves

Response curve fitting for Marketing Mix Modeling using Hill equation.

This module provides the ResponseCurveFit class for fitting saturation curves to the relationship between media spend/impressions and predicted outcomes.

The implementation follows modern Python standards: - Type hints for all parameters and return values - Private methods prefixed with underscore (_) - Keyword-only arguments for better API clarity - Comprehensive docstrings in NumPy style - Backward compatibility maintained for legacy code

Classes

`ResponseCurveFit`(data, *[, bottom_param, ...])	Fit Hill equation response curves to marketing mix model predictions.
`ResponseCurveFitter`

class deepcausalmmm.postprocess.response_curves.ResponseCurveFit(data: DataFrame, *, bottom_param: bool = False, model_level: Literal['Overall', 'DMA'] = 'Overall', date_col: str = 'week_monday')[source]

Fit Hill equation response curves to marketing mix model predictions.

The Hill equation models saturation effects: y = bottom + (top - bottom) * x^slope / (saturation^slope + x^slope)

Parameters:

data (pd.DataFrame) – DataFrame with columns: ‘week_monday’, ‘spend’, ‘impressions’, ‘predicted’ For DMA-level: also needs ‘dmacode’ column
bottom_param (bool, default=False) – Whether to fit a non-zero intercept (bottom parameter) For MMM, typically False (response at zero spend = 0)
Modellevel (str, default='Overall') – ‘Overall’: Single aggregated curve across all regions ‘DMA’: Separate curves for each DMA
Datecol (str, default='week_monday') – Name of the date column

top

Maximum response (saturation level)

Type:: float

bottom

Minimum response (typically 0)

Type:: float

saturation

Spend level at half-maximum response

Type:: float

slope

Steepness of the curve

Type:: float

r_2

R-squared score of the fitted curve

Type:: float

equation

String representation of the fitted equation

Type:: str

figure

Plotly figure object (if generate_figure=True)

Type:: go.Figure

Examples

>>> # Prepare data
>>> data = pd.DataFrame({
...     'week_monday': dates,
...     'spend': spend_values,
...     'impressions': impression_values,
...     'predicted': model_predictions
... })
>>>
>>> # Fit overall response curve
>>> fitter = ResponseCurveFit(data, Modellevel='Overall')
>>> fitter.fit_model(
...     title="Response Curve",
...     x_label="Impressions",
...     y_label="Predicted Visits",
...     generate_figure=True,
...     save_figure=True,
...     output_path='response_curve.html'
... )
>>> print(f"R²: {fitter.r_2:.3f}")
>>> print(f"Slope: {fitter.slope:.3f}")

__init__(data: DataFrame, *, bottom_param: bool = False, model_level: Literal['Overall', 'DMA'] = 'Overall', date_col: str = 'week_monday') → None[source]

Initialize ResponseCurveFit.

Parameters:

data (pd.DataFrame) – Input data with required columns
bottom_param (bool, default=False) – Whether to fit non-zero intercept
model_level ({'Overall', 'DMA'}, default='Overall') – Aggregation level for fitting
date_col (str, default='week_monday') – Name of date column

Hill(X: ndarray, *params) → ndarray[source]: Backward compatibility wrapper for _hill_equation.

get_param(curve_fit_kws: dict) → List[float][source]: Backward compatibility wrapper for _fit_curve.

regression(x_fit, y_fit, x_label, y_label, title, sigfigs, log_x, print_r_sqr, generate_figure, view_figure, *params) → None[source]: Backward compatibility wrapper for _calculate_r2_and_plot.

fit(*, x_label: str = 'x', y_label: str = 'y', title: str = 'Fitted Hill equation', sigfigs: int = 6, log_x: bool = False, print_r_sqr: bool = True, generate_figure: bool = True, view_figure: bool = False, save_figure: bool = False, output_path: str | None = None, curve_fit_kws: dict | None = None) → DataFrame | None[source]

Fit Hill equation to the data.

Parameters:

x_label (str, default='x') – X-axis label
y_label (str, default='y') – Y-axis label
title (str, default='Fitted Hill equation') – Plot title
sigfigs (int, default=6) – Significant figures for equation display
log_x (bool, default=False) – Whether to use log scale for x-axis
print_r_sqr (bool, default=True) – Whether to print R² score
generate_figure (bool, default=True) – Whether to generate visualization
view_figure (bool, default=False) – Whether to display the figure
save_figure (bool, default=False) – Whether to save the figure
output_path (str, optional) – Path to save the figure (if save_figure=True)
curve_fit_kws (dict, optional) – Additional keyword arguments for scipy.optimize.curve_fit

Returns:

For DMA-level: DataFrame with parameters for each DMA For Overall: None (parameters stored as attributes)

Return type:

pd.DataFrame or None

fit_model(**kwargs) → DataFrame | None[source]: Backward compatibility wrapper for fit().

predict(X: ndarray) → ndarray[source]

Predict response for new spend levels (Overall level only).

Parameters:: X (np.ndarray) – New spend/impression values
Returns:: Predicted response values
Return type:: np.ndarray

get_summary()[source]

Get summary of fitted parameters.

Returns:: Dictionary with ‘params’, ‘r2’, and ‘equation’
Return type:: dict

deepcausalmmm.postprocess.response_curves.ResponseCurveFitter: alias of ResponseCurveFit