From 1c39dfc81d1a64418fce888d359f04072b82c1b8 Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Fri, 5 May 2017 10:30:54 +0200 Subject: [PATCH 1/2] Make cov()'s corrected argument a keyword argument and cleanup docstrings For consistency with var and std. Also remove methods which are no longer needed now that deprecations have been removed. Add types to signatures in docstrings. --- NEWS.md | 3 +++ base/deprecated.jl | 6 +++++ base/statistics.jl | 57 +++++++++++++++++++--------------------------- test/statistics.jl | 36 ++++++++++++++--------------- 4 files changed, 50 insertions(+), 52 deletions(-) diff --git a/NEWS.md b/NEWS.md index af1aee2f30135..514a7b82d3fa8 100644 --- a/NEWS.md +++ b/NEWS.md @@ -117,6 +117,9 @@ Deprecated or removed implementations is now in AbstractFFTs.jl, the bindings to the FFTW library are in FFTW.jl, and the Base signal processing functions which used FFTs are now in DSP.jl ([#21956]). + * The `corrected` positional argument to `cov` has been deprecated in favor of + a keyword argument with the same name (#21709). + Julia v0.6.0 Release Notes ========================== diff --git a/base/deprecated.jl b/base/deprecated.jl index f31b9b7da8860..2d858ebea41e3 100644 --- a/base/deprecated.jl +++ b/base/deprecated.jl @@ -1485,6 +1485,12 @@ end using .DSP export conv, conv2, deconv, filt, filt!, xcorr +# PR #21709 +@deprecate cov(x::AbstractVector, corrected::Bool) cov(x, corrected=corrected) +@deprecate cov(x::AbstractMatrix, vardim::Int, corrected::Bool) cov(x, corrected=corrected) +@deprecate cov(X::AbstractVector, Y::AbstractVector, corrected::Bool) cov(X, Y, corrected=corrected) +@deprecate cov(X::AbstractVecOrMat, Y::AbstractVecOrMat, vardim::Int, corrected::Bool) cov(X, Y, vardim, corrected=corrected) + # END 0.7 deprecations # BEGIN 1.0 deprecations diff --git a/base/statistics.jl b/base/statistics.jl index 6e9f9dfc42ee7..17114c9424294 100644 --- a/base/statistics.jl +++ b/base/statistics.jl @@ -317,75 +317,64 @@ unscaled_covzm(x::AbstractMatrix, y::AbstractMatrix, vardim::Int) = # covzm (with centered data) -covzm(x::AbstractVector, corrected::Bool=true) = unscaled_covzm(x) / (_length(x) - Int(corrected)) -covzm(x::AbstractMatrix, vardim::Int=1, corrected::Bool=true) = +covzm(x::AbstractVector; corrected::Bool=true) = unscaled_covzm(x) / (_length(x) - Int(corrected)) +covzm(x::AbstractMatrix, vardim::Int=1; corrected::Bool=true) = scale!(unscaled_covzm(x, vardim), inv(size(x,vardim) - Int(corrected))) -covzm(x::AbstractVector, y::AbstractVector, corrected::Bool=true) = +covzm(x::AbstractVector, y::AbstractVector; corrected::Bool=true) = unscaled_covzm(x, y) / (_length(x) - Int(corrected)) -covzm(x::AbstractVecOrMat, y::AbstractVecOrMat, vardim::Int=1, corrected::Bool=true) = +covzm(x::AbstractVecOrMat, y::AbstractVecOrMat, vardim::Int=1; corrected::Bool=true) = scale!(unscaled_covzm(x, y, vardim), inv(_getnobs(x, y, vardim) - Int(corrected))) # covm (with provided mean) -covm(x::AbstractVector, xmean, corrected::Bool=true) = - covzm(x .- xmean, corrected) -covm(x::AbstractMatrix, xmean, vardim::Int=1, corrected::Bool=true) = - covzm(x .- xmean, vardim, corrected) -covm(x::AbstractVector, xmean, y::AbstractVector, ymean, corrected::Bool=true) = - covzm(x .- xmean, y .- ymean, corrected) -covm(x::AbstractVecOrMat, xmean, y::AbstractVecOrMat, ymean, vardim::Int=1, corrected::Bool=true) = - covzm(x .- xmean, y .- ymean, vardim, corrected) +covm(x::AbstractVector, xmean; corrected::Bool=true) = + covzm(x .- xmean; corrected=corrected) +covm(x::AbstractMatrix, xmean, vardim::Int=1; corrected::Bool=true) = + covzm(x .- xmean, vardim; corrected=corrected) +covm(x::AbstractVector, xmean, y::AbstractVector, ymean; corrected::Bool=true) = + covzm(x .- xmean, y .- ymean; corrected=corrected) +covm(x::AbstractVecOrMat, xmean, y::AbstractVecOrMat, ymean, vardim::Int=1; corrected::Bool=true) = + covzm(x .- xmean, y .- ymean, vardim; corrected=corrected) # cov (API) """ - cov(x[, corrected=true]) + cov(x::AbstractVector; corrected::Bool=true) Compute the variance of the vector `x`. If `corrected` is `true` (the default) then the sum is scaled with `n-1`, whereas the sum is scaled with `n` if `corrected` is `false` where `n = length(x)`. """ -cov(x::AbstractVector, corrected::Bool) = covm(x, Base.mean(x), corrected) -# This ugly hack is necessary to make the method below considered more specific than the deprecated method. When the old keyword version has been completely deprecated, these two methods can be merged -cov(x::AbstractVector) = covm(x, Base.mean(x), true) +cov(x::AbstractVector; corrected::Bool=true) = covm(x, Base.mean(x); corrected=corrected) """ - cov(X[, vardim=1, corrected=true]) + cov(X::AbstractMatrix[, vardim::Int=1]; corrected::Bool=true) Compute the covariance matrix of the matrix `X` along the dimension `vardim`. If `corrected` is `true` (the default) then the sum is scaled with `n-1`, whereas the sum is scaled with `n` if `corrected` is `false` where `n = size(X, vardim)`. """ -cov(X::AbstractMatrix, vardim::Int, corrected::Bool=true) = - covm(X, _vmean(X, vardim), vardim, corrected) -# This ugly hack is necessary to make the method below considered more specific than the deprecated method. When the old keyword version has been completely deprecated, these two methods can be merged -cov(X::AbstractMatrix) = cov(X, 1, true) +cov(X::AbstractMatrix, vardim::Int=1; corrected::Bool=true) = + covm(X, _vmean(X, vardim), vardim; corrected=corrected) """ - cov(x, y[, corrected=true]) + cov(x::AbstractVector, y::AbstractVector; corrected::Bool=true) Compute the covariance between the vectors `x` and `y`. If `corrected` is `true` (the default), computes ``\\frac{1}{n-1}\\sum_{i=1}^n (x_i-\\bar x) (y_i-\\bar y)^*`` where ``*`` denotes the complex conjugate and `n = length(x) = length(y)`. If `corrected` is `false`, computes ``\frac{1}{n}\sum_{i=1}^n (x_i-\\bar x) (y_i-\\bar y)^*``. """ -cov(x::AbstractVector, y::AbstractVector, corrected::Bool) = - covm(x, Base.mean(x), y, Base.mean(y), corrected) -# This ugly hack is necessary to make the method below considered more specific than the deprecated method. When the old keyword version has been completely deprecated, these two methods can be merged -cov(x::AbstractVector, y::AbstractVector) = - covm(x, Base.mean(x), y, Base.mean(y), true) +cov(x::AbstractVector, y::AbstractVector; corrected::Bool=true) = + covm(x, Base.mean(x), y, Base.mean(y); corrected=corrected) """ - cov(X, Y[, vardim=1, corrected=true]) + cov(X::AbstractVecOrMat, Y::AbstractVecOrMat[, vardim::Int=1]; corrected::Bool=true) Compute the covariance between the vectors or matrices `X` and `Y` along the dimension `vardim`. If `corrected` is `true` (the default) then the sum is scaled with `n-1`, whereas the sum is scaled with `n` if `corrected` is `false` where `n = size(X, vardim) = size(Y, vardim)`. """ -cov(X::AbstractVecOrMat, Y::AbstractVecOrMat, vardim::Int, corrected::Bool=true) = - covm(X, _vmean(X, vardim), Y, _vmean(Y, vardim), vardim, corrected) -# This ugly hack is necessary to make the method below considered more specific than the deprecated method. When the old keyword version has been completely deprecated, these methods can be merged -cov(x::AbstractVector, Y::AbstractMatrix) = cov(x, Y, 1, true) -cov(X::AbstractMatrix, y::AbstractVector) = cov(X, y, 1, true) -cov(X::AbstractMatrix, Y::AbstractMatrix) = cov(X, Y, 1, true) +cov(X::AbstractVecOrMat, Y::AbstractVecOrMat, vardim::Int=1; corrected::Bool=true) = + covm(X, _vmean(X, vardim), Y, _vmean(Y, vardim), vardim; corrected=corrected) ##### correlation ##### diff --git a/test/statistics.jl b/test/statistics.jl index 9253b1c8f6b6e..81856943a822c 100644 --- a/test/statistics.jl +++ b/test/statistics.jl @@ -186,50 +186,50 @@ for vd in [1, 2], zm in [true, false], cr in [true, false] y1 = vec(Y[1,:]) end - c = zm ? Base.covm(x1, 0, cr) : - cov(x1, cr) + c = zm ? Base.covm(x1, 0, corrected=cr) : + cov(x1, corrected=cr) @test isa(c, Float64) @test c ≈ Cxx[1,1] - @inferred cov(x1, cr) + @inferred cov(x1, corrected=cr) @test cov(X) == Base.covm(X, mean(X, 1)) - C = zm ? Base.covm(X, 0, vd, cr) : - cov(X, vd, cr) + C = zm ? Base.covm(X, 0, vd, corrected=cr) : + cov(X, vd, corrected=cr) @test size(C) == (k, k) @test C ≈ Cxx - @inferred cov(X, vd, cr) + @inferred cov(X, vd, corrected=cr) @test cov(x1, y1) == Base.covm(x1, mean(x1), y1, mean(y1)) - c = zm ? Base.covm(x1, 0, y1, 0, cr) : - cov(x1, y1, cr) + c = zm ? Base.covm(x1, 0, y1, 0, corrected=cr) : + cov(x1, y1, corrected=cr) @test isa(c, Float64) @test c ≈ Cxy[1,1] - @inferred cov(x1, y1, cr) + @inferred cov(x1, y1, corrected=cr) if vd == 1 @test cov(x1, Y) == Base.covm(x1, mean(x1), Y, mean(Y, 1)) end - C = zm ? Base.covm(x1, 0, Y, 0, vd, cr) : - cov(x1, Y, vd, cr) + C = zm ? Base.covm(x1, 0, Y, 0, vd, corrected=cr) : + cov(x1, Y, vd, corrected=cr) @test size(C) == (1, k) @test vec(C) ≈ Cxy[1,:] - @inferred cov(x1, Y, vd, cr) + @inferred cov(x1, Y, vd, corrected=cr) if vd == 1 @test cov(X, y1) == Base.covm(X, mean(X, 1), y1, mean(y1)) end - C = zm ? Base.covm(X, 0, y1, 0, vd, cr) : - cov(X, y1, vd, cr) + C = zm ? Base.covm(X, 0, y1, 0, vd, corrected=cr) : + cov(X, y1, vd, corrected=cr) @test size(C) == (k, 1) @test vec(C) ≈ Cxy[:,1] - @inferred cov(X, y1, vd, cr) + @inferred cov(X, y1, vd, corrected=cr) @test cov(X, Y) == Base.covm(X, mean(X, 1), Y, mean(Y, 1)) - C = zm ? Base.covm(X, 0, Y, 0, vd, cr) : - cov(X, Y, vd, cr) + C = zm ? Base.covm(X, 0, Y, 0, vd, corrected=cr) : + cov(X, Y, vd, corrected=cr) @test size(C) == (k, k) @test C ≈ Cxy - @inferred cov(X, Y, vd, cr) + @inferred cov(X, Y, vd, corrected=cr) end # test correlation From 49946f448f204b3d6275ab7307c38680906b8d18 Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Fri, 5 May 2017 10:51:44 +0200 Subject: [PATCH 2/2] Cleanup unneeded cor() methods and docstrings Remove methods which are no longer needed now that deprecations have been removed. Add types to signatures in docstrings. --- base/statistics.jl | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/base/statistics.jl b/base/statistics.jl index 17114c9424294..ee15c981920c8 100644 --- a/base/statistics.jl +++ b/base/statistics.jl @@ -479,41 +479,33 @@ corm(x::AbstractVecOrMat, xmean, y::AbstractVecOrMat, ymean, vardim::Int=1) = # cor """ - cor(x) + cor(x::AbstractVector) Return the number one. """ cor(x::AbstractVector) = one(real(eltype(x))) -# This ugly hack is necessary to make the method below considered more specific than the deprecated method. When the old keyword version has been completely deprecated, these two methods can be merged """ - cor(X[, vardim=1]) + cor(X::AbstractMatrix[, vardim::Int=1]) Compute the Pearson correlation matrix of the matrix `X` along the dimension `vardim`. """ -cor(X::AbstractMatrix, vardim::Int) = corm(X, _vmean(X, vardim), vardim) -# This ugly hack is necessary to make the method below considered more specific than the deprecated method. When the old keyword version has been completely deprecated, these two methods can be merged -cor(X::AbstractMatrix) = cor(X, 1) +cor(X::AbstractMatrix, vardim::Int=1) = corm(X, _vmean(X, vardim), vardim) """ - cor(x, y) + cor(x::AbstractVector, y::AbstractVector) Compute the Pearson correlation between the vectors `x` and `y`. """ cor(x::AbstractVector, y::AbstractVector) = corm(x, Base.mean(x), y, Base.mean(y)) -# This ugly hack is necessary to make the method below considered more specific than the deprecated method. When the old keyword version has been completely deprecated, these two methods can be merged """ - cor(X, Y[, vardim=1]) + cor(X::AbstractVecOrMat, Y::AbstractVecOrMat[, vardim=1]) Compute the Pearson correlation between the vectors or matrices `X` and `Y` along the dimension `vardim`. """ -cor(x::AbstractVecOrMat, y::AbstractVecOrMat, vardim::Int) = +cor(x::AbstractVecOrMat, y::AbstractVecOrMat, vardim::Int=1) = corm(x, _vmean(x, vardim), y, _vmean(y, vardim), vardim) -# This ugly hack is necessary to make the method below considered more specific than the deprecated method. When the old keyword version has been completely deprecated, these methods can be merged -cor(x::AbstractVector, Y::AbstractMatrix) = cor(x, Y, 1) -cor(X::AbstractMatrix, y::AbstractVector) = cor(X, y, 1) -cor(X::AbstractMatrix, Y::AbstractMatrix) = cor(X, Y, 1) ##### median & quantiles #####