🚀 v0.12.0 - (no changes, released for platform consistency)

(no changes — released for platform consistency)

🚀 v0.11.0 - (no changes, released for platform consistency)

(no changes — released for platform consistency)

🚀 v0.10.0 - (no changes, released for platform consistency)

(no changes — released for platform consistency)

🚀 v0.9.0 - (no changes, released for platform consistency)

(no changes — released for platform consistency)

🚀 v0.8.1 - (no changes, released for platform consistency)

(no changes — released for platform consistency)

🚀 v0.8.0 - (no changes, released for platform consistency)

Documentation-only: lowercased the canonical GitHub URLs (rebase-energy/TimeDataModel → timedatamodel) across the README, docs, and pyproject project URLs. No code or API changes.

🚀 v0.7.0 - (no changes — released for platform consistency)

Documentation-only: dropped bi-temporal vocabulary from the README, docs, and notebook.

🚀 v0.6.0 - (no changes — released for platform consistency)

(no changes — released for platform consistency)

🚀 v0.5.0 - TimeDataModel

TimeDataModel is a lightweight Python library that gives time series a metadata-rich container — name, unit, frequency, timezone, data type — travelling with the values as a single self-describing object. Backed by Polars internally and fully interoperable with pandas, NumPy, Polars, and PyArrow.

It is designed for energy, weather, and forecasting workflows where data arrives from many sources at different times — but it is general enough for any domain that works with timestamped numerical data. The same TimeSeries class doubles as a metadata-only declaration (no DataFrame attached), so series can be catalogued and registered before any data exists.

📈 The Series Model

Every TimeSeries carries identity, optional data, and metadata. The DataFrame is optional on purpose — the same class covers both data-bearing series and metadata-only declarations used for cataloging in downstream layers (TimeDB, EnergyDB).

Four temporal shapes select which timestamp columns are present in the underlying frame, inferred from the DataFrame at construction:

• 🟢 SIMPLE — valid_time + value. The classic point-in-time series.
• 🔵 VERSIONED — adds knowledge_time. Records when each value was produced (forecast revisions, prediction history).
• 🟠 CORRECTED — adds change_time. Records when each value was last revised (audit corrections).
• 🟣 AUDIT — both knowledge_time and change_time. Full bitemporal trail.

Metadata-only instances have shape is None; the same constructors and metadata fields apply.

✨ Key Features

• Self-describing container: name, unit, data_type, timeseries_type, frequency, timezone, and description travel with the values as one TimeSeries object.
• Polars-first, pandas-friendly: data is held in a Polars DataFrame internally. from_pandas / from_numpy / from_polars / from_pyarrow / from_list constructors normalize all common inputs; matching to_*() methods round-trip back out.
• Metadata-only mode: omit the DataFrame to declare a series before any data exists — same class for catalog entries and live series. Data-bearing methods raise ValueError until data is attached; ts.has_df reports the state.
• Four temporal shapes: switch between SIMPLE / VERSIONED / CORRECTED / AUDIT without changing the consuming code; shape is inferred from the columns at construction time.
• ISO 8601 frequencies: Frequency.PT1H, Frequency.P1D, Frequency.P1M, … — explicit, human-readable, and round-trip safe across libraries.
• Forecasting-aware data types: hierarchical DataType taxonomy (ACTUAL → OBSERVATION/DERIVED, CALCULATED → FORECAST/SIMULATION/…) so consumers can branch on the kind of value, not just the column name.
• Unit conversion at the boundary (with the [pint] extra): ts.convert_unit("kW") rescales while preserving identity and metadata.
• Geo primitives: GeoLocation (lat/lon point) and GeoArea (polygon) with distance, bearing, and containment — for series tied to physical locations.
• Tiny core: only polars required. Pandas, PyArrow, pint, shapely all live behind optional [pandas] / [pint] / [geo] / [all] extras.

🛠️ Getting Started

Install via pip:

pip install timedatamodel

Or with all optional integrations (pandas, pint, shapely, …):

pip install "timedatamodel[all]"

import pandas as pd
from timedatamodel import TimeSeries, Frequency

df = pd.DataFrame({
    "valid_time": pd.date_range("2024-01-01", periods=48, freq="h", tz="UTC"),
    "value": [float(i) for i in range(48)],
})

ts = TimeSeries.from_pandas(
    df,
    frequency=Frequency.PT1H,
    name="wind_power",
    unit="MW",
)
print(ts)

📚 Resources

• Documentation: https://timedatamodel.readthedocs.io
• Community: Join us on Slack
• License: MIT

📦 Related Projects

• TimeDB — bitemporal time-series database with auditability and overlapping-forecast support
• EnergyDataModel — data model for energy assets (solar, wind, battery, grid, …)
• EnergyDB — extends TimeDB with persistent storage for EnergyDataModel hierarchies

Full Changelog: https://github.com/rebase-energy/TimeDataModel/commits/v0.5.0

Are you using TimeDataModel in your work? We'd love to hear your feedback. Open an issue or join our Slack community to help us build a shared vocabulary for time series.

v0.3.0 Test Release

bump versions