More documentation

docs/src/api.md

@@ -14,9 +14,12 @@ Location
 
 ## Offline Format
 ```@docs
-Trk
-McTrk
 Evt
+CalibratedEvtHit
+CalibratedMCHit
+Trk
+MCTrk
+
 ```
 
 ## Online Format
@@ -63,6 +66,7 @@ K40Rates
 
 ## Trigger
 ```@docs
+triggered
 is3dmuon
 is3dshower
 ismxshower

src/KM3io.jl

@@ -16,7 +16,8 @@ export ROOTFile
 export Direction, Position, UTMPosition, Location, Quaternion
 export Detector, DetectorModule, PMT, Tripod, Hydrophone, center
 export Waveform, AcousticSignal, AcousticsTriggerParameter, piezoenabled, hydrophoneenabled
-export Hit, TriggeredHit, Trk, CalibratedEvtHit, MCTrk, CalibratedMCHit
+export Evt, Hit, TriggeredHit, Trk, CalibratedEvtHit, MCTrk, CalibratedMCHit
+export K40Rates
 
 export calibrate, floordist, slew
 

src/acoustics.jl

@@ -21,11 +21,11 @@ struct AcousticSignal
     pcm::Vector{Float32}
 end
 """
-    function read(filename::AbstractString,T::Type{AcousticSignal}, overlap::Int=DAQ_ADF_ANALYSIS_WINDOW_OVERLAP)
 
 Reads in a raw binary acoustics file.
+
 """
-function read(filename::AbstractString,T::Type{AcousticSignal}, overlap::Int=DAQ_ADF_ANALYSIS_WINDOW_OVERLAP)
+function AcousticSignal(filename::AbstractString; overlap::Int=DAQ_ADF_ANALYSIS_WINDOW_OVERLAP)
 
     id = parse(Int32, split(split(filename, "/")[end],"_")[2])
     container = Vector{UInt32}(undef,3)
@@ -40,7 +40,7 @@ function read(filename::AbstractString,T::Type{AcousticSignal}, overlap::Int=DAQ
     read!(filename,container)
     pcm = container[4:end]
 
-    return T(id, utc_seconds, ns_cycles, samples, pcm)
+    return AcousticSignal(id, utc_seconds, ns_cycles, samples, pcm)
 end
 
 

src/physics.jl

@@ -18,13 +18,13 @@ end
 """
 
 Calculates the parameters of cherenkov photons emitted from a track and hitting
-the PMTs represented as (calibrated) hits. The return value is
-`Vector{`([`CherenkovPhoton`]){@ref}`}` which holds information about the closest
-distance to track, the time residual, arrival time, impact angle, photon travel
-distance, track travel distance and photon travel direction.
+the PMTs represented as (calibrated) hits. The returned cherenkov photons hold
+information about the closest distance to track, the time residual, arrival
+time, impact angle, photon travel distance, track travel distance and photon
+travel direction. See [`CherenkovPhoton`](@ref) for more information.
 
 """
-cherenkov(track, hits::Vector{CalibratedEvtHit}) = [cherenkov(track, h) for h ∈ hits]
+cherenkov(track, hits::Vector{CalibratedEvtHit})::Vector{CherenkovPhoton} = [cherenkov(track, h) for h ∈ hits]
 cherenkov(track, hit::AbstractCalibratedHit) = cherenkov(track, hit.pos; dir=hit.dir, t=hit.t)
 function cherenkov(track, pos::Position; dir::Union{Direction,Missing}=missing, t=0)
     V = pos - track.pos
@@ -52,6 +52,11 @@ end
 (track::Track)(hits::Vector{CalibratedEvtHit}) = cherenkov(track, hits)
 
 
+"""
+
+K40 rates with L0 and higher level rates (with increasing multiplicities).
+
+"""
 struct K40Rates
     L0::Float64
     L1::Vector{Float64}

src/root/offline.jl

+"""
+
+A calibrated hit of the offline dataformat. Caveat: the `position`, `direction`
+and `t` fields might still be `0` due to the design philosophy of the offline
+format.
+
+"""
 struct CalibratedEvtHit <: AbstractCalibratedHit
     dom_id::Int32
     channel_id::UInt32
@@ -11,6 +18,13 @@ struct CalibratedEvtHit <: AbstractCalibratedHit
     dir::Direction{Float64}
 end
 
+"""
+
+A calibrated MC hit of the offline dataformat. Caveat: the `position` and
+`direction` fields might still be `0` due to the design philosophy of
+the offline format.
+
+"""
 struct CalibratedMCHit
     pmt_id::Int32
     t::Float64  # MC truth
@@ -55,6 +69,11 @@ struct MCTrk
     counter::Int32  # used by Corsika7 MC generation to store interaction counters
 end
 
+"""
+
+An offline event.
+
+"""
 struct Evt
     id::Int64  # offline event identifier
     det_id::Int64

src/tools/reconstruction.jl

@@ -86,9 +86,27 @@ function _besttrack(trks::Vector{Trk})
     sort(trks; by=c -> (length(c.rec_stages), c.lik)) |> last
 end
 
+"""
+Returns the best reconstructed JMuon track of an event or `nothing` if there are none.
+"""
 bestjppmuon(e::Evt) = bestjppmuon(e.trks)
+"""
+Returns the best reconstructed JMuon track or `nothing` if there are none.
+"""
 bestjppmuon(trks::Vector{Trk}) = filter(hasjppmuonfit, trks) |> _besttrack
+"""
+Returns the best reconstructed JShower "track" of an event or `nothing` if there are none.
+"""
 bestjppshower(e::Evt) = bestjppshower(e.trks)
+"""
+Returns the best reconstructed JShower "track" or `nothing` if there are none.
+"""
 bestjppshower(trks::Vector{Trk}) = filter(hasshowerfit, trks) |> _besttrack
+"""
+Returns the best reconstructed aashower "track" of an event or `nothing` if there are none.
+"""
 bestaashower(e::Evt) = bestaashower(e.trks)
+"""
+Returns the best reconstructed aashower "track" or `nothing` if there are none.
+"""
 bestaashower(trks::Vector{Trk}) = filter(hasaashowerfit, trks) |> _besttrack

test/acoustics.jl

@@ -4,7 +4,7 @@ using Test
 const SAMPLES_DIR = joinpath(@__DIR__, "samples")
 
 @testset "acoustics" begin
-    signal = read(joinpath(SAMPLES_DIR, "DOM_808956920_CH1_1608751683.bin"), KM3io.AcousticSignal)
+    signal = AcousticSignal(joinpath(SAMPLES_DIR, "DOM_808956920_CH1_1608751683.bin"))
     @test 808956920 == signal.dom_id
     @test 0x5fe39a3f == signal.utc_seconds
     @test 0x00020000 == signal.samples