trail-gmd

Global Macro Database (NBER Working Paper 33714) country-by-year macro indicators for Trail.

trail-gmd is country-keyed, not stock-keyed: its capabilities() declare entity_dim="country" (rows are ISO3 codes, not tickers) and bridge_field="meta.country". It carries no stock universe of its own - Trail remaps its gmd.* fields onto each stock via that stock's meta.country, supplied by an entity-keyed source such as trail-fmp or trail-edgar. So gmd always rides alongside a stock source:

# trail.yaml
sources:
  fmp:
    driver: fmp
    options:
      api_key: ${FMP_API_KEY}
      tickers: [AAPL, MSFT, DTE.DE]
  gmd:
    driver: gmd
    options:
      countries: [USA, DEU]   # optional: narrows the fetch; omit for every GMD country
precedence:
  default: [fmp, gmd]

model factor {
  export revenue = income.revenue        # from fmp - entity-keyed, native to the stock
  export cpi     = gmd.CPI                # from gmd - country-keyed, bridged via meta.country
}

Non-commercial data license - see Attribution below before you use this in anything commercial.

Provides

The gmd.* namespace: GMD's own short indicator codes, one field each, at annual frequency on the country dimension - 81 fields in total. A representative sample, with the kind hint Trail uses for each:

Full coverage otherwise: national accounts and output (GDP, deflator), consumption/investment/trade (each with _GDP-share and USD variants), the three fiscal tiers (budgetary / general-government / central-government expenditure, revenue, tax, deficit, debt), external balances and FX, money and credit, population, and the crisis/classification fields above. Kinds break down as 47 level, 23 ratio, 5 rate, 5 index, 1 meta. Run trail catalog gmd for the full, current list.

Configure

# trail.yaml
sources:
  fmp:
    driver: fmp
    options:
      api_key: ${FMP_API_KEY}
      tickers: [AAPL, MSFT]
  gmd:
    driver: gmd
    options:
      countries: [USA, DEU, JPN]   # optional; omit to fetch every GMD country
      version: current              # or a pinned "2025_09"
      historical_only: true         # mask IMF-WEO projections to null (default)
      cache_dir: .gmd-cache
precedence:
  default: [fmp, gmd]
panel:
  periods: [1990, 2024]

gmd needs no credentials - it fetches an unauthenticated, public CSV release. Then:

trail catalog gmd            # the gmd.* field vocabulary
trail run model.trail --model m --config trail.yaml

Options

Every option GmdSource.__init__ reads from options::

There is no pit option: gmd's point-in-time behavior isn't configurable, because it has nothing to be configured - see below.

Point-in-time / bridge

gmd is naive: annual macro data has no filing coordinate, so capabilities().pit is left at its default (False) - unlike a restated-statement source, there's no historical-vs-current distinction to opt into. Its only role in Trail's point-in-time model is as a country-level series remapped by the bridge, not as a series with its own PIT.

capabilities() declares entity_dim="country" (the entity column is an ISO3 code, not a ticker) and bridge_field="meta.country". At align time Trail:

1. Reads each canonical entity's (stock's) meta.country value, supplied by an entity-keyed source in the same config (e.g. trail-fmp normalizes this to ISO3 for exactly this purpose).
2. Joins gmd's row for that country onto the stock, as-of each period - gmd is coarser (annual) than most target frequencies, so this is a "most recent known value" match, not an exact one.

If no loaded source supplies meta.country, Trail raises E-DIM-UNMAPPED; a foreign-dimension source that declared no bridge_field at all would raise E-DIM-NOBRIDGE. In practice: always pair gmd with a stock source that resolves country, or its fields simply have nowhere to land.

Attribution

Required citation:

Mueller, K., Xu, C., Lehbib, M., & Chen, Z. (2025). The Global Macro Database: A New International Macroeconomic Dataset. NBER Working Paper No. 33714. https://www.globalmacrodata.com

trail-gmd prints this citation as a GmdCitationNotice warning (not stdout) the first time a load happens in a process, and never bundles, re-hosts, or commits GMD data - it fetches on demand and caches only on your machine (cache_dir).

Code: MIT. Data: CC BY-NC-SA 4.0 + GMD Research Use Terms (non-commercial), fetched on demand.