Added documentation about corrected argument in cov and mean_and_cov docstring. Also, added deprecation for cov corrected=false behaviour.

Author: rofinn

src/cov.jl

@@ -22,13 +22,6 @@ function _scalevars(x::DenseMatrix, s::DenseVector, vardim::Int)
 end
 
 ## scatter matrix
-
-scattermat_zm(x::DenseMatrix, vardim::Int) = Base.unscaled_covzm(x, vardim)
-
-scattermat_zm(x::DenseMatrix, wv::AbstractWeights, vardim::Int) =
-    _symmetrize!(Base.unscaled_covzm(x, _scalevars(x, values(wv), vardim), vardim))
-
-
 """
     scattermat(X, [wv::AbstractWeights]; mean=nothing, vardim=1)
 
@@ -44,28 +37,6 @@ that the data are centered and hence there's no need to subtract the mean.
 When `vardim = 1`, the variables are considered columns with observations in rows;
 when `vardim = 2`, variables are in rows with observations in columns.
 """
-function scattermat end
-
-
-"""
-    cov(X, wv::AbstractWeights; mean=nothing, vardim=1)
-
-Compute the weighted covariance matrix. By default, the covariance
-matrix is normalized by the sum of the weights. That is, `cov(X, wv)`
-is equivalent to `scattermat(X, wv) / sum(wv)`.
-"""
-cov
-
-
-"""
-    mean_and_cov(x, [wv::AbstractWeights]; vardim=1) -> (mean, cov)
-
-Return the mean and covariance matrix as a tuple. A weighting
-vector `wv` can be specified. `vardim` that designates whether
-the variables are columns in the matrix (`1`) or rows (`2`).
-"""
-function mean_and_cov end
-
 scattermatm(x::DenseMatrix, mean, vardim::Int=1) =
     scattermat_zm(x .- mean, vardim)
 
@@ -78,19 +49,61 @@ scattermat(x::DenseMatrix, vardim::Int=1) =
 scattermat(x::DenseMatrix, wv::AbstractWeights, vardim::Int=1) =
     scattermatm(x, Base.mean(x, wv, vardim), wv, vardim)
 
-## weighted cov
-Base.covm(x::DenseMatrix, mean, wv::AbstractWeights, vardim::Int=1, corrected::Bool=false) =
-    scale!(scattermatm(x, mean, wv, vardim), varcorrection(wv, corrected))
+scattermat_zm(x::DenseMatrix, vardim::Int) = Base.unscaled_covzm(x, vardim)
+
+scattermat_zm(x::DenseMatrix, wv::AbstractWeights, vardim::Int) =
+    _symmetrize!(Base.unscaled_covzm(x, _scalevars(x, values(wv), vardim), vardim))
+
+"""
+    cov(X, wv::AbstractWeights, [vardim, corrected])
 
-Base.cov(x::DenseMatrix, wv::AbstractWeights, vardim::Int=1; corrected=false) =
+Compute the weighted covariance matrix. Similar to `var` and `std` the biased covariance
+matrix (`corrected=false`) can be computed by multiplying `scattermat(X, wv)` by
+``\frac{1}{\sum{w}}`` to normalize. However, the unbiased covariance matrix
+(`corrected=true`) is dependent on the type of weights used:
+
+* AnalyticWeights: ``\\frac{1}{\sum w - \sum {w^2} / \sum{w}^2}``
+* FrequencyWeights: ``\\frac{1}{\sum{w} - 1}``
+* ProbabilityWeights: ``\\frac{n}{(n - 1) \sum w}`` where `n = length(w)`
+"""
+Base.cov(x::DenseMatrix, wv::AbstractWeights, corrected::Bool) =
+    Base.covm(x, Base.mean(x, wv, 1), wv, 1, corrected)
+
+Base.cov(x::DenseMatrix, wv::AbstractWeights, vardim::Int, corrected::Bool) =
     Base.covm(x, Base.mean(x, wv, vardim), wv, vardim, corrected)
 
-function mean_and_cov(x::DenseMatrix, vardim::Int=1; corrected=false)
+Base.covm(x::DenseMatrix, mean, wv::AbstractWeights, corrected::Bool) =
+    scale!(scattermatm(x, mean, wv, 1), varcorrection(wv, corrected))
+
+Base.covm(x::DenseMatrix, mean, wv::AbstractWeights, vardim::Int, corrected::Bool) =
+    scale!(scattermatm(x, mean, wv, vardim), varcorrection(wv, corrected))
+
+"""
+    mean_and_cov(x, [wv::AbstractWeights, vardim, corrected]) -> (mean, cov)
+
+Return the mean and covariance matrix as a tuple. A weighting
+vector `wv` can be specified. `vardim` that designates whether
+the variables are columns in the matrix (`1`) or rows (`2`).
+Finally, bias correction can be applied to the covariance calculation if
+`corrected=true`.
+See `cov` documentation for more details.
+"""
+function mean_and_cov(x::DenseMatrix, corrected::Bool=true)
+    m = mean(x, 1)
+    return m, Base.covm(x, m, 1, corrected)
+end
+
+function mean_and_cov(x::DenseMatrix, vardim::Int, corrected::Bool=true)
     m = mean(x, vardim)
     return m, Base.covm(x, m, vardim, corrected)
 end
 
-function mean_and_cov(x::DenseMatrix, wv::AbstractWeights, vardim::Int=1; corrected=false)
+function mean_and_cov(x::DenseMatrix, wv::AbstractWeights, corrected::Bool)
+    m = mean(x, wv, 1)
+    return m, Base.cov(x, wv, 1, corrected)
+end
+
+function mean_and_cov(x::DenseMatrix, wv::AbstractWeights, vardim::Int, corrected::Bool)
     m = mean(x, wv, vardim)
-    return m, Base.cov(x, wv, vardim; corrected=corrected)
+    return m, Base.cov(x, wv, vardim, corrected)
 end

src/deprecates.jl

@@ -156,3 +156,33 @@ function mean_and_std(A::RealArray, wv::AbstractWeights, dim::Int)
     s = stdm(A, wv, m, dim, true)
     m, s
 end
+
+function Base.cov(x::DenseMatrix, wv::AbstractWeights)
+    Base.depwarn(_correction_dep_msg("`cov`"), :cov)
+    Base.covm(x, Base.mean(x, wv, 1), wv, 1, false)
+end
+
+function Base.cov(x::DenseMatrix, wv::AbstractWeights, vardim::Int)
+    Base.depwarn(_correction_dep_msg("`cov`"), :cov)
+    Base.covm(x, Base.mean(x, wv, vardim), wv, vardim, false)
+end
+
+function Base.covm(x::DenseMatrix, mean, wv::AbstractWeights)
+    Base.depwarn(_correction_dep_msg("`covm`"), :covm)
+    scale!(scattermatm(x, mean, wv, 1), varcorrection(wv, false))
+end
+
+function Base.covm(x::DenseMatrix, mean, wv::AbstractWeights, vardim::Int)
+    Base.depwarn(_correction_dep_msg("`covm`"), :covm)
+    scale!(scattermatm(x, mean, wv, vardim), varcorrection(wv, false))
+end
+
+function mean_and_cov(x::DenseMatrix, wv::AbstractWeights)
+    m = mean(x, wv, 1)
+    return m, Base.cov(x, wv, 1)
+end
+
+function mean_and_cov(x::DenseMatrix, wv::AbstractWeights, vardim::Int)
+    m = mean(x, wv, vardim)
+    return m, Base.cov(x, wv, vardim)
+end

test/cov.jl

@@ -60,8 +60,8 @@ Sz2w = X * diagm(w2) * X'
 
 # weighted covariance
 
-@test cov(X, wv1; corrected=false)    ≈ S1w ./ sum(wv1)
-@test cov(X, wv2, 2; corrected=false) ≈ S2w ./ sum(wv2)
+@test cov(X, wv1, false)    ≈ S1w ./ sum(wv1)
+@test cov(X, wv2, 2, false) ≈ S2w ./ sum(wv2)
 
 @test Base.covm(X, 0, wv1, 1, false) ≈ Sz1w ./ sum(wv1)
 @test Base.covm(X, 0, wv2, 2, false) ≈ Sz2w ./ sum(wv2)
@@ -74,18 +74,18 @@ Sz2w = X * diagm(w2) * X'
 
 # mean_and_cov
 
-(m, C) = mean_and_cov(X, 1; corrected=false)
+(m, C) = mean_and_cov(X, 1, false)
 @test m == mean(X, 1)
 @test C == cov(X, 1, false)
 
-(m, C) = mean_and_cov(X, 2; corrected=false)
+(m, C) = mean_and_cov(X, 2, false)
 @test m == mean(X, 2)
 @test C == cov(X, 2, false)
 
-(m, C) = mean_and_cov(X, wv1, 1; corrected=false)
+(m, C) = mean_and_cov(X, wv1, 1, false)
 @test m == mean(X, wv1, 1)
-@test C == cov(X, wv1, 1; corrected=false)
+@test C == cov(X, wv1, 1, false)
 
-(m, C) = mean_and_cov(X, wv2, 2; corrected=false)
+(m, C) = mean_and_cov(X, wv2, 2, false)
 @test m == mean(X, wv2, 2)
-@test C == cov(X, wv2, 2; corrected=false)
+@test C == cov(X, wv2, 2, false)