From 586066d6dc522af48d9007f062d81b72761cced1 Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Wed, 21 Jun 2023 23:13:21 +0200 Subject: [PATCH] Document how histogram bins are chosen by default (#829) Also avoid mentioning `sturges` in the docstring since it is not exported. Co-authored-by: Alex Arslan --- src/hist.jl | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/hist.jl b/src/hist.jl index 44940a1db..7333d8424 100644 --- a/src/hist.jl +++ b/src/hist.jl @@ -363,7 +363,7 @@ fit(::Type{Histogram{T}}, vs::NTuple{N,AbstractVector}, wv::AbstractWeights; clo fit(Histogram{T}, vs, wv, histrange(vs,_nbins_tuple(vs, nbins),closed); closed=closed) """ - fit(Histogram, data[, weight][, edges]; closed=:left, nbins) + fit(Histogram, data[, weight][, edges]; closed=:left[, nbins]) Fit a histogram to `data`. @@ -377,8 +377,12 @@ Fit a histogram to `data`. bin. If no weight vector is supplied, each observation has weight 1. * `edges`: a vector (typically an `AbstractRange` object), or tuple of vectors, that gives - the edges of the bins along each dimension. If no edges are provided, these - are determined from the data. + the edges of the bins along each dimension. If no edges are provided, they are chosen + so that approximately `nbins` bins of equal width are constructed along each dimension. + +!!! note + In most cases, the number of bins will be `nbins`. However, to ensure that the bins have + equal width, more or fewer than `nbins` bins may be used. # Keyword arguments @@ -387,6 +391,8 @@ Fit a histogram to `data`. * `nbins`: if no `edges` argument is supplied, the approximate number of bins to use along each dimension (can be either a single integer, or a tuple of integers). + If omitted, it is computed using Sturges's formula, i.e. `ceil(log2(length(n))) + 1` + with `n` the number of data points. # Examples