Market Folder Contract

Each market/KPI implementation should live under:

markets/<MARKET>/<KPI>/

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:

  • market code
  • KPI name
  • owner
  • week start convention
  • model source
  • mapping source
  • input locations
  • decomp regex/configuration
  • validation requirements

See Config Reference for a worked example and field notes.

Market README Requirements

The market README.md is required and should include:

  • purpose
  • owner
  • expected input artefacts
  • market-specific assumptions
  • validation status
  • transition notes from local scripts

See Market README Template.

Why This Contract Exists

The contract exists to stop each market drifting into a private implementation that is hard to review, hard to reproduce, and inconsistent with the product workflow.