Make cov's corrected argument a keyword argument and cleanup docstrings for cov and cor

[nalimilan]

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.

This only changes the public API for cov. The changes to cor are cosmetic.

[tkelman]

worth an 0.7 news entry?

[nalimilan]

Sure. I've added a 0.7. section.

[ararslan]

LGTM

[andreasnoack]

Why not the other way around? Have you measured the overhead?

[ararslan]

What do you mean by the other way around?

[andreasnoack]

What do you mean by the other way around?

Make var and std use positional arguments instead of keyword arguments

[nalimilan]

I thought the trend was rather to move to keyword arguments where appropriate (since we won't be able to change this after 1.0), and improve their performance if needed. Maybe @StefanKarpinski can confirm?

Clearly, the overhead will depend a lot on the size of the input vector/matrix. For a relatively small vector with 1000 entries, it's about 14%:

covzm2(x::AbstractVector; corrected::Bool=true) = Base.unscaled_covzm(x) / (Base._length(x) - Int(corrected))
covm2(x::AbstractVector, xmean; corrected::Bool=true) = covzm2(x .- xmean; corrected=corrected)
cov2(x::AbstractVector; corrected::Bool=true) = covm2(x, Base.mean(x); corrected=corrected) 
using BenchmarkTools
@benchmark cov(X)
@benchmark cov2(X)

BTW, if we care about performance, we should get rid of x .- xmean, as taking a copy sounds like a very inefficient approach to me.

[nalimilan]

@StefanKarpinski What's your position WRT keyword arguments?

[StefanKarpinski]

I think that unnamed boolean arguments are not nearly as self-documenting as keywords. If you see cov(v, false) you have no idea what that false is about. If you see cov(v, corrected=false) you immediately know what's going on without look at the docs. This is worse for boolean flags because the value itself carries so little semantic information. When a positional argument is a vector or matrix or something, you get some sense of what it means based on how it's used and what the variable is named. What does false mean? Could be literally mean anything – all you know is that it's the opposite of whatever true means. The only case where you have a hint what it means from the calling context is if someone writes corrected=false; cov(v, corrected). I.e. almost never.

[StefanKarpinski]

@JeffBezanson can verify, but I think we have semiconcrete plans to make keywords more efficient in 1.0 and should therefore not be overly worried about the efficiency gap between positional and keyword argument forms and choose based on better APIs, not performance.

[nalimilan]

OK, thanks. Should be good to go then.

[nalimilan]

Barring objections I'll merge this tomorrow.

[andreasnoack]

Is this one inferred?

[nalimilan]

All of these work:

@inferred cov([1, 2], [1, 2])
@inferred cov([1 2], [1 2], 1)
@inferred cov([1, 2], [1; 2])
@inferred cov([1; 2], [1, 2])

Did I miss other cases to test?

[andreasnoack]

I don't think so

[nalimilan]

Good to go then?

[mschauer]

@deprecate cov(x::AbstractMatrix, vardim::Int, corrected::Bool) cov(x, corrected=corrected)
ignores the vardim argument

[nalimilan]

@mschauer Thanks. That's the problem with untested code. :-) See #22595.