id: temporal_return_period
name: return_period
description: >
  Derive empirical return-period thresholds from a 1-D timeseries using
  plotting-position rank statistics over the annual-maxima series.
  Hazard-agnostic — commonly applied to river discharge for flood-trigger
  threshold derivation in anticipatory-action recipes, but the same op is
  valid for precipitation, wind speed, surge height, or any positive
  extreme variable. Empirical (non-parametric) quantile only; GEV/Gumbel
  fitting and confidence intervals are out of scope for v0
  (see .tickets/impl/eap-recipe-bangladesh-floods/02-op-return-period.md).
version: 1.0.0
category: aggregate
type: timeseries-to-mapping
default_implementation: native

inputs:
  - name: series
    type: table
    description: >
      1-D timeseries with a time dimension. The op extracts annual
      maxima internally; sub-annual cadence (daily, hourly) is supported.
      Accepts an in-memory xarray DataArray or a path to a Parquet/NetCDF
      file with a single value column and a time index.
    required: true

requires: {}

outputs:
  - name: thresholds
    type: table
    description: >
      Mapping of {return_period_years -> value at that empirical
      return-period threshold}. Returned as a Python dict keyed by the
      input `return_periods` values.
  - name: annual_maxima
    type: table
    description: >
      The underlying annual-maxima series used to derive the thresholds,
      for transparency and provenance. xarray DataArray with one entry
      per water year.

params:
  return_periods:
    type: array
    items:
      type: number
    default: [2, 5, 10, 25, 50, 100]
    description: >
      Return periods in years to derive thresholds for. Values <= 1.0
      are rejected (return period < 1 year has no physical meaning for
      annual maxima).
  plotting_position:
    type: select
    options: [weibull, gringorten, hazen]
    default: weibull
    description: >
      Plotting-position formula. Weibull = i/(n+1) — operational
      hydrology default. Gringorten = (i-0.44)/(n+0.12) — closer to
      unbiased for Gumbel-distributed extremes. Hazen = (i-0.5)/n —
      US Weather Service historical convention. Rank i ascending of n
      annual maxima.
  water_year_start:
    type: select
    options: [jan, oct, jul]
    default: jan
    description: >
      Calendar month at which the water year begins. `jan` = calendar
      year (default; matches GloFAS reanalysis convention). `oct` = US
      water-year convention. `jul` = austral water year convention used
      in some southern-hemisphere monsoon basins.

# backends: audited 2026-08-14 (defect 50). A key means a runtime that DISPATCHES this op —
# folia-engine `dispatch_op` (products/sdk/folia-engine/src/lib.rs), a `registerOp`/OP_TABLE
# entry in packages/compute, `_BUILTIN_OP_MAP` in folia/compute.py, or a backend manifest
# (folia/backends/*/backend.yaml).
backends:
  python:
    function: temporal.ops.return_period
    dispatch: folia/compute.py _BUILTIN_OP_MAP

# Display hints: a return-period mapping is naturally tabular —
# a small two-column table (return_period_years, value).
display_hints:
  table:
    renderer: tanstack-table
    columns:
      - { field: return_period_years, header: "Return Period (years)" }
      - { field: value, header: "Threshold value" }