Add dejitter

Author: abcsds

CHANGELOG.md

@@ -1,3 +1,8 @@
+## [UNRELEASED] - 2025-01-08
+ - Add CI workflow for versions 1.11, 1.6 (LTS), and "pre".
+ - Format [blue](https://github.com/JuliaDiff/BlueStyle)
+ - Add dejitter function
+
 ## [0.2.0] - 2022-02-23
 - Add support for string markers and string streams ([#2](https://github.com/cbrnr/XDF.jl/pull/2) by [Alberto Barradas](https://github.com/abcsds) and [Clemens Brunner](https://github.com/cbrnr))
 - Make header and footer XML available in "xml" key ([#4](https://github.com/cbrnr/XDF.jl/pull/4) by [Alberto Barradas](https://github.com/abcsds))

README.md

@@ -20,7 +20,6 @@ streams = read_xdf("minimal.xdf")
 ## Current status
 This package is currently in an early stage, so here's an overview of what doesn't work (yet):
 
-- [ ] Dejittering of streams with regular sampling rates is not available yet
 - [ ] Loading only specific streams does not work yet
 
 If you have a feature request or found a bug, please open a new issue and let me know. I'd be especially interested in making the code more efficient, because this is basically my first Julia project. Currently, the function is passing through the file twice: the first pass reads everything except sample chunks, whereas the second pass reads samples into preallocated arrays. I'm not sure if this is ideal, the code would be much simpler if it used just a simple pass (but then sample arrays will need to be concatenated).

src/XDF.jl

@@ -1,4 +1,4 @@
-# Authors: Clemens Brunner
+# Authors: Clemens Brunner, Alberto Barradas
 # License: BSD (3-clause)
 
 module XDF
@@ -185,4 +185,59 @@ function sync_clock(time::Array{Float64,1}, offsets::Array{Float64,2})
     return time .+ (coefs[1] .+ coefs[2] .* time)
 end
 
+"""
+    dejitter(stream::Dict, max_time::Float64=1, max_samples::Int=500)
+    Calculate timestamps assuming constant intervals within each continuous segment in a stream. Chooses the minimum of the time difference and the number of samples as indicator for a new segment.
+    args:
+        stream: Dict
+            Stream dictionary.
+        max_time: Float64
+            Maximum time difference between two consecutive samples (default: 1 second).
+        max_samples: Int
+            Maximum number of samples in a segment (default: 500 samples).
+    return:
+        Dict: Stream dictionary with updated timestamps.
+
+Example:
+```julia
+stream = read_xdf(Downloads.download("https://github.com/xdf-modules/example-files/blob/master/data_with_clock_resets.xdf?raw=true"))[2]
+stream = dejitter(stream, 1.0, 500) # process segments with a maximum time difference of 1 second or 500 samples
+stream["segments"] # list of segments
+stream["nominal_srate"] # recalculated nominal sampling rate
+```
+"""
+function dejitter(stream::Dict; max_time::Float64=1.0, max_samples::Int=500)
+    srate = stream["srate"]
+    if srate == 0
+        @warn "Attempting to dejitter marker streams or streams with zero sampling rate. Skipping."
+        return stream
+    end
+    nsamples = size(stream["data"], 1)
+    if nsamples == 0
+        @warn "Attempting to dejitter empty stream. Skipping."
+        return stream
+    end
+    stream["nominal_srate"] = 0 # Recalculated if possible
+    stream["segments"] = []
+    time = stream["time"]
+    breaks = [1; findall(diff(time) .> min.(max_time, max_samples .* (1 / srate)));]
+    seg_starts = breaks
+    seg_ends = [breaks[2:end] .- 1; nsamples]
+    for (start, stop) in zip(seg_starts, seg_ends)
+        push!(stream["segments"], (start, stop))
+        idx = [start:stop;]
+        X = hcat(ones(length(idx)), time[idx])
+        y = time[idx]
+        coefs = X \ y
+        stream["time"][idx] = coefs[1] .+ coefs[2] .* time[idx]
+    end
+    # Recalculate nominal sampling rate
+    counts = (seg_ends .- seg_starts) .+ 1
+    durations = diff([time[seg_starts]; time[seg_ends[end]]])
+    stream["nominal_srate"] = sum(counts) / sum(durations)
+    if stream["srate"] != 0 && abs(stream["srate"] - stream["nominal_srate"]) > 1e-1
+        @warn "After dejittering: Nominal sampling rate differs from specified rate: $(stream["nominal_srate"]) vs. $(stream["srate"]) Hz"
+    end
+    return stream
+end
 end

test/runtests.jl

@@ -70,4 +70,7 @@ end
     @test startswith(streams[2]["footer"], "<?xml version=\"1.0\"?>")
     @test endswith(streams[2]["footer"], "</clock_offsets></info>")
     @test size(streams[2]["data"]) == (27815, 8)
+    d_stream = XDF.dejitter(streams[2])
+    @test d_stream["segments"][1] == (1, 12875)
+    @test d_stream["segments"][2] == (12876, 27815)
 end