Output components¶

The output components turn the summary stream (from summarypy) into ORD result tables. They are implemented in pytools and are ORD-native — each tool writes the relevant ORD tables directly (CSV, binary, or parquet via -E/-f).

Result	pytools tool	ORD tables produced	Replaces (deprecated ktools)
Event loss table	`eltpy`	SELT, MELT, QELT	`eltcalc`
Period loss table	`pltpy`	SPLT, MPLT, QPLT	`pltcalc`
Loss exceedance (EP)	`lecpy`	EPT, PSEPT	`leccalc` / `ordleccalc`
Average annual loss	`aalpy`	ALT (AAL), ALCT	`aalcalc`
Concatenate partitions	`katpy`	—	`kat` / `katparquet`

The exact column layout of each ORD table is defined by the ORD standard (the ODS_OpenResultsData repository); see also the worked EP-curve analysis in the example notebooks. This page documents what each tool does and how it is run.

eltpy¶

eltpy produces event loss tables from a summary stream: the SELT (sample ELT), MELT (moment ELT — mean and standard deviation by event/summary) and QELT (quantile ELT).

Parameters — --run_dir; -i, --files_in; -s SELT, -m MELT, -q QELT (output files for each table); -E {csv,bin,parquet}; -H (no header).

Usage

summarypy -t gul -1 - < gul.bin | eltpy -s gul_selt.csv -m gul_melt.csv
eltpy -i gul_summary.bin -s gul_selt.csv

pltpy¶

pltpy produces period loss tables — SPLT (sample PLT), MPLT (moment PLT) and QPLT (quantile PLT) — with event occurrence dates from the occurrence file.

Parameters — --run_dir; -i, --files_in; -s SPLT, -m MPLT, -q QPLT; -E {csv,bin,parquet}; -H.

Internal data — input/occurrence.bin (to assign events to periods and dates).

Usage

summarypy -t il -1 - < il.bin | pltpy -s il_splt.csv -m il_mplt.csv

lecpy¶

lecpy computes loss exceedance (EP) curves — the ORD EPT (Exceedance Probability Table) and PSEPT (Per-Sample EPT). Losses are assigned to periods (typically years) via the occurrence file, then rank-ordered by period; the relative frequency of ranked period losses is the exceedance probability, expressed as a return period. Only non-zero loss periods are returned.

Losses within a period are combined per curve basis:

Aggregate (AEP) — sum of event losses in the period.
Occurrence (OEP) — maximum event loss in the period.

and the EP curve is computed by one of four methods (each available as an aggregate and an occurrence variant):

Full uncertainty — all sampled period losses rank-ordered into a single curve.
Wheatsheaf / per-sample — period losses rank-ordered per sample, giving one curve per sample (shows the variation due to damage uncertainty).
Sample mean — losses averaged across samples per period, then a single curve.
Wheatsheaf mean — the per-sample curves averaged at each return period.

The analytical mean loss (sidx = -1) is always output as its own curve; with zero samples only that curve is produced.

Parameters

-K, --subfolder — the work/ sub-directory holding the summary binaries.
-O, --ept / -o, --psept — output files for EPT / PSEPT.
Aggregate methods: -F full-uncertainty, -W wheatsheaf, -S sample-mean, -M wheatsheaf-mean.
Occurrence methods: -f, -w, -s, -m (same order).
-r — use a return-period file (input/returnperiods.bin) if present.

Internal data — input/occurrence.bin (required); optionally input/returnperiods.bin and input/periods.bin (period weighting). lecpy does not read a stream: it reads all summary binaries for a summary set from work/<subfolder>/ (the full event set must be written there first, since EP curves are not valid on an event subset).

Usage

# summary binaries for the set are first written to work/summary1/
lecpy -K summary1 -O ept.csv -F -f          # full-uncertainty AEP + OEP
lecpy -K summary1 -O ept.csv -o psept.csv -W -w   # wheatsheaf EPT + PSEPT

Period weightings — if input/periods.bin is present, per-period weights vary each period’s reoccurrence rate (neutral weight = 1 ÷ number of periods); zero-weight periods contribute nothing. All periods 1..P must appear (no gaps); the sum is unconstrained.

aalpy¶

aalpy computes the average annual loss table (ALT/AAL) and, optionally, the Average Loss Convergence Table (ALCT), which estimates the simulation error in the sample AAL. Analytical (type 1) and sample (type 2) statistics are produced; with zero samples only type 1 is returned.

Parameters — -K, --subfolder (the work/ sub-directory); -a, --aal (AAL output); -c, --alct (ALCT output); -M, --meanonly; -l, --confidence (ALCT confidence level); -E {csv,bin,parquet}.

Internal data — input/occurrence.bin (required); reads summary binaries from work/<subfolder>/ (like lecpy, not a stream). Optionally uses input/periods.bin for period weightings.

Usage

aalpy -K summary1 -a aal.csv                       # AAL
aalpy -K summary1 -a aal.csv -c alct.csv -l 0.95   # + ALCT at 95% confidence

Calculation — event losses are assigned to periods and summed by period and sample (“annual loss samples”). The AAL is the mean of annual losses over periods (type 1 from the numerically-integrated means, type 2 across all period×sample annual losses), with the standard deviation from the squared errors about the mean over the degrees of freedom.

The ALCT partitions the variance of the AAL estimate into hazard and vulnerability components with a one-factor ANOVA on the annual loss samples:

L(i,m) = AAL + h(i) + v(i,m)      # year i, sample m
Var(L) = Var(h) + Var(v)
Var(AAL estimate) = Var(v) / (I · M)   # events fixed across years → error is vulnerability-only

It reports the mean/SD, confidence interval, standard/relative error and the hazard vs vulnerability variance contributions, and repeats the statistics over increasing sample subsets (1, 2, 4, …) to show convergence of the AAL estimate with sample size.

katpy¶

katpy concatenates the per-partition output files (produced when the run is split across processes) into a single result file — CSV, parquet or binary.

Parameters — -o, --out (output file); -f, --file_type {csv,parquet,bin}; -i, --files_in (explicit files) or -d, --dir_in (a directory); one flag per ORD table type (-s SELT, -m MELT, …) to select what to concatenate.

Usage

katpy -s -d work/kat/gul_S1_elt_sample -o gul_S1_selt.csv          # concat SELT partitions (csv)
katpy -m -f parquet -i mplt_P1.parquet mplt_P2.parquet -o MPLT.parquet

See also: Core components · ORD output components (the ORD tables in detail) · Data conversion components.