Cherenkov example

.gitlab-ci.yml

@@ -49,7 +49,7 @@ Julia 1.8:
     - .coverage
 
 docs:
-  image: docker.km3net.de/base/julia:1.8
+  image: docker.km3net.de/base/julia:1.8-tex
   stage: docs
   script:
     - |

docs/Project.toml

 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+FHist = "68837c9b-b678-4cd5-9925-8a54edc8f695"
 KM3NeTTestData = "3249b543-581e-4f22-b7da-6c2cdf549b24"
+PGFPlotsX = "8314cec4-20b6-5062-9cdb-752b83310925"

docs/assets/custom.css

+article#documenter-page img {
+    width: 50%;
+    background-color: white;
+}

docs/make.jl

@@ -5,8 +5,8 @@ makedocs(;
     sitename = "KM3io.jl",
     authors = "Tamas Gal",
     format = Documenter.HTML(;
-        assets = ["assets/extra_styles.js"],
-	sidebar_sitename = false,
+        assets = ["assets/custom.css"],
+        sidebar_sitename = false,
         collapselevel = 4,
         warn_outdated = true,
     ),

docs/src/examples/cherenkov_times.md

 # Cherenkov times
 
+```@setup 1
+using PGFPlotsX
+savefigs = (figname, obj) -> begin
+    pgfsave(figname * ".pdf", obj)
+    run(`pdftocairo -svg -l  1 $(figname * ".pdf") $(figname * ".svg")`)
+    pgfsave(figname * ".tex", obj);
+    return nothing
+end
+```
+
 In this example, we will pick the best reconstructed muon (from the Jpp muon
 reconstruction chain `JMuon`) in each event and calculate the Cherenkov hit time
 residuals for each triggered hit.
 
-We open the `numucc.root` file from the `KM3NeTTestData` package:
+We open the a sample file from the `KM3NeTTestData` package:
 
 ```@example 1
 using KM3io, KM3NeTTestData
 
-f = ROOTFile(datapath("offline", "numucc.root"))
+f = ROOTFile(datapath("offline", "mcv6.0.gsg_muon_highE-CC_50-500GeV.km3sim.jterbr00008357.jorcarec.aanet.905.root"))
 ```
 
 Each event holds a vector of reconstructed tracks (`Vector{Trk}`) behind the
@@ -24,13 +34,57 @@ for a given event:
 
 ```@example 1
 evt = f.offline[1]
-m = bestjppmuon(evt)
+best_muon = bestjppmuon(evt)
 ```
 
 We now use this track as a seed to calculate the Cherenkov photon (see
 [`CherenkovPhoton`](@ref)) parameters using [`cherenkov()`](@ref) for each hit
-in the event.
+triggered hit in the event. To select only triggered hits, we use the
+[`triggered()`](@ref) function together withe `filter()` which returns a new
+vector of triggered hits:
 
 ```@example 1
-cherenkov_photons = cherenkov(m, evt.hits)
+cherenkov(best_muon, filter(triggered, evt.hits))
 ```
+
+To obtain more statistics, we iterate through all the events and calculate the
+Cherenkov time residuals for each set of hits based on the best reconstruction
+track. We fill the time residuals in a 1D histogram using the
+[FHist](https://github.com/Moelf/FHist.jl) package.
+
+
+!!! note
+
+    This example uses [PGFPlotsX](https://github.com/KristofferC/PGFPlotsX.jl)
+    which is a wrapper for the LaTeX library PGFPlots. Feel free to adapt the
+    example to use your favourite plotting library.
+
+
+```@example 1
+using FHist
+
+Δts = Hist1D(;bins=-10:50)
+
+for evt ∈ f.offline
+    m = bestjppmuon(evt)
+    cherenkov_photons = cherenkov(m, filter(triggered, evt.hits))
+    for cp ∈ cherenkov_photons
+        push!(Δts, cp.Δt)
+    end
+end
+
+axis = @pgf Axis(
+    {
+        ybar, const_plot, grid,
+        xlabel=raw"\Delta t / ns",
+        ylabel="counts",
+    },
+    PlotInc(Coordinates(bincenters(Δts), bincounts(Δts)), raw"\closedcycle")
+)
+axis
+savefigs("cherenkov", ans) # hide
+```
+
+[\[.pdf\]](cherenkov.pdf), [\[generated .tex\]](cherenkov.tex)
+
+![](cherenkov.svg)