DOCSEARCHbyAlgolia
Submit Docs

Meridian

repository·main·Indexed 23 days ago

https://github.com/google/meridian

A Bayesian causal inference framework for Marketing Mix Modeling (MMM) that helps advertisers measure marketing impact, calculate ROI, and optimize budget allocation using aggregated, privacy-safe data. It features a dual-backend system supporting TensorFlow and JAX, utilizes a No U-Turn Sampler (NUTS) MCMC approach, and includes tools for budget optimization, model diagnostics, and MLflow tracking.

Tokens
9.7K
Snippets
24
Records
37
Agent score
80%

What's inside google-meridian

  1. Overview of Meridian MMM framework

    main

    Meridian is a highly customizable Marketing Mix Modeling (MMM) framework based on Bayesian causal inference. It allows advertisers to measure the impact of marketing channels on KPIs (like revenue) and optimize budget allocation.

    Key features include:

    • Privacy-safe: Uses aggregated data and does not use cookies or user-level information.
    • Scalable: Capable of handling large-scale geo-level data or national-level modeling.
    • Advanced Methodologies: Supports calibration with experiments/prior information and optimization of target ad frequency using reach and frequency data.
    • Performance: Uses a No U-Turn Sampler (NUTS) MCMC approach. GPU support is available out-of-the-box via tensors to significantly reduce training time.

  2. What is MMM Proto Schema?

    main
    The MMM Proto Schema is a language-agnostic data standard designed to represent trained Marketing Mix Models (MMMs) and their analysis artifacts. It provides a consistent, serializable format that allows MMM outputs from various tools and methodologies to be uniformly represented, stored, shared, and compared. This standardization is intended to improve interoperability for downstream tasks such as scenario planning, optimization, and reporting.

  3. Maintain backend agnosticism in Meridian

    main

    Meridian uses a dual-backend system supporting both TensorFlow and JAX. To ensure code remains compatible with both, do not directly import tensorflow or jax in core library code (such as inside meridian/model/ or meridian/analysis/).

    All numerical, probabilistic, and tensor operations must be accessed exclusively through the meridian.backend module.

  4. Install Meridian with JAX backend

    main

    To use Meridian with the JAX backend, you must uninstall TensorFlow first to avoid conflicts. Ensure you are using a GPU runtime (like T4, V100, A100, or L4) as it is required.

    Set the MERIDIAN_BACKEND environment variable to jax before importing any Meridian modules.

    # Uninstall TensorFlow
!pip uninstall tensorflow -y -q

# Install meridian with required extras
!pip install --upgrade google-meridian[colab,and-cuda,schema]

import os
# MUST be set prior to meridian import
os.environ['MERIDIAN_BACKEND'] = 'jax'

  5. Install MMM Proto Schema

    main

    You can install the MMM Proto Schema package using PIP or by installing from the Meridian source code.

    Using PIP

    To install or upgrade the package via PIP, run:

    pip install --upgrade mmm-proto-schema

    Installing from Source

    To install the schema from the Meridian repository, clone the repository and install with the [schema] extra:

    git clone https://github.com/google/meridian.git
cd meridian
pip install .[schema]

  6. Run model health checks and diagnostics

    main

    After modeling, use the following tools to assess convergence and fit:

    1. Model Reviewer: Use reviewer.ModelReviewer(mmm).run() to generate a comprehensive health card (HTML).
    2. Convergence (R-hat): Use visualizer.ModelDiagnostics(mmm).plot_rhat_boxplot() to check if R-hat values are close to 1.0.
    3. Model Fit: Use visualizer.ModelFit(mmm).plot_model_fit() to compare expected sales against actual sales.

  7. Install Meridian

    main

    Meridian requires Python 3.11-3.13. For optimal performance, a GPU is recommended (tested on T4 GPU with 16 GB RAM). It is highly recommended to install Meridian in a fresh virtual environment.

    Install latest release from PyPI

    For Linux-GPU users (requires CUDA toolchain and compatible GPU):

    $ pip install --upgrade google-meridian[and-cuda]

    For macOS and general CPU users (no official GPU support for macOS):

    $ pip install --upgrade google-meridian

    Install unreleased version from GitHub

    For GPU users:

    $ pip install --upgrade "google-meridian[and-cuda] @ git+https://github.com/google/meridian.git"

    For CPU users:

    $ pip install --upgrade git+https://github.com/google/meridian.git
    pip install --upgrade google-meridian[and-cuda]

  9. Get started with Meridian

    main

    To begin using Meridian, you can run the library programmatically using sample data via the Getting Started Colab.

    For a more detailed workflow, refer to the following resources:

    • User Guide: Detailed walkthrough for using your own data and generating visualizations.
    • Pre-modeling: Guidance on data collection and analysis.
    • Modeling: Guidance on model refinement and edge cases.
    • Post-modeling: Guidance on model fit, visualizations, optimizations, and debugging.

  10. Install Meridian with Scenario Planner support

    main

    To use the Scenario Planner features, install the google-meridian package with the [scenarioplanner,and-cuda] extras. Note that running Meridian optimization requires a GPU runtime (e.g., T4, V100, A100, or L4) in environments like Google Colab.

    !pip install google-meridian[scenarioplanner,and-cuda]
    # @markdown Then we can install meridian library with scenario planner feature, this step can take 3-7 mins
!pip install google-meridian[scenarioplanner,and-cuda]

  11. Generate a Looker Studio dashboard from a Meridian model

    main

    To create an interactive Looker Studio dashboard, you must convert the model's inference results into a Google Sheet. This involves several steps:

    1. Authenticate: Grant Colab access to spreadsheets and drive scopes.
    2. Configure Specs: Define BudgetOptimizationSpec (including constraints like min_spend_shift_ratio and max_spend_shift_ratio) and MediaSummarySpec.
    3. Generate Proto: Use mmm_ui_gen.create_mmm_ui_data_proto to create the UI data proto from the model and your specs.
    4. Convert to Dataframe: Use dataframe_model_converter.DataFrameModelConverter to turn the proto into dataframes.
    5. Upload: Use sheets.upload_to_gsheet to push the dataframes to a Google Sheet.
    6. Create URL: Use url_generator.create_report_url(spreadsheet) to get the Looker Studio link.

    Note: This process can take significant time (up to 20 minutes) as it performs multiple inferences based on your configuration.

    # Example configuration snippet for dashboard generation
# ... (authentication and setup) ...

budgetOptSpec = budget_optimization_processor.BudgetOptimizationSpec(
    start_date=start_date,
    end_date=end_date,
    optimization_name=optimization_name,
    grid_name=grid_name_prefix,
    constraints=channel_constraints,
    use_optimal_frequency=use_optimal_frequency,
    max_frequency=max_frequency,
)

summary_spec = marketing_processor.MediaSummarySpec(
    include_non_paid_channels=include_non_paid_channels)

mmm_proto = mmm_ui_gen.create_mmm_ui_data_proto(
    mmm=mmm,
    specs=[
        model_fit_processor.ModelFitSpec(),
        marketing_processor.MarketingAnalysisSpec(
            media_summary_spec=summary_spec,
        ),
        budgetOptSpec,
    ],
    time_breakdown_generators=time_breakdown_generators,
)

converter = dataframe_model_converter.DataFrameModelConverter(mmm_proto)
dataframes = converter()

spreadsheet = sheets.upload_to_gsheet(dataframes, credentials, spreadsheet_name=spreadsheet_name)
url = url_generator.create_report_url(spreadsheet)