MMMSummaryFactory#

class pymc_marketing.mmm.summary.factory.MMMSummaryFactory(data, model=None, hdi_probs=(0.94,), output_format='pandas', validate_data=True)[source]#

Factory for creating summary DataFrames from MMM data.

Provides a convenient interface for generating summary DataFrames with shared default settings. Accepts data wrapper (required) and optionally the MMM model to access transformations.

The factory is immutable (frozen dataclass). To create a factory with different settings, instantiate a new one directly.

Parameters:
dataMMMIDataWrapper

Data wrapper containing idata and schema (required)

modelMMM, optional

Fitted MMM model with transformations (saturation, adstock). Required for saturation_curves() and adstock_curves() methods.

hdi_probssequence of float, optional

Default HDI probability levels (default: (0.94,)). Accepts list or tuple; stored internally as tuple.

output_format{“pandas”, “polars”}, default “pandas”

Default output DataFrame format

Examples

>>> # With data only (for most summaries)
>>> factory = MMMSummaryFactory(mmm.data)
>>> contributions_df = factory.contributions()
>>>
>>> # Frontend-ready JSON records
>>> from pymc_marketing.mmm.summary import dataframe_to_json_records
>>> records = dataframe_to_json_records(mmm.summary.contributions())
>>>
>>> # With model (for transformation curves)
>>> factory = MMMSummaryFactory(mmm.data, model=mmm)
>>> saturation_df = factory.saturation_curves()
>>>
>>> # Via model property (recommended - includes model automatically)
>>> factory = mmm.summary
>>> saturation_df = factory.saturation_curves()
>>>
>>> # Create new factory with different settings (direct instantiation)
>>> polars_factory = MMMSummaryFactory(
...     mmm.data, model=mmm, output_format="polars", hdi_probs=[0.80, 0.94]
... )
>>> df = polars_factory.contributions()  # Uses configured defaults

Methods

MMMSummaryFactory.__init__(data[, model, ...])

MMMSummaryFactory.adstock_curves([...])

Create adstock curves summary DataFrame.

MMMSummaryFactory.change_over_time([...])

Create change over time summary with per-date percentage changes.

MMMSummaryFactory.channel_share_hdi([...])

Create channel share of total contribution summary DataFrame.

MMMSummaryFactory.channel_spend([output_format])

Create channel spend DataFrame (raw data, no HDI).

MMMSummaryFactory.contributions([hdi_probs, ...])

Create contribution summary DataFrame.

MMMSummaryFactory.posterior_predictive([...])

Create posterior predictive summary DataFrame.

MMMSummaryFactory.prior_predictive([...])

Create prior predictive summary DataFrame.

MMMSummaryFactory.prior_vs_posterior([...])

Create prior vs posterior density grid summary DataFrame.

MMMSummaryFactory.residuals_distribution([...])

Create residual distribution quantile summary DataFrame.

MMMSummaryFactory.residuals_over_time([...])

Create residuals-over-time summary DataFrame.

MMMSummaryFactory.roas([hdi_probs, ...])

Create ROAS (Return on Ad Spend) summary DataFrame.

MMMSummaryFactory.saturation_curves([...])

Create saturation curves summary DataFrame.

MMMSummaryFactory.saturation_scatterplot([...])

Create saturation scatterplot data as a long-form DataFrame.

MMMSummaryFactory.sensitivity_analysis([...])

Summarize raw sensitivity sweep results (sensitivity_analysis['x']).

MMMSummaryFactory.sensitivity_marginal([...])

Summarize marginal effects (sensitivity_analysis['marginal_effects']).

MMMSummaryFactory.sensitivity_uplift([...])

Summarize uplift curves (sensitivity_analysis['uplift_curve']).

MMMSummaryFactory.total_contribution([...])

Create total contribution summary (all effects combined).

MMMSummaryFactory.waterfall([hdi_probs, ...])

Create waterfall decomposition summary DataFrame.

Attributes

hdi_probs

model

output_format

validate_data

data