time-anchor 0.1.0

Time-series forecasting and attribution utilities for Time-Anchor checkpoints.

---

license: apache-2.0 library_name: transformers tags:

• time-series
• forecasting
• explainability
• modernbert pipeline_tag: time-series-forecasting

---

Time-Anchor

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

📈 Quantile forecast	Probabilistic forecasts at any requested quantile levels
🧭 Variable / time impact	Normalized contribution of every input variable at every time step
📌 Anchor forecast	Forecasts conditioned on known future points you specify

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: mixing three equal-amplitude sinusoids with known weights recovers the mixing ratios — true weights 0.60/0.30/0.10 yield measured shares 0.55/0.33/0.12, and reordering the weights reorders the shares. In a regime-switch test the per-time-step impact follows whichever function is active in each half of the context.

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 — 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).