catagg 0.1.0.dev0__tar.gz → 0.1.0.dev1__tar.gz

catagg-0.1.0.dev1/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Docs build output
+site/
+
+# Environments
+.venv/
+venv/
+
+# OS
+.DS_Store

catagg-0.1.0.dev1/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- `simulate` now puts each year's occurrences in chronological order, drawn as
+  a uniform random permutation from a reserved child seed, and
+  `occurrence_index` is documented as that order. Previously occurrences were
+  grouped by peril in alphabetical order within each year, which would have
+  biased any cover consumed event by event towards the first peril. For a
+  fixed seed the YELT contains the same rows as before; only their order within
+  each year differs, so every order-free metric is unchanged.
+
+### Added
+
+- Financial module: `QuotaShare`, `ExcessOfLoss` (per occurrence, with a
+  required number of reinstatements and the annual cap
+  `limit * (1 + reinstatements)`), and `AggregateStopLoss`, chained by
+  `Programme` in inuring order. `Programme.apply` returns a `ProgrammeResult`
+  with gross, ceded and net loss per occurrence and each structure's cession.
+  Limited covers are consumed in chronological order within each year.
+  `net_loss + ceded_loss` equals `gross_loss` to within one unit in the last
+  place on every occurrence, and every structure's cession is checked to lie
+  between zero and the loss it was offered.
+- A `Structure` protocol, so custom structures can join a programme.
+- `column=` on `to_ylt` and `ep_curve`, to build curves from `ceded_loss` or
+  `net_loss`.
+
+- Repository scaffolding generated from the shared template: hatchling build
+  with src layout, ruff and mypy configuration, pytest setup, GitHub Actions
+  CI (lint, type-check, five-way test matrix, docs build, distribution build),
+  MkDocs Material documentation site, MIT licence, issue and pull request
+  templates.
+- Empty subpackages fixing the module layout: `io`, `frequency`, `severity`,
+  `dependence`, `simulate`, `financial`, `metrics`.
+- Packaging tests: version/metadata drift and `py.typed` installation.
+- Release workflow publishing to PyPI via Trusted Publishing, with a
+  tag-versus-package-version guard, and the release procedure documented in
+  `docs/releasing.md`.
+- ELT schema with `validate_elt`, which reports every failed check at once and
+  enforces the feasibility bound `std_loss**2 <= mean_loss * (exposure_value -
+  mean_loss)`; `read_elt` for Parquet and CSV.
+- Frequency models `Poisson` and `NegativeBinomial`, applied to a group's annual
+  event count rather than per event, so that specified over-dispersion survives
+  into the aggregate.
+- `simulate`, generating a year event loss table by rate-proportional allocation
+  of each group's annual occurrences; `to_ylt`, collapsing it to one row per
+  simulated year including years with no events.
+- `write_yelt` and `read_yelt`, round-tripping the simulated year count through
+  Parquet file metadata.
+- Closed-form references `analytic_aal`, `analytic_annual_loss_variance` and
+  `aal_standard_error`, used as the tolerances in the convergence tests.
+- `swiss_multiperil_elt`, a documented synthetic generator so the repository
+  runs from a clean clone with no data dependencies.
+- `BetaSeverity` and `SeverityRegime` in `catagg.severity`: a method-of-moments
+  beta fit on `[0, exposure_value]` with probability mass at the endpoints,
+  reproducing each event's mean and standard deviation to machine precision.
+  The endpoint masses are the boundary member of the beta family rather than
+  free parameters, since an ELT row carries two moments and cannot determine
+  four; see the simulation page for why.
+- `simulate(..., secondary_uncertainty=True)`, drawing loss given occurrence
+  from that fit. Severity uses a reserved child seed, so switching the flag on
+  leaves the frequency and allocation streams bit-identical. The flag is a
+  no-op, exactly, on an ELT whose variances are all zero.
+- Severity validation: per-event moment recovery against Monte Carlo standard
+  errors derived from the fit's own fourth moment, regime assignment at and
+  below the feasibility bound, and end-to-end agreement between the simulated
+  annual loss variance and `analytic_annual_loss_variance(...,
+  secondary_uncertainty=True)`.
+- `ep_curve` and `EPCurve` in `catagg.metrics`: OEP and AEP curves built from a
+  YELT or a YLT, with `at_return_period`, `tvar`, `to_frame` and the curve mean.
+  Quantiles use the Weibull plotting position, which is unbiased for the
+  exceedance probability of an order statistic; the `k / n` convention is not.
+- Monte Carlo standard errors on every figure those methods return. The quantile
+  error perturbs the probability level by the sampling deviation of the
+  empirical CDF, so it needs no bandwidth constant. The TVaR error adds a
+  `(1 - p) * (TVaR - VaR) ** 2` term for the uncertainty in the exceedance
+  threshold; without it the naive tail-mean error understates the truth by
+  between a fifth and a third. Both are checked against a replication study
+  rather than asserted.
+- `at_return_period` and `tvar` refuse return periods longer than the
+  simulation, rather than returning the largest simulated year as though it were
+  a return period.
+- `catagg.plot.ep_comparison`, drawing EP curves with their standard error band.
+  matplotlib is an optional extra (`pip install catagg[plot]`), not a runtime
+  dependency.
+- Simulation and metrics documentation pages.
+
+[Unreleased]: https://github.com/John-Amal/catagg/commits/main

{catagg-0.1.0.dev0 → catagg-0.1.0.dev1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: catagg
-Version: 0.1.0.dev0
+Version: 0.1.0.dev1
 Summary: Catastrophe loss aggregation, from event loss tables to net exceedance probability curves.
 Project-URL: Homepage, https://github.com/John-Amal/catagg
 Project-URL: Documentation, https://john-amal.github.io/catagg/
 Project-URL: Source, https://github.com/John-Amal/catagg
 Project-URL: Changelog, https://github.com/John-Amal/catagg/blob/main/CHANGELOG.md
 Project-URL: Issues, https://github.com/John-Amal/catagg/issues
-Author: Amal John
+Author-email: Amal John <amaljohn.met@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
 Keywords: actuarial,catastrophe-modelling,exceedance-probability,monte-carlo,reinsurance
@@ -24,13 +24,17 @@ Requires-Dist: pandas>=2.1
 Requires-Dist: pyarrow>=15.0
 Requires-Dist: scipy>=1.11
 Provides-Extra: dev
+Requires-Dist: matplotlib>=3.8; extra == 'dev'
 Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.2; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == 'plot'
 Description-Content-Type: text/markdown
 
 # catagg
@@ -52,7 +56,7 @@ A reinsurer holds a portfolio exposed to several perils. The catastrophe models
 
 `catagg` answers both. It simulates the year loss table, builds the gross exceedance probability curves, applies the reinsurance structures in the correct order, and returns gross, ceded and net views — with the validation checks that show the answer can be trusted.
 
-![Gross versus net OEP curve for the example Swiss multi-peril portfolio](docs/img/gross_vs_net_oep.png)
+![Gross versus net OEP curve for the example Swiss multi-peril portfolio](https://raw.githubusercontent.com/John-Amal/catagg/main/docs/img/gross_vs_net_oep.png)
 
 *Example portfolio: three perils, 20% quota share, a 50m xs 50m per-occurrence layer with two reinstatements, and a 100m aggregate stop-loss. The programme removes roughly two thirds of the 200-year occurrence loss — and the reinstatement cap is visible as the point where the net curve stops flattening.*
 
@@ -61,10 +65,12 @@ A reinsurer holds a portfolio exposed to several perils. The catastrophe models
 ## Install
 
 ```bash
-pip install catagg
+pip install --pre catagg          # early pre-release on PyPI
+# or the latest development version
+pip install git+https://github.com/John-Amal/catagg
 ```
 
-Python 3.11+. Runtime dependencies are numpy, pandas, pyarrow and scipy — nothing else.
+Python 3.11+. Runtime dependencies are numpy, pandas, pyarrow and scipy — nothing else. `catagg` is in active development towards v0.1.0; the API below may still change.
 
 ---
 
@@ -73,34 +79,28 @@ Python 3.11+. Runtime dependencies are numpy, pandas, pyarrow and scipy — noth
 ```python
 import catagg as ca
 
-# 1. Load an event loss table
-elt = ca.read_elt("portfolio.parquet")
+# 1. An event loss table (synthetic example portfolio; use ca.read_elt("portfolio.parquet") for your own)
+elt = ca.swiss_multiperil_elt(n_events=1_000, seed=0)
 
 # 2. Simulate 100,000 years
-yelt = ca.simulate(
-    elt,
-    n_years=100_000,
-    frequency="negative_binomial",   # or "poisson"
-    secondary_uncertainty=True,
-    seed=42,
-)
+yelt = ca.simulate(elt, n_years=100_000, secondary_uncertainty=True, seed=42)
 
 # 3. Gross view
-gross = ca.ep_curve(yelt)
+gross = ca.ep_curve(yelt, kind="OEP")
 print(gross.at_return_period([10, 50, 100, 200, 250]))
 
 # 4. Apply a reinsurance programme
 programme = ca.Programme([
     ca.QuotaShare(cession=0.20),
-    ca.ExcessOfLoss(attachment=50e6, limit=50e6, reinstatements=2, basis="occurrence"),
+    ca.ExcessOfLoss(attachment=50e6, limit=50e6, reinstatements=2),
     ca.AggregateStopLoss(attachment=100e6, limit=100e6),
 ])
-
 result = programme.apply(yelt)
-net = ca.ep_curve(result.net)
+net = ca.ep_curve(result.yelt, kind="OEP", column="net_loss")
 
 # 5. Compare
-ca.plot.ep_comparison({"Gross": gross, "Net": net}, kind="OEP")
+from catagg.plot import ep_comparison  # pip install "catagg[plot]"
+ep_comparison({"Gross": gross, "Net": net})
 ```
 
 Everything runs from a clean clone — the example portfolio is generated synthetically by a documented generator, so there are no data dependencies and no licensing questions.
@@ -127,16 +127,15 @@ If you already work in cat modelling, skip this. If you're reading the code to l
 
 **Frequency.** Poisson, or negative binomial where event clustering matters — European windstorm and hurricane seasons are both over-dispersed, and a Poisson assumption understates the aggregate tail.
 
-**Secondary uncertainty.** Loss given occurrence is sampled from a beta distribution on `[0, exposed_value]`, fitted by moments to the ELT's mean and standard deviation, with probability mass at zero and at full exposure. Degenerate cases — zero variance, or a variance the beta support cannot accommodate — are handled explicitly rather than silently clipped.
+**Secondary uncertainty.** Loss given occurrence is sampled from a beta distribution on `[0, exposed_value]`, fitted by moments to the ELT's mean and standard deviation. At the largest variance the support allows, that fit becomes the two-point law carrying probability mass at zero and at full exposure — the boundary member of the same family, reached continuously, rather than a free parameter. Degenerate cases — zero variance, or a variance the beta support cannot accommodate — are handled explicitly rather than silently clipped.
 
-**Dependence.** Perils are correlated through a Gaussian or Student-t copula applied to annual losses. Independence is the default; the example shows what assuming it costs you in the tail.
+**Dependence.** Perils are currently simulated independently. Correlating them through a copula is on the roadmap.
 
 **Financial structures.** Applied in programme order:
 
-- Quota share, with optional ceding commission
+- Quota share
 - Per-occurrence excess of loss: attachment, limit, *n* reinstatements at stated percentages, pro-rata to amount, with the aggregate cap of `limit × (1 + n)` enforced
 - Aggregate excess of loss and stop-loss
-- Franchise deductible
 
 **Metrics.** OEP, AEP, AAL, TVaR at any return period, full return-period tables, and Monte Carlo standard errors on every tail statistic.
 
@@ -144,7 +143,7 @@ If you already work in cat modelling, skip this. If you're reading the code to l
 
 ## Validation
 
-Numerical libraries in this domain live or die on whether you can show they're right. `catagg` ships a validation suite that runs in CI and as a readable notebook:
+Numerical libraries in this domain live or die on whether you can show they're right. `catagg` ships a validation suite that runs in CI on every commit:
 
 - Simulated AAL converges to the analytic `Σ λᵢ · μᵢ`
 - Sampled frequency moments match the specified Poisson or negative binomial
@@ -155,7 +154,7 @@ Numerical libraries in this domain live or die on whether you can show they're r
 
 That last one matters more than it looks. A 200-year return period estimated from 10,000 simulation years carries a standard error large enough to change decisions, and most workflows never report it. `catagg` reports it by default.
 
-See [docs/validation](https://john-amal.github.io/catagg/validation/).
+See [docs/validation](https://john-amal.github.io/catagg/validation/); a readable validation notebook with published results is in progress.
 
 ---
 
@@ -171,6 +170,7 @@ See [docs/validation](https://john-amal.github.io/catagg/validation/).
 
 ## Roadmap
 
+- **v0.1** — Gaussian and Student-t copulas across perils, ceding commission, franchise deductible, validation notebook
 - **v0.2** — location and policy-level terms, surplus share, reinstatement premium calculation
 - **v0.3** — OED-compatible ELT ingest, `oasislmf` interoperability
 - **v0.4** — event-level correlation across sub-perils, seasonality in event timing

{catagg-0.1.0.dev0 → catagg-0.1.0.dev1}/README.md

@@ -17,7 +17,7 @@ A reinsurer holds a portfolio exposed to several perils. The catastrophe models
 
 `catagg` answers both. It simulates the year loss table, builds the gross exceedance probability curves, applies the reinsurance structures in the correct order, and returns gross, ceded and net views — with the validation checks that show the answer can be trusted.
 
-![Gross versus net OEP curve for the example Swiss multi-peril portfolio](docs/img/gross_vs_net_oep.png)
+![Gross versus net OEP curve for the example Swiss multi-peril portfolio](https://raw.githubusercontent.com/John-Amal/catagg/main/docs/img/gross_vs_net_oep.png)
 
 *Example portfolio: three perils, 20% quota share, a 50m xs 50m per-occurrence layer with two reinstatements, and a 100m aggregate stop-loss. The programme removes roughly two thirds of the 200-year occurrence loss — and the reinstatement cap is visible as the point where the net curve stops flattening.*
 
@@ -26,10 +26,12 @@ A reinsurer holds a portfolio exposed to several perils. The catastrophe models
 ## Install
 
 ```bash
-pip install catagg
+pip install --pre catagg          # early pre-release on PyPI
+# or the latest development version
+pip install git+https://github.com/John-Amal/catagg
 ```
 
-Python 3.11+. Runtime dependencies are numpy, pandas, pyarrow and scipy — nothing else.
+Python 3.11+. Runtime dependencies are numpy, pandas, pyarrow and scipy — nothing else. `catagg` is in active development towards v0.1.0; the API below may still change.
 
 ---
 
@@ -38,34 +40,28 @@ Python 3.11+. Runtime dependencies are numpy, pandas, pyarrow and scipy — noth
 ```python
 import catagg as ca
 
-# 1. Load an event loss table
-elt = ca.read_elt("portfolio.parquet")
+# 1. An event loss table (synthetic example portfolio; use ca.read_elt("portfolio.parquet") for your own)
+elt = ca.swiss_multiperil_elt(n_events=1_000, seed=0)
 
 # 2. Simulate 100,000 years
-yelt = ca.simulate(
-    elt,
-    n_years=100_000,
-    frequency="negative_binomial",   # or "poisson"
-    secondary_uncertainty=True,
-    seed=42,
-)
+yelt = ca.simulate(elt, n_years=100_000, secondary_uncertainty=True, seed=42)
 
 # 3. Gross view
-gross = ca.ep_curve(yelt)
+gross = ca.ep_curve(yelt, kind="OEP")
 print(gross.at_return_period([10, 50, 100, 200, 250]))
 
 # 4. Apply a reinsurance programme
 programme = ca.Programme([
     ca.QuotaShare(cession=0.20),
-    ca.ExcessOfLoss(attachment=50e6, limit=50e6, reinstatements=2, basis="occurrence"),
+    ca.ExcessOfLoss(attachment=50e6, limit=50e6, reinstatements=2),
     ca.AggregateStopLoss(attachment=100e6, limit=100e6),
 ])
-
 result = programme.apply(yelt)
-net = ca.ep_curve(result.net)
+net = ca.ep_curve(result.yelt, kind="OEP", column="net_loss")
 
 # 5. Compare
-ca.plot.ep_comparison({"Gross": gross, "Net": net}, kind="OEP")
+from catagg.plot import ep_comparison  # pip install "catagg[plot]"
+ep_comparison({"Gross": gross, "Net": net})
 ```
 
 Everything runs from a clean clone — the example portfolio is generated synthetically by a documented generator, so there are no data dependencies and no licensing questions.
@@ -92,16 +88,15 @@ If you already work in cat modelling, skip this. If you're reading the code to l
 
 **Frequency.** Poisson, or negative binomial where event clustering matters — European windstorm and hurricane seasons are both over-dispersed, and a Poisson assumption understates the aggregate tail.
 
-**Secondary uncertainty.** Loss given occurrence is sampled from a beta distribution on `[0, exposed_value]`, fitted by moments to the ELT's mean and standard deviation, with probability mass at zero and at full exposure. Degenerate cases — zero variance, or a variance the beta support cannot accommodate — are handled explicitly rather than silently clipped.
+**Secondary uncertainty.** Loss given occurrence is sampled from a beta distribution on `[0, exposed_value]`, fitted by moments to the ELT's mean and standard deviation. At the largest variance the support allows, that fit becomes the two-point law carrying probability mass at zero and at full exposure — the boundary member of the same family, reached continuously, rather than a free parameter. Degenerate cases — zero variance, or a variance the beta support cannot accommodate — are handled explicitly rather than silently clipped.
 
-**Dependence.** Perils are correlated through a Gaussian or Student-t copula applied to annual losses. Independence is the default; the example shows what assuming it costs you in the tail.
+**Dependence.** Perils are currently simulated independently. Correlating them through a copula is on the roadmap.
 
 **Financial structures.** Applied in programme order:
 
-- Quota share, with optional ceding commission
+- Quota share
 - Per-occurrence excess of loss: attachment, limit, *n* reinstatements at stated percentages, pro-rata to amount, with the aggregate cap of `limit × (1 + n)` enforced
 - Aggregate excess of loss and stop-loss
-- Franchise deductible
 
 **Metrics.** OEP, AEP, AAL, TVaR at any return period, full return-period tables, and Monte Carlo standard errors on every tail statistic.
 
@@ -109,7 +104,7 @@ If you already work in cat modelling, skip this. If you're reading the code to l
 
 ## Validation
 
-Numerical libraries in this domain live or die on whether you can show they're right. `catagg` ships a validation suite that runs in CI and as a readable notebook:
+Numerical libraries in this domain live or die on whether you can show they're right. `catagg` ships a validation suite that runs in CI on every commit:
 
 - Simulated AAL converges to the analytic `Σ λᵢ · μᵢ`
 - Sampled frequency moments match the specified Poisson or negative binomial
@@ -120,7 +115,7 @@ Numerical libraries in this domain live or die on whether you can show they're r
 
 That last one matters more than it looks. A 200-year return period estimated from 10,000 simulation years carries a standard error large enough to change decisions, and most workflows never report it. `catagg` reports it by default.
 
-See [docs/validation](https://john-amal.github.io/catagg/validation/).
+See [docs/validation](https://john-amal.github.io/catagg/validation/); a readable validation notebook with published results is in progress.
 
 ---
 
@@ -136,6 +131,7 @@ See [docs/validation](https://john-amal.github.io/catagg/validation/).
 
 ## Roadmap
 
+- **v0.1** — Gaussian and Student-t copulas across perils, ceding commission, franchise deductible, validation notebook
 - **v0.2** — location and policy-level terms, surplus share, reinstatement premium calculation
 - **v0.3** — OED-compatible ELT ingest, `oasislmf` interoperability
 - **v0.4** — event-level correlation across sub-perils, seasonality in event timing

catagg-0.1.0.dev1/docs/financial.md

@@ -0,0 +1,92 @@
+# Financial structures
+
+!!! note "v0.1.0 is in development"
+
+    This page documents loss-side reinsurance mechanics. Premium, ceding
+    commission and reinstatement premium are not yet modelled.
+
+A `Programme` applies reinsurance structures to a simulated YELT and returns
+gross, ceded and net loss on every occurrence.
+
+```python
+import catagg as ca
+
+elt = ca.swiss_multiperil_elt(n_events=1_000, seed=0)
+yelt = ca.simulate(elt, n_years=100_000, secondary_uncertainty=True, seed=42)
+
+programme = ca.Programme([
+    ca.QuotaShare(cession=0.20),
+    ca.ExcessOfLoss(attachment=50e6, limit=50e6, reinstatements=2),
+    ca.AggregateStopLoss(attachment=100e6, limit=100e6),
+])
+result = programme.apply(yelt)
+
+gross = ca.ep_curve(result.yelt, kind="OEP")
+net = ca.ep_curve(result.yelt, kind="OEP", column="net_loss")
+```
+
+`result.yelt` holds `gross_loss`, `ceded_loss` and `net_loss` side by side, and
+`result.ceded_by_structure` holds each structure's own cession, labelled by
+position: `1_quota_share`, `2_excess_of_loss`, `3_aggregate_stop_loss`.
+
+## Programme order is inuring order
+
+Each structure protects what the structures before it left retained. In the
+programme above the quota share takes 20% of every gross loss; the 50m xs 50m
+layer then responds to the retained 80%, not to the gross; and the stop-loss
+responds to what the layer left. Reversing two structures changes the answer,
+so the order in the list is the order of application.
+
+## Structures
+
+| Structure | Pays, per occurrence | Running total |
+|---|---|---|
+| `QuotaShare(cession)` | `cession × retained` | None |
+| `ExcessOfLoss(attachment, limit, reinstatements)` | Retained loss above `attachment`, up to `limit` | Annual cap `limit × (1 + reinstatements)`, or none if `reinstatements=None` |
+| `AggregateStopLoss(attachment, limit)` | Its share of the annual recovery above `attachment` | Annual deductible, then annual `limit` |
+
+`reinstatements` has no default. Market terms vary too much for any default to
+be safe, and a silently assumed one would change every net figure.
+
+`AggregateStopLoss` takes its attachment and limit in money, which also makes
+it an aggregate excess of loss. A stop-loss quoted as a loss ratio converts to
+this form given the subject premium.
+
+## Order within the year
+
+The per-occurrence layer's annual cap and the stop-loss's deductible and limit
+are consumed in chronological order, using `occurrence_index` (see
+[Simulation](simulation.md#occurrence-order-is-chronological)). A 50 xs 50
+layer with two reinstatements pays at most 150 a year. Given layer losses of
+30, 50, 50 and 40 in that order, the fourth recovers only the 20 left. In the
+reverse order it is the 30 that is cut, to 10.
+
+Order never changes a structure's annual total, so AAL and AEP of ceded and net
+loss are unaffected by it. It does change which occurrence is cut off, and so
+the net loss per occurrence and the **net OEP**. Allocating the stop-loss
+recovery the same way is what gives a net OEP after an aggregate cover a
+definite meaning.
+
+## Conservation, in floating point
+
+Net loss is what remains after each structure's cession is taken off in turn,
+and `ceded_loss` is computed once, as `gross_loss − net_loss`. With that
+construction `net_loss + ceded_loss` equals `gross_loss` to within one unit in
+the last place on every occurrence: rounding one subtraction moves the result
+by at most half a unit, and adding back at most doubles it.
+
+That is the strongest form the identity can take in floating point. A bitwise
+equality is not attainable: for a 20% quota share alone, a few percent of
+occurrences differ from gross by one unit in the last place, whatever order the
+arithmetic is done in.
+
+`Programme.apply` also checks every structure's cession, including structures
+written outside the library against the `Structure` protocol: none may be
+negative, and none may exceed the loss it was offered. So net loss can never go
+negative.
+
+## API
+
+::: catagg.financial.structures
+
+::: catagg.financial.programme

{catagg-0.1.0.dev0 → catagg-0.1.0.dev1}/docs/index.md

@@ -18,6 +18,7 @@ Python 3.11+. Runtime dependencies are numpy, pandas, pyarrow and scipy.
 
 ## Where to start
 
+- **[Simulation](simulation.md)** — the ELT schema, frequency models and the year loop.
 - **[Validation](validation.md)** — the checks that show the numbers can be trusted.
 - **[API reference](api.md)** — the public surface.
 - **[Changelog](changelog.md)** — what changed, and when.

catagg-0.1.0.dev1/docs/metrics.md

@@ -0,0 +1,148 @@
+# Metrics
+
+!!! note "v0.1.0 is in development"
+
+    This page documents the gross view: EP curves, tail metrics and their Monte
+    Carlo error. For ceded and net curves, pass the result of a reinsurance
+    programme with `column="ceded_loss"` or `column="net_loss"`; see
+    [Financial structures](financial.md).
+
+An exceedance probability curve is the empirical distribution of a per-year
+loss, read from the tail. Two of them matter, and they answer different
+questions.
+
+**OEP**, occurrence exceedance probability, is the distribution of the largest
+single event in a year. It is what a per-occurrence layer responds to.
+**AEP**, aggregate exceedance probability, is the distribution of total annual
+loss. It is what aggregate cover and capital respond to. Both come from the
+same year loss table, so one simulation gives you both.
+
+```python
+import catagg as ca
+
+elt = ca.swiss_multiperil_elt(n_events=400, seed=0)
+yelt = ca.simulate(elt, n_years=50_000, seed=1, secondary_uncertainty=True)
+
+aggregate = ca.ep_curve(yelt, kind="AEP")
+print(aggregate.at_return_period([100, 200, 250]))
+print(aggregate.tvar(200))
+```
+
+`EPCurve` keeps the whole per-year loss vector rather than a summarised curve,
+so any return period, tail metric or standard error can be read afterwards
+without re-simulating.
+
+## Return periods, and which plotting position
+
+A return period $R$ is the reciprocal of an annual exceedance probability, so
+the loss at $R$ is the $1 - 1/R$ quantile of the annual loss. The quantile uses
+the **Weibull plotting position**, $k / (n + 1)$ for the $k$-th largest of $n$
+simulated years.
+
+That is not a cosmetic choice. For a continuous distribution $k / (n + 1)$ is
+unbiased for the exceedance probability of the $k$-th order statistic. The
+$k / n$ convention some vendor tools use is biased, and it cannot represent the
+largest simulated year at all without assigning it a zero exceedance
+probability — an infinite return period from one observation.
+
+## Refusing to extrapolate
+
+`at_return_period` raises rather than answering when the return period is longer
+than the simulation:
+
+```pycon
+>>> curve = ca.ep_curve(ca.simulate(elt, n_years=10_000, seed=1), kind="AEP")
+>>> curve.at_return_period(10_000)
+CataggError: return_period 10000 exceeds the 10000 simulated years...
+```
+
+Reading a 1-in-10,000 loss off 10,000 simulated years returns the single largest
+year and dresses one observation up as a return period. The library will not do
+it quietly.
+
+## TVaR
+
+Tail value at risk is the mean loss in the years that exceed a return period, so
+it answers what capital regimes actually ask: not "how bad is the 1-in-200 year"
+but "how bad is the average year worse than that". It is computed as the
+integrated expected shortfall over the largest $n / R$ years, with a fractional
+weight on the boundary year so the figure stays continuous in $R$ rather than
+jumping as the count crosses an integer.
+
+## Standard error is not optional
+
+Every figure this module returns carries the Monte Carlo standard error of the
+estimate, because a return period read off a simulation is a statistic and
+carries sampling error like any other. For the example portfolio the RP-200 AEP
+estimated from 10,000 simulation years has a standard error of around 8% —
+large enough to move a reinsurance decision, and almost never reported.
+
+Neither estimator introduces a tuning constant, and both are checked against a
+replication study rather than asserted.
+
+### Quantiles
+
+The empirical CDF at the quantile has standard deviation
+$\sqrt{p(1-p)/n}$. Perturbing the probability level by exactly that amount and
+reading the quantile function at both ends gives the sampling spread of the
+estimate, mapped through the distribution's own shape:
+
+$$\text{se} = \frac{Q(u + h) - Q(u - h)}{2}, \qquad u = 1 - p, \quad h = \sqrt{\frac{p\,(1-p)}{n}}$$
+
+This is the Siddiqui density-quantile estimator with the bandwidth pinned to the
+statistically natural scale rather than chosen. It needs no density estimate and
+degrades correctly in the far tail, where the spacing between order statistics
+is wide.
+
+### TVaR, and the mistake worth naming
+
+The tail mean over $k = np$ years is a mean, so the obvious estimator of its
+error is $s_{\text{tail}} / \sqrt{k}$.
+
+That estimator is wrong, and wrong in the dangerous direction. It treats the
+exceedance threshold as known when the threshold is itself estimated from the
+same sample. Against a replication study it **understates the true error by
+between a fifth and a third**. The correction restores what it omits:
+
+$$\text{se} = \sqrt{\frac{s_{\text{tail}}^2 + (1 - p)\,(\text{TVaR} - \text{VaR})^2}{k}}$$
+
+### How well they do
+
+Measured against 30 independent reruns of the same portfolio, as the ratio of
+the error a single run reports to the spread actually observed across runs:
+
+| Simulated years | Quantile | TVaR |
+|---|---|---|
+| 10,000 | 1.14 | 1.15 |
+| 100,000 | 0.98 | 0.99 |
+
+Both run slightly conservative at short simulations, which is the right
+direction for a number whose purpose is to stop someone over-reading a tail.
+The tests assert this ratio directly, so a change that quietly breaks an error
+estimate fails rather than shipping a comfortable, wrong number.
+
+## Plotting
+
+matplotlib is **not** a runtime dependency. The engine needs numpy, pandas,
+pyarrow and scipy, and a library that forces a plotting stack on everyone who
+imports it has made a decision on their behalf. Install the extra:
+
+```bash
+pip install catagg[plot]
+```
+
+```python
+from catagg.plot import ep_comparison
+
+ep_comparison({"Gross": aggregate}, title="Swiss multi-peril, gross")
+```
+
+The shaded band is plus or minus one standard error, drawn by default. At the
+long return periods on the right of the plot it is wide enough to change a
+decision, and a curve drawn as a clean line hides that.
+
+## API
+
+::: catagg.metrics.ep
+
+::: catagg.plot