Skip to content

Reference

Tips and Common Pitfalls

  • Run from the root directory


    Always execute from the main directory so that the proper modules are used.

  • Respect the sequence


    Every step depends on the outputs of the one before it.

  • Review judgment


    simulate_forecast is where judgment is applied — revisit existing adjustments against current conditions.

  • Use the report steps


    Steps 4, 6 and 8 validate calibration, data quality and forecast reasonableness.

Quick troubleshooting

Symptom Likely cause What to do
ModuleNotFoundError or wrong module runs Command run outside the project root, or cpm_venv not active cd to the project root and activate cpm_venv
Packages fail to install Environment not activated before pip install Activate first; prompt should show (cpm_venv)
bt.request_data fails External or India forecast not yet submitted, or IDs do not match Complete us → cn/jp/ea → in; check IDs in attributes.json
Tunes not applied annual_tunes.csv still open or forecast_span not set to 1 Save and close the file; check forecast_span = 1
Implausible growth or rates Rates entered as percentages Enter decimals; roc is gross (5% → 1.05)

Command Cheat Sheet

Environment

python -m venv cpm_venv
cpm_venv\Scripts\activate
pip install -r requirements.txt
python3 -m venv cpm_venv
source cpm_venv/bin/activate
pip install -r requirements.txt

Data

python -m datastore_pumps.update_all

Country models

`python -m {country}.{step}`
# Step Command (Bhutan)
1 Create Model python -m ph.create_model
2 Request Data python -m ph.request_data
3 Prepare History python -m ph.prepare_history
4 Review Steady-State python -m ph.report_steady_calibration
5 Filter History python -m ph.filter_history
6 Report Filter python -m ph.report_filter
7 Simulate Forecast python -m ph.simulate_forecast
8 Report Forecast python -m ph.report_forecast
9 Submit Forecast python -m ph.submit_forecast
— All steps (skips 4 and 6) python -m ph.run_all

Run order

datastore_pumps → us → cn · jp · ea → in → bt

Key files

File Purpose
datastore/data.csv Central datastore output
{country}/attributes.json Forecast IDs and sample periods
tune_files/annual_tunes.csv Annual tunes for judgment

Glossary

Term Meaning
CPM Country Projection Model
Datastore Central store of historical series and submitted forecasts, served through datastore_api
External environment The US, euro area, Japan and PRC models whose forecasts feed the focus economies
Focus economy A country forecast using the external environment (pilot: Bhutan, India, Philippines)
Forecast ID Identifier for a forecast round; part of the datastore storage key
Steady-state calibration The model's long-term equilibrium assumptions, reviewed in Step 4
Kalman filter / filtering Separates trends from cyclical components in historical data (Step 5)
Tune A target value set directly for a variable; the simulation solves for the shocks needed to hit it
Exogenize / endogenize Fix a variable at a set value / let a shock adjust freely so the target is met
roc Gross rate of change (e.g. 1.05 = 5% growth)
Real exchange rate gap Computed against the US dollar using US CPI projections — the reason the US runs first

Country codes: bt Bhutan · cn PRC · ea euro area · in India · jp Japan · ph Philippines · us United States


Recap: From Data to Submitted Forecast

  1. Set up the environment and run everything from the project root.
  2. Update and refresh the datastore with datastore_pumps.update_all.
  3. Build the external environment: US first, then CN, JP and EA.
  4. Run focus countries: PH, IN, and then BT.
  5. Work through the nine steps in order, pausing at the review gates.
  6. Apply judgment through annual tunes, then report and submit.

Data sources

Data such as quarterly national accounts, prices and financial data are pulled through macrotap from external providers.

Provider Name Code Link
Federal Reserve Bank Federal Reserve Economic Data FRED Visit site
European Central Bank Indices of Consumer Prices ICP Visit site
European Central Bank Main aggregates, national accounts MNA Visit site
European Central Bank Financial Market data FM Visit site
European Central Bank Exchange Rates EXR Visit site
International Monetary Fund National Economic Accounts, Quarterly Data QNEA Visit site
International Monetary Fund National Economic Accounts, Annual Data ANEA Visit site
International Monetary Fund Consumer Price Index (CPI) CPI Visit site
International Monetary Fund Exchange Rates ER Visit site
International Monetary Fund Monetary and Financial Statistics MFS Visit site

Variable names

Frequency: M = monthly, Q = quarterly, Y = annual. Seasonal: SA = seasonally adjusted, NSA = not seasonally adjusted, X = not applicable.

United States

Concept Freq. Seasonal Provider API request Label
RGDP Q SA FRED GDPC1 Real Gross Domestic Product, Billions of Chained 2017 Dollars, Quarterly, Seasonally Adjusted Annual Rate
STGY M X FRED TB3MS 3-Month Treasury Bill Secondary Market Rate, Discount Basis, Percent, Monthly, Not Seasonally Adjusted
CPI M SA FRED CPIAUCSL Consumer Price Index for All Urban Consumers: All Items in U.S. City Average, Index 1982-1984=100, Monthly, Seasonally Adjusted

People’s Republic of China

Concept Freq. Seasonal Provider API request Label
CPI M NSA IMF:CPI CHN.CPI._T.IX.M Consumer price index, All items, Index, Monthly
RGDP Q NSA IMF:QNEA CHN.B1GQ.Q.NSA.XDC.Q Gross Domestic Product, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Annual
STMR M X FRED IR3TIB01CNM156N Interest Rates: 3-Month or 90-Day Rates and Yields: Interbank Rates: Total for China, Percent, Monthly, Not Seasonally Adjusted
USD M X IMF:ER CHN.XDC_USD.PA_RT.M Domestic currency per US Dollar, Period average, Monthly

Japan

Concept Freq. Seasonal Provider API request Label
CPI M NSA IMF:CPI JPN.CPI._T.IX.M Consumer price index, All items, Index, Monthly
RGDP Q NSA IMF:QNEA JPN.B1GQ.Q.NSA.XDC.Q Gross Domestic Product, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Annual
STMR M X FRED IR3TIB01JPM156N —
USD M X IMF:ER JPN.XDC_USD.PA_RT.M Domestic currency per US Dollar, Period average, Monthly

Euro area

Concept Freq. Seasonal Provider API request Label
CPI M NSA ECB:ICP M.U2.N.000000.4.INX Euro area (changing composition) - HICP - Overall index, Index, Eurostat, Neither seasonally nor working day adjusted
RGDP Q SA ECB:MNA Q.Y.I9.W2.S1.S1.B.B1GQ._Z._Z._Z.EUR.LR.N Gross domestic product at market prices - Euro area 20 (fixed composition) as of 1 January 2023 - Domestic (home or reference area), Total economy, Euro, Chain linked volume (rebased), , Calendar and seasonally adjusted data
STMR M X ECB:FM M.U2.EUR.RT.MM.EURIBOR3MD_.HSTA Euro area (changing composition) - Money Market - Euribor 3-month - Historical close, average of observations through period
USD M X ECB:EXR M.USD.EUR.SP00.A ECB reference exchange rate, US dollar/Euro

Bhutan

Concept Freq. Seasonal Provider API request Label
CPI M NSA MANUAL:bhutan.csv CPI National Consumer Price Index, Total, Monthly
USD M X IMF:ER BTN.XDC_USD.PA_RT.M Domestic currency per US Dollar, Period average, Monthly
NGDP Y X IMF:ANEA BTN.B1GQ.V.XDC.A Gross Domestic Product, Current Prices, Not Seasonally Adjusted, Domestic Currency, Annual
NCPR Y X IMF:ANEA BTN.P3_PS.V.XDC.A Final consumption expenditure, Private sector, Current Prices, Not Seasonally Adjusted, Domestic Currency, Annual
NCGG Y X IMF:ANEA BTN.P3_S13.V.XDC.A Final consumption expenditure, General government, Current Prices, Not Seasonally Adjusted, Domestic Currency, Annual
NFCF Y X IMF:ANEA BTN.P51G.V.XDC.A Gross fixed capital formation, Current Prices, Not Seasonally Adjusted, Domestic Currency, Annual
NCBI Y X IMF:ANEA BTN.P52.V.XDC.A Changes in inventories, Current Prices, Not Seasonally Adjusted, Domestic Currency, Annual
NXGS Y X IMF:ANEA BTN.P6.V.XDC.A Exports of goods and services, Current Prices, Not Seasonally Adjusted, Domestic Currency, Annual
NMGS Y X IMF:ANEA BTN.P7.V.XDC.A Imports of goods and services, Current Prices, Not Seasonally Adjusted, Domestic Currency, Annual
RGDP Y X IMF:ANEA BTN.B1GQ.Q.XDC.A Gross Domestic Product, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Annual
RCPR Y X IMF:ANEA BTN.P3_PS.Q.XDC.A Final consumption expenditure, Private sector, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Annual
RCGG Y X IMF:ANEA BTN.P3_S13.Q.XDC.A Final consumption expenditure, General government, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Annual
RFCF Y X IMF:ANEA BTN.P51G.Q.XDC.A Gross fixed capital formation, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Annual
RCBI Y X IMF:ANEA BTN.P52.Q.XDC.A Changes in inventories, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Annual
RXGS Y X IMF:ANEA BTN.P6.Q.XDC.A Exports of goods and services, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Annual
RMGS Y X IMF:ANEA BTN.P7.Q.XDC.A Imports of goods and services, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Annual
NGDP Q NSA MANUAL:bhutan.csv NGDP Gross Domestic Product at Current Prices (Nu in Million), Quarterly
RGDP Q NSA MANUAL:bhutan.csv RGDP Real Domestic Product at Constant Prices (Nu in Million), Quarterly
BLR M X IMF:MFS_IR BTN.MFS162_RT_PT_A_PT.M Lending Rate, Percent per annum, Monthly
BDR M X IMF:MFS_IR BTN.MFS135_RT_PT_A_PT.M Deposit rate, Foreign Currency, Rate, Percent per annum, Monthly

Philippines

Concept Freq. Seasonal Provider API request Label
CPI M NSA IMF:CPI PHL.CPI._T.IX.M Consumer price index, All items, Index, Monthly
STMR M X IMF:MFS_IR PHL.MMRT_RT_PT_A_PT.M Money market Rate, Percent per annum, Monthly
USD M X IMF:ER PHL.XDC_USD.PA_RT.M Domestic currency per US Dollar, Period average, Monthly
NGDP Q NSA IMF:QNEA PHL.B1GQ.V.NSA.XDC.Q Gross Domestic Product, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NCPR Q NSA IMF:QNEA PHL.P3_PS.V.NSA.XDC.Q Final consumption expenditure, Private sector, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NCGG Q NSA IMF:QNEA PHL.P3_S13.V.NSA.XDC.Q Final consumption expenditure, General government, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NFCF Q NSA IMF:QNEA PHL.P51G.V.NSA.XDC.Q Gross fixed capital formation, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NCBI Q NSA IMF:QNEA PHL.P52.V.NSA.XDC.Q Changes in inventories, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NSDX Q NSA IMF:QNEA PHL.YA0.V.NSA.XDC.Q Statistical discrepancy (expenditure approach), Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NXGS Q NSA IMF:QNEA PHL.P6.V.NSA.XDC.Q Exports of goods and services, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NMGS Q NSA IMF:QNEA PHL.P7.V.NSA.XDC.Q Imports of goods and services, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RGDP Q NSA IMF:QNEA PHL.B1GQ.Q.NSA.XDC.Q Gross Domestic Product, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RCPR Q NSA IMF:QNEA PHL.P3_PS.Q.NSA.XDC.Q Final consumption expenditure, Private sector, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RCGG Q NSA IMF:QNEA PHL.P3_S13.Q.NSA.XDC.Q Final consumption expenditure, General government, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RFCF Q NSA IMF:QNEA PHL.P51G.Q.NSA.XDC.Q Gross fixed capital formation, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RCBI Q NSA IMF:QNEA PHL.P52.Q.NSA.XDC.Q Changes in inventories, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RSDX Q NSA IMF:QNEA PHL.YA0.Q.NSA.XDC.Q Statistical discrepancy (expenditure approach), Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RXGS Q NSA IMF:QNEA PHL.P6.Q.NSA.XDC.Q Exports of goods and services, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RMGS Q NSA IMF:QNEA PHL.P7.Q.NSA.XDC.Q Imports of goods and services, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly

India

Concept Freq. Seasonal Provider API request Label
CPI M NSA IMF:CPI IND.CPI._T.IX.M Consumer price index, All items, Index, Monthly
STGY M X FRED INDIR3TIB01STM Interest Rates: 3-Month or 90-Day Rates and Yields: Interbank Rates: Total for India, Percent, Not Seasonally Adjusted, Monthly
USD M X IMF:ER IND.XDC_USD.PA_RT.M Domestic currency per US Dollar, Period average, Monthly
NGDP Q NSA IMF:QNEA IND.B1GQ.V.NSA.XDC.Q Gross Domestic Product, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NCPR Q NSA IMF:QNEA IND.P3_PS.V.NSA.XDC.Q Final consumption expenditure, Private sector, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NCGG Q NSA IMF:QNEA IND.P3_S13.V.NSA.XDC.Q Final consumption expenditure, General government, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NFCF Q NSA IMF:QNEA IND.P51G.V.NSA.XDC.Q Gross fixed capital formation, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NCBI Q NSA IMF:QNEA IND.P52.V.NSA.XDC.Q Changes in inventories, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NSDX Q NSA IMF:QNEA IND.YA0.V.NSA.XDC.Q Statistical discrepancy (expenditure approach), Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NXGS Q NSA IMF:QNEA IND.P6.V.NSA.XDC.Q Exports of goods and services, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
NMGS Q NSA IMF:QNEA IND.P7.V.NSA.XDC.Q Imports of goods and services, Current Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RGDP Q NSA IMF:QNEA IND.B1GQ.Q.NSA.XDC.Q Gross Domestic Product, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RCPR Q NSA IMF:QNEA IND.P3_PS.Q.NSA.XDC.Q Final consumption expenditure, Private sector, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RCGG Q NSA IMF:QNEA IND.P3_S13.Q.NSA.XDC.Q Final consumption expenditure, General government, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RFCF Q NSA IMF:QNEA IND.P51G.Q.NSA.XDC.Q Gross fixed capital formation, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RCBI Q NSA IMF:QNEA IND.P52.Q.NSA.XDC.Q Changes in inventories, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RSDX Q NSA IMF:QNEA IND.YA0.Q.NSA.XDC.Q Statistical discrepancy (expenditure approach), Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RXGS Q NSA IMF:QNEA IND.P6.Q.NSA.XDC.Q Exports of goods and services, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly
RMGS Q NSA IMF:QNEA IND.P7.Q.NSA.XDC.Q Imports of goods and services, Constant Prices, Not Seasonally Adjusted, Domestic Currency, Quarterly