tscp 0.1.0.dev0__py3-none-any.whl

tscp/data/io.py

@@ -0,0 +1,109 @@
+"""Self-contained ``.npz`` residual archives.
+
+A file holds every array of a :class:`~tscp.data.ResidualArchive` plus a JSON header with
+the format name, schema version, names, provenance and the archive fingerprint. Files are
+written without pickle, are never overwritten, and are checked against their fingerprint
+when loaded.
+"""
+
+import json
+from pathlib import Path
+
+import numpy as np
+import torch
+
+from tscp import __version__
+from tscp.data.archive import Graph, ResidualArchive
+from tscp.data.splits import SplitPlan
+
+FORMAT = "tscp.residual_archive"
+SCHEMA_VERSION = 2
+"""The schema version :func:`save_archive` writes. Version 2 added ``timestamps``."""
+READABLE_VERSIONS = (1, 2)
+"""Schema versions :func:`load_archive` reads."""
+
+_PLAIN = ("residuals", "origins", "steps", "forecasts", "context", "observed", "timestamps")
+_PREFIXES = ("split.", "output.", "graph.")
+
+
+def save_archive(archive: ResidualArchive, path: str | Path) -> None:
+    """Write ``archive`` to a new ``.npz`` file.
+
+    Raises:
+        FileExistsError: If ``path`` exists; archives are never overwritten.
+        ValueError: If the provenance is not JSON-serializable without NaN.
+    """
+    arrays = {name: value.detach().cpu().numpy() for name, value in archive.arrays().items()}
+    header = {
+        "format": FORMAT,
+        "schema_version": SCHEMA_VERSION,
+        "tscp_version": __version__,
+        "fingerprint": archive.fingerprint(),
+        "series": list(archive.series),
+        "context_names": list(archive.context_names),
+        "graph_num_nodes": None if archive.graph is None else archive.graph.num_nodes,
+        "provenance": dict(archive.provenance),
+    }
+    try:
+        text = json.dumps(header, sort_keys=True, allow_nan=False)
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"provenance must be JSON-serializable without NaN: {error}") from error
+    arrays["header"] = np.asarray(text)
+    with Path(path).open("xb") as handle:
+        np.savez_compressed(handle, **arrays)
+
+
+def load_archive(path: str | Path) -> ResidualArchive:
+    """Read an archive written by :func:`save_archive`, checking its fingerprint.
+
+    Raises:
+        ValueError: If the file is not a tscp archive, has another schema version, holds
+            unexpected arrays, or its arrays do not match the fingerprint in its header.
+    """
+    with np.load(path, allow_pickle=False) as data:
+        if "header" not in data.files:
+            raise ValueError(f"{path} is not a tscp residual archive: it has no header")
+        header = json.loads(str(data["header"].item()))
+        if header.get("format") != FORMAT:
+            raise ValueError(f"{path} is not a tscp residual archive")
+        if header.get("schema_version") not in READABLE_VERSIONS:
+            raise ValueError(
+                f"{path} has schema version {header.get('schema_version')}; "
+                f"this tscp reads versions {READABLE_VERSIONS}"
+            )
+        names = [name for name in data.files if name != "header"]
+        unexpected = [n for n in names if n not in _PLAIN and not n.startswith(_PREFIXES)]
+        if unexpected:
+            raise ValueError(f"{path} holds unexpected arrays: {unexpected}")
+        arrays = {name: torch.from_numpy(data[name]) for name in names}
+
+    splits = {n.removeprefix("split."): v for n, v in arrays.items() if n.startswith("split.")}
+    outputs = {n.removeprefix("output."): v for n, v in arrays.items() if n.startswith("output.")}
+    graph = None
+    if "graph.edge_index" in arrays:
+        graph = Graph(
+            edge_index=arrays["graph.edge_index"],
+            num_nodes=header["graph_num_nodes"],
+            edge_weight=arrays.get("graph.edge_weight"),
+        )
+    archive = ResidualArchive(
+        residuals=arrays["residuals"],
+        origins=arrays["origins"],
+        steps=arrays["steps"],
+        splits=SplitPlan(splits) if splits else None,
+        forecasts=arrays.get("forecasts"),
+        outputs=outputs,
+        context=arrays.get("context"),
+        context_names=tuple(header["context_names"]),
+        observed=arrays.get("observed"),
+        timestamps=arrays.get("timestamps"),
+        graph=graph,
+        series=tuple(header["series"]),
+        provenance=header["provenance"],
+    )
+    if archive.fingerprint() != header["fingerprint"]:
+        raise ValueError(f"{path}: the arrays do not match the fingerprint in the header")
+    return archive
+
+
+__all__ = ["FORMAT", "READABLE_VERSIONS", "SCHEMA_VERSION", "load_archive", "save_archive"]

tscp/data/splits.py

@@ -0,0 +1,169 @@
+"""Chronological split plans with no shared target times."""
+
+import math
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+
+import torch
+from torch import Tensor
+
+SPLIT_NAMES = ("fit", "validation", "calibration", "test")
+"""Split names in chronological order.
+
+``fit`` (and the optional ``validation``) are for trainable components; ``calibration``
+supplies the conformal scores; ``test`` is where regions are made and evaluated.
+"""
+
+
+def _rows(values, name: str) -> Tensor:
+    rows = torch.as_tensor(values)
+    if rows.ndim != 1 or rows.dtype.is_floating_point or rows.dtype == torch.bool:
+        raise ValueError(f"split {name!r} must be a vector of integer row indices")
+    rows = rows.to(torch.int64)
+    if rows.numel() == 0:
+        raise ValueError(f"split {name!r} is empty")
+    if rows[0] < 0 or (rows.diff() <= 0).any():
+        raise ValueError(f"split {name!r} rows must be nonnegative and strictly increasing")
+    return rows
+
+
+@dataclass(frozen=True, eq=False)
+class SplitPlan:
+    """Named sets of archive rows, in time order, that share no target time.
+
+    Rows are positions in the archive, not origins. :meth:`validate` checks the plan against
+    an archive's timeline; :class:`~tscp.data.ResidualArchive` does so on construction.
+
+    Args:
+        indices: Row indices per split name; names come from :data:`SPLIT_NAMES`.
+    """
+
+    indices: Mapping[str, Tensor]
+
+    def __post_init__(self):
+        unknown = sorted(set(self.indices) - set(SPLIT_NAMES))
+        if unknown:
+            raise ValueError(f"unknown split names {unknown}; use names from {SPLIT_NAMES}")
+        ordered = {
+            name: _rows(self.indices[name], name) for name in SPLIT_NAMES if name in self.indices
+        }
+        object.__setattr__(self, "indices", ordered)
+
+    @property
+    def names(self) -> tuple[str, ...]:
+        """Split names present, in time order."""
+        return tuple(self.indices)
+
+    def sizes(self) -> dict[str, int]:
+        """Number of rows per split."""
+        return {name: rows.numel() for name, rows in self.indices.items()}
+
+    def __getitem__(self, name: str) -> Tensor:
+        return self.indices[name]
+
+    def __contains__(self, name: object) -> bool:
+        return name in self.indices
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.indices)
+
+    def to(self, device: torch.device | str) -> "SplitPlan":
+        return SplitPlan({name: rows.to(device) for name, rows in self.indices.items()})
+
+    def validate(self, origins: Tensor, steps: Tensor) -> None:
+        """Check that the splits fit the timeline, keep time order and share no target time.
+
+        The target of (origin ``s``, step ``h``) is at time ``s + h``. Consecutive splits
+        must not share a target time, so the first target of a split must come after the
+        last target of the split before it. For steps ``1..H`` this means the first origin
+        of a split is at least ``H`` base steps after the last origin of the previous one.
+
+        Raises:
+            ValueError: If a split runs past the archive, overlaps or precedes the split
+                before it, or shares a target time with it.
+        """
+        num_rows = origins.numel()
+        previous: tuple[str, Tensor] | None = None
+        for name, rows in self.indices.items():
+            if rows[-1] >= num_rows:
+                raise ValueError(f"split {name!r} refers to row {int(rows[-1])}, past the archive")
+            if previous is not None:
+                previous_name, previous_rows = previous
+                last_origin = int(origins[previous_rows[-1]])
+                first_origin = int(origins[rows[0]])
+                if first_origin <= last_origin:
+                    message = f"split {name!r} must start after split {previous_name!r} ends"
+                    raise ValueError(message)
+                last_target = last_origin + int(steps[-1])
+                first_target = first_origin + int(steps[0])
+                if first_target <= last_target:
+                    needed = last_target - int(steps[0]) + 1
+                    raise ValueError(
+                        f"splits {previous_name!r} and {name!r} share target times: "
+                        f"{previous_name!r} has targets up to time {last_target}, so "
+                        f"{name!r} must start at origin {needed} or later, not {first_origin}"
+                    )
+            previous = (name, rows)
+
+
+def chronological_split(
+    origins: Tensor, steps: Tensor, sizes: Mapping[str, int | float | None]
+) -> SplitPlan:
+    """Cut consecutive splits in time order, skipping the origins needed between them.
+
+    Args:
+        origins: ``[T]`` forecast origins, strictly increasing.
+        steps: ``[H]`` horizon steps, strictly increasing.
+        sizes: Rows per split, keyed by names from :data:`SPLIT_NAMES` (any order; splits
+            are laid out in time order). An ``int`` is a row count, a ``float`` in (0, 1) a
+            fraction of all ``T`` rows (rounded down), and ``None``, allowed only for the
+            last split, takes every remaining row.
+
+    Returns:
+        A validated plan. Between two splits it skips the fewest rows that keep their
+        target times apart.
+
+    Raises:
+        ValueError: If a size is invalid or the archive has too few origins.
+    """
+    origins = torch.as_tensor(origins, dtype=torch.int64)
+    steps = torch.as_tensor(steps, dtype=torch.int64)
+    unknown = sorted(set(sizes) - set(SPLIT_NAMES))
+    if unknown:
+        raise ValueError(f"unknown split names {unknown}; use names from {SPLIT_NAMES}")
+    names = [name for name in SPLIT_NAMES if name in sizes]
+    if not names:
+        raise ValueError("sizes names no split")
+    num_rows = origins.numel()
+    indices: dict[str, Tensor] = {}
+    start = 0
+    for position, name in enumerate(names):
+        if indices:
+            last_target = origins[next(reversed(indices.values()))[-1]] + steps[-1]
+            # First row whose earliest target comes after the previous split's last target.
+            start = int(torch.searchsorted(origins, last_target - steps[0], right=True))
+        size = sizes[name]
+        if size is None:
+            if position != len(names) - 1:
+                raise ValueError(f"only the last split may take the remaining rows, not {name!r}")
+            count = num_rows - start
+        elif isinstance(size, bool) or not isinstance(size, int | float):
+            raise ValueError(f"size of split {name!r} must be an int, a float or None")
+        elif isinstance(size, float):
+            if not 0 < size < 1:
+                raise ValueError(f"fraction for split {name!r} must lie in (0, 1)")
+            count = math.floor(size * num_rows)
+        else:
+            count = size
+        if count < 1 or start + count > num_rows:
+            raise ValueError(
+                f"not enough origins for split {name!r}: it needs {count} rows from row {start}, "
+                f"and the archive has {num_rows} rows"
+            )
+        indices[name] = torch.arange(start, start + count)
+    plan = SplitPlan(indices)
+    plan.validate(origins, steps)
+    return plan
+
+
+__all__ = ["SPLIT_NAMES", "SplitPlan", "chronological_split"]

tscp/datasets/__init__.py

@@ -0,0 +1,6 @@
+"""Datasets as residual archives."""
+
+from . import synthetic
+from .synthetic import context_scale, gaussian_control, variance_shift
+
+__all__ = ["context_scale", "gaussian_control", "synthetic", "variance_shift"]

tscp/datasets/synthetic.py

@@ -0,0 +1,177 @@
+"""Synthetic residual archives.
+
+Both generators simulate a Gaussian random walk forecast by its last value, so the
+residual of (origin ``s``, step ``h``) is the sum of the next ``h`` innovations. Residuals
+over overlapping targets are correlated, as real multi-step errors are.
+
+Gaussian data are controls, for checking validity, not benchmarks.
+"""
+
+from collections.abc import Mapping
+from dataclasses import replace
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive, chronological_split
+
+DEFAULT_SIZES = {"fit": 0.2, "calibration": 0.3, "test": None}
+"""Default split sizes: 20% fit, 30% calibration, the rest test."""
+
+
+def _random_walk_archive(
+    scales: Tensor,
+    *,
+    horizon: int,
+    num_series: int,
+    sizes: Mapping[str, int | float | None] | None,
+    seed: int,
+    provenance: dict,
+) -> ResidualArchive:
+    if horizon < 1:
+        raise ValueError("horizon must be at least 1")
+    num_origins = scales.numel() - horizon
+    generator = torch.Generator().manual_seed(seed)
+    innovations = torch.randn(scales.numel(), num_series, generator=generator)
+    path = torch.cumsum(innovations * scales[:, None], dim=0)
+    steps = torch.arange(1, horizon + 1)
+    targets = torch.stack([path[step : num_origins + step] for step in steps.tolist()], dim=1)
+    forecasts = path[:num_origins, None, :].expand(-1, horizon, -1).clone()
+    origins = torch.arange(num_origins)
+    return ResidualArchive(
+        residuals=targets - forecasts,
+        origins=origins,
+        steps=steps,
+        splits=chronological_split(origins, steps, sizes or DEFAULT_SIZES),
+        forecasts=forecasts,
+        provenance={**provenance, "horizon": horizon, "seed": seed},
+    )
+
+
+def gaussian_control(
+    *,
+    horizon: int,
+    num_origins: int = 2000,
+    num_series: int = 1,
+    scale: float = 1.0,
+    sizes: Mapping[str, int | float | None] | None = None,
+    seed: int = 0,
+) -> ResidualArchive:
+    """A random walk with i.i.d. Gaussian innovations: an exchangeable control.
+
+    Args:
+        horizon: Number of steps ``H``; take it from the experiment config.
+        num_origins: Number of forecast origins ``T``.
+        num_series: Number of independent series ``N``.
+        scale: Innovation standard deviation.
+        sizes: Split sizes for :func:`~tscp.data.chronological_split`;
+            :data:`DEFAULT_SIZES` if None.
+        seed: Seed of the generator.
+    """
+    scales = torch.full((num_origins + horizon,), float(scale))
+    provenance = {"dataset": "gaussian_control", "role": "control", "scale": scale}
+    return _random_walk_archive(
+        scales,
+        horizon=horizon,
+        num_series=num_series,
+        sizes=sizes,
+        seed=seed,
+        provenance={**provenance, "forecaster": "last value"},
+    )
+
+
+def variance_shift(
+    *,
+    horizon: int,
+    num_origins: int = 2000,
+    num_series: int = 1,
+    shift_at: float = 0.75,
+    scale_before: float = 1.0,
+    scale_after: float = 3.0,
+    sizes: Mapping[str, int | float | None] | None = None,
+    seed: int = 0,
+) -> ResidualArchive:
+    """A Gaussian random walk whose innovation scale jumps once: not exchangeable.
+
+    With the default splits the jump falls inside the test period, so methods that
+    calibrate once under-cover after it, and adaptive ones should recover.
+
+    Args:
+        horizon: Number of steps ``H``; take it from the experiment config.
+        num_origins: Number of forecast origins ``T``.
+        num_series: Number of independent series ``N``.
+        shift_at: Fraction of the timeline after which the scale changes.
+        scale_before: Innovation standard deviation before the jump.
+        scale_after: Innovation standard deviation after the jump.
+        sizes: Split sizes; :data:`DEFAULT_SIZES` if None.
+        seed: Seed of the generator.
+    """
+    if not 0 < shift_at < 1:
+        raise ValueError("shift_at must lie in (0, 1)")
+    scales = torch.full((num_origins + horizon,), float(scale_before))
+    scales[int(shift_at * num_origins) :] = float(scale_after)
+    provenance = {
+        "dataset": "variance_shift",
+        "role": "shift",
+        "shift_at": shift_at,
+        "scale_before": scale_before,
+        "scale_after": scale_after,
+        "forecaster": "last value",
+    }
+    return _random_walk_archive(
+        scales,
+        horizon=horizon,
+        num_series=num_series,
+        sizes=sizes,
+        seed=seed,
+        provenance=provenance,
+    )
+
+
+def context_scale(
+    *,
+    horizon: int,
+    num_origins: int = 2000,
+    num_series: int = 1,
+    strength: float = 1.0,
+    sizes: Mapping[str, int | float | None] | None = None,
+    seed: int = 0,
+) -> ResidualArchive:
+    """A Gaussian random walk whose next innovation scale is set by a known covariate.
+
+    Each origin ``t`` has a covariate ``x_t``, a standard normal draw stored as the
+    context column ``x``, and the innovation that follows it has standard deviation
+    ``exp(strength * x_t)``. The one-step residual of origin ``t`` therefore has a known
+    conditional scale, and a score that learns the scale from the context gives narrower
+    intervals than one that ignores it. Gaussian, so a control, not a benchmark.
+
+    Args:
+        horizon: Number of steps ``H``; take it from the experiment config.
+        num_origins: Number of forecast origins ``T``.
+        num_series: Number of independent series ``N``.
+        strength: How strongly the covariate scales the innovations.
+        sizes: Split sizes; :data:`DEFAULT_SIZES` if None.
+        seed: Seed of the generator.
+    """
+    generator = torch.Generator().manual_seed(seed + 1)
+    covariate = torch.randn(num_origins + horizon, generator=generator)
+    scales = torch.ones(num_origins + horizon)
+    scales[1:] = torch.exp(strength * covariate[:-1])  # x_t scales the innovation at t + 1
+    provenance = {
+        "dataset": "context_scale",
+        "role": "control",
+        "strength": strength,
+        "forecaster": "last value",
+    }
+    archive = _random_walk_archive(
+        scales,
+        horizon=horizon,
+        num_series=num_series,
+        sizes=sizes,
+        seed=seed,
+        provenance=provenance,
+    )
+    return replace(archive, context=covariate[:num_origins, None], context_names=("x",))
+
+
+__all__ = ["DEFAULT_SIZES", "context_scale", "gaussian_control", "variance_shift"]

tscp/features/__init__.py

@@ -0,0 +1,22 @@
+"""Feature maps from what is known at each origin to vectors."""
+
+from .base import ENCODINGS, FeatureMap, encode_cycles, timeline_of
+from .calendar import FIELDS, Calendar, calendar_fields
+from .combine import Concat
+from .context import ContextColumns
+from .history import ResidualHistory
+from .phase import Phase
+
+__all__ = [
+    "ENCODINGS",
+    "FIELDS",
+    "Calendar",
+    "Concat",
+    "ContextColumns",
+    "FeatureMap",
+    "Phase",
+    "ResidualHistory",
+    "calendar_fields",
+    "encode_cycles",
+    "timeline_of",
+]

tscp/features/base.py

@@ -0,0 +1,64 @@
+"""The feature-map interface."""
+
+import math
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.utils import Component
+
+ENCODINGS = ("integer", "cyclic")
+"""How cyclic quantities such as the hour of day become features."""
+
+
+def timeline_of(rows: ResidualArchive) -> ResidualArchive:
+    """The archive ``rows`` were taken from; a whole archive is its own timeline."""
+    return rows.timeline if rows.timeline is not None else rows
+
+
+def encode_cycles(values: Tensor, periods: Tensor, encoding: str) -> Tensor:
+    """Encode ``[T, K]`` integer positions in cycles of the given ``[K]`` periods.
+
+    ``"integer"`` keeps the positions (``K`` features). ``"cyclic"`` gives the sine and
+    cosine of each position's angle in its cycle (``2 K`` features: all sines, then all
+    cosines), so that the end of a cycle lies next to its start.
+    """
+    if encoding not in ENCODINGS:
+        raise ValueError(f"encoding must be one of {ENCODINGS}, not {encoding!r}")
+    dtype = torch.get_default_dtype()
+    if encoding == "integer":
+        return values.to(dtype)
+    angles = 2 * math.pi * values.to(torch.float64) / periods.to(values.device, torch.float64)
+    return torch.cat([angles.sin(), angles.cos()], dim=-1).to(dtype)
+
+
+class FeatureMap(Component):
+    """Turns what is known at each origin into features.
+
+    :meth:`forward` returns ``[T, *element, F]`` for ``T`` rows: one vector of ``F``
+    features per row (element ``()``), per series (``(N,)``) or per step and series
+    (``(H, N)``). Weights compare these vectors, quantile models regress on them, and
+    Mondrian weights group by them.
+
+    The features of a row may use only what is known at its origin: its own forecasts,
+    outputs, context and timestamp, and the residuals of its timeline whose target time
+    has passed, which :meth:`~tscp.data.ResidualArchive.known_counts` finds. A row
+    subset's ``timeline`` holds that history; a whole archive is its own timeline
+    (:func:`timeline_of`).
+    """
+
+    def forward(self, rows: ResidualArchive) -> Tensor:
+        """Return ``[T, *element, F]`` features of the ``T`` rows."""
+        raise NotImplementedError
+
+    def valid(self, rows: ResidualArchive) -> Tensor | None:
+        """Return ``[T, *element]`` bool, False where a row's features are incomplete.
+
+        Incomplete features, such as a residual history before enough of it is known, are
+        0. None means every row's features are complete.
+        """
+        return None
+
+
+__all__ = ["ENCODINGS", "FeatureMap", "encode_cycles", "timeline_of"]

tscp/features/calendar.py

@@ -0,0 +1,105 @@
+"""Calendar fields of the origins' timestamps."""
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.features.base import ENCODINGS, FeatureMap, encode_cycles
+from tscp.registry import register
+
+FIELDS = {"minute": 60, "hour": 24, "dayofweek": 7, "day": 31, "month": 12, "dayofyear": 366}
+"""Calendar fields and the length of their cycle, for the cyclic encoding."""
+
+_FROM_ONE = ("day", "month", "dayofyear")  # fields that count from 1
+_NS_PER_SECOND = 1_000_000_000
+_SECONDS_PER_DAY = 86_400
+_MONTH_STARTS = (0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334)  # in a common year
+
+
+def _floordiv(a: Tensor, b: int) -> Tensor:
+    return torch.div(a, b, rounding_mode="floor")
+
+
+def calendar_fields(timestamps: Tensor) -> dict[str, Tensor]:
+    """Calendar fields of int64 nanosecond timestamps, in UTC, by integer arithmetic.
+
+    Dates follow the proleptic Gregorian calendar, by H. Hinnant's days-to-civil
+    algorithm, so they agree with Python's :mod:`datetime` before and after 1970.
+
+    Returns:
+        ``minute`` (0-59), ``hour`` (0-23), ``dayofweek`` (0 is Monday), ``day`` (1-31),
+        ``month`` (1-12) and ``dayofyear`` (1-366), each an int64 tensor shaped like
+        ``timestamps``.
+    """
+    seconds = _floordiv(timestamps, _NS_PER_SECOND)
+    days = _floordiv(seconds, _SECONDS_PER_DAY)
+    second_of_day = seconds - days * _SECONDS_PER_DAY
+    shifted = days + 719_468  # days since 0000-03-01
+    era = _floordiv(shifted, 146_097)
+    day_of_era = shifted - era * 146_097
+    year_of_era = _floordiv(
+        day_of_era
+        - _floordiv(day_of_era, 1_460)
+        + _floordiv(day_of_era, 36_524)
+        - _floordiv(day_of_era, 146_096),
+        365,
+    )
+    day_from_march = day_of_era - (
+        365 * year_of_era + _floordiv(year_of_era, 4) - _floordiv(year_of_era, 100)
+    )
+    month_from_march = _floordiv(5 * day_from_march + 2, 153)
+    day = day_from_march - _floordiv(153 * month_from_march + 2, 5) + 1
+    month = torch.where(month_from_march < 10, month_from_march + 3, month_from_march - 9)
+    year = year_of_era + era * 400 + (month <= 2).to(torch.int64)
+    leap = ((year % 4 == 0) & (year % 100 != 0)) | (year % 400 == 0)
+    starts = torch.tensor(_MONTH_STARTS, device=timestamps.device)
+    dayofyear = starts[month - 1] + day + ((month > 2) & leap).to(torch.int64)
+    return {
+        "minute": _floordiv(second_of_day, 60) % 60,
+        "hour": _floordiv(second_of_day, 3_600),
+        "dayofweek": (days + 3) % 7,  # 1970-01-01 was a Thursday
+        "day": day,
+        "month": month,
+        "dayofyear": dayofyear,
+    }
+
+
+@register("features", "calendar")
+class Calendar(FeatureMap):
+    """Calendar fields of each origin's timestamp: ``[T, F]``.
+
+    Fields come from the archive's ``timestamps``, in UTC; pass local times as if they
+    were UTC to get local fields. ``offset`` shifts the times first, for example by the
+    forecast step to read the fields of the targets. The ``"integer"`` encoding gives one
+    feature per field (see :func:`calendar_fields` for the ranges); ``"cyclic"`` gives the
+    sine and cosine of each field in its cycle (see :data:`FIELDS`).
+
+    Args:
+        fields: Names from :data:`FIELDS`.
+        encoding: ``"integer"`` or ``"cyclic"``.
+        offset: Nanoseconds added to each timestamp.
+    """
+
+    def __init__(self, fields=("hour",), encoding: str = "integer", offset: int = 0):
+        super().__init__()
+        fields = list(fields)
+        unknown = sorted(set(fields) - set(FIELDS))
+        if not fields or unknown:
+            raise ValueError(f"fields must name some of {sorted(FIELDS)}, not {unknown}")
+        if encoding not in ENCODINGS:
+            raise ValueError(f"encoding must be one of {ENCODINGS}, not {encoding!r}")
+        self.fields = fields
+        self.encoding = encoding
+        self.offset = int(offset)
+
+    def forward(self, rows: ResidualArchive) -> Tensor:
+        if rows.timestamps is None:
+            raise ValueError("Calendar needs an archive with timestamps")
+        values = calendar_fields(rows.timestamps + self.offset)
+        shift = int(self.encoding == "cyclic")  # cycles start at 0
+        columns = [values[f] - (shift if f in _FROM_ONE else 0) for f in self.fields]
+        periods = torch.tensor([FIELDS[field] for field in self.fields])
+        return encode_cycles(torch.stack(columns, dim=-1), periods, self.encoding)
+
+
+__all__ = ["FIELDS", "Calendar", "calendar_fields"]