Feature Request: Support bin width/step size in fit(Histogram, ...)

[anurag-mds]

As I, was discussing on slack about this with some members;

This idea was discussed in the community: See the thread

I thought that currently, fit(Histogram, data) requires users to either specify the number of bins (nbins) or the exact bin edges. While flexible, a common workflow in scientific computing is to specify bins by a fixed width (e.g., "one bin every 0.5 units") independent of the data range.

Although this can be done manually with fit(Histogram, data, min:width:max), it requires calculating bounds and handling potential edge alignment issues manually.

Reference:
The current fit implementations for Histogram are centered around these methods:

StatsBase.jl/src/hist.jl

Lines 298 to 307 in 7388a8e

	fit(::Type{Histogram{T}},v::AbstractVector, edg::AbstractVector; closed::Symbol=:left) where {T} =
	fit(Histogram{T},(v,), (edg,), closed=closed)
	fit(::Type{Histogram{T}},v::AbstractVector; closed::Symbol=:left, nbins=sturges(length(v))) where {T} =
	fit(Histogram{T},(v,); closed=closed, nbins=nbins)
	fit(::Type{Histogram{T}},v::AbstractVector, wv::AbstractWeights, edg::AbstractVector; closed::Symbol=:left) where {T} =
	fit(Histogram{T},(v,), wv, (edg,), closed=closed)
	fit(::Type{Histogram{T}},v::AbstractVector, wv::AbstractWeights; closed::Symbol=:left, nbins=sturges(length(v))) where {T} =
	fit(Histogram{T}, (v,), wv; closed=closed, nbins=nbins)
	fit(::Type{Histogram}, v::AbstractVector, wv::AbstractWeights{W}, args...; kwargs...) where {W} = fit(Histogram{W}, v, wv, args...; kwargs...)

Proposed Change:
Add a keyword argument or helper type to allow binning by width. Examples:

# Option 1: keyword argument
fit(Histogram, data; width=0.5)

# Option 2: helper type
fit(Histogram, data, BinWidth(0.5))

My proposal is to extend this dispatch pattern. Currently, we have:

fit(..., edges) (User provides the range)

fit(..., nbins) (Internal histrange calculates the range)

I will add a third path:
3. fit(..., binwidth) (A simple range min:binwidth:max is generated and passed to the existing edges method).

Additional Considerations:

Alignment/anchor: Optional parameter to control where the first bin edge starts.

Variable resolution: Optional method for "equal-count" bins using data quantiles.

This Simplifies the API for new users, aligns with common libraries (NumPy, matplotlib), and reduces errors in manual bin calculations.

[anurag-mds]

Hey, following up on my histogram idea. First bin could default to minimum(data) but allow an anchor. Last bin would just extend to include the max. closed stays the same, NaNs ignored. Fixed-width only quantile bins are separate. Curious if this makes sense or I’m missing something.

[dcelisgarza]

Related, is there a way to compute optimal bin widths a la numpy.histogram_bin_edges

[anurag-mds]

I really appreciate you bringing this to my attention. The thing about my proposal is that it gives people the option to have bins that're all the same width and this does not depend on how many bins there are or where the edges are. This is similar to what numpy.histogram_bin_edges does.

The first bin will start at the value in the data but people can also choose to start it somewhere else if they want to.

If there are any NaNs in the data they will be ignored.

Also whether the bins are closed or open will stay the same.

I think it would be better if bins that can change in width or bins that are based on quantiles were a method, for creating bins.

Does this approach align with what you envision, or would you prefer integrating an automatic ‘optimal width’ heuristic as part of the same API?

[dcelisgarza]

It aligns with the proposal. width could accept a symbol as well as a number. Then internally dispatch using Val or an if statement.

[anurag-mds]

I appreciate your feedback. What I suggest is:

Add a width keyword or helper type to generate fixed-width bins internally via min:width:max.

Set the first bin to minimum (data) by default, but permit an optional anchor.

Maintain all current behaviour, such as respecting weights, handling closed edges, and ignoring NaNs.

To prevent duplication, this path will internally reuse the existing edges method.

Automatic heuristics such as Freedman-Diaconis or variable-width/quantile-based bins will continue to be distinct approaches.

Does this match the direction you see for this enhancement?

[dcelisgarza]

Sounds good to me but i'm not a maintainer. I just thought i'd chime in with something useful that's oddly missing.