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 TimeSeries, 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 TimeSeries

A TimeSeries needs a frequency, timestamps, and values. You can optionally attach metadata like a name, unit, and data type.

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.TimeSeries(
    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.MEASUREMENT,
)

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
Cell In[1], line 3
      1 from datetime import datetime, timedelta, timezone
----> 3 import timedatamodel as tdm
      5 base = datetime(2024, 1, 15, tzinfo=timezone.utc)
      6 timestamps = [base + timedelta(hours=i) for i in range(24)]

ModuleNotFoundError: No module named 'timedatamodel'

Rich notebook display

Simply evaluate a TimeSeries in a cell to see its HTML representation — metadata and a data preview with head/tail rows.

ts

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[2], line 1
----> 1 ts

NameError: name 'ts' is not defined

DataPoints and iteration

Each element in a TimeSeries is a DataPoint — a named tuple of (timestamp, value). You can index, slice, and iterate.

dp = ts[0]
print(f"First point: {dp}")
print(f"  timestamp = {dp.timestamp}")
print(f"  value     = {dp.value}")

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[3], line 1
----> 1 dp = ts[0]
      2 print(f"First point: {dp}")
      3 print(f"  timestamp = {dp.timestamp}")

NameError: name 'ts' is not defined

ts[:3]

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[4], line 1
----> 1 ts[:3]

NameError: name 'ts' is not defined

for dp in ts.head(4):
    print(f"{dp.timestamp:%H:%M}  {dp.value:>6.1f} MW")

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[5], line 1
----> 1 for dp in ts.head(4):
      2     print(f"{dp.timestamp:%H:%M}  {dp.value:>6.1f} MW")

NameError: name 'ts' is not defined

Inspecting properties

A TimeSeries exposes handy properties for quick inspection.

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}")

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[6], line 1
----> 1 print(f"Length:      {len(ts)} points")
      2 print(f"Begin:       {ts.begin}")
      3 print(f"End:         {ts.end}")

NameError: name 'ts' is not defined

Creating from DataPoints

You can also construct a TimeSeries from a list of DataPoint objects.

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.TimeSeries(
    tdm.Frequency.PT1H,
    data=data,
    name="temperature",
    unit="°C",
)
ts_temp

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[7], line 2
      1 data = [
----> 2     tdm.DataPoint(datetime(2024, 1, 15, h, tzinfo=timezone.utc), v)
      3     for h, v in [(0, 5.2), (1, 5.8), (2, 6.1), (3, 5.5)]
      4 ]
      6 ts_temp = tdm.TimeSeries(
      7     tdm.Frequency.PT1H,
      8     data=data,
      9     name="temperature",
     10     unit="°C",
     11 )
     12 ts_temp

NameError: name 'tdm' is not defined

Summary

In this notebook you learned how to:

• Create a TimeSeries with metadata (name, unit, data type)

• View its rich display in a notebook

• Access individual DataPoint elements via indexing, slicing, and iteration

• Inspect basic properties: begin, end, duration, has_missing

Next up: nb_02 shows how to use numpy and pandas to transform time series data.