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_forecastis 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¶
Data¶
Country models¶
| # | 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¶
- Set up the environment and run everything from the project root.
- Update and refresh the datastore with
datastore_pumps.update_all. - Build the external environment: US first, then CN, JP and EA.
- Run focus countries: PH, IN, and then BT.
- Work through the nine steps in order, pausing at the review gates.
- 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 |