Client¶

TimeNet is the single Python entry point for using TimeNet from code. It wraps a registry (the catalog) and a local storage path (the download cache). It never runs connector code. Lives in timenet.client.

from timenet.client import TimeNet
from timenet.types import Domain

client = TimeNet()                                   # default local registry (~/.cache/timenet/registry)

for meta in client.search(domain=Domain.CARDIOLOGY):
    print(meta.dataset_id)

dataset = client.load("timenet/hello-world")         # download if needed + read
values = dataset.samples[0].time_series[0].to_numpy()

Construction¶

TimeNet(registry=None, *, storage_path=None)

Registry selection order: the registry argument, then $TIMENET_REGISTRY, then the local default registry (<home>/registry). registry accepts a BaseRegistry, a local path or file:// URI, an s3:// URI, or a hosted timenet:// / http(s):// URL:

client = TimeNet("./local_registry")                 # any directory a build wrote to

The s3:// and remote backends are deferred. Constructing TimeNet("timenet://") succeeds, but every call against it raises NotImplementedError, so today only local registries serve data; see Registry.

Configuration¶

All local state lives under ~/.cache/timenet/ by default. Setting the home relocates everything; the per-area variables override just their own path. Precedence for any value is CLI flag / argument > environment variable > default.

Env var	Default	What
`TIMENET_HOME`	`~/.cache/timenet`	Root; setting it relocates everything below.
`TIMENET_REGISTRY`	`<home>/registry`	The catalog to browse and pull from (local path or remote URL), and where `timenet-curate build` writes unless `--out` overrides it. A remote value makes `build` fail: there is nowhere local to write.
`TIMENET_STORAGE`	`<home>/storage`	Local copies that `download`/`load` fetch from the registry to read.
`TIMENET_CACHE`	`<home>/cache`	Raw sources fetched during curation (removed after a successful build).

Configuration is a pydantic-settings model (timenet.config.TimeNetSettings), so new settings can be added there.

Methods¶

Method	Description
`list()`	Every dataset's metadata.
`get(dataset_id, version=None)`	A dataset's manifest.
`search(...)`	Filter datasets, mirrors `registry.search`.
`download(dataset_id, version=None, *, force=False)`	Copy a version's files into local storage; returns the directory. Idempotent unless `force`.
`load(dataset_id, version=None)`	`download` if needed, then read into a `TimeFDataset` with lazy per-series values.
`load_torch(dataset_id, version=None)`	`load`, wrapped in a read-only `torch.utils.data.Dataset` (needs the `torch` extra).

Versions¶

Pin a version by suffixing the id with @<version>; with no suffix (or @latest) you get the latest committed version. This works everywhere an id is accepted, in both the SDK and the CLI:

client.get("chengsenwang/tsqa@1.0.0")   # pinned
client.load("chengsenwang/tsqa")         # latest (default)
client.load("chengsenwang/tsqa@latest")  # latest, explicit

get / download / load / load_torch also accept an explicit version= argument. Passing both a @version ref and version= is an error, and pinning a version that isn't committed raises DatasetNotFoundError. list and search always report the latest version.

PyTorch¶

load_torch returns a TimeFTorchDataset, a read-only, map-style torch.utils.data.Dataset. Each item is a dict with the sample's series as float32 tensors (one per channel), plus sample_id, tasks, and annotations.

from timenet.client import TimeNet

ds = TimeNet().load_torch("chengsenwang/tsqa")   # needs the timenet[torch] extra (coming soon)
item = ds[0]
series, question = item["series"][0], item["tasks"][0].question

To feed a DataLoader, select what your model needs (the item's tasks/annotations are Python objects, not tensors, and series lengths vary between samples), either with a transform on the dataset or a collate_fn on the loader:

from torch.utils.data import DataLoader

loader = DataLoader(ds, batch_size=8, collate_fn=lambda b: [(x["series"][0], x["tasks"][0].target) for x in b])

The torch module is imported lazily, so base users who never call load_torch don't need torch.

Command line¶

Every method here has a shell equivalent. See the timenet CLI.

See the API reference for timenet.client for the full symbol listing.