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. It would switch to O(1) `searchsortedlast` if the binning is uniform.

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}}

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}}

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}}

function _factor(n::Integer)

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

push!(h::Hist3D, valx::Real, valy::Real, wgt::Real=1)
atomic_push!(h::Hist3D, 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.

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.

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)

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.

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)

Create a cumulative histogram. If forward, start summing from the left.

effective_entries(h) -> scalar

Get the number of effective entries for the entire histogram:

\[n_{eff} = \frac{(\sum Weights )^2}{(\sum 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_{eff} = \frac{(\sum Weights )^2}{(\sum 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_{eff} = \frac{(\sum Weights )^2}{(\sum Weight^2 )}\]

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

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 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.

function 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 and y bins of a histogram.

nentries(h::Hist1D)

Get the number of times a histogram is filled (push!ed)

nentries(h::Hist2D)

Get the number of times a histogram is filled (push!ed)

nentries(h::Hist3D)

Get the number of times a histogram is filled (push!ed)

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(nx::Int, ny::Int) = h::Hist2D -> rebin(h, nx, ny)

Merges nx (ny) consecutive bins into one along the x (y) axis by summing.

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 and span the full histogram range.

If the edges is an array and doesn't include original histogram's leftmost and rightmost edges, those bins will be ignored.

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::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).

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.

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:

h1 = Hist1D(rand(1000);  binedges = [0, 0.5])
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)

Create a normalized histogram via division by integral(h).

normalize(h::Hist3D)

Create a normalized histogram via division by integral(h).

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, return tuple instead, e.g (mean(project(h, :x)), mean(project(h, :y))) etc.