timeline#

Shared, data-agnostic timeline utilities backed by the dataqueue master clock.

Expects a dataqueue.csv DataSource loader. The dataqueue file contains this structure:

```python [‘queue_elapsed’, ‘packet_ts’, ‘device_ts’, ‘device_id’, ‘payload’]

queue_elapsed packet_ts … device_id payload

0 976929.429661 2025-07-08 16:58:03.627918 … encoder_COM3 0 1 976929.439462 2025-07-08 16:58:03.637494 … encoder_COM3 0 2 976929.470421 2025-07-08 16:58:03.668444 … encoder_COM3 0 3 976929.503343 2025-07-08 16:58:03.701397 … encoder_COM3 0 4 976929.503767 2025-07-08 16:58:03.701888 … encoder_COM3 0 ```

class mesofield.datakit.timeline.TimelineSlice[source]#

Bases: object

Lightweight view over a subset of the dataqueue.

It simply holds the filtered rows plus the selector that produced them so callers can reapply the same logic or log what slice they were analysing.

packet_absolute()[source]#

Return packet_ts as UTC ISO8601 strings.

Return type:

Series

__init__(rows, selector=None)#
Parameters:
Return type:

None

class mesofield.datakit.timeline.DataqueueIndex[source]#

Bases: object

Cacheable facade over a session’s dataqueue CSV.

The class deliberately avoids hard-coding knowledge of specific hardware. Consumers supply selectors or parsing callbacks that describe which device streams they are interested in. The index exposes common utilities for retrieving filtered views and fitting time mappings onto the shared clock.

__init__(directory, dataqueue_path, dataqueue)[source]#
Parameters:
dataframe()[source]#

Return a shallow copy of the underlying dataqueue frame.

Return type:

DataFrame

queue_series(selector=None)[source]#

Return queue_elapsed samples filtered by an optional device selector.

Parameters:

selector (str | Sequence[str] | Callable[[Series], Series] | None)

Return type:

Series

slice(selector)[source]#

Return a filtered subset of the dataqueue rows matching the selector.

Parameters:

selector (str | Sequence[str] | Callable[[Series], Series])

Return type:

TimelineSlice

absolute_for_device(device_pattern)[source]#

Return (elapsed_s, absolute_iso) arrays for devices matching pattern, or None if empty.

Parameters:

device_pattern (str)

Return type:

tuple[ndarray, ndarray] | None

static fit_affine(x, y)[source]#

Fit an affine transform y ≈ a * x + b and return (a, b, r²).

Parameters:
Return type:

tuple[float, float, float]

static relative(series)[source]#

Produce a series relative to its first finite value.

Parameters:

series (Iterable[float])

Return type:

ndarray

static fix_32bit_wraparound(values)[source]#

Correct unsigned 32-bit wraparound for monotonically increasing counters.

A wrap is only registered when the backward step exceeds half the counter range (2**31). Small backward steps caused by clock jitter, duplicate or slightly out-of-order samples are left alone — otherwise every µs of jitter would falsely add 2**32 (~4295 s) to the tail of the series.

Parameters:

values (Iterable[int])

Return type:

ndarray