Use a dataset¶

Every TimeF dataset loads through the same client. Each Record contains a Source hierarchy, and each Source contains Signals.

from timenet.client import TimeNet

dataset = TimeNet(".timenet-registry").load("timenet/hello-world")
record = dataset.records[0]
signal = record.signals[0]

load() reads the hierarchy and every Signal value into memory. For a large dataset, open it instead. The reader's reads leave each Signal's values in storage until an array method reads them:

with TimeNet(".timenet-registry").open("timenet/hello-world") as reader:
    dataset = reader.read()
    values = dataset.records[0].signals[0].to_numpy()

Arrow and NumPy¶

Use to_arrow() to preserve Arrow types and nullable values:

arrow_values = signal.to_arrow()

Use to_numpy() when the Signal has no null values:

numpy_values = signal.to_numpy()

For data with nulls, use to_arrow() to preserve missing values:

values = signal.to_arrow()
present = values.is_valid()

Use read_steps() to read one half-open range:

first_second = signal.read_steps(0, 500)

pandas¶

Create a DataFrame from one Signal:

import pandas as pd

frame = pd.DataFrame({signal.name: signal.to_numpy()})

For a regular timeline, build offsets from the Signal axis:

offsets_us = [
    signal.time_axis.time_offset_us(index)
    for index in range(signal.n_values)
]
frame.insert(0, "time_offset_us", offsets_us)

An ordinal Signal has ordered steps but no time offsets. Do not create timestamps for that axis.

Polars¶

Polars accepts the Arrow array directly:

import polars as pl

column = pl.from_arrow(signal.to_arrow())
frame = pl.DataFrame({signal.name: column})

PyTorch¶

Install the adapter with uv add 'timenet[torch]'. Then open a map-style PyTorch dataset. The view holds an open reader, so use it in a with block or call its close():

from timenet.client import TimeNet

client = TimeNet(".timenet-registry")
with client.open_torch("timenet/hello-world") as view:
    item = view[0]

    values = item["series"][0]
    present = item["series_masks"][0]
    targets = item["tasks"][0].targets

The adapter preserves the Signal dtype and per-timestep shape. It raises TimeFValidationError when values contain nulls, even when nullable=True. Consumers must handle missing data before conversion to PyTorch. Each mask in series_masks contains only true values.

Tasks and annotations remain Python objects. Signal lengths can also vary. Supply a model-specific transform or collate_fn when the default PyTorch batching cannot combine them.

Train a small classifier¶

The timenet/test-mean connector provides a deterministic classification example. Each Record has one Signal and one label.

from pathlib import Path

from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split

from timenet.client import TimeNet
import timenet_connectors

registry = Path(".timenet-registry")
timenet_connectors.build("timenet/test-mean", out=registry)
dataset = TimeNet(registry).load("timenet/test-mean")

x, y = dataset.to_features_and_targets(output="numpy")
x_train, x_test, y_train, y_test = train_test_split(
    x,
    y,
    test_size=0.25,
    stratify=y,
    random_state=0,
)
model = LogisticRegression(max_iter=1000).fit(x_train, y_train)
print(model.score(x_test, y_test))

The helper infers the task type because this dataset has one scalar target type. Pass task= when a dataset contains several eligible task types. When a dataset ships its own partition, pass split= instead of splitting at random: to_features_and_targets(split="train") and to_features_and_targets(split="test") build the two pairs from the Tasks the dataset marks as such.

The runnable version is examples/test_mean_classifier.py.

Work with downloaded files¶

download() returns a local TimeF version directory:

path = TimeNet().download("org/name@1.0.0")

The directory contains manifest.json, control.duckdb, and a Parquet or Zarr values plane. Use the TimeNet reader when you need reconstructed Python objects and lazy Signal values.

See TimeF format for direct access to the physical layout.