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.

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

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.

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

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

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

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

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.

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

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.

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.