Tutorials

Learn TimeToAlign! step by step

These tutorials take you from zero to a working multimodal alignment, introducing one concept at a time. They begin with hand-built timelines and reach loading real data in the fourth notebook. Each notebook can be run locally after installing the library with pip install "timetoalign[tutorial]".

Prerequisites: Python 3.11+, basic familiarity with Jupyter notebooks.

Tutorial Notebooks

Topics at a Glance

The tutorials are designed to be followed in order, following a learning curve from foundations through practical data work to the internals of the model:

Foundations

• Quickstart — What the library is for, in five minutes: one section per tutorial that follows.
• Timelines and Coordinates — Coordinates, units, domains, the six timeline classes, and conversion maps.
• Nesting and Timestamps — Children, offsets, regions, segment lines, and the cross-section a timestamp gives you.
• Events on a Timeline — Adding events, EventData, the shared filter vocabulary, and one timestamp per event.

Working with Data

• Loading Real Data — The two-phase loader contract, EventStores, timeline ids, and what a loader builds for you.
• Timeline Groups — Commensurability, interpolation between peers, group timestamps, and partial alignment.
• Alignment Bundles and MatchClaims — Claims, claim types, MatchLines and WarpMaps, MatchStamps, and support policies.
• Flow Control and Grids — Folded and unfolded time, FlowMaps, apply_flow, and metrical grids.

Under the Hood

• The Data Model — Why PyArrow, the three layers, raw and semantic fields, blueprints, and Parquet metadata.
• Pitch and Harmony across Formats — What each format knows about a note, and why the library refuses to invent the rest.