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

```bash
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:

```python
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:

```bash
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:

```python
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:

```python
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:

```python
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

```python
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)

```python
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:

```python
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](DATA_DICTIONARY.md) 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](DATA_DICTIONARY.md) and [RECOMMENDATIONS.md](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](API_REFERENCE.md) and [DATA_DICTIONARY.md](DATA_DICTIONARY.md). For additional recommendations (full CCP, FX disclosure, white paper), see [RECOMMENDATIONS.md](RECOMMENDATIONS.md).