Cluster sequence utilities and reconstruction animation (#65)

* Add ranking of jets

Utility function that returns a ranking of initial jets according to some
value, by default p_T

Used to assign stable values to subsequently reconstructed jets based on
their constituents, e.g., for mapping to colours for plotting

* Add intermediate state and plotting

Add a method to retrieve the intermediate state of a reconstruction
(using a special struct, JetWithAncestors)

Plotter for this intermediate state, which preserves colours based on
a ranking of primary clusters (defaults to p_T ranking)

* Fix bug in reco_state

Use the jetp_index of the parent's history entry, instead of the history
entry index (which is wrong)

Add merge_steps method to count the number of meaningful
iterations in the reconstruction
process (used to get the number
of animation steps)

* Add reconstruction animation function

animatereco() calculates all of the intermediate states during the
reconstruction and plots them with meshplot, creating an
animation output

* Add feature to plot ancestors

Option to plot all ancestors of a growing jet, using the colour of
the jet they merge to

* Shifting perspective

Allow passing of tuple of two numbers for axis view options
that give the starting and ending points for the axis view

Code refomatted

* Wrap colormap values

When there are > length(colormap) starting clusters
the extra ones are clipped, so instead wrap back to the start
of the colormap

N.B. There is an assumption here that the colormap has 256
categorical values, which may not be true. However,
I can't currently find an easy way to inspect a colormap Symbol
and extract the length

* Use variable for colormap end

* Add title and end frames options

Title does what it says on the tin...
End frames extend the animation at the end

* Minor updates

Ignore video files in the example directory
Remove unneeded dependencies from jetreco.jl

* Improved documentation

Add Documenter setup to use @autodocs to generate
all public and internal documentation.
Use @ref links to refer to methods and types in
main documentation pages.

Move get_all_ancestors() method to ClusterSequence
(it is not visualisation).

Add logo for the package!

Author: graeme-a-stewart

docs/Project.toml

@@ -1,6 +1,8 @@
 [deps]
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 JetReconstruction = "44e8cb2c-dfab-4825-9c70-d4808a591196"
+Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 
 [compat]
 Documenter = "1.4"

docs/make.jl

@@ -1,7 +1,19 @@
 using Documenter
+using CairoMakie
 using JetReconstruction
 
-makedocs(sitename = "JetReconstruction.jl")
+push!(LOAD_PATH, "../ext/")
+
+include(joinpath(@__DIR__, "..", "ext", "JetVisualisation.jl"))
+
+makedocs(sitename = "JetReconstruction.jl",
+         pages = [
+             "Home" => "index.md",
+             "Examples" => "examples.md",
+             "Reference" => Any["Public API" => "lib/public.md",
+                                "Internal API" => "lib/internal.md",
+                                "Visualisation API" => "lib/visualisation.md"]
+         ])
 
 deploydocs(repo = "github.com/JuliaHEP/JetReconstruction.jl.git",
            push_preview = true)

docs/src/assets/logo.png

@@ -44,3 +44,8 @@ Similar to `visualise-jets.jl` this notebook will produce a visualisation of jet
 reconstruction in the browser. This is a 3D plot where all the initial energy
 deposits are visualised, with colours that indicate in which final cluster the
 deposit ended up in.
+
+## `animate-reconstruction.jl`
+
+Performs jet reconstruction and then produces and animation of the process,
+showing how the jets merge from their different constituents.

docs/src/assets/logo.svg

@@ -16,17 +16,16 @@ inclusive ``k_\text{T}``.
 
 ## Reconstruction Interface
 
-The main interface for reconstruction is:
+The main interface for reconstruction is [`jet_reconstruct`](@ref), called as, e.g.,
 
-```@docs
-jet_reconstruct(particles; p = -1, R = 1.0, recombine = +, strategy = RecoStrategy.Best)
+```julia
+jet_reconstruct(particles; p = -1, R = 1.0)
 ```
 
-The object returned is a `ClusterSequence`, which internally tracks all merge steps.
+Where `particles` is a collection of 4-vector objects to reconstruct.
 
-```@docs
-ClusterSequence
-```
+The object returned is a [`ClusterSequence`](@ref), which internally tracks all
+merge steps.
 
 ## Strategy
 
@@ -38,9 +37,12 @@ Three strategies are available for the different algorithms:
 | `RecoStrategy.N2Plain` | Global matching of particles at each interation (works well for low $N$) | `plain_jet_reconstruct` |
 | `RecoStrategy.N2Tiled` | Use tiles of radius $R$ to limit search space (works well for higher $N$) | `tiled_jet_reconstruct` |
 
-Generally one can use the `jet_reconstruct` interface, shown above, as the *Best* strategy safely as the overhead is extremely low. That interface supports a `strategy` option to switch to a different option.
+Generally one can use the `jet_reconstruct` interface, shown above, as the
+*Best* strategy safely as the overhead is extremely low. That interface supports
+a `strategy` option to switch to a different option.
 
-Another option, if one wishes to use a specific strategy, is to call that strategy's interface directly, e.g.,
+Another option, if one wishes to use a specific strategy, is to call that
+strategy's interface directly, e.g.,
 
 ```julia
 # For N2Plain strategy called directly
@@ -54,19 +56,8 @@ Note that there is no `strategy` option in these interfaces.
 To obtain final jets both inclusive (``p_T`` cut) and exclusive (``n_{jets}`` or
 ``d_{ij}`` cut) selections are supported:
 
-```@docs
-inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)
-```
-
-```@docs
-exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)
-```
-
-The number of exclusive jets passing a particular `dcut` can be obtained:
-
-```@docs
-n_exclusive_jets(clusterseq::ClusterSequence; dcut::AbstractFloat)
-```
+- [inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)](@ref)
+- [exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)](@ref)
 
 ### Sorting
 
@@ -79,7 +70,7 @@ sorted_jets = sort!(inclusive_jets(cs::ClusterSequence; ptmin=5.0),
   by=JetReconstruction.energy, rev=true)
 ```
 
-## Plotting
+## Plotting and Animation
 
 ![illustration](assets/jetvis.png)
 
@@ -91,6 +82,10 @@ directory.
 The plotting code is a package extension and will load if the one of the `Makie`
 modules is loaded in the environment.
 
+The [`animatereco`](@ref) function will animate the reconstruction sequence, given a
+`ClusterSequence` object. See the function documentation for the many options
+that can be customised.
+
 ## Serialisation
 
 The package also provides methods such as `loadjets`, `loadjets!`, and

docs/src/examples.md

@@ -0,0 +1,23 @@
+# Jet Reconstruction Internal Documentation
+
+Documentation for `JetReconstruction.jl`'s internal methods and types.
+
+N.B. no guarantee is made of stability of these interfaces or types.
+
+```@meta
+CollapsedDocStrings = true
+```
+
+## Index
+
+```@index
+Pages = ["internal.md"]
+```
+
+## Public Interface
+
+```@autodocs
+Modules = [JetReconstruction]
+Public = false
+Order = [:function, :type]
+```

docs/src/index.md

@@ -0,0 +1,17 @@
+# Jet Reconstruction Public Documentation
+
+Documentation for `JetReconstruction.jl`'s public interfaces.
+
+## Index
+
+```@index
+Pages = ["public.md"]
+```
+
+## Public Methods and Types
+
+```@autodocs
+Modules = [JetReconstruction]
+Private = false
+Order = [:function, :type]
+```

docs/src/lib/internal.md

@@ -0,0 +1,16 @@
+# Jet Visualisation Documentation
+
+Documentation for visualisation interfaces extension module.
+
+## Index
+
+```@index
+Pages = ["visualisation.md"]
+```
+
+## Jet Visualisation Public Interfaces
+
+```@autodocs
+Modules = [JetVisualisation]
+Order = [:function]
+```

docs/src/lib/public.md

@@ -1,3 +1,4 @@
 # Ignore visualisation outputs
 *.pdf
 *.png
+*.mp4

docs/src/lib/visualisation.md

@@ -29,3 +29,8 @@ colours that indicate in which final cluster the deposit ended up in.
 This notebook will produce a visualisation of jet reconstruction in the browser.
 This is a 3D plot where all the initial energy deposits are visualised, with
 colours that indicate in which final cluster the deposit ended up in.
+
+## `animate-reconstruction.jl`
+
+Performs jet reconstruction and then produces and animation of the process,
+showing how the jets merge from their different constituents.