chronoseq 0.3.0

Exact time axes and time-indexed streams for Python

ChronoSeq

ChronoSeq is a Python library for time-indexed streams of sampled data. It provides exact integer-nanosecond timestamps, rational sampling rates, regular and irregular time axes, nearest-sample lookup, and half-open time-window slicing. Data may be stored in memory, a file, a database, a video container, an external API, or any custom backend.

ChronoSeq has no time-zone, calendar, or wall-clock semantics. Timestamps are exact integer nanosecond offsets on a user-defined timeline.

Installation

pip install chronoseq

Core model

ChronoSeq has three main concepts:

• TimeAxis: converts between timestamps and integer sample indices.
• Reader: reads values by integer sample index.
• Stream: combines a TimeAxis and Reader into a time-queryable stream.

The common constructors are concise:

from chronoseq import Hz, Stream, seconds

frames = Stream.regular(
    start=seconds(0),
    rate=Hz(30),
    values=[f"frame_{i:03d}" for i in range(300)],
)

frame = frames.nearest(seconds("0.101"))

print(frame.index)
print(frame.time)
print(frame.value)

For irregular sampled data:

from chronoseq import Stream, seconds

speed = Stream.irregular(
    timestamps=[
        seconds("0.000"),
        seconds("0.047"),
        seconds("0.101"),
        seconds("0.153"),
    ],
    values=[10.0, 10.3, 10.8, 11.1],
)

sample = speed.nearest(seconds("0.100"))

More documentation

• docs/semantics.md: formal timestamp, lookup, window, and reader rules.
• docs/custom_readers.md: custom backend and stream extension patterns.
• docs/performance.md: complexity notes, batching guidance, and benchmark snapshots.
• samples/: dependency-free usage patterns.
• benchmarks/: local benchmark scripts for large regular and irregular axes.

Licence

MIT