ere

Point-in-time data operations for Polars. Prevent look-ahead bias in quantitative research and backtesting.

The problem

When you join quarterly earnings onto daily prices using a naive merge, every row gets the final value, including restated figures that weren't published yet. Your backtest sees the future and the results are meaningless.

Standard tools have no concept of when a data point became known. ere fixes this by tracking two dates per row:

• ref_date: when the event occurred (e.g. fiscal quarter end)
• knowledge_date — the date you actually had it (e.g. SEC filing date)

After any as_of() call, every row satisfies knowledge_date <= query_date. No future information leaks.

Install

pip install ere

Requires Python >= 3.12 and Polars >= 1.0.

Quick start

from datetime import date
import polars as pl
import ere

PRICES = ere.TemporalSpec(ref_date="date", entity="ticker")
EARNINGS = ere.TemporalSpec(
    ref_date="fiscal_quarter_end",
    knowledge_date="filing_date",
    entity="ticker",
)

ere.validate(prices_df, spec=PRICES)
ere.validate(earnings_df, spec=EARNINGS)

# What did we know on Feb 1?
snap = ere.as_of(earnings_df, query_date="2025-02-01", spec=EARNINGS)
# AAPL shows original filing (1.50), not the restatement filed Feb 20 (1.42)

snap_later = ere.as_of(earnings_df, query_date="2025-03-01", spec=EARNINGS)
# now AAPL shows 1.42, the restated value

# Multi-source snapshot at one date
combined = ere.as_of(
    [(prices_df, PRICES), (earnings_df, EARNINGS)],
    query_date="2025-02-15",
)

# Multi-date snapshots for backtesting
rebalance_dates = [date(2025, 1, 31), date(2025, 2, 15), date(2025, 2, 28)]
snapshots = ere.panel(prices_df, spec=PRICES, dates=rebalance_dates, lookback=252)

# Post-hoc audit
ere.audit(earn_snap, as_of_date="2025-02-15", knowledge_date_col="filing_date")

API

* Also accepts a list/dict of (frame, spec) sources; see Multi-source snapshots below.

Key concepts

TemporalSpec binds your column names to temporal roles. Define it once per dataset:

SPEC = ere.TemporalSpec(
    ref_date="fiscal_quarter_end",  # when the event happened
    knowledge_date="filing_date",   # when it became known
    entity="ticker",                # optional grouping key
)

Restatements are handled automatically. If a data point is published multiple times (same entity + ref_date, different knowledge_dates), as_of() returns the latest version that was known at the query date.

Multi-source snapshots. Pass a list (or dict) of (frame, spec) pairs anywhere a single (frame, spec) goes. Each source is PIT-aligned independently, then asof-joined into one frame:

sources = [(prices_df, PRICES), (earnings_df, EARNINGS)]

snapshot = ere.as_of(sources, "2025-02-15")            # joined point-in-time view
panels   = ere.panel(sources, dates=rebalance_dates)   # multi-date snapshots

# Entity-less specs (no `entity=`) broadcast across entities automatically:
MACRO = ere.TemporalSpec(ref_date="release_period", knowledge_date="release_date")
with_macro = ere.as_of([*sources, (macro_df, MACRO)], "2025-02-15")

# Want them separate instead of merged? Use align:
per_source = ere.align(sources, "2025-02-15")          # -> [prices_snap, earn_snap]

Examples

Runnable end-to-end scripts live in examples/:

• quickstart.py — end-to-end backtest walkthrough: restatements, naive-join leakage, multi-date rebalancing.
• multi_source.py — list/dict sources, entity-less broadcasting, panel/panel_iter/align.
• panel_lazy.py — benchmarks as_of() loop vs panel_lazy/panel_map on second-granularity orderbook data.

Run any of them with uv run python examples/<name>.py.

License

MIT