Merge branch 'more-calibration-tools' into 'main'

Add calibratedtime and more structs

See merge request !27

docs/src/api.md

@@ -17,6 +17,7 @@ Location
 Evt
 CalibratedHit
 CalibratedMCHit
+XCalibratedHit
 Trk
 MCTrk
 ```
@@ -27,6 +28,8 @@ DAQEvent
 EventHeader
 SnapshotHit
 TriggeredHit
+CalibratedSnapshotHit
+CalibratedTriggeredHit
 UTCTime
 UTCExtended
 Summaryslice
@@ -88,6 +91,7 @@ read(filename::AbstractString, T::Type{AcousticsTriggerParameter})
 ## Calibration
 ```@docs
 calibrate
+calibratetime
 combine
 floordist
 slew

src/KM3io.jl

@@ -40,11 +40,12 @@ export DAQEvent, EventHeader, SnapshotHit, UTCTime, UTCExtended, Summaryslice,
        count_active_channels, count_fifostatus, count_hrvstatus, status,
        maximal_udp_sequence_number, number_of_udp_packets_received
 # Offline dataformat
-export Evt, Hit, TriggeredHit, Trk, CalibratedHit, XCalibratedHit, MCTrk, CalibratedMCHit
+export Evt, TriggeredHit, Trk, CalibratedHit, XCalibratedHit, MCTrk, CalibratedMCHit, CalibratedSnapshotHit,
+       CalibratedTriggeredHit
 
 export K40Rates
 
-export calibrate, floordist, slew, combine
+export calibrate, calibratetime, floordist, slew, combine
 
 export besttrack, bestjppmuon, bestjppshower, bestaashower,
        RecStageRange, hashistory, hasjppmuonprefit, hasjppmuonsimplex, hasjppmuongandalf,

src/calibration.jl

 """
-Apply geometry and time calibration to given hits.
+
+Apply full geometry and time calibration to given hits. This way of calibration
+should be used wisely since it creates a very bloaded [`XCalibratedHit`](@ref)
+object, which might not be necessary. Often, we only need time the calibration
+to be applied.
+
 """
 function calibrate(det::Detector, hits)
     calibrated_hits = Vector{XCalibratedHit}()
@@ -25,6 +30,34 @@ function calibrate(det::Detector, hits)
     calibrated_hits
 end
 
+Base.time(det::Detector, hit; correct_slew=true) = time(hit; correct_slew=correct_slew) + getpmt(det, hit).t₀
+
+"""
+
+Calibrate the time of a given array of snapshot hits.
+
+"""
+function calibratetime(det::Detector, hits::Vector{T}) where T<:SnapshotHit
+    out = sizehint!(Vector{CalibratedSnapshotHit}(), length(hits))
+    for h in hits
+        push!(out, CalibratedSnapshotHit(h.dom_id, h.channel_id, h.t + getpmt(det, h).t₀, h.tot))
+    end
+    out
+end
+
+"""
+
+Calibrate the time of a given array of triggered hits.
+
+"""
+function calibratetime(det::Detector, hits::Vector{T}) where T<:TriggeredHit
+    out = sizehint!(Vector{CalibratedTriggeredHit}(), length(hits))
+    for h in hits
+        push!(out, CalibratedSnapshotHit(h.dom_id, h.channel_id, h.t + getpmt(det, h).t₀, h.tot, h.trigger_mask))
+    end
+    out
+end
+
 """
 Combine snapshot and triggered hits to a single hits-vector.
 

src/types.jl

@@ -60,6 +60,18 @@ end
 
 """
 
+A calibrated snapshot hit.
+
+"""
+struct CalibratedSnapshotHit <: AbstractCalibratedHit
+    dom_id::UInt32
+    channel_id::UInt8
+    t::Float64
+    tot::UInt8
+end
+
+"""
+
 A hit which was triggered.
 
 """
@@ -71,7 +83,28 @@ struct TriggeredHit <: AbstractDAQHit
     trigger_mask::UInt64
 end
 
+"""
+
+A calibrated triggered hit.
 
+"""
+struct CalibratedTriggeredHit <: AbstractCalibratedHit
+    dom_id::UInt32
+    channel_id::UInt8
+    t::Float64
+    tot::UInt8
+    trigger_mask::UInt64
+end
+
+
+"""
+
+A fully dressed hit with all calibration information which can be
+obtained. This structure is similar to the Hit structure in aanet
+and should be used wisely. Most of the time it's much more
+performant to use dedicated (simplified) structures.
+
+"""
 struct XCalibratedHit <: AbstractCalibratedHit
     dom_id::UInt32
     channel_id::UInt32

test/calibration.jl

@@ -9,6 +9,12 @@ using Test
     chits = calibrate(det, hits)
     @test 96 == length(hits)
     @test 96 == length(chits)
+
+    @test 30733918 == hits[1].t
+    @test 3.0941664391e7 ≈ chits[1].t
+
+    chits = calibratetime(det, hits)
+    @test 3.0941664391e7 ≈ chits[1].t
 end