{"id":42269207,"url":"https://github.com/adityapt/deepcausalmmm","last_synced_at":"2026-04-18T19:01:57.781Z","repository":{"id":306528682,"uuid":"1026496776","full_name":"adityapt/deepcausalmmm","owner":"adityapt","description":"A Python Package to build Deep Learning (GRU) based causal MMM models at scale","archived":false,"fork":false,"pushed_at":"2026-04-18T17:31:05.000Z","size":7525,"stargazers_count":4,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-18T18:37:46.941Z","etag":null,"topics":["documentation"],"latest_commit_sha":null,"homepage":"https://deepcausalmmm.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adityapt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-26T02:31:48.000Z","updated_at":"2026-04-18T17:31:09.000Z","dependencies_parsed_at":"2025-07-26T08:59:18.387Z","dependency_job_id":"d3f25022-cb10-41c4-aff2-cda40e8b93fa","html_url":"https://github.com/adityapt/deepcausalmmm","commit_stats":null,"previous_names":["adityapt/deepcausalmmm"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/adityapt/deepcausalmmm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityapt%2Fdeepcausalmmm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityapt%2Fdeepcausalmmm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityapt%2Fdeepcausalmmm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityapt%2Fdeepcausalmmm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adityapt","download_url":"https://codeload.github.com/adityapt/deepcausalmmm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityapt%2Fdeepcausalmmm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31980783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T17:30:12.329Z","status":"ssl_error","status_checked_at":"2026-04-18T17:29:59.069Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation"],"created_at":"2026-01-27T07:11:10.316Z","updated_at":"2026-04-18T19:01:57.774Z","avatar_url":"https://github.com/adityapt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DeepCausalMMM\n\n**Advanced Marketing Mix Modeling with Causal Inference and Deep Learning**\n\n[![Documentation](https://readthedocs.org/projects/deepcausalmmm/badge/?version=latest)](https://deepcausalmmm.readthedocs.io/en/latest/?badge=latest)\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adityapt/deepcausalmmm/blob/main/examples/quickstart.ipynb)\n[![PyPI version](https://img.shields.io/pypi/v/deepcausalmmm.svg)](https://pypi.org/project/deepcausalmmm/)\n[![Downloads](https://static.pepy.tech/badge/deepcausalmmm)](https://pepy.tech/project/deepcausalmmm)\n[![Downloads/month](https://static.pepy.tech/badge/deepcausalmmm/month)](https://pepy.tech/project/deepcausalmmm)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16934842.svg)](https://doi.org/10.5281/zenodo.16934842)\n[![MMM](https://img.shields.io/badge/Marketing%20Mix-Modeling-brightgreen)](https://en.wikipedia.org/wiki/Marketing_mix_modeling)\n[![Deep Learning](https://img.shields.io/badge/Deep-Learning-blue)](https://pytorch.org)\n[![Causal DAG](https://img.shields.io/badge/Causal-DAG-purple)](https://en.wikipedia.org/wiki/Directed_acyclic_graph)\n[![GRU](https://img.shields.io/badge/Neural-GRU-orange)](https://pytorch.org/docs/stable/generated/torch.nn.GRU.html)\n[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)\n[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-red.svg)](https://pytorch.org)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n## Development history\n\nA substantial part of the design and prototyping was done **locally before this repository was published on GitHub**. The public commit history therefore reflects **integration, hardening, documentation, tests, and packaging** of that prior work more than a day-by-day log of initial exploration. You may see **bursts** of commits (e.g. around releases or doc pushes) and quieter periods in between; that pattern is typical when integrating a working prototype into an open-source layout rather than indicating only the span of weeks visible on GitHub.\n\n## Key Features\n\n### Architecture\n- **Config-Driven**: Every setting configurable via `config.py`\n- **GRU-Based Temporal Modeling**: Captures complex time-varying effects\n- **DAG Learning**: Discovers causal relationships between channels\n- **Learnable Coefficient Bounds**: Channel-specific, data-driven constraints\n- **Data-Driven Seasonality**: Automatic seasonal decomposition per region\n\n### Robust Statistical Methods\n- **Huber Loss**: Robust to outliers and extreme values\n- **Multiple Metrics**: RMSE, R², MAE, Trimmed RMSE\n- **Advanced Regularization**: L1/L2, sparsity, coefficient-specific penalties\n- **Gradient Clipping**: Parameter-specific clipping for stability\n\n### Comprehensive Analysis in Examples Folder\n- **Interactive Visualizations**: Example html dashboard with some plots and insights\n- **Response Curves**: Non-linear saturation analysis with Hill equations\n- **Budget Optimization**: Constrained optimization for optimal channel allocation\n- **DMA-Level Contributions**: True economic impact calculation at DMA level\n- **Channel Effectiveness**: Detailed performance analysis\n\n## Quick Start\n\n### Installation\n\n#### From PyPI (Recommended)\n```bash\npip install deepcausalmmm\n```\n\n#### From GitHub (Development Version)\n```bash\n# Install the latest development version with all fixes\npip install git+https://github.com/adityapt/deepcausalmmm.git\n```\n\n#### Manual Installation\n```bash\n# Clone repository\ngit clone https://github.com/adityapt/deepcausalmmm.git\ncd deepcausalmmm\npip install -e .\n```\n\n#### Dependencies Only\nSame lower/upper bounds as `pyproject.toml` `[project] dependencies` (install libraries without the `deepcausalmmm` package):\n\n```bash\npip install \\\n  \"torch\u003e=2.0\" \\\n  \"pandas\u003e=1.5\" \\\n  \"numpy\u003e=1.21,\u003c2.0\" \\\n  \"plotly\u003e=5.0\" \\\n  \"networkx\u003e=2.6\" \\\n  \"scikit-learn\u003e=1.0\" \\\n  \"scipy\u003e=1.7\" \\\n  \"statsmodels\u003e=0.13\" \\\n  \"tqdm\u003e=4.60\"\n```\n\n---\n\n## IMPORTANT: Version Compatibility\n\n**The code examples in this README are for version 1.0.19+**\n\nIf you installed from PyPI previously (`pip install deepcausalmmm`), you might have **v1.0.18** or below which has a **completely different API**. The examples below will NOT work for v1.0.18 and below.\n\n### For Current PyPI Users (v1.0.18 and below):\n```bash\n# Option 1: Upgrade to latest version from PyPi\npip install --upgrade deepcausalmmm\n# OR shorthand\npip install -U deepcausalmmm\n\n# Option 2: Install the development version (from GitHub)\npip install --upgrade git+https://github.com/adityapt/deepcausalmmm.git\n\n# Option 3: Force reinstall if you have conflicts\npip install --upgrade --force-reinstall deepcausalmmm\n```\n\n### API Changes in v1.0.19:\n- **New**: `pipeline` parameter in `ModelTrainer.train()`\n- **Fixed**: Proper data scaling without leakage\n- **Fixed**: Correct attribution calculation\n- **New**: `ConfigurableDataGenerator.generate_mmm_dataset()` method\n- **Removed**: `y_full_for_baseline` parameter (data leakage fix)\n\n---\n\n### Basic Usage\n\n```python\nimport numpy as np\nfrom deepcausalmmm import get_device\nfrom deepcausalmmm.core import get_default_config\nfrom deepcausalmmm.core.trainer import ModelTrainer\nfrom deepcausalmmm.core.data import UnifiedDataPipeline\nfrom deepcausalmmm.utils.data_generator import ConfigurableDataGenerator\n\n# Generate synthetic data for testing\n# You can replace this with your own data in the same format\nn_regions = 50        # Number of DMAs/regions\nn_weeks = 104         # 2 years of weekly data\nn_media = 13          # Number of media channels\nn_control = 3         # Number of control variables\n\ngenerator = ConfigurableDataGenerator()\nX_media, X_control, y = generator.generate_mmm_dataset(\n    n_regions=n_regions,\n    n_weeks=n_weeks,\n    n_media_channels=n_media,\n    n_control_channels=n_control\n)\n\n# Expected data format:\n# X_media: [n_regions, n_weeks, n_media_channels] - Media inputs\n# X_control: [n_regions, n_weeks, n_control_variables] - Control variables\n# y: [n_regions, n_weeks] - Target variable (KPI units)\n\n# Get configuration\nconfig = get_default_config()\nconfig['n_epochs'] = 200  # Adjust as needed\n\n# Check device availability\ndevice = get_device()\nprint(f\"Using device: {device}\")\n\n# Initialize pipeline\npipeline = UnifiedDataPipeline(config)\n\n# Split data temporally (train/holdout)\ntrain_data, holdout_data = pipeline.temporal_split(X_media, X_control, y)\n\n# Process training data\ntrain_tensors = pipeline.fit_and_transform_training(train_data)\nholdout_tensors = pipeline.transform_holdout(holdout_data)\n\n# Create trainer and model\ntrainer = ModelTrainer(config)\nmodel = trainer.create_model(\n    n_media=train_tensors['X_media'].shape[2],\n    n_control=train_tensors['X_control'].shape[2],\n    n_regions=train_tensors['X_media'].shape[0]\n)\ntrainer.create_optimizer_and_scheduler()\n\n# Train model\nresults = trainer.train(\n    train_tensors['X_media'], train_tensors['X_control'],\n    train_tensors['R'], train_tensors['y'],\n    holdout_tensors['X_media'], holdout_tensors['X_control'],\n    holdout_tensors['R'], holdout_tensors['y'],\n    pipeline=pipeline,\n    verbose=True\n)\n\n# View results\nprint(f\"Training R²: {results['final_train_r2']:.3f}\")\nprint(f\"Holdout R²: {results['final_holdout_r2']:.3f}\")\n```\n\n### Running Examples (Requires Cloning Repository)\n\nThe `examples/` folder is only available if you clone the repository (not included in pip install):\n\n```bash\n# Clone the repository first\ngit clone https://github.com/adityapt/deepcausalmmm.git\ncd deepcausalmmm\n\n# Install the package\npip install -e .\n\n# Run the comprehensive dashboard (uses real-world anonymized data)\npython examples/dashboard_rmse_optimized.py\n\n# Or run other examples\npython examples/example_budget_optimization.py\npython examples/example_response_curves.py\n```\n\n### Package Import Test\n\n```python\n# Verify installation works\nfrom deepcausalmmm import DeepCausalMMM, get_device\nfrom deepcausalmmm.core import get_default_config\n\nprint(\"DeepCausalMMM package imported successfully!\")\nprint(f\"Device: {get_device()}\")\n```\n\n## Project Structure\n\n```\ndeepcausalmmm/                      # Project root\n├── pyproject.toml                  # Package configuration and dependencies\n├── README.md                       # This documentation\n├── LICENSE                         # MIT License\n├── CHANGELOG.md                    # Version history and changes\n├── RELEASE_NOTES_1.0.19.md         # Latest release notes\n├── CONTRIBUTING.md                 # Development guidelines\n├── CODE_OF_CONDUCT.md              # Code of conduct\n├── CITATION.cff                    # Citation metadata for Zenodo/GitHub\n├── Makefile                        # Build and development tasks\n├── MANIFEST.in                     # Package manifest for distribution\n│\n├── deepcausalmmm/                  # Main package directory\n│   ├── __init__.py                 # Package initialization and exports\n│   ├── cli.py                      # Command-line interface\n│   ├── exceptions.py               # Custom exception classes\n│   │\n│   ├── core/                       # Core model components\n│   │   ├── __init__.py            # Core module initialization\n│   │   ├── config.py              # Optimized configuration parameters\n│   │   ├── unified_model.py       # Main DeepCausalMMM model architecture\n│   │   ├── trainer.py             # ModelTrainer class for training\n│   │   ├── data.py                # UnifiedDataPipeline for data processing\n│   │   ├── scaling.py             # SimpleGlobalScaler for data normalization\n│   │   ├── seasonality.py         # Seasonal decomposition utilities\n│   │   ├── dag_model.py           # DAG learning and causal inference\n│   │   ├── inference.py           # Model inference and prediction\n│   │   ├── train_model.py         # Training functions and utilities\n│   │   └── visualization.py       # Core visualization components\n│   │\n│   ├── postprocess/                # Analysis and post-processing\n│   │   ├── __init__.py            # Postprocess module initialization\n│   │   ├── analysis.py            # Statistical analysis utilities\n│   │   ├── comprehensive_analysis.py  # Comprehensive analyzer\n│   │   ├── response_curves.py     # Non-linear response curve fitting (Hill equations)\n│   │   ├── optimization.py        # Budget optimization with response curves\n│   │   ├── optimization_utils.py  # Optimization utility functions\n│   │   └── dag_postprocess.py     # DAG post-processing and analysis\n│   │\n│   └── utils/                      # Utility functions\n│       ├── __init__.py            # Utils module initialization\n│       ├── device.py              # GPU/CPU device detection\n│       └── data_generator.py      # Synthetic data generation (ConfigurableDataGenerator)\n│\n├── examples/                       # Example scripts and notebooks\n│   ├── quickstart.ipynb           # Short API intro (Google Colab badge)\n│   ├── mmm_three_way_benchmark.ipynb  # PyMC / Meridian / DCM / Ridge benchmark (optional; long runtimes)\n│   ├── dashboard_rmse_optimized.py # Comprehensive dashboard with 14+ visualizations\n│   ├── example_response_curves.py  # Response curve fitting examples\n│   ├── example_budget_optimization.py  # Budget optimization workflow\n│   └── data/                      # Example data directory\n│       └── MMM Data.csv           # Anonymized real-world MMM dataset\n│\n├── tests/                          # Test suite\n│   ├── __init__.py                # Test package initialization\n│   ├── unit/                      # Unit tests\n│   │   ├── __init__.py\n│   │   ├── test_config.py         # Configuration tests\n│   │   ├── test_model.py          # Model architecture tests\n│   │   ├── test_scaling.py        # Data scaling tests\n│   │   ├── test_response_curves.py # Response curve fitting tests\n│   │   └── test_inference.py      # InferenceManager.predict / forward contract\n│   └── integration/               # Integration tests\n│       ├── __init__.py\n│       ├── test_end_to_end.py     # End-to-end integration tests\n│       └── test_dashboard_rmse_optimized.py  # Dashboard script + real CSV data path\n│\n├── docs/                           # Documentation\n│   ├── Makefile                   # Documentation build tasks\n│   ├── make.bat                   # Windows documentation build\n│   ├── requirements.txt           # Documentation dependencies\n│   └── source/                    # Sphinx documentation source\n│       ├── conf.py               # Sphinx configuration\n│       ├── index.rst             # Documentation index\n│       ├── installation.rst      # Installation guide\n│       ├── quickstart.rst        # Quick start guide\n│       ├── contributing.rst      # Contributing guide\n│       ├── api/                  # API documentation\n│       │   ├── index.rst\n│       │   ├── core.rst\n│       │   ├── data.rst\n│       │   ├── trainer.rst\n│       │   ├── inference.rst\n│       │   ├── analysis.rst\n│       │   ├── response_curves.rst # Response curves API\n│       │   ├── optimization.rst    # Budget optimization API\n│       │   ├── cli.rst             # Command-line interface\n│       │   ├── visualization.rst   # core.visualization (VisualizationManager)\n│       │   ├── utils.rst\n│       │   └── exceptions.rst\n│       ├── examples/             # Example documentation\n│       │   ├── index.rst\n│       │   ├── retail_mmm.rst\n│       │   └── multi_region.rst\n│       └── tutorials/            # Tutorial documentation\n│           └── index.rst\n│\n└── JOSS/                           # Journal of Open Source Software submission\n    ├── paper.md                   # JOSS paper manuscript\n    ├── paper.bib                  # Bibliography\n    ├── figure_dag_professional.png # DAG visualization figure\n    └── figure_response_curve_simple.png # Response curve figure\n```\n\n## Examples Folder Dashboard Has\n\n1. **Performance Metrics**: Training vs Holdout comparison\n2. **Actual vs Predicted**: Time series visualization\n3. **Holdout Scatter**: Generalization assessment\n4. **Economic Contributions**: Total KPI per channel\n5. **Contribution Breakdown**: Donut chart with percentages\n6. **Waterfall Analysis**: Decomposed contribution flow\n7. **Channel Effectiveness**: Coefficient distributions\n9. **DAG Heatmap**: Adjacency matrix visualization\n10. **Stacked Contributions**: Time-based channel impact\n11. **Individual Channels**: Detailed channel analysis\n12. **Scaled Data**: Normalized time series\n13. **Response Curves**: Non-linear response curves (diminishing returns analysis) with Hill equations\n\n## Configuration\n\nKey configuration parameters:\n\n```python\n{\n    # Model Architecture\n    'hidden_dim': 320,           # Optimal hidden dimension\n    'dropout': 0.08,             # Proven stable dropout\n    'gru_layers': 1,             # Single layer for stability\n    \n    # Training Parameters  \n    'n_epochs': 6500,            # Optimal convergence epochs\n    'learning_rate': 0.009,      # Fine-tuned learning rate\n    'temporal_regularization': 0.04,  # Proven regularization\n    \n    # Loss Function\n    'use_huber_loss': True,      # Robust to outliers\n    'huber_delta': 0.3,          # Optimal delta value\n    \n    # Data Processing\n    'holdout_ratio': 0.08,       # Optimal train/test split\n    'burn_in_weeks': 6,          # Stabilization period\n}\n```\n\n## More Details\n\n### Learnable Parameters\n- **Media Coefficient Bounds**: `F.softplus(coeff_max_raw) * torch.sigmoid(media_coeffs_raw)`\n- **Control Coefficients**: Unbounded with gradient clipping\n- **Trend Damping**: Disabled for now, will be enabled in future releases\n- **Baseline Components**: Non-negative via `F.softplus`\n- **Seasonal Coefficient**: Learnable seasonal contribution\n\n### Data Processing\n- **Linear Scaling**: Dependent variable scaled by regional mean (y/y_mean) for balanced training\n- **SOV Scaling**: Share-of-voice normalization for media channels\n- **Z-Score Normalization**: For control variables (weather, events, etc.)\n- **Min-Max Seasonality**: Regional seasonal scaling (0-1) using `seasonal_decompose`\n- **DMA-Level Processing**: Contributions calculated per region\n- **Attribution Priors**: Media contribution regularization with dynamic loss scaling\n- **Data-Driven Hill Initialization**: Hill parameters initialized from channel-specific SOV percentiles\n\n### Regularization Strategy\n- **Coefficient L2**: Channel-specific regularization\n- **Sparsity Control**: GRU parameter sparsity\n- **DAG Regularization**: Acyclicity constraints\n- **Gradient Clipping**: Parameter-specific clipping\n\n### Response Curves\n- **Hill Saturation Modeling**: Non-linear response curves with Hill equations\n- **Data-Driven Initialization**: Hill `g` parameter initialized from channel-specific SOV 60th percentile\n- **Automatic Curve Fitting**: Fits S-shaped saturation curves to channel data\n- **National-Level Aggregation**: Aggregates DMA-week data to national weekly level\n- **Linear Scaling**: Direct scaling with prediction_scale × y_mean for accurate attribution\n- **Interactive Visualizations**: Plotly-based interactive response curve plots\n- **Performance Metrics**: R², slope, and saturation point for each channel\n\n```python\nimport pandas as pd\nimport numpy as np\nfrom deepcausalmmm.postprocess import ResponseCurveFit\n\n# After training your model, prepare channel data for response curve fitting\n# The data should have 'week_monday', 'spend', 'impressions', and 'predicted' columns\n\n# Example: Create channel data from your model results\n# Replace this with actual data extraction from your trained model\nn_weeks = 104\nchannel_data = pd.DataFrame({\n    'week_monday': pd.date_range('2024-01-01', periods=n_weeks, freq='W'),\n    'spend': np.random.uniform(10000, 50000, n_weeks),       # Replace with actual spend\n    'impressions': np.random.uniform(100000, 500000, n_weeks),  # Replace with actual impressions\n    'predicted': np.random.uniform(1000, 5000, n_weeks)      # Replace with model predictions\n})\n\n# Fit response curves to channel data\nfitter = ResponseCurveFit(\n    data=channel_data,\n    model_level='Overall',\n    date_col='week_monday'\n)\n\n# Fit the curve and generate visualization\nfitter.fit(\n    x_label='Impressions',\n    y_label='Predicted KPI Units',\n    title='Channel Response Curve',\n    save_figure=True,\n    output_path='response_curve.html'\n)\n\nprint(f\"Slope: {fitter.slope:.3f}, Saturation: {fitter.saturation:.0f}, R²: {fitter.r_2:.3f}\")\n```\n\n### Budget Optimization\n- **Constrained Optimization**: Find optimal budget allocation across channels\n- **Multiple Methods**: SLSQP (default), trust-constr, differential evolution, hybrid\n- **Hill Equation Integration**: Uses fitted response curves for saturation modeling\n- **Channel Constraints**: Set min/max spend limits based on business requirements\n- **Scenario Comparison**: Compare current vs optimal allocations\n- **ROI Maximization**: Maximize predicted response subject to budget and constraints\n\n```python\nimport pandas as pd\nfrom deepcausalmmm import optimize_budget_from_curves\n\n# After training your model and fitting response curves...\n# Create a DataFrame with fitted curve parameters for each channel\n# Replace this with actual fitted parameters from your response curve fitting\n\nfitted_curves_df = pd.DataFrame({\n    'channel': ['TV', 'Search', 'Social', 'Display', 'Radio'],\n    'top': [2.5, 3.0, 2.2, 1.8, 2.0],              # Hill parameter (slope at inflection)\n    'bottom': [0.0, 0.0, 0.0, 0.0, 0.0],           # Minimum response\n    'saturation': [500000, 300000, 200000, 150000, 400000],  # Saturation point (impressions)\n    'slope': [0.002, 0.003, 0.004, 0.002, 0.001]   # Initial slope\n})\n\n# Optimize budget allocation\nresult = optimize_budget_from_curves(\n    budget=1_000_000,\n    curve_params=fitted_curves_df,\n    num_weeks=52,\n    constraints={\n        'TV': {'lower': 100000, 'upper': 600000},\n        'Search': {'lower': 150000, 'upper': 500000},\n        'Social': {'lower': 50000, 'upper': 300000}\n    },\n    method='SLSQP'\n)\n\n# View results\nif result.success:\n    print(f\"Optimal Allocation: {result.allocation}\")\n    print(f\"Predicted Response: {result.predicted_response:,.0f}\")\n    print(result.by_channel)\n```\n\n**Example Output:**\n```\nOptimal Allocation: {'TV': 100000, 'Search': 420000, 'Social': 300000, ...}\nPredicted Response: 627,788\n\nDetailed Metrics:\n  channel  total_spend  weekly_spend  roi  spend_pct  response_pct  saturation_pct\n   Search      420,000      8,076.92  0.56      42.0%        37.8%           323%\n   Social      300,000      5,769.23  0.73      30.0%        34.8%           288%\n       TV      100,000      1,923.08  0.13      10.0%         2.1%            64%\n```\n\nSee `examples/example_budget_optimization.py` for complete workflow and tips.\n\n## Benchmarks\n\n**Example Validation** (190 regions, 109 weeks, 13 channels, 7 controls):\n\n- **Training R²**: 0.950 | **Holdout R²**: 0.842\n- **Performance Gap**: 10.8% (indicating good generalization)\n- **Generalization Gap**: 10.8% (reasonable out-of-sample performance)\n- **Temporal Split**: Default **`holdout_ratio = 0.12`** in config—about **96** training weeks and **13** holdout weeks on **109** observed weeks (burn-in padding in the pipeline may change logged lengths slightly)\n\n## Development\n\n### Requirements\n- Python 3.9+\n- PyTorch 2.0+\n- pandas 1.5+\n- numpy 1.21+ (package metadata caps below 2.0)\n- scipy 1.7+\n- plotly 5.0+\n- NetworkX 2.6+\n- statsmodels 0.13+\n- scikit-learn 1.0+\n- tqdm 4.60+\n\n### Testing\n```bash\npython -m pytest tests/\n```\n\n### Contributing\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n## Support\n\n- **Documentation**: Includes a comprehensive README with examples\n- **Issues**: Use GitHub issues for bug reports and feature requests\n\n## Documentation\n\n- **Full Documentation**: [deepcausalmmm.readthedocs.io](https://deepcausalmmm.readthedocs.io/)\n- **Quick Start Guide**: [Installation \u0026 Usage](https://deepcausalmmm.readthedocs.io/en/latest/quickstart.html)\n- **API Reference**: [Complete API Documentation](https://deepcausalmmm.readthedocs.io/en/latest/api/)\n- **Tutorials**: [Step-by-step Guides](https://deepcausalmmm.readthedocs.io/en/latest/tutorials/)\n- **Examples**: [Practical Use Cases](https://deepcausalmmm.readthedocs.io/en/latest/examples/)\n\n## Roadmap\n\n### Version 1.0.22 (planned)\n- **NOTEARS DAG Learning**: Full implementation of the NOTEARS (DAGs with NO TEARS) continuous optimization method for discovering arbitrary DAG structures\n- **Enhanced Causal Discovery**: Move beyond upper triangular constraints to learn more flexible causal relationships between marketing channels\n\n## Citation\n\nIf you use DeepCausalMMM in your work, please cite:\n\n```bibtex\n@article{tirumala2025deepcausalmmm,\n  title={DeepCausalMMM: A Deep Learning Framework for Marketing Mix Modeling with Causal Inference},\n  author={Puttaparthi Tirumala, Aditya},\n  journal={arXiv preprint arXiv:2510.13087},\n  year={2025}\n}\n```\n\nOr click the **\"Cite this repository\"** button on GitHub for other citation formats (APA, Chicago, MLA).\n\n## Quick Links\n\n- **Main Dashboard**: `dashboard_rmse_optimized.py` - Complete analysis pipeline\n- **Budget Optimization**: `examples/example_budget_optimization.py` - End-to-end optimization workflow\n- **Core Model**: `deepcausalmmm/core/unified_model.py` - DeepCausalMMM architecture\n- **Configuration**: `deepcausalmmm/core/config.py` - All tunable parameters\n- **Data Pipeline**: `deepcausalmmm/core/data.py` - Data processing and scaling\n\n---\n\n**DeepCausalMMM** - Where Deep Learning meets Causal Inference for Superior Marketing Mix Modeling\n\n**arXiv preprint** - https://www.arxiv.org/abs/2510.13087\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityapt%2Fdeepcausalmmm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadityapt%2Fdeepcausalmmm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityapt%2Fdeepcausalmmm/lists"}