Basic Usage

Creating a TimeSeries

From a pandas DataFrame

import pandas as pd
from timedatamodel import TimeSeries, Frequency

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

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

From a Polars DataFrame directly

import polars as pl
from timedatamodel import TimeSeries, Frequency

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

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

Slicing

first_six = ts.head(6)
last_six  = ts.tail(6)

Unit conversion

Requires the [pint] extra:

ts_kw = ts.convert_unit("kW")

Format conversions

All export methods return the full table (all columns including timestamps).

# Always available (polars is the base dependency)
df_pl  = ts.to_polars()       # pl.DataFrame
cols   = ts.to_list()         # dict[str, list] — column-oriented, datetime objects for timestamps

# Optional dependencies — raises ImportError with install hint if not present
arr = ts.to_numpy()    # dict[str, np.ndarray] — column-oriented; requires numpy
tbl = ts.to_pyarrow()  # pa.Table; requires pyarrow

# Pandas interop (requires timedatamodel[pandas])
df = ts.to_pandas()    # DatetimeTZDtype index per shape

to_pandas() restores the conventional index per shape — see the API reference.

Each export format has a matching constructor:

ts = TimeSeries.from_polars(df_pl, ...)
ts = TimeSeries.from_list(cols, ...)
ts = TimeSeries.from_numpy(arr, ...)    # requires numpy
ts = TimeSeries.from_pyarrow(tbl, ...)  # requires pyarrow
ts = TimeSeries.from_pandas(df, ...)    # requires pandas

Coverage bar

cb = ts.coverage_bar()   # CoverageBar — renders as SVG in Jupyter, Unicode blocks in terminal

Versioned series

import pandas as pd
from timedatamodel import TimeSeries, Frequency

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

ts = TimeSeries.from_pandas(
    df,
    frequency=Frequency.PT1H,
    name="forecast",
)