chronoseq 0.4.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 fractions import Fraction

from chronoseq import Rate, Stream, timestamp

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

# Rate(n, d) means n / d hertz, i.e. samples per second.
# For example, Rate(30000, 1001) is an exact 29.97 fps-style rate.
# Decimal rates can be represented exactly with Fraction.
rate_2856 = Rate(Fraction("28.56"))

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

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

For irregular sampled data:

from chronoseq import Rate, Stream, timestamp

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

sample = speed.nearest(timestamp("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