FOUR-QUADRANT_BALANCE_SHEET_MATRIX/docs/USER_GUIDE.md

FQBM User Guide and Tutorial

This guide walks you through installing, running, and interpreting the Four-Quadrant Balance Sheet Matrix (FQBM) framework.

---

1. Install

cd FOUR-QUADRANT_BALANCE_SHEET_MATRIX
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

Optional: pip install pytest for tests; pip install streamlit for the Streamlit dashboard.

---

2. Quick start: run the workbook

The workbook runs all eight sheets (central bank, commercial bank, capital stress, FX parity, sovereign debt, commodity, Monte Carlo, dashboard) in one go:

from fqbm.workbook.runner import run_workbook
from fqbm.state import FQBMState

state = FQBMState(B=100, R=50, C=20, Loans=800, Deposits=700, E_cb=30, E_b=100)
result = run_workbook(initial_state=state, mc_runs=50, export_path="out.xlsx")

Or from the command line:

python -m fqbm.workbook.runner

This produces a result dictionary (and optionally an Excel file) with keys such as state, stress_tables, fx_parity, sovereign, commodity, monte_carlo, dashboard, and ipsas (if requested).

---

3. Using scenarios (Part XI)

Use built-in historical scenarios instead of building state by hand:

from fqbm.workbook.runner import run_workbook

run_workbook(scenario="asia_1997", mc_runs=100, export_path="asia_1997.xlsx")
run_workbook(scenario="gfc_2008", mc_runs=100)
run_workbook(scenario="pandemic_2020", mc_runs=50)
run_workbook(scenario="rate_shock_2022", mc_runs=50)

List scenarios and get structured narrative:

from fqbm.scenarios.presets import list_scenarios, get_scenario, get_case_narrative

print(list_scenarios())  # ['asia_1997', 'gfc_2008', 'pandemic_2020', 'rate_shock_2022']
preset = get_scenario("gfc_2008")
case = get_case_narrative("gfc_2008")  # narrative, state_summary, key_drivers, suggested_shocks

---

4. Interpreting stress tables and Monte Carlo

• Capital stress (result["stress_tables"]): capital and leverage under different shock assumptions; see Sheet 3.
• Monte Carlo (result["monte_carlo"]): distribution of outcomes (e.g. equity, deposits) over many runs; use percentiles for VaR-style analysis.
• Dashboard (result["dashboard"]): aggregated view of key ratios and totals.

---

5. IPSAS layer and export

Generate IPSAS-style outputs from state:

from fqbm.state import FQBMState
from fqbm.ipsas.presentation import (
    statement_of_financial_position,
    budget_vs_actual_structure,
    budget_actual_from_state,
    cash_flow_from_state_changes,
    statement_of_financial_position_comparative,
)

state = FQBMState(B=100, R=50, C=20, Loans=800, Deposits=700, E_cb=30, E_b=100)
df = statement_of_financial_position(state, entity="central_bank")
# Comparative: prior vs current
state_prior = state.copy()
state_prior.B = 80
comparative = statement_of_financial_position_comparative(state_prior, state, entity="central_bank")
# Budget vs actual from state
budget_df = budget_actual_from_state(state, budget={"Total assets": 900, "Total liabilities": 650})
# Cash flow from balance sheet changes
cashflow = cash_flow_from_state_changes(state_prior, state)

Excel export (when export_path is set) includes IPSAS-style sheets when available.

---

6. Matrix and cross-sector check

from fqbm.state import FQBMState
from fqbm.matrix import four_quadrant_matrix, four_quadrant_summary, cross_sector_consistency_check

state = FQBMState(B=100, R=50, C=20, Loans=800, Deposits=700, E_cb=30, E_b=100)
matrix_df = four_quadrant_matrix(state)
summary = four_quadrant_summary(state)
check = cross_sector_consistency_check(state)  # consistent, cb_balance, bank_balance, message

---

7. Differential model and stability (Part XIV)

from fqbm.system.differential_model import solve_trajectory, check_stability, DifferentialParams
import numpy as np

params = DifferentialParams()
x0 = [100, 50, 20, 800, 700, 30, 100, 1.0, 0.0, 0.02, 1.0, 0.0]
t_span = (0, 10)
sol = solve_trajectory(x0, t_span, params)
stable = check_stability(params)

---

8. Empirical regressions (Part X)

Synthetic data and regression helpers for inflation pass-through, sovereign spread, and capital flow sensitivity:

from fqbm.empirical.regressions import (
    run_inflation_pass_through,
    run_sovereign_spread,
    run_capital_flow_sensitivity,
)

df_inf = run_inflation_pass_through(n=100)
df_spread = run_sovereign_spread(n=100)
df_cap = run_capital_flow_sensitivity(n=100)

Required columns for each model are documented in the Data dictionary and in the module docstrings.

---

9. Optional features

• Streamlit dashboard: streamlit run scripts/streamlit_dashboard.py
• CBDC / CCP / repo: workbook accepts cbdc_params, ccp_params, shadow_params. State has cbdc_liability after a CBDC shift; IPSAS presentation shows it. Repo multiplier is always in result["dashboard"]["repo_multiplier"] (optional shadow_params to customize haircut/rounds).
• Real data: from fqbm.data.pipelines import fetch_fed_h41, fetch_bis_series, fetch_imf_series for Fed H.4.1, BIS bulk CSV (e.g. credit_gap, total_credit), and IMF (optional api_key). Pipelines can be extended (e.g. more series, caching, retries); see DATA_DICTIONARY.md and RECOMMENDATIONS.md.
• FX parity: Sheet 4 and fqbm.sheets.fx_parity (CIP, UIP, Dornbusch, pass-through).

For more detail on the API, see API_REFERENCE.md and DATA_DICTIONARY.md. For additional recommendations (full CCP, FX disclosure, white paper), see RECOMMENDATIONS.md.