Add low-level allocating histogram interface

Author: jmert

src/histogram.jl

@@ -135,4 +135,32 @@ __hist_eltype(eltypes) = _invunit(typeof(mapreduce(oneunit, *, eltypes)))
 _hist_eltype(edges::Tuple{Vararg{AbstractRange}}) = __hist_eltype(map(eltype, edges))
 _hist_eltype(edges::Tuple{Vararg{HistEdge}}) = __hist_eltype(map(eltype, edges))
 
+_hist_size(edges::Tuple{Vararg{AbstractRange}}) = map(e -> length(e) - 1, edges)
+_hist_size(edges::Tuple{Vararg{HistEdge}}) = map(e -> e.nbin, edges)
+
+function _histogram(binning::AbstractBinning,
+                    data::AbstractVector{<:Tuple{Vararg{Any,N}}},
+                    edges::Tuple{Vararg{HistEdge,N}};
+                    weights::Union{Nothing,<:AbstractVector} = nothing
+                   ) where {N}
+    hist = zeros(_hist_eltype(edges), _hist_size(edges)...)
+    _histogram!(binning, hist, edges, data, weights)
+    return hist
+end
+function _histogram(binning::AbstractBinning,
+                    data::AbstractVector{<:Tuple{Vararg{Any,N}}},
+                    edges::Tuple{Vararg{AbstractRange,N}};
+                    weights::Union{Nothing,<:AbstractVector} = nothing
+                   ) where {N}
+    edges′ = map(HistEdge, edges)
+    return _histogram(binning, data, edges′; weights)
+end
+function _histogram(binning::AbstractBinning,
+                    data::AbstractVector{<:Tuple{Vararg{Any,N}}},
+                    edges::Union{<:HistEdge,<:AbstractRange}...;
+                    weights::Union{Nothing,<:AbstractVector} = nothing
+                   ) where {N}
+    return _histogram(binning, data, edges; weights)
+end
+
 end  # module Histogramming

src/kde.jl

@@ -398,11 +398,9 @@ function estimate(method::AbstractBinningKDE,
                   info::UnivariateKDEInfo) where {T}
     lo, hi, nbins = info.lo, info.hi, info.nbins
 
-    f = zeros(_invunit(T), nbins)
     data′ = reinterpret(reshape, Tuple{T}, data)
-    Histogramming._histogram!(_kde2hist_method(method), f,
-                              (Histogramming.HistEdge(lo, hi, nbins),), data′, weights)
-
+    f = Histogramming._histogram(_kde2hist_method(method),
+                                 data′, (Histogramming.HistEdge(lo, hi, nbins),); weights)
     if lo == hi
         centers = range(lo, hi, length = 1)
     else

test/histogram.jl

@@ -88,7 +88,7 @@ const LB = Histogramming.LinearBinning()
 end
 
 @testset "Low Level ($(N)D, $style)" for N in 1:3, style in (HB, LB)
-    using .Histogramming: HistEdge, _histogram!
+    using .Histogramming: HistEdge, _histogram!, _histogram
 
     edges = ((0.0:0.25:1.0 for _ in 1:N)...,)
     edges′ = HistEdge.(edges)
@@ -104,6 +104,9 @@ end
     fill!(hist, 0)
     _histogram!(style, hist, edges′, x1, nothing)
     @test sum(hist) * step(edges[1])^N == 1.0
+    # compare to the allocating interface
+    @test hist == _histogram(style, x1, edges′)
+    @test hist == _histogram(style, x1, edges′; weights = [1])
 
     # out-of-bounds elements are not binned
     x0 = [(-1.0, (0.0 for _ in 1:N-1)...,)]
@@ -115,6 +118,15 @@ end
         fill!(hist, 0)
         @test (@inferred _histogram!(style, hist, edges′, x1, nothing)) === 1.0
         @test_broken (@allocated _histogram!(style, hist, edges′, x1, nothing)) == 0
+
+        @test (@inferred _histogram(style, x1, edges)) isa Array{Float64,N}
+        @test (@inferred _histogram(style, x1, edges; weights = [1])) isa Array{Float64,N}
+        @test (@inferred _histogram(style, x1, edges′)) isa Array{Float64,N}
+        @test (@inferred _histogram(style, x1, edges′; weights = [1])) isa Array{Float64,N}
+        @test (@inferred _histogram(style, x1, edges...)) isa Array{Float64,N}
+        @test (@inferred _histogram(style, x1, edges...; weights = [1])) isa Array{Float64,N}
+        @test (@inferred _histogram(style, x1, edges′...)) isa Array{Float64,N}
+        @test (@inferred _histogram(style, x1, edges′...; weights = [1])) isa Array{Float64,N}
     end
 
     @testset "Unitful numbers" begin
@@ -128,6 +140,14 @@ end
         # verify that the function accepts unitful quantities
         @test _histogram!(style, uhist, HistEdge.(uedges), vals, nothing) === 1.0
         @test sum(uhist) * mapreduce(step, *, uedges) ≈ 1.0 rtol=2eps(1.0)
+
+        uhist2 = _histogram(style, vals, uedges)
+        @test eltype(uhist2) == eltype(uhist)
+        @test uhist2 == uhist
+
+        uhist3 = _histogram(style, vals, uedges...)
+        @test eltype(uhist3) == eltype(uhist)
+        @test uhist3 == uhist
     end
 end