feat: add correct_clock_drift and document scale_time_index use case#290
Open
sorlob wants to merge 5 commits into
Open
feat: add correct_clock_drift and document scale_time_index use case#290sorlob wants to merge 5 commits into
sorlob wants to merge 5 commits into
Conversation
Add TimeSeriesBase.correct_clock_drift(anchor_time, drift_point, *, drift=..., true_time=...) for the common workflow of correcting a linear clock drift from one anchor and one drift observation. The drift can be expressed either as a signed Timedelta (device − true) or via the wall-clock time at the second observation; the two forms are mutually exclusive. The method computes the appropriate scale_factor and delegates to scale_time_index. Rework the scale_time_index docstring to name clock-drift correction as the primary use case, give the explicit mapping formula, and explain how to derive scale_factor from two sync points so the method is discoverable by users searching for "drift". Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Clock drift is a property of a clock, which typically governs more than one channel/label of a recording — and some devices have several clocks (e.g. via OEM modules). Correcting only some of the channels sharing a drifted clock would desynchronise them, and correcting unaffected channels would introduce new desync. Document that users should loop over all channels and labels driven by the affected clock.
Allow modifying the time index in-place by passing inplace=True, avoiding the copy overhead when the original object is no longer needed. Default remains inplace=False to preserve the existing copy-on-modify semantics.
The offset represents a deliberate alignment shift, not a clock-rate artefact — it should not be scaled along with the recording. Previously scale_time_index absorbed the offset into time_index and reset _offset to zero, making it impossible to recover the original alignment after the fact. Now the offset is un-baked before scaling and re-applied unchanged afterwards, so _offset is preserved on the returned series and the effective timestamps (as returned by get_data) remain consistent.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
TimeSeriesBase.correct_clock_drift(anchor_time, drift_point, *, drift=..., true_time=...)for the common workflow of correcting a linear clock drift from one anchor and one drift observation. The drift is expressed either as a signedTimedelta(device − true) or via the wall-clock time at the second observation; the two forms are mutually exclusive. Internally delegates toscale_time_index.scale_time_indexdocstring so clock-drift correction is named as the primary use case, with the explicit mapping formula and a recipe for derivingscale_factorfrom two sync points — making the method discoverable to users searching for "drift".ChannelandLabelviaTimeSeriesBase.Test plan
pytest tests/test_timeseries.py -k "scale_time_index or correct_clock_drift"(6 passed)scale_time_indextests still pass.drift=form, thetrue_time=form, the "exactly one of" guard (neither / both), and the zero-interval guard.🤖 Generated with Claude Code