Skip to content

Commit 3aac9cd

Browse files
graeme-a-stewartgraeme-a-stewart
committed
Improved documentation
Restructure documentation to keep the main page short and with the most important information. Move other documentation to its oen pages and cross reference.
1 parent 4422bc1 commit 3aac9cd

8 files changed

+125
-81
lines changed

‎docs/make.jl

+5-2
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,11 @@ makedocs(sitename = "JetReconstruction.jl",
1515
"Examples" => "examples.md",
1616
"EDM4hep" => "EDM4hep.md",
1717
"Visualisation" => "visualisation.md",
18-
"Reference" => Any["Public API" => "lib/public.md",
19-
"Internal API" => "lib/internal.md"]
18+
"Particle Inputs" => "particles.md",
19+
"Reconstruction Strategies" => "strategy.md",
20+
"Reference Docs" => Any["Public API" => "lib/public.md",
21+
"Internal API" => "lib/internal.md"],
22+
"Extras" => Any["Serialisation" => "extras/serialisation.md"]
2023
])
2124

2225
deploydocs(repo = "github.com/JuliaHEP/JetReconstruction.jl.git",

‎docs/src/EDM4hep.md

+32-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,37 @@
1-
# EDM4hep
1+
# EDM4hep Inputs
22

3-
Extension functionality to read EDM4hep ReconstructedParticles
3+
Extension functionality to read EDM4hep ReconstructedParticles, using the
4+
[EDM4hep.jl](https://github.com/peremato/EDM4hep.jl) package.
45

5-
## Index
6+
## Examples
7+
8+
EDM4hep `ReconstructedParticles` can be used as direct input into jet
9+
reconstruction.
10+
11+
A number of working examples are maintained in the [EDM4hep examples
12+
directory](https://github.com/JuliaHEP/JetReconstruction.jl/tree/main/examples/EDM4hep)
13+
of the package's `examples`.
14+
15+
Here is a snippet that shows the main steps:
16+
17+
```julia
18+
using EDM4hep
19+
using EDM4hep.RootIO
20+
using JetReconstruction
21+
22+
# Change this to something that works on your system
23+
input_file = joinpath("directory", "EDM4hep.root")
24+
reader = RootIO.Reader(input_file)
25+
events = RootIO.get(reader, "events")
26+
27+
evt = events[1]
28+
29+
recps = RootIO.get(reader, evt, "ReconstructedParticles")
30+
31+
cs = jet_reconstruct(recps; algorithm = JetAlgorithm.Durham)
32+
```
33+
34+
## Function Index
635

736
```@index
837
Pages = ["EDM4hep.md"]

‎docs/src/examples.md

+4-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
# Jet Reconstruction Examples
22

33
The Jet Reconstruction package has a number of example files that show how to
4-
usage.
4+
usage. These are in the `examples` subdirectory of the package and can be
5+
browsed directly on
6+
[GitHub](https://github.com/JuliaHEP/JetReconstruction.jl/tree/main/examples).
57

68
*Note:* because of extra dependencies in these scripts, one must use the
79
`Project.toml` file in the `examples` directory.
@@ -58,4 +60,4 @@ showing how the jets merge from their different constituents.
5860

5961
The `examples/EDM4hep` folder contains examples of using EDM4hep reconstructed
6062
particles as input to jet reconstruction. See the specific `README.md` file in
61-
that directory.
63+
that directory as well as [EDM4hep Inputs](@ref).

‎docs/src/extras/serialisation.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Jet Serialisation
2+
3+
The package provides methods such as `loadjets`, `loadjets!`, and `savejets`
4+
that one can use to save and load objects on/from disk easily in a very flexible
5+
format. See documentation for more.

‎docs/src/index.md

+20-73
Original file line numberDiff line numberDiff line change
@@ -26,42 +26,22 @@ jet_reconstruct(particles; algorithm = JetAlgorithm.AntiKt, R = 1.0)
2626
or with some of the optional arguments,
2727

2828
```julia
29-
jet_reconstruct(particles; algorithm = JetAlgorithm.GenKt, R = 0.4, p = 0.5, recombine = +, strategy = RecoStrategy.Best)
29+
jet_reconstruct(particles; algorithm = JetAlgorithm.GenKt, R = 0.4,
30+
p = 0.5, recombine = +, strategy = RecoStrategy.Best)
3031
```
3132

32-
Where `particles` is a collection of 4-vector objects to reconstruct and the
33-
algorithm is either given explicitly or implied by the power value. For the case
34-
of generalised ``k_T`` (for ``pp`` and ``e^+e^-``) both the algorithm
35-
(`JetAlgorithm.GenKt`) and `p` are needed. For the case of the Durham algorithm
36-
the `R` value is ignored.
33+
Where `particles` is a collection of 4-vector objects (see [Input Particle
34+
Types](@ref)) to reconstruct and the algorithm is either given explicitly or
35+
implied by the power value.
3736

38-
The object returned is a [`ClusterSequence`](@ref), which internally tracks all
39-
merge steps.
40-
41-
### Input Particle Types
42-
43-
For the `particles` input to the reconstruction any one dimensional
44-
`AbstractArray{T, 1}` can be used, where the type `T` has to implement methods
45-
to extract the 4-vector components, viz, the following are required:
46-
47-
- `JetReconstuction.px(particle::T)`
48-
- `JetReconstuction.py(particle::T)`
49-
- `JetReconstuction.pz(particle::T)`
50-
- `JetReconstuction.energy(particle::T)`
51-
52-
Currently built-in supported types are
53-
[`LorentzVectorHEP`](https://github.com/JuliaHEP/LorentzVectorHEP.jl), the
54-
`PseudoJet` and `EEjet`s from this package, and `ReconstructedParticles` from
55-
[EDM4hep](https://github.com/peremato/EDM4hep.jl).
37+
For the case of generalised ``k_T`` (for ``pp`` and ``e^+e^-``) both the
38+
algorithm (`GenKt`, `EEKt`) and `p` are needed.
5639

57-
If you require support for a different input collection type then ensure you
58-
define the `px()`, etc. methods *for your specific type* and *in the
59-
`JetReconstruction` package*. This use of what might be considered type piracy
60-
is blessed as long as you are en *end user* of the jet reconstruction package.
40+
The `R` value determines the cone size; in the case of the Durham algorithm the
41+
`R` value is ignored.
6142

62-
If your type is used in several places or by different users, please consider
63-
writing a package extension that will support your type, following the model for
64-
EDM4hep in `ext/EDM4hepJets.jl`.
43+
The object returned is a [`ClusterSequence`](@ref), which internally tracks all
44+
merge steps and is used for [Inclusive and Exclusive Selections](@ref).
6545

6646
### Algorithm Types
6747

@@ -76,37 +56,26 @@ Each known algorithm is referenced using a `JetAlgorithm` scoped enum value.
7656
| ``e^+e-`` ``k_\text{T}`` / Durham | `JetAlgorithm.Durham` | `R` value ignored and can be omitted |
7757
| generalised ``e^+e-`` ``k_\text{T}`` | `JetAlgorithm.EEKt` | For ``e^+e^-``, value of `p` must also be specified |
7858

79-
### ``pp`` Algorithms
59+
#### ``pp`` Algorithms
8060

8161
For the three ``pp`` algorithms with fixed `p` values, the `p` value can be
8262
given instead of the algorithm name. However, this should be considered
8363
*deprecated* and will be removed in a future release.
8464

85-
## Strategy
86-
87-
For the ``pp`` algorithms three strategies are available for the different
88-
algorithms, which can be specified by passing the named argument `strategy=...`.
89-
90-
| Strategy Name | Notes | Interface |
91-
|---|---|---|
92-
| `RecoStrategy.Best` | Dynamically switch strategy based on input particle density | `jet_reconstruct` |
93-
| `RecoStrategy.N2Plain` | Global matching of particles at each interation (works well for low $N$) | `plain_jet_reconstruct` |
94-
| `RecoStrategy.N2Tiled` | Use tiles of radius $R$ to limit search space (works well for higher $N$) | `tiled_jet_reconstruct` |
95-
96-
Generally one can use the `jet_reconstruct` interface, shown above, as the
97-
*Best* strategy safely as the overhead is extremely low. That interface supports
98-
a `strategy` option to switch to a different option.
65+
### Strategy
9966

100-
For ``e^+e^-`` algorithms particle densities are low, so the only implementation
101-
is of the same type as `N2Plain`.
67+
Generally one does not need to manually specify a strategy, but [Algorithm
68+
Strategy](@ref) describes how to do this, if desired.
10269

10370
## Inclusive and Exclusive Selections
10471

10572
To obtain final jets both inclusive (``p_T`` cut) and exclusive (``n_{jets}`` or
10673
``d_{ij}`` cut) selections are supported:
10774

108-
- [inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)](@ref)
109-
- [exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)](@ref)
75+
- [`inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)`](@ref)
76+
- [`exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)`](@ref)
77+
78+
(For `exclusive_jets` either `dcut` or `njets` is needed, but not both.)
11079

11180
### Sorting
11281

@@ -119,29 +88,7 @@ sorted_jets = sort!(inclusive_jets(cs::ClusterSequence; ptmin=5.0),
11988
by=JetReconstruction.energy, rev=true)
12089
```
12190

122-
## Plotting and Animation
123-
124-
![illustration](assets/jetvis.png)
125-
126-
To visualise the clustered jets as a 3d bar plot (see illustration above) we now
127-
use `Makie.jl`. See the `jetsplot` function in `ext/JetVisualisation.jl` and its
128-
documentation for more. There are two worked examples in the `examples`
129-
directory.
130-
131-
The plotting code is a package extension and will load if the one of the `Makie`
132-
modules is loaded in the environment.
133-
134-
The [`animatereco`](@ref) function will animate the reconstruction sequence, given a
135-
`ClusterSequence` object. See the function documentation for the many options
136-
that can be customised.
137-
138-
## Serialisation
139-
140-
The package also provides methods such as `loadjets`, `loadjets!`, and
141-
`savejets` that one can use to save and load objects on/from disk easily in a
142-
very flexible format. See documentation for more.
143-
144-
## Reference
91+
## References
14592

14693
Although it has been developed further since the CHEP2023 conference, the CHEP
14794
conference proceedings,

‎docs/src/particles.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Input Particle Types
2+
3+
For the `particles` input to the reconstruction any one dimensional
4+
`AbstractArray{T, 1}` can be used, where the type `T` has to implement methods
5+
to extract the 4-vector components, viz, the following are required:
6+
7+
- `JetReconstuction.px(particle::T)`
8+
- `JetReconstuction.py(particle::T)`
9+
- `JetReconstuction.pz(particle::T)`
10+
- `JetReconstuction.energy(particle::T)`
11+
12+
Currently built-in supported types are
13+
[`LorentzVectorHEP`](https://github.com/JuliaHEP/LorentzVectorHEP.jl), the
14+
`PseudoJet` and `EEjet`s from this package, and `ReconstructedParticles` from
15+
[EDM4hep Inputs](@ref).
16+
17+
If you require support for a different input collection type then ensure you
18+
define the `px()`, etc. methods *for your specific type* and *in the
19+
`JetReconstruction` package*. This use of what might be considered type piracy
20+
is blessed as long as you are en *end user* of the jet reconstruction package.
21+
22+
If your type is used in several places or by different users, please consider
23+
writing a package extension that will support your type, following the model for
24+
EDM4hep in `ext/EDM4hepJets.jl`.

‎docs/src/strategy.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Algorithm Strategy
2+
3+
For the ``pp`` algorithms three strategies are available for the different
4+
algorithms, which can be specified by passing the named argument `strategy=...`
5+
to the reconstruction.
6+
7+
| Strategy Name | Notes | Interface |
8+
|---|---|---|
9+
| `RecoStrategy.Best` | Dynamically switch strategy based on input particle density | `jet_reconstruct` |
10+
| `RecoStrategy.N2Plain` | Global matching of particles at each interation (works well for low $N$) | `plain_jet_reconstruct` |
11+
| `RecoStrategy.N2Tiled` | Use tiles of radius $R$ to limit search space (works well for higher $N$) | `tiled_jet_reconstruct` |
12+
13+
Generally one can use the `jet_reconstruct` interface, shown above, as the
14+
*Best* strategy safely as the overhead is extremely low. That interface supports
15+
a `strategy` option to switch to a different option.
16+
17+
For ``e^+e^-`` algorithms particle densities are low, so the only implementation
18+
is of the same type as `N2Plain`.

‎docs/src/visualisation.md

+17-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,23 @@
22

33
Documentation for visualisation interfaces extension module.
44

5-
## Index
5+
## Plotting and Animation
6+
7+
![illustration](assets/jetvis.png)
8+
9+
To visualise the clustered jets as a 3d bar plot (see illustration above)
10+
`Makie.jl` is used. See the `jetsplot` function in `ext/JetVisualisation.jl` and
11+
its documentation for more. There are two worked examples in the `examples`
12+
directory of this package.
13+
14+
The plotting code is a package extension and will load if the one of the `Makie`
15+
modules is loaded in the environment.
16+
17+
The [`animatereco`](@ref) function will animate the reconstruction sequence,
18+
given a `ClusterSequence` object. See the function documentation below for the
19+
many options that can be customised.
20+
21+
## Function Index
622

723
```@index
824
Pages = ["visualisation.md"]

0 commit comments

Comments
 (0)