Skip to content

Quickstart

Get from zero to a validated Telemachus dataset in a few minutes.

Install

Python 3.10+ :

pip install telemachus

This ships the library (import telemachus), the tele CLI, and every adapter (AEGIS, PVS, STRIDE). Schema validation is built-in — no ajv or external tool needed.

Try it — 5-minute demo

The easiest way to see Telemachus in action is the AEGIS demo notebook. It downloads a real open dataset from Zenodo, loads it, and plots one trip. Runnable in Colab in one click.

Read a dataset

import telemachus as tele

df = tele.read("path/to/manifest.yaml")   # or directly to a .parquet
print(f"{len(df):,} rows, {df['trip_id'].nunique()} trips, "
      f"profile = {tele.sensor_profile(df)}")

tele.read() returns a regular pandas DataFrame with SI units and UTC-aware timestamps — no wrapper, no hidden state.

Validate a dataset

tele validate path/to/dataset/ --level full

Or from Python:

report = tele.validate(df, profile="full")  # core | imu | full
print(report)
# ValidationReport(PASS, profile=full, level=basic, errors=0, warnings=0)

Convert an open dataset

tele convert aegis  /path/to/aegis/csvs      -o datasets/aegis/
tele convert stride /path/to/stride/road_data -o datasets/stride/ --category driving
tele convert pvs    /path/to/pvs/trips        -o datasets/pvs/    --placement dashboard

Next steps