Builders

The builders module provides fluent API classes for constructing configuration objects using the builder pattern.

Base Builders

Base classes and mixins for configuration builders.

Provides shared functionality used across all builder types.

class mmm_framework.builders.base.BuilderProtocol(*args, **kwargs)

Bases: Protocol[T]

Protocol for configuration builders.

All builders should implement a build() method that returns the final configuration object.

build()

Build and return the configuration object.

Return type:

TypeVar(T)

__init__(*args, **kwargs)

class mmm_framework.builders.base.VariableConfigBuilderMixin

Bases: object

Mixin providing shared methods for variable configuration builders.

This mixin provides common functionality for builders that configure variables with display names, units, and dimensions. It should be used by MediaChannelConfigBuilder, ControlVariableConfigBuilder, and KPIConfigBuilder to eliminate code duplication.

Attributes

_display_namestr | None

Human-readable display name for the variable.

_unitstr | None

Unit of measurement (e.g., ‘USD’, ‘GRPs’).

_dimensionslist[DimensionType]

Dimensions this variable is defined over.

with_display_name(name)

Set human-readable display name.

Return type:

Self

Parameters

namestr

Display name for the variable.

Returns

Self

Builder instance for method chaining.

with_unit(unit)

Set unit of measurement.

Return type:

Self

Parameters

unitstr

Unit of measurement (e.g., ‘USD’, ‘GRPs’, ‘Index’).

Returns

Self

Builder instance for method chaining.

with_dimensions(*dims)

Set dimensions this variable is defined over.

If PERIOD is not included in the provided dimensions, it will be automatically inserted at the beginning.

Parameters:

*dims (DimensionType) – Variable number of dimension types.

Return type:

Self

Returns:

Builder instance for method chaining.

national()

Set as national-level (Period only).

This is a convenience method equivalent to: with_dimensions(DimensionType.PERIOD)

Return type:

Self

Returns

Self

Builder instance for method chaining.

by_geo()

Set as geo-level (Period + Geography).

This is a convenience method equivalent to: with_dimensions(DimensionType.PERIOD, DimensionType.GEOGRAPHY)

Return type:

Self

Returns

Self

Builder instance for method chaining.

by_product()

Set as product-level (Period + Product).

This is a convenience method equivalent to: with_dimensions(DimensionType.PERIOD, DimensionType.PRODUCT)

Return type:

Self

Returns

Self

Builder instance for method chaining.

by_geo_and_product()

Set as geo+product level (Period + Geography + Product).

This is a convenience method equivalent to: with_dimensions(DimensionType.PERIOD, DimensionType.GEOGRAPHY, DimensionType.PRODUCT)

Return type:

Self

Returns

Self

Builder instance for method chaining.

Prior Builders

Prior and transformation configuration builders.

Provides builders for PriorConfig, AdstockConfig, and SaturationConfig.

class mmm_framework.builders.prior.PriorConfigBuilder

Bases: object

Builder for PriorConfig objects.

Examples

>>> prior = (PriorConfigBuilder()
...     .half_normal(sigma=2.0)
...     .with_dims("channel")
...     .build())

>>> prior = (PriorConfigBuilder()
...     .gamma(alpha=2, beta=1)
...     .build())

__init__()

half_normal(sigma=1.0)

Set HalfNormal distribution.

Return type:

Self

normal(mu=0.0, sigma=1.0)

Set Normal distribution.

Return type:

Self

log_normal(mu=0.0, sigma=1.0)

Set LogNormal distribution.

Return type:

Self

gamma(alpha=2.0, beta=1.0)

Set Gamma distribution.

Return type:

Self

beta(alpha=2.0, beta=2.0)

Set Beta distribution.

Return type:

Self

truncated_normal(mu=0.0, sigma=1.0, lower=0.0, upper=None)

Set TruncatedNormal distribution.

Return type:

Self

half_student_t(nu=3.0, sigma=1.0)

Set HalfStudentT distribution.

Return type:

Self

with_dims(dims)

Set dimension(s) for the prior.

Return type:

Self

with_params(**params)

Set additional parameters.

Return type:

Self

build()

Build the PriorConfig object.

Return type:

PriorConfig

class mmm_framework.builders.prior.AdstockConfigBuilder

Bases: object

Builder for AdstockConfig objects.

Examples

>>> adstock = (AdstockConfigBuilder()
...     .geometric()
...     .with_max_lag(8)
...     .with_alpha_prior(PriorConfigBuilder().beta(1, 3).build())
...     .build())

__init__()

geometric()

Use geometric adstock transformation.

Return type:

Self

weibull()

Use Weibull adstock transformation.

Return type:

Self

delayed()

Use delayed adstock transformation.

Return type:

Self

none()

Disable adstock transformation.

Return type:

Self

with_max_lag(l_max)

Set maximum lag weeks (1-52).

Return type:

Self

with_normalize(normalize=True)

Set whether to normalize adstock weights.

Return type:

Self

with_alpha_prior(prior)

Set prior for decay rate (geometric adstock).

Return type:

Self

with_theta_prior(prior)

Set prior for peak delay (Weibull adstock).

Return type:

Self

with_slow_decay()

Configure for slow decay (long memory).

Return type:

Self

with_fast_decay()

Configure for fast decay (short memory).

Return type:

Self

build()

Build the AdstockConfig object.

Return type:

AdstockConfig

class mmm_framework.builders.prior.SaturationConfigBuilder

Bases: object

Builder for SaturationConfig objects.

Examples

>>> saturation = (SaturationConfigBuilder()
...     .hill()
...     .with_kappa_prior(PriorConfigBuilder().beta(2, 2).build())
...     .with_slope_prior(PriorConfigBuilder().half_normal(1.5).build())
...     .with_kappa_bounds(0.1, 0.9)
...     .build())

__init__()

hill()

Use Hill saturation function.

Return type:

Self

logistic()

Use logistic saturation function.

Return type:

Self

michaelis_menten()

Use Michaelis-Menten saturation function.

Return type:

Self

tanh()

Use tanh saturation function.

Return type:

Self

root()

Use root / power saturation x ** k (exponent via slope prior).

Return type:

Self

none()

Disable saturation transformation.

Return type:

Self

with_kappa_prior(prior)

Set prior for half-saturation point (EC50).

Return type:

Self

with_slope_prior(prior)

Set prior for curve steepness.

Return type:

Self

with_beta_prior(prior)

Set prior for maximum effect scaling.

Return type:

Self

with_kappa_bounds(lower, upper)

Set percentile bounds for kappa prior (data-driven).

Return type:

Self

with_strong_saturation()

Configure for strong diminishing returns.

Return type:

Self

with_weak_saturation()

Configure for weak diminishing returns.

Return type:

Self

build()

Build the SaturationConfig object.

Return type:

SaturationConfig

Variable Builders

Variable configuration builders.

Provides builders for MediaChannelConfig, ControlVariableConfig, and KPIConfig.

class mmm_framework.builders.variable.MediaChannelConfigBuilder(name)

Bases: VariableConfigBuilderMixin

Builder for MediaChannelConfig objects.

Examples

>>> tv_config = (MediaChannelConfigBuilder("TV")
...     .with_dimensions(DimensionType.PERIOD)
...     .with_adstock(AdstockConfigBuilder().geometric().with_max_lag(8).build())
...     .with_saturation(SaturationConfigBuilder().hill().build())
...     .with_positive_prior(sigma=2.0)
...     .build())

>>> social_meta = (MediaChannelConfigBuilder("Meta")
...     .with_dimensions(DimensionType.PERIOD)
...     .with_parent_channel("Social")
...     .with_split_dimensions(DimensionType.OUTLET)
...     .build())

__init__(name)

with_adstock(config)

Set adstock configuration.

Return type:

Self

with_adstock_builder(builder)

Set adstock from builder.

Return type:

Self

with_geometric_adstock(l_max=8)

Convenience: set geometric adstock with max lag.

Return type:

Self

with_saturation(config)

Set saturation configuration.

Return type:

Self

with_saturation_builder(builder)

Set saturation from builder.

Return type:

Self

with_hill_saturation()

Convenience: set Hill saturation with defaults.

Return type:

Self

with_logistic_saturation()

Convenience: set logistic saturation with defaults.

Return type:

Self

with_michaelis_menten_saturation()

Convenience: set Michaelis-Menten saturation with defaults.

Return type:

Self

with_tanh_saturation()

Convenience: set tanh saturation with defaults.

Return type:

Self

with_root_saturation()

Convenience: set root / power saturation (x ** k) with defaults.

Return type:

Self

with_coefficient_prior(prior)

Set coefficient prior.

Return type:

Self

with_positive_prior(sigma=2.0)

Convenience: set HalfNormal prior for positive effects.

Return type:

Self

with_roi_prior(*, median=None, mu=None, sigma=None)

State the channel’s prior directly on the ROI (decision) scale.

Sets the hyper-parameters of the ROI-parameterized prior roi_<ch> ~ LogNormal(mu, sigma) — the channel then uses the ROI parameterization even under media_prior_mode="coefficient". Give the location as median (ROI units, e.g. 1.2 for a break-even+ belief; mu = log(median)) or as mu (log scale) — not both. sigma is the log-scale spread: 0.5 ⇒ 90% within ~[0.44×, 2.3×] of the median; the default 1.0 within ~[0.19×, 5.2×].

Return type:

Self

with_parent_channel(parent)

Set parent channel for hierarchical grouping.

Return type:

Self

with_split_dimensions(*dims)

Set additional split dimensions (e.g., Outlet for platforms).

Return type:

Self

with_time_varying(enabled=True, innovation_sigma=0.15)

Model this channel’s coefficient as time-varying (a random walk on log(beta_t)) so effectiveness can drift. innovation_sigma is the per-step log-innovation scale (smaller ⇒ closer to constant beta).

Return type:

Self

measured_in(unit)

Declare how the modeled variable is measured.

"spend" (default) keeps normal ROI. "impressions" / "clicks" / "other" mark the variable as a volume, so ROI is resolved from a spend_column / cpm / cpc if provided, else reported as efficiency per 1,000 impressions (or per click / unit). The response curve is always fit on the modeled variable regardless.

Return type:

Self

with_spend_column(column)

Use a SEPARATE MFF variable as the dollar spend for ROI (option a).

Implies a non-spend measurement_unit; defaults it to impressions if still spend.

Return type:

Self

with_cpm(cpm)

Derive ROI by costing the modeled impressions at cpm per 1,000 (option b). Implies impressions if measurement_unit is still spend.

Return type:

Self

with_cpc(cpc)

Derive ROI by costing the modeled clicks at cpc per click (option b). Sets measurement_unit to clicks.

Return type:

Self

build()

Build the MediaChannelConfig object.

Return type:

MediaChannelConfig

class mmm_framework.builders.variable.ControlVariableConfigBuilder(name)

Bases: VariableConfigBuilderMixin

Builder for ControlVariableConfig objects.

Examples

>>> price = (ControlVariableConfigBuilder("Price")
...     .with_dimensions(DimensionType.PERIOD)
...     .allow_negative()
...     .with_normal_prior(mu=0, sigma=1)
...     .build())

>>> distribution = (ControlVariableConfigBuilder("Distribution")
...     .national()
...     .with_shrinkage()
...     .build())

__init__(name)

with_causal_role(role, reason=None)

Declare the control’s causal role (confounder vs precision control).

Accepts the enum or its string value ("confounder" / "precision_control"; the spec-level shorthand "precision" is normalized). The role drives back-door reporting and the explicit-prior-on-confounder warning in the core model.

Return type:

Self

allow_negative(allow=True)

Allow negative coefficient (e.g., for price).

Return type:

Self

positive_only()

Constrain coefficient to be positive.

Return type:

Self

with_coefficient_prior(prior)

Set coefficient prior.

Return type:

Self

with_normal_prior(mu=0.0, sigma=1.0)

Convenience: set Normal prior.

Return type:

Self

with_shrinkage(use=True)

Enable shrinkage prior for variable selection.

Return type:

Self

build()

Build the ControlVariableConfig object.

Return type:

ControlVariableConfig

class mmm_framework.builders.variable.KPIConfigBuilder(name)

Bases: VariableConfigBuilderMixin

Builder for KPIConfig objects.

Examples

>>> kpi = (KPIConfigBuilder("Sales")
...     .with_dimensions(DimensionType.PERIOD, DimensionType.GEOGRAPHY)
...     .multiplicative()
...     .build())

__init__(name)

additive()

Use additive model specification (no log transform).

Return type:

Self

multiplicative()

Use multiplicative model specification (log transform).

Return type:

Self

with_floor_value(floor)

Set minimum value for log transform safety.

Return type:

Self

build()

Build the KPIConfig object.

Return type:

KPIConfig

Model Builders

Model-level configuration builders.

Provides builders for ModelConfig and related configuration objects.

class mmm_framework.builders.model.HierarchicalConfigBuilder

Bases: object

Builder for HierarchicalConfig objects.

Examples

>>> hierarchical = (HierarchicalConfigBuilder()
...     .enabled()
...     .pool_across_geo()
...     .pool_across_product()
...     .with_non_centered_threshold(20)
...     .build())

__init__()

enabled(enable=True)

Enable hierarchical modeling.

Return type:

Self

disabled()

Disable hierarchical modeling.

Return type:

Self

pool_across_geo(pool=True)

Enable partial pooling across geographies.

Return type:

Self

pool_across_product(pool=True)

Enable partial pooling across products.

Return type:

Self

no_geo_pooling()

Disable geo pooling (independent effects).

Return type:

Self

no_product_pooling()

Disable product pooling.

Return type:

Self

use_non_centered(use=True)

Use non-centered parameterization.

Return type:

Self

use_centered()

Use centered parameterization.

Return type:

Self

with_non_centered_threshold(threshold)

Set minimum observations for centered parameterization.

Return type:

Self

with_mu_prior(prior)

Set prior for group mean.

Return type:

Self

with_sigma_prior(prior)

Set prior for group standard deviation.

Return type:

Self

build()

Build the HierarchicalConfig object.

Return type:

HierarchicalConfig

class mmm_framework.builders.model.SeasonalityConfigBuilder

Bases: object

Builder for SeasonalityConfig objects.

Examples

>>> seasonality = (SeasonalityConfigBuilder()
...     .with_yearly(order=2)
...     .with_weekly(order=3, prior_sigma=0.2)
...     .with_prior_sigma(0.5)  # shared amplitude prior
...     .build())

__init__()

with_yearly(order=2, prior_sigma=None)

Add yearly seasonality with given Fourier order (and optionally a component-specific amplitude prior sigma).

Return type:

Self

with_monthly(order=2, prior_sigma=None)

Add monthly seasonality.

Return type:

Self

with_weekly(order=3, prior_sigma=None)

Add weekly seasonality.

Return type:

Self

with_prior_sigma(sigma)

Set the shared seasonal amplitude prior: Fourier coefficients get Normal(0, sigma) on standardized y. Per-component sigmas (passed to with_yearly(..., prior_sigma=) etc.) override this.

Return type:

Self

no_yearly()

Disable yearly seasonality.

Return type:

Self

no_seasonality()

Disable all seasonality.

Return type:

Self

build()

Build the SeasonalityConfig object.

Return type:

SeasonalityConfig

class mmm_framework.builders.model.ControlSelectionConfigBuilder

Bases: object

Builder for ControlSelectionConfig objects.

Examples

>>> selection = (ControlSelectionConfigBuilder()
...     .horseshoe(expected_nonzero=3)
...     .build())

__init__()

none()

No variable selection (use all controls).

Return type:

Self

horseshoe(expected_nonzero=3)

Use horseshoe prior for sparse selection.

Return type:

Self

spike_slab()

Use spike-and-slab prior.

Return type:

Self

lasso(regularization=1.0)

Use LASSO-like regularization.

Return type:

Self

with_expected_nonzero(n)

Set expected number of nonzero controls.

Return type:

Self

with_regularization(strength)

Set regularization strength.

Return type:

Self

build()

Build the ControlSelectionConfig object.

Return type:

ControlSelectionConfig

class mmm_framework.builders.model.ModelConfigBuilder

Bases: object

Builder for ModelConfig objects.

Examples

>>> model = (ModelConfigBuilder()
...     .additive()
...     .bayesian_numpyro()
...     .with_chains(4)
...     .with_draws(2000)
...     .with_hierarchical(HierarchicalConfigBuilder().enabled().build())
...     .build())

__init__()

additive()

Use additive model specification.

Return type:

Self

multiplicative()

Use multiplicative model specification.

Return type:

Self

with_parametric_adstock(enabled=True)

Estimate a continuous in-graph adstock kernel per channel (default).

Honors each MediaChannelConfig.adstock (geometric, delayed, or Weibull). Pass enabled=False for the legacy fixed-alpha blend — the pre-2026-06 default, kept for reproducing older fits.

Return type:

Self

with_legacy_blend_adstock()

Use the legacy fixed-alpha-bank blend adstock (pre-change default).

Return type:

Self

bayesian_pymc()

Use PyMC for Bayesian inference (CPU).

Return type:

Self

bayesian_numpyro()

Use NumPyro for Bayesian inference (JAX, faster).

Return type:

Self

bayesian_nutpie()

Use the nutpie NUTS sampler (Rust implementation).

Samples the same graph as bayesian_pymc() / bayesian_numpyro() — only the NUTS implementation differs, so all three target the identical posterior. Which one is fastest is model-dependent: measured on effective samples per second, the ranking inverts between a small national model and a geo panel. Benchmark on your own model rather than assuming (nbs/demos/nuts_backends.ipynb does exactly this).

Return type:

Self

frequentist_ridge()

Ridge estimation with bootstrap confidence intervals (epic #180).

A different paradigm, not a faster Bayesian one. Adstock and saturation are chosen by rolling-origin out-of-sample search rather than estimated under priors, the remaining coefficients are solved in closed form, and the intervals come from a moving-block residual bootstrap.

Not a synonym for fit(method="map"): ridge is MAP under Gaussian coefficient priors, and this framework’s media prior is Gamma(mu=1.5, sigma=1) or LogNormal(0, 1) on ROI — neither of which is Gaussian, so MAP here is a different penalized estimator. What this adds is transform selection by search, bootstrap confidence intervals, and (via frequentist_cvxpy()) hard constraints.

MMMResults.converged is None for such a fit and every report surface labels its intervals as confidence intervals. Requires a model that is linear given fixed transforms; a GP trend, per-geo media coefficients or reach/frequency channels raise, naming the feature.

Return type:

Self

frequentist_cvxpy()

Constrained estimation via a convex program (epic #180).

Everything frequentist_ridge() does, with hard linear constraints the solver must satisfy exactly — the one capability a prior cannot express. A HalfNormal prior makes a negative coefficient merely unlikely; a constraint makes it impossible, and a sum-of-contributions constraint (“match the number finance booked”) has no prior analogue at all.

Selecting this with no explicit constraints= applies non-negative media, the one restriction every MMM wants. Needs the optional extra: pip install 'mmm-framework[frequentist]' (cvxpy).

A coefficient pinned by an active constraint has no meaningful two-sided interval; those columns are listed in diagnostics["at_boundary"].

Return type:

Self

with_inference_method(method)

Set the inference method (paradigm) directly.

The generic form of bayesian_pymc() / frequentist_ridge() / …, for a caller holding the enum value rather than choosing at the call site — e.g. the agent spec layer mapping inference.method.

Selecting a frequentist paradigm also clears fit_method — enforced by ModelConfig’s own validator rather than here, so it holds however the config was built.

Return type:

Self

with_chains(n)

Set number of MCMC chains.

Return type:

Self

with_draws(n)

Set number of posterior draws per chain.

Return type:

Self

with_tune(n)

Set number of tuning samples.

Return type:

Self

with_target_accept(rate)

Set target acceptance rate for NUTS.

Return type:

Self

with_fit_method(method)

Set the default fit method used by BayesianMMM.fit().

"nuts" (default) runs full MCMC; "smc" runs tempered Sequential Monte Carlo (also exact — robust to multimodality, estimates the log marginal likelihood, but slower than NUTS on well-behaved posteriors). The approximate methods — "map", "laplace", "advi", "fullrank_advi", "pathfinder" — fit in seconds for quick model checks but produce uncalibrated uncertainty.

None is accepted and means “no Bayesian fit method applies” — the state a frequentist config is left in, since FitMethod has no member for a penalized point estimate and a default of "nuts" would make an unfitted model’s prefit surfaces announce a full MCMC posterior.

Return type:

Self

map_fit()

Default to a maximum a posteriori (MAP) point estimate — fastest check.

Return type:

Self

laplace()

Default to a Laplace (Gaussian around the MAP point) approximation.

Cheap curvature-based uncertainty — a step up from bare MAP for model checking, still approximate (via the declared pymc_extras dep).

Return type:

Self

advi(full_rank=False)

Default to variational inference (ADVI, or full-rank ADVI).

Return type:

Self

pathfinder()

Default to Pathfinder VI (requires the optional pymc_extras package).

Return type:

Self

smc()

Default to tempered Sequential Monte Carlo (pm.sample_smc).

An exact sampler (not an approximate check): use it to confirm suspected multimodality (R-hat across independent SMC runs) or to get a log marginal likelihood for model comparison. Slower than NUTS on well-behaved posteriors.

Return type:

Self

with_likelihood(likelihood)

Set the observation (likelihood) family. Default is normal/identity.

Return type:

Self

with_intercept_prior(mu=0.0, sigma=0.5)

Set the intercept prior: Normal(mu, sigma) on standardized y.

mu is measured in KPI standard deviations from the mean, so values beyond roughly ±2 place the baseline outside the observed KPI range.

Return type:

Self

with_media_prior_mode(mode='roi', *, roi_mu=None, roi_sigma=None)

Choose the DEFAULT media-effect prior parameterization.

"roi" samples each channel’s prior ROI directly (roi_<ch> ~ LogNormal(roi_mu, roi_sigma), default median 1.0 = break-even) and derives beta_<ch> in-graph — the default prior lives on the decision scale and is comparable across channels. "coefficient" keeps the historical standardized-coefficient Gamma. Only applies to channels without an experiment-calibrated roi_prior or an explicit coefficient_prior.

Return type:

Self

roi_based_media_priors(roi_mu=0.0, roi_sigma=1.0)

Convenience: switch the default media priors to the ROI scale.

Return type:

Self

with_grouped_media_priors(enabled=True)

Partial-pool the coefficients of channels sharing a parent_channel group toward a shared mean (DF-2). Off by default; only pool genuinely exchangeable channels. Calibrated / explicitly-priored channels are excluded from the pool.

Return type:

Self

with_events(events)

Add holiday / event effects (#143) — an EventsConfig of named country holidays and/or custom event windows, fit as an additive event_component distinct from the smooth Fourier seasonality.

Return type:

Self

with_channel_interactions(*interactions)

Add cross-channel synergy / interaction terms (#142) — one or more ChannelInteraction, each a beta_ij * sat_i * sat_j term with a sign-aware, shrink-to-zero prior. Off by default (strictly additive).

Return type:

Self

with_price(price)

Promote a control column to a price lever (#138) — a log-price elasticity (≤ 0) with an optional reference/discount-depth. Pass a PriceConfig.

Return type:

Self

with_promotions(*promotions)

Promote control columns to promo levers (#138) — a lift with its own carryover. Pass one or more PromoConfig.

Return type:

Self

with_reach_frequency(*configs)

Model channels as reach × a frequency-saturation curve (#141). Pass one or more ReachFrequencyConfig; each names a channel (its column is reach) and a frequency column (from the control block). Off by default.

Return type:

Self

with_hierarchical(config)

Set hierarchical configuration.

Return type:

Self

with_hierarchical_builder(builder)

Set hierarchical from builder.

Return type:

Self

with_seasonality(config)

Set seasonality configuration.

Return type:

Self

with_seasonality_builder(builder)

Set seasonality from builder.

Return type:

Self

with_control_selection(config)

Set control selection configuration.

Return type:

Self

with_control_selection_builder(builder)

Set control selection from builder.

Return type:

Self

with_ridge_alpha(alpha)

Set Ridge regularization strength.

Return type:

Self

with_bootstrap_samples(n)

Set number of bootstrap samples for uncertainty.

Return type:

Self

with_optim_maxiter(n)

Set maximum optimization iterations.

Return type:

Self

with_optim_seed(seed)

Set optimization random seed.

Return type:

Self

build()

Build the ModelConfig object.

Return type:

ModelConfig

class mmm_framework.builders.model.TrendConfigBuilder

Bases: object

Builder for TrendConfig objects with support for various trend types.

Supports: - None (intercept only) - Linear (simple linear trend) - Piecewise (Prophet-style changepoint detection) - Spline (B-spline flexible trend) - Gaussian Process (HSGP approximation for smooth trends)

Examples

>>> # Simple linear trend
>>> trend = TrendConfigBuilder().linear().build()

>>> # Piecewise linear with changepoints
>>> trend = (TrendConfigBuilder()
...     .piecewise()
...     .with_n_changepoints(10)
...     .with_changepoint_range(0.8)
...     .with_changepoint_prior_scale(0.05)
...     .build())

>>> # B-spline trend
>>> trend = (TrendConfigBuilder()
...     .spline()
...     .with_n_knots(15)
...     .with_spline_degree(3)
...     .with_spline_prior_sigma(1.0)
...     .build())

>>> # Gaussian Process trend
>>> trend = (TrendConfigBuilder()
...     .gaussian_process()
...     .with_gp_lengthscale(mu=0.3, sigma=0.2)
...     .with_gp_amplitude(sigma=0.5)
...     .with_gp_n_basis(25)
...     .build())

__init__()

none()

No trend (intercept only).

Return type:

Self

linear()

Simple linear trend.

Return type:

Self

piecewise()

Prophet-style piecewise linear trend with changepoints.

Return type:

Self

spline()

B-spline flexible trend.

Return type:

Self

gaussian_process()

Gaussian Process trend using HSGP approximation.

Return type:

Self

gp()

Alias for gaussian_process().

Return type:

Self

with_n_changepoints(n)

Set number of changepoints for piecewise trend.

Return type:

Self

with_changepoint_range(range_pct)

Set range (0-1) for placing changepoints.

Return type:

Self

with_changepoint_prior_scale(scale)

Set prior scale for changepoint magnitudes.

Return type:

Self

with_n_knots(n)

Set number of knots for spline trend.

Return type:

Self

with_spline_degree(degree)

Set B-spline degree (default 3 = cubic).

Return type:

Self

with_spline_prior_sigma(sigma)

Set prior sigma for spline coefficients.

Return type:

Self

with_gp_lengthscale(mu=0.3, sigma=0.2)

Set prior for GP lengthscale.

Return type:

Self

with_gp_amplitude(sigma=0.5)

Set prior sigma for GP amplitude.

Return type:

Self

with_gp_n_basis(n)

Set number of basis functions for HSGP approximation.

Return type:

Self

with_gp_boundary_factor(c)

Set boundary factor for HSGP.

Return type:

Self

with_growth_prior(mu=0.0, sigma=0.5)

Set prior for linear growth rate.

Return type:

Self

smooth()

Preset: Very smooth trend (good for long-term patterns).

Return type:

Self

flexible()

Preset: Flexible trend (good for capturing shifts).

Return type:

Self

changepoint_detection()

Preset: Good for detecting structural breaks.

Return type:

Self

build()

Build the TrendConfig object.

class mmm_framework.builders.model.DimensionAlignmentConfigBuilder

Bases: object

Builder for DimensionAlignmentConfig objects.

Examples

>>> alignment = (DimensionAlignmentConfigBuilder()
...     .geo_by_population()
...     .product_by_sales()
...     .build())

__init__()

geo_equal()

Allocate to geos equally.

Return type:

Self

geo_by_population()

Allocate to geos by population.

Return type:

Self

geo_by_sales()

Allocate to geos by historical sales.

Return type:

Self

geo_by_custom(weight_variable)

Allocate to geos using custom weight variable from MFF.

Return type:

Self

product_equal()

Allocate to products equally.

Return type:

Self

product_by_sales()

Allocate to products by historical sales.

Return type:

Self

product_by_custom(weight_variable)

Allocate to products using custom weight variable.

Return type:

Self

prefer_disaggregation(prefer=True)

Prefer disaggregating national data vs aggregating detailed data.

Return type:

Self

prefer_aggregation()

Prefer aggregating detailed data vs disaggregating.

Return type:

Self

build()

Build the DimensionAlignmentConfig object.

Return type:

DimensionAlignmentConfig

MFF Builders

MFF (Master Flat File) configuration builders.

Provides builders for MFFColumnConfig and MFFConfig.

class mmm_framework.builders.mff.MFFColumnConfigBuilder

Bases: object

Builder for MFFColumnConfig objects.

Examples

>>> columns = (MFFColumnConfigBuilder()
...     .with_period_column("Week")
...     .with_geography_column("Region")
...     .build())

__init__()

with_period_column(name)

Set period/date column name.

Return type:

Self

with_geography_column(name)

Set geography column name.

Return type:

Self

with_product_column(name)

Set product column name.

Return type:

Self

with_campaign_column(name)

Set campaign column name.

Return type:

Self

with_outlet_column(name)

Set outlet column name.

Return type:

Self

with_creative_column(name)

Set creative column name.

Return type:

Self

with_variable_name_column(name)

Set variable name column name.

Return type:

Self

with_variable_value_column(name)

Set variable value column name.

Return type:

Self

build()

Build the MFFColumnConfig object.

Return type:

MFFColumnConfig

class mmm_framework.builders.mff.MFFConfigBuilder

Bases: object

Builder for MFFConfig objects - the main configuration builder.

Examples

>>> config = (MFFConfigBuilder()
...     .with_kpi(KPIConfigBuilder("Sales").by_geo().build())
...     .add_media(MediaChannelConfigBuilder("TV").national().with_geometric_adstock(8).build())
...     .add_media(MediaChannelConfigBuilder("Digital").national().with_geometric_adstock(4).build())
...     .add_control(ControlVariableConfigBuilder("Price").allow_negative().build())
...     .with_alignment(DimensionAlignmentConfigBuilder().geo_by_sales().build())
...     .with_date_format("%Y-%m-%d")
...     .weekly()
...     .build())

__init__()

with_columns(config)

Set column name mappings.

Return type:

Self

with_columns_builder(builder)

Set columns from builder.

Return type:

Self

with_kpi(config)

Set KPI configuration.

Return type:

Self

with_kpi_builder(builder)

Set KPI from builder.

Return type:

Self

with_kpi_name(name)

Convenience: set simple national KPI by name.

Return type:

Self

add_media(config)

Add a media channel configuration.

Return type:

Self

add_media_builder(builder)

Add media channel from builder.

Return type:

Self

add_media_channels(*configs)

Add multiple media channel configurations.

Return type:

Self

add_national_media(name, adstock_lmax=8)

Convenience: add national media with defaults.

Return type:

Self

add_social_platforms(platforms, parent_name='Social', adstock_lmax=4)

Convenience: add social platforms with hierarchy.

Return type:

Self

add_control(config)

Add a control variable configuration.

Return type:

Self

add_control_builder(builder)

Add control from builder.

Return type:

Self

add_controls(*configs)

Add multiple control configurations.

Return type:

Self

add_price_control(name='Price')

Convenience: add price control (allows negative).

Return type:

Self

add_distribution_control(name='Distribution')

Convenience: add distribution/ACV control.

Return type:

Self

with_alignment(config)

Set dimension alignment configuration.

Return type:

Self

with_alignment_builder(builder)

Set alignment from builder.

Return type:

Self

with_date_format(fmt)

Set date parsing format.

Return type:

Self

weekly()

Set weekly frequency.

Return type:

Self

daily()

Set daily frequency.

Return type:

Self

monthly()

Set monthly frequency.

Return type:

Self

with_fill_missing_media(value)

Set fill value for missing media (default: 0).

Return type:

Self

with_fill_missing_controls(value)

Set fill value for missing controls (None = forward fill).

Return type:

Self

build()

Build the MFFConfig object.

Return type:

MFFConfig