time-anchor

Time-Anchor

Source-code repository for the time-anchor Python package. Looking for the ready-to-use model and its model card? See K-Iwa/time-anchor-modernbert-32m. This repository bundles the same checkpoint under models/ so the code can be developed and tested self-contained.

A time-series forecasting package built around three outputs from one call:

Hourly temperature in Tokyo (Open-Meteo archive), 64-hour holdout: median MAE 0.57 °C, with every actual value inside the q10–q90 band.

Installation

python -m pip install -e .

Quick Start

import pandas as pd
from time_anchor import predict_time_anchor

url = (
    "https://archive-api.open-meteo.com/v1/archive"
    "?latitude=35.69&longitude=139.69&start_date=2024-10-01&end_date=2024-12-31"
    "&hourly=temperature_2m,relative_humidity_2m,surface_pressure,wind_speed_10m&format=csv"
)
weather = pd.read_csv(url, skiprows=3)
temperature = weather.iloc[:, 1].astype("float32")

result = predict_time_anchor(
    "models/time-anchor-modernbert-32m",
    target_context=temperature[:1440],
    prediction_length=64,
    quantile_levels=(0.1, 0.5, 0.9),
)
print(pd.DataFrame(result.forecast_rows))

The first argument may be a local checkpoint directory or a Hugging Face Hub model id. For a combined code/model repository, add subfolder="models/time-anchor-modernbert-32m".

Variable / Time-Step Impact

Per-hour contribution of each weather variable over a one-week Tokyo context. For each time_index, impact across all variables sums to 1.

result = predict_time_anchor(
    "models/time-anchor-modernbert-32m",
    target_context=temperature[:168],
    explanatory_contexts=[weather.iloc[:168, i].astype("float32") for i in (2, 3, 4)],
    gaf={"enabled": True, "topk_time_steps": 0},
)
print(pd.DataFrame(result.variable_impact_rows))

Validation: build a target with known ground truth, `target = 0.60f1 + 0.30f2

• 0.10*f3` from three sine waves, and pass the waves as explanatory series — the measured impact shares come out at 0.55 / 0.33 / 0.12, matching the true weights. Swapping the weights swaps the shares, and when the target switches drivers mid-context, each wave's per-time impact is higher in the half it drives. See the model card for the full validation.

Anchor Forecast

Monthly airline passengers (Box & Jenkins), 24-month holdout: pinning six known months cuts the median forecast MAE from 46 to 10 thousand passengers.

url = "https://raw.githubusercontent.com/jbrownlee/Datasets/master/airline-passengers.csv"
passengers = pd.read_csv(url)["Passengers"].astype("float32")

result = predict_time_anchor(
    "models/time-anchor-modernbert-32m",
    target_context=passengers[:-24],
    prediction_length=24,
    anchor={
        "mode": "observed",
        "positions": [4, 8, 12, 16, 20, 24],
        "values": [396, 559, 405, 461, 606, 432],
    },
)
print(pd.DataFrame(result.forecast_rows))

positions are 1-based forecast horizon steps. Anchor forecasts use the target history only; disable anchors when passing explanatory_contexts.

CLI

time-anchor-infer                                   # forecast + impact on the bundled sample
time-anchor-infer --no-impact                       # forecast only
time-anchor-infer --no-impact --anchor-mode observed \
    --anchor-positions 12,24,36 --anchor-values 0.2,0.4,0.1
time-anchor-infer --checkpoint K-Iwa/time-anchor-modernbert-32m --input data.csv

Outputs are written to output/forecast.csv, output/variable_impact.csv, and output/result.json. time-anchor-sine-test runs a sine-wave anchor evaluation (requires pip install -e ".[examples]").

Repository Layout

• src/time_anchor — model, pipeline, anchor samplers, and explainability code
• models/time-anchor-modernbert-32m — checkpoint and model card
• examples/sample_data.csv — small input file for smoke tests
• docs/publishing.md — Hugging Face / PyPI release checklist

Development

python -m pip install -e ".[dev]"
python -m ruff check .
python -m ruff format --check .
python -m pytest

References

• Ansari et al. Chronos: Learning the Language of Time Series. TMLR 2024 (OpenReview) — informs the forecasting/tokenization design.
• Azarkhalili and Libbrecht. Generalized Attention Flow: Feature Attribution for Transformer Models via Maximum Flow. 2025 — the variable/time impact method (GAF).

See docs/references.md, NOTICE, and CITATION.cff for attribution details.

License

Apache-2.0. Some source files retain upstream Amazon copyright notices.

Figures use historical weather data from Open-Meteo (CC BY 4.0) and the classic airline passengers dataset (Box & Jenkins, 1976).