get_derivation

Compute **capture price**, **capture rate** (a.k.a. value factor /
quality factor / Marktwertfaktor), **TBx battery-arbitrage spreads**,
and other generation-weighted market metrics server-side from landed
Parquet. Use this instead of fetching hourly prices + hourly generation
yourself and weighting them client-side — server-side aggregation has
no row cap and no pagination.

slug: a key from list_derivations() — today: "capture_price",
"negative_price_hours", "residual_load", "res_share",
"emissions", "tb_spread".

tb_spread returns monthly (default) or annual (aggregation='annual')
Top-Bottom spreads TB1/TB2/TB4/TB6 in <currency>/MW per period — the sum
of daily (top-x minus bottom-x hourly prices) over SDAC market days. The
only slug accepting aggregation, and the only one accepting
multi-zone zone ('all', a list, or CSV). Example — annual TB2 across
every European market in ONE call:
get_derivation("tb_spread", "2025-01-01", "2026-01-01",
zone="all", aggregation="annual")
For a single day's top/bottom hour TIMESTAMPS use get_tb_spread.

capture_price returns monthly rows per (zone, psr_type, currency) with
columns: currency, capture_price_eur_per_mwh, baseload_price_eur_per_mwh,
quality_factor (the capture rate = capture/baseload), total_gen_mwh,
n_hours. Months are bucketed by local time using the zone's IANA
timezone.

CURRENCY (capture_price and tb_spread alike): the *_eur_per_mwh /
tb*_eur_per_mw key names are FIXED for API stability and do NOT track
the actual unit — read the row's currency column, which is
authoritative (EUR for euro zones, GBP for GB, PLN/RON/BGN for the
PL/RO/BG local-currency eras). The response echoes it top-level as
currency; a window spanning two currencies instead sets unit to null
with mixed_currency: true and a currencies list. A month (or period)
spanning a redenomination splits into one row PER CURRENCY, each computed
only from that currency's hours — so never average or sum a price column
across rows with different currency values. Summing total_gen_mwh
across them IS correct: the split rows partition the month's hours rather
than duplicating them. quality_factor is a ratio and stays comparable
across currencies.

emissions returns monthly rows per (zone, psr_type) with columns:
generation_mwh, n_hours, emission_factor_kg_per_mwh, emissions_t_co2.
Production-based; IPCC AR5 lifecycle factors. Zero-emission rows
(nuclear, wind, solar, hydro, geothermal, marine) appear with
emissions_t_co2 = 0 — useful for stacked charts.

Filter via psr_types=["solar","wind_onshore","wind_offshore"] (or
raw B-codes like "B16") to get only the technologies you care about.
Defaults to all psr_types that have generation data.

Example — Spain solar capture price, last 12 months:
get_derivation("capture_price", "2025-05-01", "2026-05-01",
zone="ES", psr_types=["B16"], tz="Europe/Madrid")
Example — Germany 2024 emissions by fuel:
get_derivation("emissions", "2024-01-01", "2025-01-01",
zone="DE_LU", tz="Europe/Berlin")
Returns 12 monthly rows in one call; no pagination.