Getting Started with TimeDataModel
TimeDataModel is a lightweight Python data model for time series data. It gives you structured, metadata-rich time series objects with seamless bridges to pandas, numpy, and polars. This notebook walks you through the basics: creating a TimeSeriesList, inspecting it, and converting it.
Installation
pip install timedatamodel
# With optional extras
pip install timedatamodel[polars] # polars support
pip install timedatamodel[geo] # GeoArea support via shapely
Creating your first TimeSeriesList
A TimeSeriesList needs a frequency, timestamps, and values. You can optionally attach metadata like a name, unit, and data type.
[1]:
from datetime import datetime, timedelta, timezone
import timedatamodel as tdm
base = datetime(2024, 1, 15, tzinfo=timezone.utc)
timestamps = [base + timedelta(hours=i) for i in range(24)]
values = [
120.0, 115.0, 108.0, 105.0, 102.0, 100.0,
110.0, 135.0, 160.0, 175.0, 180.0, 178.0,
172.0, 170.0, 168.0, 165.0, 175.0, 190.0,
200.0, 195.0, 180.0, 165.0, 145.0, 130.0,
]
ts = tdm.TimeSeriesList(
tdm.Frequency.PT1H,
timezone="UTC",
timestamps=timestamps,
values=values,
name="power",
unit="MW",
description="Hourly power output from wind farm Alpha",
data_type=tdm.DataType.OBSERVATION,
)
Rich notebook display
Simply evaluate a TimeSeriesList in a cell to see its HTML representation — metadata and a data preview with head/tail rows.
[2]:
ts
[2]:
| timestamp | power |
|---|---|
| 2024-01-15 00:00 | 120.0 |
| 2024-01-15 01:00 | 115.0 |
| 2024-01-15 02:00 | 108.0 |
| … | … |
| 2024-01-15 21:00 | 165.0 |
| 2024-01-15 22:00 | 145.0 |
| 2024-01-15 23:00 | 130.0 |
DataPoints and iteration
Each element in a TimeSeriesList is a DataPoint — a named tuple of (timestamp, value). You can index, slice, and iterate.
[3]:
dp = ts[0]
print(f"First point: {dp}")
print(f" timestamp = {dp.timestamp}")
print(f" value = {dp.value}")
First point: DataPoint
┌────────────────────────────────┐
│ Timestamp: 2024-01-15 00:00 │
│ Timezone: UTC (+00:00) │
│ Value: 120.0 │
└────────────────────────────────┘
timestamp = 2024-01-15 00:00:00+00:00
value = 120.0
[4]:
ts[:3]
[4]:
[DataPoint
┌────────────────────────────────┐
│ Timestamp: 2024-01-15 00:00 │
│ Timezone: UTC (+00:00) │
│ Value: 120.0 │
└────────────────────────────────┘,
DataPoint
┌────────────────────────────────┐
│ Timestamp: 2024-01-15 01:00 │
│ Timezone: UTC (+00:00) │
│ Value: 115.0 │
└────────────────────────────────┘,
DataPoint
┌────────────────────────────────┐
│ Timestamp: 2024-01-15 02:00 │
│ Timezone: UTC (+00:00) │
│ Value: 108.0 │
└────────────────────────────────┘]
[5]:
for dp in ts.head(4):
print(f"{dp.timestamp:%H:%M} {dp.value:>6.1f} MW")
00:00 120.0 MW
01:00 115.0 MW
02:00 108.0 MW
03:00 105.0 MW
Inspecting properties
A TimeSeriesList exposes handy properties for quick inspection.
[6]:
print(f"Length: {len(ts)} points")
print(f"Begin: {ts.begin}")
print(f"End: {ts.end}")
print(f"Duration: {ts.duration}")
print(f"Has missing: {ts.has_missing}")
Length: 24 points
Begin: 2024-01-15 00:00:00+00:00
End: 2024-01-15 23:00:00+00:00
Duration: 23:00:00
Has missing: False
Creating from DataPoints
You can also construct a TimeSeriesList from a list of DataPoint objects.
[7]:
data = [
tdm.DataPoint(datetime(2024, 1, 15, h, tzinfo=timezone.utc), v)
for h, v in [(0, 5.2), (1, 5.8), (2, 6.1), (3, 5.5)]
]
ts_temp = tdm.TimeSeriesList(
tdm.Frequency.PT1H,
data=data,
name="temperature",
unit="°C",
)
ts_temp
[7]:
| timestamp | temperature |
|---|---|
| 2024-01-15 00:00 | 5.2 |
| 2024-01-15 01:00 | 5.8 |
| 2024-01-15 02:00 | 6.1 |
[ ]:
Summary
In this notebook you learned how to:
Create a
TimeSeriesListwith metadata (name, unit, data type)View its rich display in a notebook
Access individual
DataPointelements via indexing, slicing, and iterationInspect basic properties:
begin,end,duration,has_missing
Next up: nb_02 shows how to use numpy and pandas to transform time series data.