Make cov's corrected argument a keyword argument and cleanup docstr…

…ings for `cov` and `cor` (#21709)

* 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.

* 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.

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
 ==========================

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

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 #####
 
@@ -490,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 #####
 

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