src.core.hierarchical_mmm_v2

Hierarchical Market Structures for AMMM Model.

This module implements hierarchical modeling capabilities that allow for: - Multi-market/region modeling with partial pooling - Brand-level effects across product variants - Store-level hierarchies for retail analytics - Cross-market learning and information sharing - Market-specific and global effects separation

The implementation uses PyMC’s hierarchical modeling capabilities to share information across markets while allowing for market-specific variations.

Module Contents

class src.core.hierarchical_mmm_v2.HierarchicalMMMv2(date_column: str, channel_columns: List[str], hierarchy_column: str, adstock_max_lag: int, pooling_mode: Literal['partial', 'complete', 'no'] = 'partial', global_channels: List[str] | None = None, market_specific_channels: List[str] | None = None, hyperprior_config: Dict[str, Any] | None = None, correlation_structure: Literal['independent', 'lkj'] = 'independent', **kwargs)

Bases: src.core.mmm_model_v2.DelayedSaturatedMMMv2

Media Mix Model V2 with Hierarchical Market Structures.

Extends the base Model to handle multiple markets/regions with hierarchical Bayesian modeling. This allows for: - Partial pooling of parameters across markets - Market-specific variations while learning from global patterns - Efficient estimation even with limited data per market

The hierarchy can represent: - Geographic markets (countries, regions, cities) - Product categories or brands - Store clusters or customer segments - Time periods (for dynamic hierarchies)

Parameters:

  • date_column (str) – Column name of the date variable.

  • channel_columns (List[str]) – Column names of the media channel variables.

  • hierarchy_column (str) – Column identifying the hierarchical unit (e.g., “market”, “region”).

  • adstock_max_lag (int) – Maximum lag for the adstock transformation.

  • pooling_mode (Literal["partial", "complete", "no"]) – Degree of parameter pooling. Defaults to “partial”.

  • global_channels (Optional[List[str]]) – Channels with global effects only.

  • market_specific_channels (Optional[List[str]]) – Channels with market-specific effects.

  • hyperprior_config (Optional[Dict]) – Configuration for hyperpriors.

  • **kwargs – Additional arguments passed to DelayedSaturatedMMMv2.

Examples

>>> # Create hierarchical model for multiple markets
>>> model = HierarchicalMMMv2(
...     date_column="date",
...     channel_columns=["tv", "online", "radio"],
...     hierarchy_column="market",
...     adstock_max_lag=4,
...     pooling_mode="partial",
...     global_channels=["online"],  # Online has same effect everywhere
...     market_specific_channels=["tv", "radio"]  # TV/Radio vary by market
... )
>>> # Fit model with multi-market data
>>> idata = model.fit(X_multi_market, y_multi_market)
>>> # Analyze market-specific effects
>>> market_effects = model.get_market_effects("tv")
build_model(X: pandas.DataFrame, y: pandas.Series | numpy.ndarray, **kwargs) → None

Build the hierarchical model.

Overrides the base build_model to incorporate hierarchical structure for multi-market modeling.

Parameters:

  • X – Feature dataframe with media channels, controls, and hierarchy column

  • y – Target variable series or array

  • **kwargs – Additional arguments for model building

get_market_effects(channel: str, markets: List[str] | None = None) → pandas.DataFrame

Get market-specific effects for a channel.

Parameters:

  • channel – Channel name to analyze

  • markets – Specific markets to include (default: all)

Returns:

DataFrame with market effects and credible intervals

plot_market_comparison(channels: List[str] | None = None, markets: List[str] | None = None, figsize: tuple = (12, 6)) → None

Plot comparison of channel effects across markets.

Parameters:

  • channels – Channels to plot (default: all market-specific)

  • markets – Markets to include (default: all)

  • figsize – Figure size

get_pooling_factor(channel: str) → float

Calculate the pooling factor for a channel.

The pooling factor indicates how much information is shared across markets (0 = no pooling, 1 = complete pooling).

Parameters:

channel – Channel name

Returns:

Pooling factor between 0 and 1

predict_new_market(X_new: pandas.DataFrame, market_name: str, n_samples: int = 1000) → numpy.ndarray

Predict for a new market not in training data.

Uses the hierarchical structure to make predictions for a new market based on the global distribution.

Parameters:

  • X_new – Features for new market

  • market_name – Name of new market

  • n_samples – Number of posterior samples to use

Returns:

Predicted values with uncertainty