# Examples

The examples catalog is organized by workflow. Every notebook is authored as a Jupytext `py:percent` file, executed from the Python source, and then synced to its paired `.ipynb`.

## Layout

```text
examples/
  README.md
  _shared/
  _fixtures/
  01_foundations/
  02_curves/
  03_bonds/
  04_analytics/
  05_portfolio/
  06_data_io/
  07_engine/
```

## How To Run

Install the notebook stack:

```bash
python -m pip install -e ".[examples]"
```

From the repository root:

```bash
python examples/03_bonds/01_fixed_rate_bonds_pricing_and_risk.py
python -m jupytext --sync examples/03_bonds/01_fixed_rate_bonds_pricing_and_risk.py
```

Run JupyterLab from the repository root so the `examples` package is importable without `sys.path` mutations inside notebook cells.

## Notebook Catalog

| Notebook | Goal | Runtime | Packages |
| --- | --- | --- | --- |
| `examples/01_foundations/01_dates_daycounts_and_calendars.ipynb` | Compare settlement, business-day adjustments, and accrued interest across calendars and day-count rules. | <10s | `core`, `bonds` |
| `examples/01_foundations/02_numerical_methods_for_term_structures.ipynb` | Show interpolation, extrapolation, solving, and fitting in a term-structure context. | <10s | `math`, `curves`, `core` |
| `examples/02_curves/01_curve_construction_and_value_conversions.ipynb` | Build rate and credit curves and translate between zero, discount, and forward views. | <10s | `curves`, `core`, `math` |
| `examples/02_curves/02_curve_calibration_piecewise_and_global_fit.ipynb` | Compare sequential bootstrap, global-fit calibration, cross-sectional fitted bond curves, and optional shadow-rate / jump-diffusion overlays on stylized USD data. | <10s | `curves`, `core`, `math`, `data`, `bonds` |
| `examples/02_curves/03_curve_scenarios_key_rates_and_multicurve.ipynb` | Apply parallel and key-rate shocks in a multi-curve environment. | <10s | `curves`, `bonds`, `core` |
| `examples/03_bonds/01_fixed_rate_bonds_pricing_and_risk.ipynb` | Walk through schedules, accrued, pricing, duration, convexity, and DV01 for fixed-rate bonds. | <10s | `bonds`, `core`, `analytics` |
| `examples/03_bonds/02_floating_rate_notes_fixings_and_discount_margin.ipynb` | Project FRN coupons from fixings and curves, then compare price and discount margin. | <10s | `bonds`, `analytics`, `curves`, `core` |
| `examples/03_bonds/03_callable_puttable_and_sinking_fund_structures.ipynb` | Compare bullet, callable/puttable, and sinking-fund cashflow structures. | <10s | `bonds`, `curves`, `core` |
| `examples/04_analytics/01_yield_measures_and_yas.ipynb` | Recreate a sell-side bond worksheet with multiple yield measures and YAS-style outputs. | <10s | `analytics`, `bonds`, `core`, `curves` |
| `examples/04_analytics/02_spread_toolkit_g_i_z_asw_oas.ipynb` | Compare spread measures, full asset-swap decomposition, balance-sheet overlays, CDS bootstrap and basis views, extend the workflow into fitted-curve local/global RV plus deterministic signal-to-trade hooks, and finish with a compact rates-options and delivery-option overlay example. | <10s | `analytics`, `bonds`, `credit`, `curves`, `funding`, `rates`, `core`, `data` |
| `examples/04_analytics/03_risk_hedging_and_var.ipynb` | Combine duration, key rates, hedge ratios, and VaR in one rates-and-credit risk worksheet. | <10s | `analytics`, `bonds`, `curves`, `core` |
| `examples/05_portfolio/01_portfolio_summary_bucketing_and_liquidity.ipynb` | Build a PM-style portfolio dashboard with buckets, spreads, and liquidity. | <10s | `portfolio`, `bonds`, `curves`, `core` |
| `examples/05_portfolio/02_benchmark_active_risk_and_attribution.ipynb` | Compare a portfolio with a benchmark and isolate active bets and attribution. | <10s | `portfolio`, `curves`, `bonds`, `core` |
| `examples/05_portfolio/03_stress_testing_key_rate_profiles_and_scenarios.ipynb` | Run parallel, spread, and key-rate stresses on the portfolio. | <10s | `portfolio`, `curves`, `core` |
| `examples/05_portfolio/04_etf_nav_basket_and_sec_yield.ipynb` | Turn the bond book into an ETF-style basket with NAV, premium/discount, and SEC yield. | <10s | `portfolio`, `bonds`, `curves`, `core` |
| `examples/06_data_io/01_market_data_reference_data_and_pricing_specs.ipynb` | Separate market data, reference data, and pricing specs for downstream workflows, then hand shared records into repo, futures, and CDS-ready funding/rates/credit objects. | <10s | `data`, `credit`, `funding`, `rates`, `core`, `engine` |
| `examples/06_data_io/02_file_json_and_sqlite_workflows.ipynb` | Load fixtures from files and store reproducible snapshots in JSON and SQLite. | <10s | `io`, `data`, `core` |
| `examples/07_engine/01_curve_builder_and_batch_pricing_router.ipynb` | Build curve bundles and route bond, tradable-rates, and funding/repo instruments through the dedicated engine routers. | <15s | `engine`, `data`, `bonds`, `curves`, `funding`, `rates`, `core` |
| `examples/07_engine/02_reactive_market_data_listener_and_scheduling.ipynb` | Show dirty-node propagation and scheduler concepts in the reactive engine. | <10s | `engine`, `data`, `core` |
| `examples/07_engine/03_end_to_end_research_pipeline.ipynb` | Run a deterministic end-to-end pipeline from fixtures to priced instruments to ETF and portfolio outputs. | <15s | `engine`, `data`, `io`, `portfolio`, `core` |

## Notebook Policy

- Notebook source of truth is the paired `.py` file in Jupytext `py:percent` format.
- Shared synthetic data builders and plotting helpers live under `examples/_shared/`.
- Curated deterministic fixtures live under `examples/_fixtures/`.
- Structured notebooks must not import `fuggers_py.traits`, `fuggers_py.ext`, `tests.*`, or mutate `sys.path`.
