πŸ“ analysis.response_curveΒΆ

The ResponseCurveAnalyzer module within the analysis submodule of the MMM package provides tools for analyzing and visualizing response curves for marketing mix models (MMM). It enables fitting S-curves to model features, generating response curves, and quantifying feature contributions.

OverviewΒΆ

This module exposes a response curve analyzer class that:

  • Accepts a DataFrame and configuration parameters

  • Fits S-curves to features using customizable transformers and models

  • Generates response curves for features, including predicted targets and contributions

  • Provides utilities for feature contribution analysis and reporting

Class ReferenceΒΆ

class mmm.analysis.response_curve.ResponseCurveParams(model=None, feature_columns=None, target_column=None, transformers=None, curve_type='exponential', add_default_transformers=True)ΒΆ

Configuration parameters for response curve analysis.

Parameters:

  • model (ModelProtocol or None) – The model to use for fitting (must implement ModelProtocol).

  • feature_columns (list[str]) – List of feature column names to analyze.

  • target_column (str) – Name of the target column.

  • transformers (dict[str, TransformerPipeline] or None) – Dictionary mapping feature names to transformer pipelines.

  • curve_type (str) – Type of S-curve to fit (e.g., β€œexponential”).

  • add_default_transformers (bool) – Whether to add default transformers if not provided.

class mmm.analysis.response_curve.ResponseCurveAnalyzer(df, params)ΒΆ

Analyzes response curves for features in a DataFrame.

Parameters:

  • df (pandas.DataFrame) – Input data as a pandas DataFrame.

  • params (ResponseCurveParams) – Configuration parameters for analysis.

fit(num_points=100, generate_curves=True, clip_negative_target=True, return_raw_target=True, return_uplift=False)ΒΆ

Fits S-curves for each feature and optionally generates curve data.

Parameters:

  • num_points (int) – Number of points in the response curve grid.

  • generate_curves (bool) – Whether to generate curve data after fitting.

  • clip_negative_target (bool) – If True, negative predictions are floored at 0.

  • return_raw_target (bool) – If True, includes raw predicted targets in output.

  • return_uplift (bool) – If True, includes uplift vs. baseline in output.

Returns:

Dictionary of curves (if generate_curves=True) or self.

generate_curve(feature, num_points=50, clip_negative_target=True, return_raw_target=True, return_uplift=False)ΒΆ

Generates a response curve for a specific feature.

Parameters:

  • feature (str) – Feature name to generate the curve for.

  • num_points (int) – Number of points in the curve grid.

  • clip_negative_target (bool) – If True, negative predictions are floored at 0.

  • return_raw_target (bool) – If True, includes raw predicted targets in output.

  • return_uplift (bool) – If True, includes uplift vs. baseline in output.

Returns:

Dictionary containing curve data.

feature_contribution(feature)ΒΆ

Computes the contribution of a feature by comparing predictions with and without the feature.

Parameters:

feature (str) – Feature name.

Returns:

Numpy array of contributions.

total_contribution(feature)ΒΆ

Computes the total contribution of a feature.

Parameters:

feature (str) – Feature name.

Returns:

Total contribution as a float.

average_contribution(feature)ΒΆ

Computes the average contribution of a feature.

Parameters:

feature (str) – Feature name.

Returns:

Average contribution as a float.

print_curve(curve)ΒΆ

Prints the response curve as a formatted table.

Parameters:

curve (dict) – Curve dictionary as returned by generate_curve.

print_curve_json(curve, indent=2)ΒΆ

Prints the response curve as formatted JSON.

Parameters:

  • curve (dict) – Curve dictionary as returned by generate_curve.

  • indent (int) – Indentation level for JSON output.

Curve Output Example

{
  "feature": "tv_spend",
  "input_value": [0.0, 10.0, ..., 100.0],
  "observed_input_min": 0.0,
  "observed_input_max": 100.0,
  "predicted_target": [100.0, 110.0, ..., 200.0],
  "contribution": {
    "contribution": [0.0, 5.0, ..., 50.0],
    "total_contribution": 500.0,
    "average_contribution": 25.0
  },
  "predicted_target_raw": [100.0, 110.0, ..., 200.0],
  "predicted_target_clipped": [100.0, 110.0, ..., 200.0],
  "predicted_target_uplift": [0.0, 10.0, ..., 100.0]
}

NotesΒΆ

  • The analyzer supports custom transformer pipelines for each feature.

  • S-curve fitting is robust to missing or infinite values, with warnings for dropped rows.

  • Negative predictions can be clipped to zero for interpretability.

  • Feature contributions are computed by comparing model predictions with and without the feature.

  • Designed for use with MMM models to visualize and interpret feature effects.

ReferencesΒΆ

Back to Home