API Reference

DataPoint

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

Parameters:

timestamp (datetime)
value (float | None)

timestamp: datetime: Alias for field number 0

value: float | None: Alias for field number 1

TimeSeries

TimeSeriesTable

class timedatamodel.TimeSeriesTable(frequency, *, timezone='UTC', timestamps=None, values, names=None, units=None, descriptions=None, data_types=None, locations=None, timeseries_types=None, attributes=None, labels=None, index_names=None)[source]

Bases: _TimeSeriesBase, _TimeSeriesTableReprMixin, _DataFrameMixin, _TimeSeriesTableOpsMixin, _TimeSeriesTableIOMixin, _TimeSeriesTableConverterMixin

Parameters:

frequency (Frequency)
timezone (str)
timestamps (list[datetime] | list[tuple[datetime, ...]] | None)
values (np.ndarray | list)
names (list[str | None])
units (list[str | None])
descriptions (list[str | None])
data_types (list[DataType | None])
locations (list[GeoLocation | GeoArea | None])
timeseries_types (list[TimeSeriesType])
attributes (list[dict[str, str]])
labels (list[dict[str, str]])
index_names (list[str] | None)

frequency: Frequency

timezone: str

names: list[str | None]

units: list[str | None]

descriptions: list[str | None]

data_types: list[DataType | None]

locations: list[GeoLocation | GeoArea | None]

timeseries_types: list[TimeSeriesType]

attributes: list[dict[str, str]]

labels: list[dict[str, str]]

property values: ndarray

property n_columns: int

property column_names: tuple[str, ...]

property has_missing: bool: True if any value is NaN.

convert_unit(target_unit, column=None)[source]

Return a new table with values converted to target_unit.

Parameters:

target_unit (str) – The unit to convert to.
column (int | str | None) – If None, convert all columns. Otherwise convert only the specified column (by index or name).

Return type:

TimeSeriesTable

filter_columns_by_location(center, radius_km)[source]

Keep only columns within radius_km of center.

Return type:

TimeSeriesTable

Parameters:

center (GeoLocation)
radius_km (float)

filter_columns_by_area(area)[source]

Keep only columns inside area.

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

nearest_columns(target, n=1)[source]

Keep the n nearest columns to target.

Return type:

TimeSeriesTable

Parameters:

target (GeoLocation)
n (int)

select_column(col)[source]

Extract a single column as a univariate TimeSeriesList.

Return type:: TimeSeriesList
Parameters:: col (int | str)

to_univariate_list()[source]

Convert to a list of univariate TimeSeriesList, one per column.

Return type:: list[‘TimeSeriesList’]

head(n=5)[source]

Return a new TimeSeriesTable with the first n points.

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

tail(n=5)[source]

Return a new TimeSeriesTable with the last n points.

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

copy()[source]

Return a shallow copy (timestamps list and values array are new).

Return type:: TimeSeriesTable

validate()[source]

Return a list of validation warnings.

Return type:: list[str]

TimeSeriesArray

class timedatamodel.TimeSeriesArray(frequency, *, timezone='UTC', name=None, unit=None, description=None, data_type=None, attributes=None, dimensions=None, values)[source]

Bases: _TimeSeriesArrayReprMixin

Parameters:

frequency (Frequency)
timezone (str)
name (str | None)
unit (str | None)
description (str | None)
data_type (DataType | None)
attributes (dict[str, str])
dimensions (list[Dimension])
values (np.ndarray | np.ma.MaskedArray)

frequency: Frequency

timezone: str

name: str | None

unit: str | None

description: str | None

data_type: DataType | None

attributes: dict[str, str]

dimensions: list[Dimension]

property shape: tuple[int, ...]

property ndim: int

property dim_names: tuple[str, ...]

property coords: dict[str, list]

property primary_time_dim: Dimension

property begin: datetime | float | str | None

property end: datetime | float | str | None

property has_missing: bool

sel(**kwargs)[source]

Return type:: TimeSeriesArray | ‘TimeSeriesTable’ | ‘TimeSeriesList

isel(**kwargs)[source]

Return type:: TimeSeriesArray | ‘TimeSeriesTable’ | ‘TimeSeriesList

to_timeseries(**sel_kwargs)[source]

Return type:: TimeSeriesList

to_table(**sel_kwargs)[source]

Return type:: TimeSeriesTable

to_numpy()[source]

Return type:: MaskedArray

to_pandas_dataframe()[source]

Return type:: pd.DataFrame

to_xarray()[source]

Convert to an xarray DataArray.

Each Dimension becomes a named coordinate. Masked values are exported as NaN. Metadata is stored in DataArray.attrs so that from_xarray can round-trip it.

Return type:: xr.DataArray

classmethod from_xarray(da, frequency=None, *, timezone=None, name=None, unit=None, description=None, data_type=None, attributes=None)[source]

Construct a TimeSeriesArray from an xr.DataArray.

Metadata is read from da.attrs but explicit keyword arguments take precedence.

Return type:

TimeSeriesArray

Parameters:

da (xr.DataArray)
frequency (Frequency | None)
timezone (str | None)
name (str | None)
unit (str | None)
description (str | None)
data_type (DataType | None)
attributes (dict[str, str] | None)

apply_xarray(func)[source]

Apply an xarray transformation, reading metadata from result.attrs with self as fallback.

Return type:: TimeSeriesArray

apply_pandas(func)[source]

Apply a pandas transformation to the array as a DataFrame.

Gated to arrays with at most 2 non-time dimensions.

Return type:: TimeSeriesArray

apply_polars(func)[source]

Apply a polars transformation to the array as a DataFrame.

Gated to arrays with at most 2 non-time dimensions.

Return type:: TimeSeriesArray

classmethod from_numpy(dimensions, values, frequency, *, timezone='UTC', name=None, unit=None, description=None, data_type=None, attributes=None)[source]

Return type:

TimeSeriesArray

Parameters:

dimensions (list[Dimension])
values (ndarray | MaskedArray)
frequency (Frequency)
timezone (str)
name (str | None)
unit (str | None)
description (str | None)
data_type (DataType | None)
attributes (dict[str, str] | None)

classmethod from_timeseries_list(series, dimension, *, frequency=None, timezone=None, name=None, unit=None, description=None, data_type=None, attributes=None)[source]

Return type:

TimeSeriesArray

Parameters:

series (list)
dimension (Dimension)
frequency (Frequency | None)
timezone (str | None)
name (str | None)
unit (str | None)
description (str | None)
data_type (DataType | None)
attributes (dict[str, str] | None)

equals(other)[source]

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

Dimension

class timedatamodel.Dimension(name, labels)[source]

Parameters:

name (str)
labels (list[datetime] | list[float] | list[str])

name: str

labels: list[datetime] | list[float] | list[str]

TimeSeriesCollection

class timedatamodel.TimeSeriesCollection(series=None, *, name=None, description=None)[source]

Container for TimeSeriesList and/or TimeSeriesTable objects that don’t share an index.

Items are stored internally as an ordered dict[str, TimeSeriesList | TimeSeriesTable].

Parameters:

series (list[TimeSeriesList | TimeSeriesTable] | dict[str, TimeSeriesList | TimeSeriesTable] | None)
name (str | None)
description (str | None)

property name: str | None

property description: str | None

property names: list[str]

property series_count: int

keys()[source]

values()[source]

items()[source]

add(item, name=None)[source]

Return type:

TimeSeriesCollection

Parameters:

item (TimeSeriesList | TimeSeriesTable)
name (str | None)

remove(name)[source]

Return type:: TimeSeriesCollection
Parameters:: name (str)

filter_by_location(center, radius_km)[source]

Keep series within radius_km of center.

Return type:

TimeSeriesCollection

Parameters:

center (GeoLocation)
radius_km (float)

filter_by_area(area)[source]

Keep series inside area.

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

nearest(target, n=1)[source]

Keep the n nearest series to target.

Return type:

TimeSeriesCollection

Parameters:

target (GeoLocation)
n (int)

to_pandas_dataframe()[source]

Outer-join all series into a single pandas DataFrame.

Each series becomes a column named by its key. The index is the union of all timestamps (outer join), with NaN for missing values.

Return type:: pd.DataFrame

to_pd_df()[source]

Alias for to_pandas_dataframe().

Return type:: pd.DataFrame

to_polars_dataframe()[source]: Outer-join all series into a single polars DataFrame.

to_pl_df()[source]: Alias for to_polars_dataframe().

to_numpy()[source]

Return each series as a numpy array in a dict keyed by series name.

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

property arr: dict[str, np.ndarray]: Shorthand for to_numpy().

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'

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)

AggregationMethod

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

SUM = 'sum'

MEAN = 'mean'

MIN = 'min'

MAX = 'max'

HierarchyNode

class timedatamodel.HierarchyNode(key, level, children=<factory>, timeseries=None, location=None, _parent=None)[source]

Parameters:

key (str)
level (str)
children (list[HierarchyNode])
timeseries (TimeSeriesList | None)
location (GeoLocation | GeoArea | None)
_parent (HierarchyNode | None)

key: str

level: str

children: list[HierarchyNode]

timeseries: TimeSeriesList | None

location: GeoLocation | GeoArea | None

property is_leaf: bool

property parent: HierarchyNode | None

property siblings: list[HierarchyNode]

property depth: int

property path: list[str]

property leaf_count: int

HierarchyTree

class timedatamodel.HierarchyTree(root)[source]

Displayable tree visualization for a HierarchicalTimeSeries.

Parameters:: root (HierarchyNode)

HierarchicalTimeSeries

class timedatamodel.HierarchicalTimeSeries(root, *, name=None, description=None, aggregation=AggregationMethod.SUM, levels=None)[source]

Bases: _HierarchicalTimeSeriesReprMixin

A tree of time series organised into named hierarchy levels.

Parameters:

root (HierarchyNode)
name (str | None)
description (str | None)
aggregation (AggregationMethod)
levels (list[str] | None)

classmethod from_dict(tree, series_map, *, levels=None, name=None, description=None, aggregation=AggregationMethod.SUM)[source]

Build from a nested dict and a flat series mapping.

Example:

tree = {"Norway": {"Bergen": "bergen_ts", "Oslo": "oslo_ts"}}
series_map = {"bergen_ts": ts_bergen, "oslo_ts": ts_oslo}

Return type:

HierarchicalTimeSeries

Parameters:

tree (dict)
series_map (dict[str, TimeSeriesList])
levels (list[str] | None)
name (str | None)
description (str | None)
aggregation (AggregationMethod)

classmethod from_dataframe(df, level_columns, value_column, timestamp_column=None, *, name=None, description=None, aggregation=AggregationMethod.SUM, frequency=None, timezone='UTC')[source]

Build from a long-format pandas DataFrame with hierarchy columns.

Return type:

HierarchicalTimeSeries

Parameters:

level_columns (list[str])
value_column (str)
timestamp_column (str | None)
name (str | None)
description (str | None)
aggregation (AggregationMethod)
timezone (str)

property root: HierarchyNode

property name: str | None

property description: str | None

property levels: list[str]

property n_levels: int

property n_leaves: int

property n_nodes: int

property frequency: Frequency

property timezone: str

property unit: str | None

property begin: datetime | None

property end: datetime | None

get_node(*path)[source]

Navigate to a node by key path.

Return type:: HierarchyNode
Parameters:: path (str)

get_level(level)[source]

All nodes at a given level name or depth index.

Return type:: list[HierarchyNode]
Parameters:: level (str | int)

leaves()[source]

All leaf nodes.

Return type:: list[HierarchyNode]

walk(order='pre')[source]

Yield nodes in pre-order or post-order.

Return type:: Iterator[HierarchyNode]
Parameters:: order (str)

subtree(*path)[source]

Extract sub-hierarchy rooted at the given path.

Return type:: HierarchicalTimeSeries
Parameters:: path (str)

aggregate(node=None, method=None, auto_align=False)[source]

Recursive bottom-up aggregation.

Return type:

TimeSeriesList

Parameters:

node (HierarchyNode | None)
method (AggregationMethod | None)
auto_align (bool)

aggregate_level(level, method=None, auto_align=False)[source]

Aggregate every node at level.

Return type:

dict[str, TimeSeriesList]

Parameters:

level (str | int)
method (AggregationMethod | None)
auto_align (bool)

to_collection(level=None)[source]

Flatten to a TimeSeriesCollection.

Return type:: TimeSeriesCollection
Parameters:: level (str | int | None)

to_table(level=None)[source]

Flatten to a TimeSeriesTable (requires shared timestamps).

Return type:: TimeSeriesTable
Parameters:: level (str | int | None)