API Reference

TimeSeries

class timedatamodel.TimeSeries(df=None, *, name, description=None, unit='dimensionless', timezone='UTC', frequency=None, data_type=None, timeseries_type=TimeSeriesType.FLAT)[source]

Bases: _TimeSeriesReprMixin

Polars-backed container for time series data with rich metadata.

The underlying df is optional. Construct with df=None to declare a series structure (name, unit, data type, …) before any data exists — useful for registering series in a catalog. Methods that need data (converters, head/tail, convert_unit, …) raise ValueError when no df is attached. Use has_df to check.

Parameters:

df (DataFrame | None) – A polars.DataFrame whose columns conform to one of the recognised DataShape patterns, or None for a metadata-only instance. All timestamp columns must use pl.Datetime("us", time_zone="UTC").
name (str) – Series name (e.g. "wind_power", "electricity.supply").
description (str | None) – Human-readable description.
unit (str) – Canonical physical unit string (e.g. "MW", "dimensionless").
timezone (str) – IANA timezone string for display purposes. Internal data is always UTC; this is a metadata hint only.
frequency (Frequency | None) – Pandas offset alias describing the expected data cadence.
data_type (DataType | None) – Semantic nature of the observations (DataType).
timeseries_type (TimeSeriesType) – Storage/versioning model (TimeSeriesType).

property shape: DataShape | None

Which temporal columns are present (inferred from the DataFrame).

None for metadata-only instances.

property num_rows: int: Number of data rows. 0 for metadata-only instances.

property columns: list[str]

Column names present in the underlying Polars DataFrame.

Empty list for metadata-only instances.

property df: DataFrame | None

The underlying polars.DataFrame (read-only by convention).

None for metadata-only instances.

property has_df: bool: True when a DataFrame is attached.

property has_missing: bool

True if the value column contains any null values.

False for metadata-only instances.

classmethod from_polars(df, *, name, description=None, unit='dimensionless', timezone='UTC', frequency=None, data_type=None, timeseries_type=TimeSeriesType.FLAT)[source]

Create a TimeSeries directly from a polars.DataFrame.

All timestamp columns must already use pl.Datetime("us", time_zone="UTC").

Return type:

TimeSeries

Parameters:

df (DataFrame)
name (str)
description (str | None)
unit (str)
timezone (str)
frequency (Frequency | None)
data_type (DataType | None)
timeseries_type (TimeSeriesType)

classmethod from_list(data, *, name, description=None, unit='dimensionless', timezone='UTC', frequency=None, data_type=None, timeseries_type=TimeSeriesType.FLAT)[source]

Create a TimeSeries from a column-oriented dict of lists.

Accepts the format returned by to_list(). Timestamp columns are normalised to UTC automatically.

Return type:

TimeSeries

Parameters:

data (dict[str, list])
name (str)
description (str | None)
unit (str)
timezone (str)
frequency (Frequency | None)
data_type (DataType | None)
timeseries_type (TimeSeriesType)

classmethod from_numpy(data, *, name, description=None, unit='dimensionless', timezone='UTC', frequency=None, data_type=None, timeseries_type=TimeSeriesType.FLAT)[source]

Create a TimeSeries from a column-oriented dict of NumPy arrays.

Accepts the format returned by to_numpy(). Timestamp columns (numpy.datetime64, always timezone-naive) are localised to UTC.

Requires numpy.

Return type:

TimeSeries

Parameters:

data (dict[str, np.ndarray])
name (str)
description (str | None)
unit (str)
timezone (str)
frequency (Frequency | None)
data_type (DataType | None)
timeseries_type (TimeSeriesType)

classmethod from_pyarrow(table, *, name, description=None, unit='dimensionless', timezone='UTC', frequency=None, data_type=None, timeseries_type=TimeSeriesType.FLAT)[source]

Create a TimeSeries from a PyArrow Table.

Accepts the format returned by to_pyarrow(). Arrow timestamp[us, UTC] columns are converted automatically.

Requires pyarrow.

Return type:

TimeSeries

Parameters:

table (pa.Table)
name (str)
description (str | None)
unit (str)
timezone (str)
frequency (Frequency | None)
data_type (DataType | None)
timeseries_type (TimeSeriesType)

classmethod from_pandas(df, *, name, description=None, unit='dimensionless', timezone='UTC', frequency=None, data_type=None, timeseries_type=TimeSeriesType.FLAT)[source]

Create a TimeSeries from a pandas.DataFrame.

Only SIMPLE and VERSIONED shapes can be constructed via from_pandas. AUDIT and CORRECTED shapes (which require a change_time column) are read-only results from the database layer.

The data shape is inferred from the column names (and MultiIndex levels if the DataFrame uses an index).

Raises:

ValueError – If the DataFrame contains a change_time column.

Return type:

TimeSeries

Parameters:

df (DataFrame)
name (str)
description (str | None)
unit (str)
timezone (str)
frequency (Frequency | None)
data_type (DataType | None)
timeseries_type (TimeSeriesType)

validate_for_insert()[source]

Validate that this TimeSeries can be inserted and return the underlying DataFrame with its shape.

Only DataShape.SIMPLE and DataShape.VERSIONED are supported for insert.

Return type:: tuple[DataFrame, DataShape]
Raises:: ValueError – If shape is DataShape.AUDIT or DataShape.CORRECTED.

to_pandas()[source]

Convert to a pandas.DataFrame.

Restores the conventional index:

SIMPLE — valid_time as index.
VERSIONED — (knowledge_time, valid_time) MultiIndex.
AUDIT — (knowledge_time, change_time, valid_time) MultiIndex.
CORRECTED — (valid_time, change_time) MultiIndex.

Return type:: DataFrame

to_polars()[source]

Return the underlying polars.DataFrame.

Return type:: DataFrame

to_list()[source]

Return the series as a column-oriented dict of lists.

Each key is a column name; each value is a Python list of that column’s values. Timestamps are Python datetime objects; null values are None.

Example:

{"valid_time": [datetime(...), ...], "value": [1.0, None, 3.0, ...]}

Return type:: dict

to_numpy()[source]

Return the series as a dictionary of NumPy arrays.

Each column maps to a 1-D numpy.ndarray. Timestamp columns become numpy.datetime64[us] values; null values become NaN or NaT.

Requires numpy. Install with: pip install numpy.

Return type:: dict[str, np.ndarray]

to_pyarrow()[source]

Return the series as a pyarrow.Table.

All timestamp columns are Arrow timestamp[us, UTC].

Requires pyarrow. Install with: pip install pyarrow.

Return type:: pa.Table

coverage_bar()[source]

Return a CoverageBar showing value coverage.

True = value present, False = null/missing. In Jupyter the coverage bar renders as an SVG.

Return type:: CoverageBar

head(n=5)[source]

Return the first n rows as a new TimeSeries.

Return type:: TimeSeries
Parameters:: n (int)

tail(n=5)[source]

Return the last n rows as a new TimeSeries.

Return type:: TimeSeries
Parameters:: n (int)

convert_unit(target_unit)[source]

Return a new TimeSeries with values converted to target_unit.

Uses the pint library for unit conversion. The unit metadata field is updated to target_unit.

Parameters:

target_unit (str) – Target unit string understood by pint (e.g. "km/h", "kW").

Raises:

ImportError – If pint is not installed.
pint.DimensionalityError – If the current unit and target_unit are dimensionally incompatible.

Return type:

TimeSeries

metadata_dict()[source]

Return all metadata fields as a plain dict.

Return type:: dict

DataShape

class timedatamodel.DataShape(*values)[source]

Which temporal columns are present in the underlying data store.

SIMPLE = 'SIMPLE'

VERSIONED = 'VERSIONED'

AUDIT = 'AUDIT'

CORRECTED = 'CORRECTED'

Frequency

class timedatamodel.Frequency(*values)[source]

P1Y = 'P1Y'

P3M = 'P3M'

P1M = 'P1M'

P1W = 'P1W'

P1D = 'P1D'

PT1H = 'PT1H'

PT30M = 'PT30M'

PT15M = 'PT15M'

PT10M = 'PT10M'

PT5M = 'PT5M'

PT1M = 'PT1M'

PT1S = 'PT1S'

NONE = 'NONE'

property is_calendar_based: bool

to_timedelta()[source]

Return type:: timedelta | None

DataType

class timedatamodel.DataType(*values)[source]

ACTUAL = 'ACTUAL'

OBSERVATION = 'OBSERVATION'

DERIVED = 'DERIVED'

CALCULATED = 'CALCULATED'

ESTIMATION = 'ESTIMATION'

FORECAST = 'FORECAST'

PREDICTION = 'PREDICTION'

SCENARIO = 'SCENARIO'

SIMULATION = 'SIMULATION'

RECONSTRUCTION = 'RECONSTRUCTION'

REFERENCE = 'REFERENCE'

BASELINE = 'BASELINE'

BENCHMARK = 'BENCHMARK'

IDEAL = 'IDEAL'

property parent: DataType | None

property children: list[DataType]

property is_leaf: bool

property root: DataType

TimeSeriesType

class timedatamodel.TimeSeriesType(*values)[source]

FLAT = 'FLAT'

OVERLAPPING = 'OVERLAPPING'

DataPoint

class timedatamodel.DataPoint(timestamp, value)[source]

A single (timestamp, value) observation.

Supports tuple-style access for backwards compatibility: ts, val = datapoint and datapoint[0] both work.

Parameters:

timestamp (datetime)
value (float | None)

timestamp

value

GeoLocation

class timedatamodel.GeoLocation(latitude, longitude)[source]

Parameters:

latitude (float)
longitude (float)

latitude: float

longitude: float

distance_to(other, unit='km')[source]

Haversine great-circle distance to other.

Return type:

float

Parameters:

other (GeoLocation)
unit (str)

bearing_to(other)[source]

Initial bearing in degrees [0, 360) from self to other.

Return type:: float
Parameters:: other (GeoLocation)

midpoint(other)[source]

Geographic midpoint on the great circle.

Return type:: GeoLocation
Parameters:: other (GeoLocation)

offset(distance_km, bearing_deg)[source]

New point displaced by distance_km along bearing_deg.

Return type:

GeoLocation

Parameters:

distance_km (float)
bearing_deg (float)

is_within(area)[source]

True if this point is inside area.

Return type:: bool
Parameters:: area (GeoArea)

GeoArea

class timedatamodel.GeoArea(polygon, name=None)[source]

Parameters:

polygon (Polygon)
name (str | None)

polygon: Polygon

name: str | None

property bounds: tuple[float, float, float, float]

property centroid: GeoLocation

classmethod from_coordinates(coords, name=None)[source]

Create a GeoArea from a list of (lat, lon) coordinate pairs.

Return type:

GeoArea

Parameters:

coords (list[tuple[float, float]])
name (str | None)

contains_point(location)[source]

True if location is inside this area.

Return type:: bool
Parameters:: location (GeoLocation)

contains_area(other)[source]

True if other is entirely inside this area.

Return type:: bool
Parameters:: other (GeoArea)

overlaps(other)[source]

True if this area and other share any space.

Return type:: bool
Parameters:: other (GeoArea)

distance_to(other)[source]

Approximate distance in km (centroid-based Haversine).

Returns 0.0 if the point is contained or the areas overlap.

Return type:: float
Parameters:: other (GeoLocation | GeoArea)

classmethod bounding_box(center, radius_km, name=None)[source]

Create a rectangular area centered on center with half-side radius_km.

Return type:

GeoArea

Parameters:

center (GeoLocation)
radius_km (float)
name (str | None)