Market Contract — forecast-mmmapi-markets Documentation

Market Folder Contract

Mon, 01 Jan 0001 00:00:00 +0000

Each market/KPI implementation should live under: markets/// Required Files config.yml transform.R decomp.R build.R validate.R README.md versions.lock Optional support folders: fixtures/ manifests/ Expected Functions transform.R transform <- function(data, config) { ... } decomp.R decomp <- function(data, model, config) { ... } build.R build_api <- function(config) { ... } Hard Rules No hard-coded local Windows, SharePoint, or OneDrive paths in committed code. No setwd(). No hidden reads from analyst-local infrastructure inside transform() or decomp(). Package calls should be namespaced explicitly. The same model representation must be used consistently across transform, predict, and decomp. Config Expectations At minimum, config.yml should describe:

Config Reference

Mon, 01 Jan 0001 00:00:00 +0000

Each market/KPI folder must define a config.yml. Example market_code: CN kpi: store_visits owner: Winnie Chen week_start: 7 artifact_name: CN-store_visits model: source: external_rds path: data/local/model/_sv_info.rds object_path: model api_model_policy: use_one_consistent_model_for_predict_and_decomp update_strategy: explicit mapping: source: model_rds object_path: tbl_map inputs: raw_data: data/local/input/cn_raw_import.csv fixed_forecast: data/local/input/cn_fixed_forecast.csv decomp: synergy_vars_regex: "^(m_|family_|fammed_|pro_|orgsoc_|pr_)" adstock_var_regex: "..." validation: require_clean_session: true require_predict: true require_decomp: true forbid_local_paths: true forbid_hidden_imports: true Required Top-Level Keys market_code kpi owner week_start artifact_name model mapping inputs decomp validation Field Notes market_code

Market README Template

Mon, 01 Jan 0001 00:00:00 +0000

Every market/KPI folder requires a README.md. Minimum Required Content Title market name KPI name Purpose what this market folder implements Owner named analyst owner named product/engineering reviewer if useful Input Artefacts what model artefact is expected what raw data is expected whether fixed forecast input is required Market-Specific Assumptions week start convention date/calendar assumptions important transform/decomp quirks Validation Status scaffold only partially migrated fully migrated and validated Notes known risks transition notes from local scripts Why This Matters The market README is meant to make the folder understandable without relying on oral context or analyst memory.