Add generalized mean function (JuliaLang#209)

docs/source/means.rst

@@ -11,6 +11,12 @@ The package provides functions to compute means of different kinds.
 
   Compute the harmonic mean of ``x``.
 
+.. function:: genmean(x, p)
+
+  Compute the generalized/power mean of ``x`` with exponent ``p``,
+  i.e. :math:`\left( \frac{1}{n} \sum_{i=1}^n x_i^p \right)^{\frac{1}{p}}`, where ``n = length(x)``.
+  It is taken to be the geometric mean when ``p == 0``.
+
 .. function:: trimmean(x, p)
 
   Compute the trimmed mean of ``x``, with fraction ``p`` of elements ignored.
@@ -19,14 +25,14 @@ The package provides functions to compute means of different kinds.
 
   .. code-block:: julia
 
-    # computes the mean using 80% of the numbers in ``x``, 
+    # computes the mean using 80% of the numbers in ``x``,
     # ignoring 10% of the largest and 10% of the smallest values.
 
     trimmean(x, 0.2)
 
 .. function:: mean(x, w)
 
-  The ``mean`` function is also extended to accept a weight vector of type ``WeightVec`` (see :ref:`weightvec`) to compute weighted mean. 
+  The ``mean`` function is also extended to accept a weight vector of type ``WeightVec`` (see :ref:`weightvec`) to compute weighted mean.
 
   **Examples:**
 
@@ -41,4 +47,4 @@ The package provides functions to compute means of different kinds.
 
 .. function:: mean!(dst, x, w, dim)
 
-  Compute weighted means along a certain dimension, and write results to a pre-allocated destination vector ``dst``. 
+  Compute weighted means along a certain dimension, and write results to a pre-allocated destination vector ``dst``.

src/StatsBase.jl

@@ -34,6 +34,7 @@ module StatsBase
     ## scalarstats
     geomean,     # geometric mean
     harmmean,    # harmonic mean
+    genmean,     # generalized/power mean
     trimmean,    # trimmed mean
     middle,      # the mean of two real numbers
     mode,        # find a mode from data (the first one)

src/scalarstats.jl

@@ -37,6 +37,28 @@ function harmmean(a::RealArray)
     return n / s
 end
 
+# Generalized mean
+"""
+    genmean(a, p)
+
+Return the generalized/power mean with exponent `p` of a real-valued array,
+i.e. ``\left( \frac{1}{n} \sum_{i=1}^n a_i^p \right)^{\frac{1}{p}}``, where `n = length(a)`.
+It is taken to be the geometric mean when `p == 0`.
+"""
+function genmean(a::RealArray, p::Real)
+    if p == 0
+        return geomean(a)
+    end
+    s = 0.0
+    n = length(a)
+    for x in a
+        #= At least one of `x` or `p` must not be an int to avoid domain errors when `p` is a negative int.
+        We choose `x` in order to exploit exponentiation by squaring when `p` is an int. =#
+        @inbounds s += convert(Float64, x)^p
+    end
+    return (s/n)^(1/p)
+end
+
 # Trimmed mean
 """
     trimmean(x, p)

test/scalarstats.jl

@@ -17,6 +17,18 @@ using Base.Test
 @test_approx_eq harmmean(1:3) 3 / (1 + 1/2 + 1/3)
 @test_approx_eq harmmean([1, 2, 4]) 12 / 7
 
+## genmean
+@test_approx_eq genmean([1,1,2,3], 1) 7/4
+@test_approx_eq genmean([1,4,2], -1) 12/7
+@test_approx_eq genmean([1,1,2,3], 0) (6.0)^(1/4)
+@test_approx_eq genmean([1.2,-0.5,0], 2) sqrt(169/300)
+@test_approx_eq genmean([16/9,0.25,1.0], 1.5) (755/648)^(2/3)
+# Test numerical stability for `p` close to 0 (genmean should be close to geometric mean).
+@test_approx_eq_eps genmean([1,1,2,3], -1e-8) (6.0)^(1/4) 1e-8
+# Test numerical stability for large `p` (genmean should be close to max).
+@test_approx_eq_eps genmean([0.98,1.02], 1e4) 1.02 1e-4
+
+
 ## trimmean
 
 @test_approx_eq trimmean([-100, 2, 3, 7, 200], 0.0) 22.4