ATLASTHEME

Example

with_theme(ATLASTHEME) do
    h1 = Hist1D(randn(10^4))
    hist(h1; label="atlas style histogram")
end

BinEdges <: AbstractVector{Float64}

This type implements a vector-like data structure to be used for histogram bin edges, it can handle both uniform and non-uniform binnings in a single type to reduce the amount of parametric types.

Bin lookup (searchsortedlast(edges, x)) is O(1) whenever the edges are (numerically) uniform, regardless of whether they were given as an AbstractRange or as a plain Vector; otherwise a binary search is used. In both cases the result is exact, i.e. identical to searchsortedlast(collect(edges), x), including for values that sit exactly on a bin edge.

The edges are always copied on construction, mutating the input afterwards does not affect the histogram.

Hist1D(data::AbstractVector; kws...)

Convenience method: a non-tuple data is wrapped into a 1-tuple, see Hist1D for the keyword arguments.

To make an empty histogram

use the all-keyword-arguments constructor:

Hist1D(;
    counttype=Float64,
    binedges::E
    bincounts = zeros(counttype, length.(_to_tuple(binedges)) .- 1),
    sumw2 = zero(bincounts),
    nentries = 0
    overflow::Bool = false
) where {E<:NTuple{1,Any}}

To make an histogram given data (and weights etc.)

use the a positional argument for data and keyword-arguments for the rest:

Hist1D(array::E;
    counttype=Float64,
    binedges=nothing,
    weights=nothing,
    nbins=nothing,
    overflow=false)
) where {E<:NTuple{1,Any}}

nbins can be a single integer (used for every axis) or a tuple with one integer per axis.

Values that fall outside of binedges are discarded (and not counted in nentries) unless overflow=true, in which case they are clamped into the first/last bin along each axis. NaN is treated like +Inf.

To make an empty histogram

use the all-keyword-arguments constructor:

Hist2D(;
    counttype=Float64,
    binedges::E
    bincounts = zeros(counttype, length.(_to_tuple(binedges)) .- 1),
    sumw2 = zero(bincounts),
    nentries = 0
    overflow::Bool = false
) where {E<:NTuple{2,Any}}

To make an histogram given data (and weights etc.)

use the a positional argument for data and keyword-arguments for the rest:

Hist2D(array::E;
    counttype=Float64,
    binedges=nothing,
    weights=nothing,
    nbins=nothing,
    overflow=false)
) where {E<:NTuple{2,Any}}

nbins can be a single integer (used for every axis) or a tuple with one integer per axis.

Values that fall outside of binedges are discarded (and not counted in nentries) unless overflow=true, in which case they are clamped into the first/last bin along each axis. NaN is treated like +Inf.

To make an empty histogram

use the all-keyword-arguments constructor:

Hist3D(;
    counttype=Float64,
    binedges::E
    bincounts = zeros(counttype, length.(_to_tuple(binedges)) .- 1),
    sumw2 = zero(bincounts),
    nentries = 0
    overflow::Bool = false
) where {E<:NTuple{3,Any}}

To make an histogram given data (and weights etc.)

use the a positional argument for data and keyword-arguments for the rest:

Hist3D(array::E;
    counttype=Float64,
    binedges=nothing,
    weights=nothing,
    nbins=nothing,
    overflow=false)
) where {E<:NTuple{3,Any}}

nbins can be a single integer (used for every axis) or a tuple with one integer per axis.

Values that fall outside of binedges are discarded (and not counted in nentries) unless overflow=true, in which case they are clamped into the first/last bin along each axis. NaN is treated like +Inf.

searchsortedlast(b::BinEdges, x::Real)

Index i such that b[i] <= x < b[i+1]; 0 if x < first(b) and length(b) if x >= last(b) (also for NaN). O(1) for uniform edges, binary search otherwise.

append!(h::Hist1D, vals[, wgts])
append!(h::Hist2D, xs, ys[, wgts])
append!(h::Hist3D, xs, ys, zs[, wgts])

push! many values (optionally with weights) into the histogram at once. The histogram lock is held for the duration of the call, so this is thread-safe like atomic_push!. Returns h.

empty!(h)

Reset the histogram in place: bin counts, sumw2 and nentries are all set to zero. The bin edges and overflow setting are kept. Returns h.

empty!(h)

Reset the histogram in place: bin counts, sumw2 and nentries are all set to zero. The bin edges and overflow setting are kept. Returns h.

empty!(h)

Reset the histogram in place: bin counts, sumw2 and nentries are all set to zero. The bin edges and overflow setting are kept. Returns h.

_factor(n::Integer)

Helper function to calculate the prime factors of a given integer.

push!(h::Hist2D, valx::Real, valy::Real, wgt::Real=1)
atomic_push!(h::Hist2D, valx::Real, valy::Real, wgt::Real=1)

Adding one value at a time into histogram. sumw2 (sum of weights^2) accumulates wgt^2 with a default weight of 1. atomic_push! is a slower version of push! that is thread-safe.

Entries where any coordinate is outside of the bin edges are discarded (and not counted in nentries), unless the histogram was created with overflow=true, in which case the coordinates are clamped into the first/last bin along each axis. NaN is treated like +Inf.

push!(h::Hist3D, valx::Real, valy::Real, valz::Real, wgt::Real=1)
atomic_push!(h::Hist3D, valx::Real, valy::Real, valz::Real, wgt::Real=1)

Adding one value at a time into histogram. sumw2 (sum of weights^2) accumulates wgt^2 with a default weight of 1. atomic_push! is a slower version of push! that is thread-safe.

Entries where any coordinate is outside of the bin edges are discarded (and not counted in nentries), unless the histogram was created with overflow=true, in which case the coordinates are clamped into the first/last bin along each axis. NaN is treated like +Inf.

push!(h::Hist1D, val::Real, wgt::Real=1)
atomic_push!(h::Hist1D, val::Real, wgt::Real=1)

Adding one value at a time into histogram. sumw2 (sum of weights^2) accumulates wgt^2 with a default weight of 1. atomic_push! is a slower version of push! that is thread-safe.

Values outside of the bin edges are discarded (and not counted in nentries), unless the histogram was created with overflow=true, in which case they are clamped into the first/last bin. NaN is treated like +Inf.

N.B. To append multiple values at once, use broadcasting via push!.(h, [-3.0, -2.9, -2.8]) or push!.(h, [-3.0, -2.9, -2.8], 2.0), or append!.

bayes_rebin_edges(h::Hist1D; prior=BayesHistogram.Geometric(0.995))

Find optimal bin edges for a histogram using Bayesian rebinning algorithm. This function only find edges, it doesn't return a new histogram.

For possible priors, see BayesHistogram.jl.

bincenters(h::Hist1D)

Get the bin centers of the histogram

bincenters(h::Hist2D)

Get the bin centers of the histogram

bincenters(h::Hist3D)

Get the bin centers of the histogram

bincounts(h::Hist1D)

Get the bin counts (weights) of the histogram.

bincounts(h::Hist2D)

Get the bin counts (weights) of the histogram.

bincounts(h::Hist3D)

Get the bin counts (weights) of the histogram.

binedges(h)

Get the bin edges of the histogram

binedges(h)

Get the bin edges of the histogram

binedges(h)

Get the bin edges of the histogram

binerrors(f=sqrt, h)

Get the error (uncertainty) of each bin. By default, calls sqrt on sumw2(h) bin by bin as an approximation.

binerrors(f=sqrt, h)

Get the error (uncertainty) of each bin. By default, calls sqrt on sumw2(h) bin by bin as an approximation.

binerrors(f=sqrt, h)

Get the error (uncertainty) of each bin. By default, calls sqrt on sumw2(h) bin by bin as an approximation.

cumulative(h::Hist1D; forward=true)
cumulative(h::Union{Hist2D, Hist3D}; forward=true, dims=:)

Create a cumulative histogram. If forward, start summing from the left (low edge) of each accumulated axis, otherwise from the right (high edge).

For Hist2D and Hist3D, dims selects the axis (or axes) to accumulate along; the default : accumulates along every axis, so that bin (i, j) holds the sum of all bins with x-index <= i and y-index <= j (this matches ROOT's TH2::GetCumulative). Pass dims=1 (or dims=2) to accumulate along a single axis only. forward may be a Bool applied to every accumulated axis, or a tuple of Bools with one entry per axis in dims.

sumw2 is accumulated the same way, nentries and overflow are kept.

Examples

julia> h = Hist2D(; bincounts = [1 2; 3 4], binedges = (0:2, 0:2));

julia> bincounts(cumulative(h))
2×2 Matrix{Float64}:
 1.0   3.0
 4.0  10.0

julia> bincounts(cumulative(h; dims=1, forward=false))
2×2 Matrix{Float64}:
 4.0  6.0
 3.0  4.0

effective_entries(h) -> scalar

Get the number of effective entries for the entire histogram:

\[n_\text{eff} = \frac{(\sum \text{Weights} )^2}{(\sum \text{Weight}^2 )}\]

This is also equivalent to integral(hist)^2 / sum(sumw2(hist)), this is the same as TH1::GetEffectiveEntries()

effective_entries(h) -> scalar

Get the number of effective entries for the entire histogram:

\[n_\text{eff} = \frac{(\sum \text{Weights} )^2}{(\sum \text{Weight}^2 )}\]

This is also equivalent to integral(hist)^2 / sum(sumw2(hist)), this is the same as TH1::GetEffectiveEntries()

effective_entries(h) -> scalar

Get the number of effective entries for the entire histogram:

\[n_\text{eff} = \frac{(\sum \text{Weights} )^2}{(\sum \text{Weight}^2 )}\]

This is also equivalent to integral(hist)^2 / sum(sumw2(hist)), this is the same as TH1::GetEffectiveEntries()

gpu_bincounts(data::AbstractArray; binedges, weights=nothing, overflow=false,
              counttype=Float32, backend=get_backend(data), blocksize=256, sync=true)

Compute the 1D bin counts of data on the device it lives on (GPU or the KernelAbstractions CPU() backend) and return them as a new device array of element type counttype and length length(binedges) - 1.

Requires a GPU array package (CUDA.jl, AMDGPU.jl, Metal.jl, oneAPI.jl, ...) to be loaded.

• binedges can be an AbstractRange or a vector, uniform binnings use an O(1) lookup.
• weights must be nothing or a device array of the same length as data.
• overflow follows the semantics of Hist1D: values outside of the edges are discarded, or clamped into the first/last bin when overflow=true.
• counttype is the element type of the counts (Float32 by default, as not every device supports Float64 atomics; Int32 also works for unweighted data).
• blocksize is the work-group size, sync=false skips the final synchronize(backend).

To get a full Hist1D (with sumw2 and nentries) from GPU data, simply call the regular constructor with a GPU array: Hist1D(cu_data; binedges = 0:0.1:1), the result lives on the CPU.

See also gpu_bincounts!.

Example

using FHist, CUDA
xs = CUDA.randn(10^7)
counts = gpu_bincounts(xs; binedges = -3:0.1:3)            # CuVector{Float32}
h = Hist1D(xs; binedges = -3:0.1:3, counttype = Float32)   # Hist1D on the CPU

gpu_bincounts!(counts::AbstractArray, data::AbstractArray; binedges, weights=nothing,
               overflow=false, backend=get_backend(data), blocksize=256, sync=true)

In-place version of gpu_bincounts: accumulate the bin counts of data into the device array counts (which must have length length(binedges) - 1 and is not zeroed first). Returns counts.

hists_to_bars(hist1ds)

Given a vector of Hist1D, return edges (xs), heights (ys), and grps (for grouping) that is useful for plotting stacked histogram.

integral(h; width=false)

Get the integral a histogram; width means multiply each bincount by their bin width (bin area for Hist2D, bin volume for Hist3D) when calculating the integral.

lookup(h::Hist1D, x)

For given x-axis value x, find the corresponding bin and return the bin content. If a value is out of the histogram range, return missing.

function lookup(h::Hist2D, x, y)

For given x-axis and y-axis value x, y, find the corresponding bin and return the bin content. If a value is out of the histogram range, return missing.

lookup(h::Hist3D, x, y, z)

For given x/y/z-axis value x, y, z, find the corresponding bin and return the bin content. If a value is out of the histogram range, return missing.

nbins(h::Hist1D)

Get the number of bins of a histogram.

nbins(h::Hist2D)

Get a 2-tuple of the number of x and y bins of a histogram.

nbins(h::Hist3D)

Get a 3-tuple of the number of x, y and z bins of a histogram.

nentries(h::Hist1D)

Get the number of entries that were filled (push!ed) into the histogram. Values that were discarded because they fell outside of the bin edges (with overflow=false) are not counted.

nentries(h::Hist2D)

Get the number of entries that were filled (push!ed) into the histogram. Values that were discarded because they fell outside of the bin edges (with overflow=false) are not counted.

nentries(h::Hist3D)

Get the number of entries that were filled (push!ed) into the histogram. Values that were discarded because they fell outside of the bin edges (with overflow=false) are not counted.

profile(h::Hist2D, axis::Symbol=:x)
profile(axis::Symbol=:x) = h::Hist2D -> profile(h, axis)

Returns the axis-profile of the 2D histogram by calculating the weighted mean over the other axis. profile(h, :x) will return a Hist1D with the y-axis edges of h.

project(h::Hist3D, axis::Symbol=:x)
project(axis::Symbol=:x) = h::Hist3D -> project(h, axis)

Computes the :x/:y/:z axis projection of the 3D histogram by summing over the specified axis. Returns a Hist2D.

project(h::Hist2D, axis::Symbol=:x)
project(axis::Symbol=:x) = h::Hist2D -> project(h, axis)

Computes the :x (:y) axis projection of the 2D histogram by summing over the y (x) axis. Returns a Hist1D.

rebin(h::Hist2D, nx::Int=1, ny::Int=nx)
rebin(h::Hist2D, xedges::AbstractVector{<:Real}, yedges::AbstractVector{<:Real})
rebin(nx::Int, ny::Int) = h::Hist2D -> rebin(h, nx, ny)

Merges nx (ny) consecutive bins into one along the x (y) axis by summing. Alternatively, provide the new bin edges along each axis; they must be a subset of the existing edges (see the Hist1D method of rebin).

rebin(h::Hist3D, nx::Int=1, ny::Int=nx, nz::Int=nx)
rebin(h::Hist3D, xedges::AbstractVector{<:Real}, yedges::AbstractVector{<:Real}, zedges::AbstractVector{<:Real})
rebin(nx::Int, ny::Int, nz::Int) = h::Hist3D -> rebin(h, nx, ny, nz)

Merges nx (ny, nz) consecutive bins into one along the x (y, z) axis by summing. Alternatively, provide the new bin edges along each axis; they must be a subset of the existing edges (see the Hist1D method of rebin).

rebin(h::Hist1D, n::Int=1)
rebin(h::Hist1D, edges::AbstractVector{<:Real})
rebin(n::Int)
rebin(edges::AbstractVector{<:Real})

Rebin a histogram by merging existing bins. When provided an integer n, the function merges n consecutive bins and returns nbins(h) / n bins. When provided a collection of bin edges edges, the function returns a new histogram whose bin edges match edges; every element of edges must align with the original bin edges.

If the edges is an array and doesn't include original histogram's leftmost and rightmost edges, those bins will be ignored (and overflow is set to false for the result).

The curried forms rebin(n) / rebin(edges) return a function h -> rebin(h, ...), they also work for Hist2D and Hist3D (using n along every axis).

restrict(h::Hist2D, xlow=-Inf, xhigh=Inf, ylow=-Inf, yhigh=Inf)
restrict(xlow=-Inf, xhigh=Inf, ylow=-Inf, yhigh=Inf) = h::Hist2D -> restrict(h, xlow, xhigh, ylow, yhigh)

Returns a new histogram with a restricted x-axis. restrict(h, 0, 3) (or h |> restrict(0, 3)) will return a slice of h where the bin centers are in [0, 3] (inclusive).

restrict(h::Hist3D, xlow=-Inf, xhigh=Inf, ylow=-Inf, yhigh=Inf, zlow=-Inf, zhigh=Inf)
restrict(xlow, xhigh, ylow, yhigh, zlow, zhigh) = h::Hist3D -> restrict(h, xlow, xhigh, ylow, yhigh, zlow, zhigh)

Returns a new histogram with restricted axes: the slice of h where the bin centers are within the given (inclusive) intervals along each axis.

restrict(h::Hist1D, low=-Inf, high=Inf)
restrict(low=-Inf, high=Inf) = h::Hist1D -> restrict(h, low, high)

Returns a new histogram with a restricted x-axis. restrict(h, 0, 3) (or h |> restrict(0, 3)) will return a slice of h where the bin centers are in [0, 3] (inclusive).

significance(signal, bkg) -> `(significance, error_on_significance)`

Calculate the significance of signal vs. bkg histograms, this function uses a more accurate algorithm than the naive S / sqrt(B)

Ref: https://cds.cern.ch/record/2736148/files/ATL-PHYS-PUB-2020-025.pdf

Example:

julia> h1 = Hist1D(rand(1000);  binedges = [0, 0.5]);

julia> h2 = Hist1D(rand(10000); binedges = [0, 0.5]);

julia> s1 = significance(h1,h2)
(6.738690967342175, 0.3042424717261312)

sumw2(h)

Get the sum of weights squared of the histogram, it has the same shape as bincounts(h).

sumw2(h)

Get the sum of weights squared of the histogram, it has the same shape as bincounts(h).

sumw2(h)

Get the sum of weights squared of the histogram, it has the same shape as bincounts(h).

transpose(h::Hist2D)

Reverses the x and y axes.

valid_rebin_values(h::Union{Hist1D, Hist2D, Hist3D})

Calculates the legal values for rebinning, essentially the prime factors of the number of bins. For a 1D histogram, a Set of numbers is return, for higher dimensional histograms a Vector{Set} for each dimension.

normalize(h::Hist1D; width=true)

Create a normalized histogram via division by integral(h), when width==true, the resultant histogram has area under the curve equals 1.

normalize(h::Hist2D; width=false)

Create a normalized histogram via division by integral(h). When width==true, each bin is additionally divided by its area such that integral(normalize(h; width=true); width=true) == 1.

normalize(h::Hist3D; width=false)

Create a normalized histogram via division by integral(h). When width==true, each bin is additionally divided by its volume such that integral(normalize(h; width=true); width=true) == 1.

Statistics.mean(h)
Statistics.std(h)
Statistics.median(h)
Statistics.quantile(h::Hist1D, p)

Compute statistical quantities based on the bin centers weighted by the bin counts.

When the histogram is Hist2D (Hist3D), return a 2-tuple (3-tuple) instead, e.g (mean(project(h, :x)), mean(project(h, :y))) etc.

sample(h::Hist1D; n::Int=1)

Sample a histogram's with weights equal to bin count, n times. The sampled values are the bins' lower edges.

sample(h::Hist2D; n::Int=1)

Sample a histogram's with weights equal to bin count, n times. The sampled values are the bins' lower edges.

sample(h::Hist3D; n::Int=1)

Sample a histogram's with weights equal to bin count, n times. The sampled values are the bins' lower edges.