Fix arguments in docstrings (#135)

* add missing algorithm prarameter and fix enum type in docstrings

* constrain stategy argument type

* fix dots, wrong parameters, missing types in substructure docs

* fix documenting power as int!, add whitespaces in args docs

* Update more docstrings

Make sure the docstrings reflect the actual method signatures
(particularly including type specifiers).
Ensure that default values in docstring match those of the
actual method.

I reordered the named arguments in places to ensure that the more
important parameters came first (p, algorithm) with optional ones later.

For particle inputs, use Vector explicitly, instead of AbstractArray 1-D.

---------

Co-authored-by: Graeme A Stewart <[email protected]>

Author: m-fila

README.md

@@ -27,7 +27,7 @@ algorithm and generalised $`k_\text{T}`$ for $`e^+e^-`$.
 The simplest interface is to call:
 
 ```julia
-cs = jet_reconstruct(particles::AbstractArray{T, 1}; algorithm = JetAlgorithm.AntiKt, R = 1.0, [p = -1,] [recombine = +,] [strategy = RecoStrategy.Best])
+cs = jet_reconstruct(particles::Vector{T}; algorithm = JetAlgorithm.AntiKt, R = 1.0, [p = -1,] [recombine = +,] [strategy = RecoStrategy.Best])
 ```
 
 - `particles` - a one dimensional array (vector) of input particles for the clustering

src/AlgorithmStrategyEnums.jl

@@ -58,7 +58,7 @@ The dictionary is created by iterating over the `power2algorithm` dictionary and
 const algorithm2power = Dict((i.second, i.first) for i in power2algorithm)
 
 """
-    get_algorithm_power_consistency(; p::Union{Real, Nothing}, algorithm::Union{JetAlgorithm, Nothing})
+    get_algorithm_power_consistency(; p::Union{Real, Nothing}, algorithm::Union{JetAlgorithm.Algorithm, Nothing})
 
 Get the algorithm and power consistency correct
 
@@ -70,7 +70,7 @@ the power parameter is specified, it throws an `ArgumentError`.
 
 # Arguments
 - `p::Union{Real, Nothing}`: The power value.
-- `algorithm::Union{JetAlgorithm, Nothing}`: The algorithm.
+- `algorithm::Union{JetAlgorithm.Algorithm, Nothing}`: The algorithm.
 
 # Returns
 A named tuple of the consistent power and algorithm values.

src/EEAlgorithm.jl

@@ -221,9 +221,9 @@ If the algorithm is Durham, `p` is set to 1 and `R` is nominally set to 4.
 Note that unlike `pp` reconstruction the algorithm has to be specified
 explicitly.
 """
-function ee_genkt_algorithm(particles::AbstractArray{T, 1}; p = 1, R = 4.0,
+function ee_genkt_algorithm(particles::Vector{T}; p = 1,
                             algorithm::JetAlgorithm.Algorithm = JetAlgorithm.Durham,
-                            recombine = +) where {T}
+                            R = 4.0, recombine = +) where {T}
 
     # Check for consistency between algorithm and power
     (p, algorithm) = get_algorithm_power_consistency(p = p, algorithm = algorithm)

src/GenericAlgo.jl

@@ -1,21 +1,26 @@
 """
-    jet_reconstruct(particles; p = -1, algorithm = nothing, R = 1.0, recombine = +, strategy = RecoStrategy.Best)
+    jet_reconstruct(particles; p::Union{Real, Nothing} = nothing,
+                         algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
+                         R = 1.0, recombine = +,
+                         strategy::RecoStrategy.Strategy = RecoStrategy.Best)
 
 Reconstructs jets from a collection of particles using a specified algorithm and
-strategy
+strategy.
 
 # Arguments
 - `particles`: A collection of particles used for jet reconstruction. 
-- `p::Union{Real, Nothing} = -1`: The power value used for the distance measure
+- `p::Union{Real, Nothing} = nothing`: The power value used for the distance measure
   for generalised k_T, which maps to a particular reconstruction algorithm (-1 =
   AntiKt, 0 = Cambridge/Aachen, 1 = Kt).
 - `algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing`: The algorithm
   to use for jet reconstruction.
-- `R=1.0`: The jet radius parameter.
-- `recombine=+`: The recombination scheme used for combining particles.
-- `strategy=RecoStrategy.Best`: The jet reconstruction strategy to use.
-  `RecoStrategy.Best` makes a dynamic decision based on the number of starting
-  particles.
+- `R = 1.0`: The jet radius parameter.
+- `recombine = +`: The recombination scheme used for combining particles.
+- `strategy::RecoStrategy.Strategy = RecoStrategy.Best`: The jet reconstruction
+   strategy to use. `RecoStrategy.Best` makes a dynamic decision based on the
+   number of starting particles.
+
+Note that one of `p` or `algorithm` must be specified, with `algorithm` preferred.
 
 # Returns
 A cluster sequence object containing the reconstructed jets and the merging
@@ -52,10 +57,10 @@ jet_reconstruct(particles; algorithm = JetAlgorithm.Durham)
 jet_reconstruct(particles; algorithm = JetAlgorithm.GenKt, p = 0.5, R = 1.0)
 ```
 """
-function jet_reconstruct(particles; p::Union{Real, Nothing} = nothing, R = 1.0,
+function jet_reconstruct(particles; p::Union{Real, Nothing} = nothing,
                          algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
-                         recombine = +,
-                         strategy = RecoStrategy.Best)
+                         R = 1.0, recombine = +,
+                         strategy::RecoStrategy.Strategy = RecoStrategy.Best)
 
     # Either map to the fixed algorithm corresponding to the strategy
     # or to an optimal choice based on the density of initial particles

src/PlainAlgo.jl

@@ -187,19 +187,21 @@ Base.@propagate_inbounds function upd_nn_step!(i, j, k, N, Nn, kt2_array, rapidi
 end
 
 """
-    plain_jet_reconstruct(particles::Vector{T}; p = -1, R = 1.0, recombine = +) where T
+    plain_jet_reconstruct(particles::Vector{T}; p::Union{Real, Nothing} = -1,
+                               algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
+                               R = 1.0, recombine = +) where {T}
 
 Perform pp jet reconstruction using the plain algorithm.
 
 # Arguments
 - `particles::Vector{T}`: A vector of particles used for jet reconstruction, any
    array of particles, which supports suitable 4-vector methods, viz. pt2(),
    phi(), rapidity(), px(), py(), pz(), energy(), can be used. for each element.
+- `p::Union{Real, Nothing} = -1`: The power value used for jet reconstruction.
 - `algorithm::Union{JetAlgorithm, Nothing} = nothing`: The explicit jet
   algorithm to use.
-- `p::Int=-1`: The integer value used for jet reconstruction.
-- `R::Float64=1.0`: The radius parameter used for jet reconstruction.
-- `recombine::Function=+`: The recombination function used for jet
+- `R::Float64 = 1.0`: The radius parameter used for jet reconstruction.
+- `recombine::Function = +`: The recombination function used for jet
   reconstruction.
 
 **Note** for the `particles` argument, the 4-vector methods need to exist in the
@@ -219,10 +221,9 @@ jets = plain_jet_reconstruct(particles; p = -1, R = 0.4)
 jets = plain_jet_reconstruct(particles; algorithm = JetAlgorithm.Kt, R = 1.0)
 ```
 """
-function plain_jet_reconstruct(particles::AbstractArray{T, 1}; p::Union{Real, Nothing} = -1,
-                               R = 1.0,
+function plain_jet_reconstruct(particles::Vector{T}; p::Union{Real, Nothing} = -1,
                                algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
-                               recombine = +) where {T}
+                               R = 1.0, recombine = +) where {T}
 
     # Check for consistency between algorithm and power
     (p, algorithm) = get_algorithm_power_consistency(p = p, algorithm = algorithm)
@@ -252,7 +253,9 @@ function plain_jet_reconstruct(particles::AbstractArray{T, 1}; p::Union{Real, No
 end
 
 """
-    _plain_jet_reconstruct(; particles::Vector{PseudoJet}, p = -1, R = 1.0, recombine = +)
+    _plain_jet_reconstruct(; particles::Vector{PseudoJet}, p = -1, 
+                                algorithm::JetAlgorithm.Algorithm = JetAlgorithm.AntiKt,
+                                R = 1.0, recombine = +)
 
 This is the internal implementation of jet reconstruction using the plain
 algorithm. It takes a vector of `particles` representing the input particles and
@@ -264,23 +267,26 @@ entry point to this jet reconstruction.
 
 The power value maps to specific pp jet reconstruction algorithms: -1 = AntiKt,
 0 = Cambridge/Aachen, 1 = Inclusive Kt. Floating point values are allowed for
-generalised k_t algorithm.
+generalised k_t algorithm. The algorithm parameter must be consistent with the
+power parameter.
 
 # Arguments
 - `particles`: A vector of `PseudoJet` objects representing the input particles.
-- `p=-1`: The power to which the transverse momentum (`pt`) of each particle is
+- `p = -1`: The power to which the transverse momentum (`pt`) of each particle is
   raised.
-- `R=1.0`: The jet radius parameter.
+- `R = 1.0`: The jet radius parameter.
+- `algorithm::JetAlgorithm.Algorithm = JetAlgorithm.AntiKt`: The jet reconstruction
+   algorithm to use.
 - `recombine`: The recombination function used to merge two jets. Default is `+`
   (additive recombination).
 
 # Returns
 - `clusterseq`: The resulting `ClusterSequence` object representing the
   reconstructed jets.
 """
-function _plain_jet_reconstruct(; particles::Vector{PseudoJet}, p = -1, R = 1.0,
+function _plain_jet_reconstruct(; particles::Vector{PseudoJet}, p = -1,
                                 algorithm::JetAlgorithm.Algorithm = JetAlgorithm.AntiKt,
-                                recombine = +)
+                                R = 1.0, recombine = +)
     # Bounds
     N::Int = length(particles)
     # Parameters

src/Substructure.jl

@@ -22,21 +22,21 @@ function deltaR(jet1::PseudoJet, jet2::PseudoJet)
 end
 
 """
-    recluster(jet, clusterseq; R = rad, algorithm = mtd) -> ClusterSequence
+    recluster(jet, clusterseq; R = 1.0, algorithm = JetAlgorithm.CA) -> ClusterSequence
 
-Reclusters the constituents of a given jet `jet` with a different clustering method `mtd` and different jet radius `rad`.
+Reclusters the constituents of a given jet `jet` with a different clustering algorithm `algorithm` and different jet radius `R`.
 
 # Arguments
 - `jet::PseudoJet`: The jet whose constituents are to be reclustered.
 - `clusterseq::ClusterSequence`: The cluster sequence from which the original jet is obtained.
-- `rad::Float64`: The new jet radius, by default set to 1.0
-- `mtd::JetAlgorithm.Algorithm`: The new clustering method, by default set to JetAlgorithm.CA
+- `R = 1.0`: The new jet radius.
+- `algorithm::JetAlgorithm.Algorithm = JetAlgorithm.CA`: The new clustering method.
 
 # Returns
 - `ClusterSequence`: The new cluster sequence.
 """
 function recluster(jet::PseudoJet, clusterseq::ClusterSequence; R = 1.0,
-                   algorithm = JetAlgorithm.CA)
+                   algorithm::JetAlgorithm.Algorithm = JetAlgorithm.CA)
     cons = constituents(jet, clusterseq)
     new_clusterseq = jet_reconstruct(cons; p = nothing, R = R, algorithm = algorithm,
                                      strategy = RecoStrategy.Best)
@@ -50,8 +50,8 @@ end
 Used for tagging jets that undergo mass drop, a common technique in jet substructure.
 
 # Fields:
-- `mu::Float64`: Maximum allowed mass ratio for a jet to pass tagging
-- `y::Float64`: Minimum kT distance threshold for parent separation
+- `mu::Float64`: Maximum allowed mass ratio for a jet to pass tagging.
+- `y::Float64`: Minimum kT distance threshold for parent separation.
 """
 struct MassDropTagger
     mu::Float64
@@ -64,9 +64,10 @@ end
 Applies a soft-drop condition on jets, trimming away soft, wide-angle radiation.
 
 # Fields:
-- `zcut::Float64`: Minimum allowed energy fraction for subjets
-- `b::Float64`: Angular exponent controlling soft radiation suppression
-- `cluster_rad::Float64`: The new radius that will be used to recluster the components of the jet, by default set to 1.0
+- `zcut::Float64`: Minimum allowed energy fraction for subjets.
+- `b::Float64`: Angular exponent controlling soft radiation suppression.
+- `cluster_rad::Float64`: The new radius that will be used to recluster the
+  components of the jet, by default set to 1.0.
 """
 struct SoftDropTagger
     zcut::Float64
@@ -82,8 +83,8 @@ SoftDropTagger(z::Float64, b::Float64) = SoftDropTagger(z, b, 1.0)
 Filters jets based on radius and number of hardest subjets, reducing contamination.
 
 # Fields:
-- `filter_radius::Float64`: Radius parameter to recluster subjets
-- `num_hardest_jets::Int64`: Number of hardest jets to retain in the filtered result
+- `filter_radius::Float64`: Radius parameter to recluster subjets.
+- `num_hardest_jets::Int64`: Number of hardest jets to retain in the filtered result.
 """
 struct JetFilter
     filter_radius::Float64
@@ -96,9 +97,9 @@ end
 Trims soft, large-angle components from jets based on fraction and radius.
 
 # Fields:
-- `trim_radius::Float64`: Radius used for reclustering in trimming
-- `trim_fraction::Float64`: Minimum momentum fraction for retained subjets
-- `recluster_method::JetAlgorithm.Algorithm`: Method identifier for reclustering
+- `trim_radius::Float64`: Radius used for reclustering in trimming.
+- `trim_fraction::Float64`: Minimum momentum fraction for retained subjets.
+- `recluster_method::JetAlgorithm.Algorithm`: Method identifier for reclustering.
 """
 struct JetTrim
     trim_radius::Float64
@@ -113,9 +114,9 @@ Identifies subjets in a jet that pass the mass drop tagging condition.
 The method stops at the first jet satisfying the mass and distance thresholds.
 
 # Arguments:
-- `jet::PseudoJet`: PseudoJet instance representing the jet to tag
-- `clusterseq::ClusterSequence`: ClusterSequence with jet clustering history
-- `tag::MassDropTagger`: MassDropTagger instance providing mass drop parameters
+- `jet::PseudoJet`: PseudoJet instance representing the jet to tag.
+- `clusterseq::ClusterSequence`: ClusterSequence with jet clustering history.
+- `tag::MassDropTagger`: MassDropTagger instance providing mass drop parameters.
 
 # Returns:
 - `PseudoJet`: The jet (or subjet) satisfying the mass drop conditions, if tagging is successful, otherwise a zero-momentum PseudoJet
@@ -155,12 +156,12 @@ Applies soft-drop grooming to remove soft, wide-angle radiation from jets.
 This function reclusters the jet and iteratively checks the soft-drop condition on subjets.
 
 # Arguments:
-- `jet::PseudoJet`: PseudoJet instance to groom
-- `clusterseq::ClusterSequence`: ClusterSequence containing jet history
-- `tag::SoftDropTagger`: SoftDropTagger instance with soft-drop parameters
+- `jet::PseudoJet`: PseudoJet instance to groom.
+- `clusterseq::ClusterSequence`: ClusterSequence containing jet history.
+- `tag::SoftDropTagger`: SoftDropTagger instance with soft-drop parameters.
 
 # Returns:
-- `PseudoJet`: Groomed jet or zero-momentum PseudoJet if grooming fails
+- `PseudoJet`: Groomed jet or zero-momentum PseudoJet if grooming fails.
 """
 function soft_drop(jet::PseudoJet, clusterseq::ClusterSequence,
                    tag::SoftDropTagger)
@@ -201,12 +202,12 @@ end
 Filters a jet to retain only the hardest subjets based on a specified radius and number.
 
 # Arguments:
-- `jet::PseudoJet`: PseudoJet instance representing the jet to filter
-- `clusterseq::ClusterSequence`: ClusterSequence containing jet history
-- `filter::JetFilter`: Filter instance specifying radius and number of subjets
+- `jet::PseudoJet`: PseudoJet instance representing the jet to filter.
+- `clusterseq::ClusterSequence`: ClusterSequence containing jet history.
+- `filter::JetFilter`: Filter instance specifying radius and number of subjets.
 
 # Returns:
-- `PseudoJet`: Filtered jet composed of the hardest subjets
+- `PseudoJet`: Filtered jet composed of the hardest subjets.
 """
 function jet_filtering(jet::PseudoJet, clusterseq::ClusterSequence, filter::JetFilter)
     rad = filter.filter_radius
@@ -228,12 +229,12 @@ end
 Trims a jet by removing subjets with transverse momentum below a specified fraction.
 
 # Arguments:
-- `jet::PseudoJet`: PseudoJet instance representing the jet to trim
-- `clusterseq::ClusterSequence`: ClusterSequence containing jet history
-- `trim::JetTrim`: Trim instance specifying trimming parameters
+- `jet::PseudoJet`: PseudoJet instance representing the jet to trim.
+- `clusterseq::ClusterSequence`: ClusterSequence containing jet history.
+- `trim::JetTrim`: Trim instance specifying trimming parameters.
 
 # Returns:
-- `PseudoJet`: Trimmed jet composed of retained subjets
+- `PseudoJet`: Trimmed jet composed of retained subjets.
 """
 function jet_trimming(jet::PseudoJet, clusterseq::ClusterSequence, trim::JetTrim)
     rad = trim.trim_radius

src/TiledAlgoLL.jl

@@ -330,7 +330,9 @@ function find_tile_neighbours!(tile_union, jetA, jetB, oldB, tiling)
 end
 
 """
-    tiled_jet_reconstruct(particles::Vector{T}; p = -1, R = 1.0, recombine = +) where {T}
+    tiled_jet_reconstruct(particles::Vector{T}; p::Union{Real, Nothing} = -1,
+                               algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
+                               R = 1.0, recombine = +) where {T}
 
 Main jet reconstruction algorithm entry point for reconstructing jets using the
 tiled strategy for generic jet type T.
@@ -350,7 +352,7 @@ If both are given they must be consistent or an exception is thrown.
   JetReconstruction namespace)
 - `p::Union{Real, Nothing} = -1`: The power parameter for the jet reconstruction
   algorithm, thus switching between different algorithms.
-- `algorithm::Union{JetAlgorithm, Nothing} = nothing`: The explicit jet
+- `algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing`: The explicit jet
   algorithm to use.
 - `R::Float64 = 1.0`: The jet radius parameter for the jet reconstruction
   algorithm.
@@ -365,10 +367,9 @@ If both are given they must be consistent or an exception is thrown.
 tiled_jet_reconstruct(particles::Vector{LorentzVectorHEP}; p = -1, R = 0.4, recombine = +)
 ```
 """
-function tiled_jet_reconstruct(particles::AbstractArray{T, 1}; p::Union{Real, Nothing} = -1,
-                               R = 1.0,
+function tiled_jet_reconstruct(particles::Vector{T}; p::Union{Real, Nothing} = -1,
                                algorithm::Union{JetAlgorithm.Algorithm, Nothing} = nothing,
-                               recombine = +) where {T}
+                               R = 1.0, recombine = +) where {T}
 
     # Check for consistency between algorithm and power
     (p, algorithm) = get_algorithm_power_consistency(p = p, algorithm = algorithm)
@@ -398,18 +399,23 @@ Main jet reconstruction algorithm, using PseudoJet objects
 """
 
 """
-    _tiled_jet_reconstruct(particles::Vector{PseudoJet}; p = -1, R = 1.0, recombine = +) where {T}
+    _tiled_jet_reconstruct(particles::Vector{PseudoJet}; p::Real = -1,
+                                algorithm::JetAlgorithm.Algorithm = JetAlgorithm.AntiKt,
+                                R = 1.0, recombine = +)
 
 Main jet reconstruction algorithm entry point for reconstructing jets once preprocessing
-of data types are done.
+of data types are done. The algorithm parameter must be consistent with the
+power parameter.
 
 ## Arguments
 - `particles::Vector{PseudoJet}`: A vector of `PseudoJet` particles used as input for jet
   reconstruction.
-- `p::Int = -1`: The power parameter for the jet reconstruction algorithm, thus
+- `p::Real = -1`: The power parameter for the jet reconstruction algorithm, thus
   switching between different algorithms.
-- `R::Float64 = 1.0`: The jet radius parameter for the jet reconstruction
+- `R = 1.0`: The jet radius parameter for the jet reconstruction
   algorithm.
+- `algorithm::JetAlgorithm.Algorithm = JetAlgorithm.AntiKt`: The jet reconstruction
+   algorithm to use.
 - `recombine::Function = +`: The recombination function used for combining
   pseudojets.
 
@@ -421,9 +427,9 @@ of data types are done.
 tiled_jet_reconstruct(particles::Vector{PseudoJet}; p = 1, R = 1.0, recombine = +)
 ```
 """
-function _tiled_jet_reconstruct(particles::Vector{PseudoJet}; p::Real = -1, R = 1.0,
+function _tiled_jet_reconstruct(particles::Vector{PseudoJet}; p::Real = -1,
                                 algorithm::JetAlgorithm.Algorithm = JetAlgorithm.AntiKt,
-                                recombine = +)
+                                R = 1.0, recombine = +)
     # Bounds
     N::Int = length(particles)