Docs

JuliaLang · May 8, 2019 · 4618723 · 4618723
1 parent d7ae38b
commit 4618723
Show file tree

Hide file tree

Showing 4 changed files with 57 additions and 31 deletions.
diff --git a/base/reducedim.jl b/base/reducedim.jl
@@ -353,9 +353,19 @@ reduce(op, A::AbstractArray; kw...) = mapreduce(identity, op, A; kw...)
 
 ##### Specific reduction functions #####
 """
-    sum(A::AbstractArray; dims)
+    sum(A::AbstractArray; [dims], [weights::AbstractArray])
 
-Sum elements of an array over the given dimensions.
+Compute the sum of array `A`.
+If `dims` is provided, return an array of sums over these dimensions.
+If `weights` is provided, return the weighted sum(s). `weights` must be
+either an array of the same size as `A` if `dims` is omitted,
+or a vector with the same length as `size(A, dims)` if `dims` is provided.
+
+!!! compat "Julia 1.1"
+    `mean` for empty arrays requires at least Julia 1.1.
+
+!!! compat "Julia 1.3"
+    The `weights` keyword argument requires at least Julia 1.3.
 
 # Examples
 ```jldoctest
@@ -372,14 +382,26 @@ julia> sum(A, dims=2)
 2×1 Array{Int64,2}:
  3
  7
+
+julia> sum(A, weights=[2 1; 2 1])
+14
+
+julia> sum(A, weights=[2, 1], dims=1)
+1×2 Array{Int64,2}:
+ 5  8
 ```
 """
 sum(A::AbstractArray; dims)
 
 """
-    sum!(r, A)
+    sum!(r, A; [weights::AbstractVector])
 
 Sum elements of `A` over the singleton dimensions of `r`, and write results to `r`.
+If `r` has only one singleton dimension `i`, `weights` can be a vector of length
+`size(v, i)` to compute the weighted mean.
+
+!!! compat "Julia 1.3"
+    The `weights` keyword argument requires at least Julia 1.3.
 
 # Examples
 ```jldoctest

diff --git a/stdlib/Statistics/src/Statistics.jl b/stdlib/Statistics/src/Statistics.jl
@@ -107,10 +107,14 @@ _mean(f, A::AbstractArray, ::Colon) = sum(f, A) / length(A)
 _mean(f, A::AbstractArray, dims) = sum(f, A, dims=dims) / mapreduce(i -> size(A, i), *, unique(dims); init=1)
 
 """
-    mean!(r, v; weights::AbstractArray)
+    mean!(r, v; [weights::AbstractVector])
 
 Compute the mean of `v` over the singleton dimensions of `r`, and write results to `r`.
-Weights can be provided via an array of the same size as `A`.
+If `r` has only one singleton dimension `i`, `weights` can be a vector of length
+`size(v, i)` to compute the weighted mean.
+
+!!! compat "Julia 1.3"
+    The `weights`  argument requires at least Julia 1.3.
 
 # Examples
 ```jldoctest
@@ -155,8 +159,8 @@ or a vector with the same length as `size(A, dims)` if `dims` is provided.
 !!! compat "Julia 1.1"
     `mean` for empty arrays requires at least Julia 1.1.
 
-!!! compat "Julia 1.2"
-    The `weights` keyword argument requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    The `weights` keyword argument requires at least Julia 1.3.
 
 # Examples
 ```jldoctest
@@ -575,8 +579,8 @@ weights used:
     Use the [`skipmissing`](@ref) function to omit `missing` entries and compute the
     standard deviation of non-missing values.
 
-!!! compat "Julia 1.2"
-    The `weights` keyword argument requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    The `weights` keyword argument requires at least Julia 1.3.
 """
 std(A::AbstractArray;
     corrected::Bool=true, mean=nothing, dims=:,
@@ -987,8 +991,8 @@ at the same time.
 
 See the documentation for [`quantile`](@ref) for more details.
 
-!!! compat "Julia 1.2"
-    The `weights` keyword argument requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    The `weights` keyword argument requires at least Julia 1.3c.
 
 # Examples
 ```jldoctest

diff --git a/stdlib/Statistics/src/moments.jl b/stdlib/Statistics/src/moments.jl
@@ -51,8 +51,8 @@ specifying a pre-computed `mean`.
 If `x` is an `AbstractArray`, a `weights` array of the same length as `x`
 can be specified to compute the weighted skewness.
 
-!!! compat "Julia 1.2"
-    This function requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    This function requires at least Julia 1.3.
 """
 skewness(A; mean::Union{Real, Nothing}=nothing) = _skewness(A, nothing, mean)
 
@@ -125,8 +125,8 @@ specifying a pre-computed `mean`.
 If `x` is an `AbstractArray`, a `weights` array of the same length as `x`
 can be specified to compute the weighted kurtosis.
 
-!!! compat "Julia 1.2"
-    This function requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    This function requires at least Julia 1.3.
 """
 kurtosis(A; mean::Union{Real, Nothing}=nothing) = _kurtosis(A, nothing, mean)
 

diff --git a/stdlib/Statistics/src/weights.jl b/stdlib/Statistics/src/weights.jl
@@ -13,8 +13,8 @@ Concrete `AbstractWeights` type indicates what correction
 has to be applied when computing statistics which depend on the
 meaning of weights.
 
-!!! compat "Julia 1.2"
-    This type requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    This type requires at least Julia 1.3.
 """
 abstract type AbstractWeights{S<:Real, T<:Real, V<:AbstractVector{T}} <: AbstractVector{T} end
 
@@ -62,8 +62,8 @@ The `Weights` type describes a generic weights vector which does not support
 all operations possible for [`FrequencyWeights`](@ref), [`AnalyticWeights`](@ref)
 and [`ProbabilityWeights`](@ref).
 
-!!! compat "Julia 1.2"
-    This type requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    This type requires at least Julia 1.3.
 """ Weights
 
 """
@@ -88,8 +88,8 @@ for each observation. These weights may also be referred to as reliability weigh
 precision weights or inverse variance weights. These are typically used when the observations
 being weighted are aggregate values (e.g., averages) with differing variances.
 
-!!! compat "Julia 1.2"
-    This type requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    This type requires at least Julia 1.3.
 """ AnalyticWeights
 
 """
@@ -98,8 +98,8 @@ being weighted are aggregate values (e.g., averages) with differing variances.
 Construct an `AnalyticWeights` vector from array `vs`.
 See the documentation for [`AnalyticWeights`](@ref) for more details.
 
-!!! compat "Julia 1.2"
-    This function requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    This function requires at least Julia 1.3.
 """
 aweights(vs::AbstractVector{<:Real}) = AnalyticWeights(vs)
 aweights(vs::AbstractArray{<:Real}) = AnalyticWeights(vec(vs))
@@ -115,8 +115,8 @@ A precomputed sum may be provided as `wsum`.
 Frequency weights describe the number of times (or frequency) each observation
 was observed. These weights may also be referred to as case weights or repeat weights.
 
-!!! compat "Julia 1.2"
-    This type requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    This type requires at least Julia 1.3.
 """ FrequencyWeights
 
 """
@@ -125,8 +125,8 @@ was observed. These weights may also be referred to as case weights or repeat we
 Construct a `FrequencyWeights` vector from a given array.
 See the documentation for [`FrequencyWeights`](@ref) for more details.
 
-!!! compat "Julia 1.2"
-    This function requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    This function requires at least Julia 1.3.
 """
 fweights(vs::AbstractVector{<:Real}) = FrequencyWeights(vs)
 fweights(vs::AbstractArray{<:Real}) = FrequencyWeights(vec(vs))
@@ -143,8 +143,8 @@ Probability weights represent the inverse of the sampling probability for each o
 providing a correction mechanism for under- or over-sampling certain population groups.
 These weights may also be referred to as sampling weights.
 
-!!! compat "Julia 1.2"
-    This type requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    This type requires at least Julia 1.3.
 """ ProbabilityWeights
 
 """
@@ -153,8 +153,8 @@ These weights may also be referred to as sampling weights.
 Construct a `ProbabilityWeights` vector from a given array.
 See the documentation for [`ProbabilityWeights`](@ref) for more details.
 
-!!! compat "Julia 1.2"
-    This function requires at least Julia 1.2.
+!!! compat "Julia 1.3"
+    This function requires at least Julia 1.3.
 """
 pweights(vs::AbstractVector{<:Real}) = ProbabilityWeights(vs)
 pweights(vs::AbstractArray{<:Real}) = ProbabilityWeights(vec(vs))