deprecate histogram functionality

base/deprecated.jl

@@ -1273,6 +1273,164 @@ end
 @deprecate print_unescaped unescape_string
 @deprecate print_joined join
 
+##### histogram #####
+
+## nice-valued ranges for histograms
+export hist, hist!, hist2d, hist2d!, histrange
+
+function histrange{T<:AbstractFloat,N}(v::AbstractArray{T,N}, n::Integer)
+ depwarn("histrange(...) is deprecated, use StatsBase.histrange(...) instead",:histrange)
+ nv = length(v)
+ if nv == 0 && n < 0
+ throw(ArgumentError("number of bins must be ≥ 0 for an empty array, got $n"))
+ elseif nv > 0 && n < 1
+ throw(ArgumentError("number of bins must be ≥ 1 for a non-empty array, got $n"))
+ end
+ if nv == 0
+ return 0.0:1.0:0.0
+ end
+ lo, hi = extrema(v)
+ if hi == lo
+ step = 1.0
+ else
+ bw = (hi - lo) / n
+ e = 10.0^floor(log10(bw))
+ r = bw / e
+ if r <= 2
+ step = 2*e
+ elseif r <= 5
+ step = 5*e
+ else
+ step = 10*e
+ end
+ end
+ start = step*(ceil(lo/step)-1)
+ nm1 = ceil(Int,(hi - start)/step)
+ start:step:(start + nm1*step)
+end
+
+function histrange{T<:Integer,N}(v::AbstractArray{T,N}, n::Integer)
+ depwarn("histrange(...) is deprecated, use StatsBase.histrange(...) instead",:histrange)
+ nv = length(v)
+ if nv == 0 && n < 0
+ throw(ArgumentError("number of bins must be ≥ 0 for an empty array, got $n"))
+ elseif nv > 0 && n < 1
+ throw(ArgumentError("number of bins must be ≥ 1 for a non-empty array, got $n"))
+ end
+ if nv == 0
+ return 0:1:0
+ end
+ if n <= 0
+ throw(ArgumentError("number of bins n=$n must be positive"))
+ end
+ lo, hi = extrema(v)
+ if hi == lo
+ step = 1
+ else
+ bw = (Float64(hi) - Float64(lo)) / n
+ e = 10.0^max(0,floor(log10(bw)))
+ r = bw / e
+ if r <= 1
+ step = e
+ elseif r <= 2
+ step = 2*e
+ elseif r <= 5
+ step = 5*e
+ else
+ step = 10*e
+ end
+ end
+ start = step*(ceil(lo/step)-1)
+ nm1 = ceil(Int,(hi - start)/step)
+ start:step:(start + nm1*step)
+end
+
+## midpoints of intervals
+midpoints(r::Range) = r[1:length(r)-1] + 0.5*step(r)
+midpoints(v::AbstractVector) = [0.5*(v[i] + v[i+1]) for i in 1:length(v)-1]
+
+## hist ##
+function sturges(n) # Sturges' formula
+ depwarn("sturges(n) is deprecated, use StatsBase.sturges(n) instead.",:sturges)
+ n==0 && return one(n)
+ ceil(Int,log2(n))+1
+end
+
+function hist!{HT}(h::AbstractArray{HT}, v::AbstractVector, edg::AbstractVector; init::Bool=true)
+ depwarn("hist(...) and hist!(...) are deprecated. Use fit(Histogram,...) in StatsBase.jl instead.",:hist!)
+ n = length(edg) - 1
+ length(h) == n || throw(DimensionMismatch("length(histogram) must equal length(edges) - 1"))
+ if init
+ fill!(h, zero(HT))
+ end
+ for x in v
+ i = searchsortedfirst(edg, x)-1
+ if 1 <= i <= n
+ h[i] += 1
+ end
+ end
+ edg, h
+end
+
+hist(v::AbstractVector, edg::AbstractVector) = hist!(Array(Int, length(edg)-1), v, edg)
+hist(v::AbstractVector, n::Integer) = hist(v,histrange(v,n))
+hist(v::AbstractVector) = hist(v,sturges(length(v)))
+
+function hist!{HT}(H::AbstractArray{HT,2}, A::AbstractMatrix, edg::AbstractVector; init::Bool=true)
+ depwarn("hist(...) and hist!(...) are deprecated. Use fit(Histogram,...) in StatsBase.jl instead.",:hist!)
+
+ m, n = size(A)
+ sH = size(H)
+ sE = (length(edg)-1,n)
+ sH == sE || throw(DimensionMismatch("incorrect size of histogram"))
+ if init
+ fill!(H, zero(HT))
+ end
+ for j = 1:n
+ hist!(sub(H, :, j), sub(A, :, j), edg)
+ end
+ edg, H
+end
+
+hist(A::AbstractMatrix, edg::AbstractVector) = hist!(Array(Int, length(edg)-1, size(A,2)), A, edg)
+hist(A::AbstractMatrix, n::Integer) = hist(A,histrange(A,n))
+hist(A::AbstractMatrix) = hist(A,sturges(size(A,1)))
+
+
+## hist2d
+function hist2d!{HT}(H::AbstractArray{HT,2}, v::AbstractMatrix,
+ edg1::AbstractVector, edg2::AbstractVector; init::Bool=true)
+ depwarn("hist2d!(...) and hist2d(...) are deprecated. Use fit(Histogram,...) in StatsBase.jl instead.",:hist2d!)
+
+ size(v,2) == 2 || throw(DimensionMismatch("hist2d requires an Nx2 matrix"))
+ n = length(edg1) - 1
+ m = length(edg2) - 1
+ size(H) == (n, m) || throw(DimensionMismatch("incorrect size of histogram"))
+ if init
+ fill!(H, zero(HT))
+ end
+ for i = 1:size(v,1) # fixme (iter): update when #15459 is done
+ x = searchsortedfirst(edg1, v[i,1]) - 1
+ y = searchsortedfirst(edg2, v[i,2]) - 1
+ if 1 <= x <= n && 1 <= y <= m
+ @inbounds H[x,y] += 1
+ end
+ end
+ edg1, edg2, H
+end
+
+hist2d(v::AbstractMatrix, edg1::AbstractVector, edg2::AbstractVector) =
+ hist2d!(Array(Int, length(edg1)-1, length(edg2)-1), v, edg1, edg2)
+
+hist2d(v::AbstractMatrix, edg::AbstractVector) = hist2d(v, edg, edg)
+
+hist2d(v::AbstractMatrix, n1::Integer, n2::Integer) =
+ hist2d(v, histrange(sub(v,:,1),n1), histrange(sub(v,:,2),n2))
+hist2d(v::AbstractMatrix, n::Integer) = hist2d(v, n, n)
+hist2d(v::AbstractMatrix) = hist2d(v, sturges(size(v,1)))
+
+
+
 # During the 0.5 development cycle, do not add any deprecations below this line
 # To be deprecated in 0.6
 

base/docs/helpdb/Base.jl

@@ -287,14 +287,6 @@ Multiply elements of `A` over the singleton dimensions of `r`, and write results
 """
 prod!
 
-"""
- hist2d!(counts, M, e1, e2) -> (e1, e2, counts)
-
-Compute a "2d histogram" with respect to the bins delimited by the edges given in `e1` and
-`e2`. This function writes the results to a pre-allocated array `counts`.
-"""
-hist2d!
-
 """
  airybi(x)
 
@@ -4291,18 +4283,6 @@ An indexing operation into an array, `a`, tried to access an out-of-bounds eleme
 """
 BoundsError
 
-"""
- hist2d(M, e1, e2) -> (edge1, edge2, counts)
-
-Compute a "2d histogram" of a set of N points specified by N-by-2 matrix `M`. Arguments `e1`
-and `e2` are bins for each dimension, specified either as integer bin counts or vectors of
-bin edges. The result is a tuple of `edge1` (the bin edges used in the first dimension),
-`edge2` (the bin edges used in the second dimension), and `counts`, a histogram matrix of
-size `(length(edge1)-1, length(edge2)-1)`. Note: Julia does not ignore `NaN` values in the
-computation.
-"""
-hist2d
-
 """
  which(f, types)
 
@@ -5895,15 +5875,6 @@ order with arrays.
 """
 symdiff
 
-"""
- histrange(v, n)
-
-Compute *nice* bin ranges for the edges of a histogram of `v`, using approximately `n` bins.
-The resulting step sizes will be 1, 2 or 5 multiplied by a power of 10. Note: Julia does not
-ignore `NaN` values in the computation.
-"""
-histrange
-
 """
  eta(x)
 
@@ -6886,14 +6857,6 @@ of a string. Control characters are the non-printing characters of the Latin-1 s
 """
 iscntrl
 
-"""
- hist!(counts, v, e) -> e, counts
-
-Compute the histogram of `v`, using a vector/range `e` as the edges for the bins. This
-function writes the resultant counts to a pre-allocated array `counts`.
-"""
-hist!
-
 """
  minimum!(r, A)
 
@@ -9634,24 +9597,6 @@ transformation is performed internally to map the infinite interval to a finite
 """
 quadgk
 
-"""
- hist(v[, n]) -> e, counts
-
-Compute the histogram of `v`, optionally using approximately `n` bins. The return values are
-a range `e`, which correspond to the edges of the bins, and `counts` containing the number
-of elements of `v` in each bin. Note: Julia does not ignore `NaN` values in the computation.
-"""
-hist(v,n::Int=?)
-
-"""
- hist(v, e) -> e, counts
-
-Compute the histogram of `v` using a vector/range `e` as the edges for the bins. The result
-will be a vector of length `length(e) - 1`, such that the element at location `i` satisfies
-`sum(e[i] .< v .<= e[i+1])`. Note: Julia does not ignore `NaN` values in the computation.
-"""
-hist(v,e)
-
 """
  islower(c::Union{Char,AbstractString}) -> Bool
 

base/exports.jl

@@ -905,11 +905,6 @@ export
 # statistics
  cor,
  cov,
- hist,
- hist!,
- hist2d,
- hist2d!,
- histrange,
  mean!,
  mean,
  median!,