Add geometric mean function

[delphidabbler]

The geometric mean, sometimes also called geometric average, is an average calculated by multiplying a set of positive values and taking the nth root, where n is the number of values.

The geometric mean is used to minimize the effects of extreme values; for instance, when averaging growth rates.

--- Source: Eurostat

Geometric mean requires that all numbers are > 0.

There are two formula:

1. For N +ve numbers a1, a2, ... aN, GeoMean = Nth root of (a1 × a2 × ... aN).
2. For N +ve numbers a1, a2, ... aN, GeoMean = exp(sum(ln(a1)), ln(a2), ... ĺn(aN)) / N).

--- Source: Wikipedia

Note that formula 1 could overflow easily, so formula 2 seems the best algorithm.

E.g.:

function GeoMean(const A: array of Double): Double;
begin
  Assert(Length(A) > 0);  // replace with exception
  var SumOfLogs: Double := 0.0;
  for var D in A do
  begin
    if Sign(D) <> PositiveValue then
      raise EArgumentOutOfRangeException.Create('Non positive value passed to GeoMean');
    SumOfLogs := SumOfLogs + Ln(A);
  end;
  Result := Exp(SumOfLogs / Length(A));
end;

This function was extracted from issue #16

[delphidabbler]

Also, there is the weighted geometric mean:

Source: Wikipedia

[delphidabbler]

UPDATE: This comment has been extracted into it own issue: #44

---

There is a discussion on the Wikipedia page about the weighted arithmetic mean that discusses that fact that weights can be "normalised" to fall in the range [0..1].

There are three possible approaches:

1. To always normalise the weights before performing the calculation.
2. To provide two functions, one of which does no normalisation & the other that performs normalisation but uses a simpler algorithm.
3. To never alter the weights provided by the user, so that the user can normalise them if necessary before calling the function.

The are problems with all these approaches:

1. There may be circumstances where rounding errors cause problems if weights are always normalised.
2. Two functions increase complexity and maintenance issues.
3. Passing in normalised weights means that the simpler algorithm can't be used.

Regardless of any those issues, some method that can transform an array of values into a normalised array will be of some use, so the following routine is proposed:

function NormaliseWeights(const Weights: array of Double):
  Types.TDoubleDynArray;
var
  Weight: Double;
  WeightSum: Double;
  Idx: Integer;
begin
  if (System.Length(Weights) = 0) then
    raise SysUtils.EArgumentException.Create('Array of weights is empty');
  WeightSum := 0.0;
  for Weight in Weights do
  begin
    if Math.Sign(Weight) = Math.NegativeValue then
      raise SysUtils.EArgumentException.Create('Weights must all be >= 0');
    WeightSum := WeightSum + Weight;
  end;
  if Math.IsZero(WeightSum) then
    raise SysUtils.EArgumentException.Create('Sum of weights can''t be zero');
  System.SetLength(Result, System.Length(Weights));
  for Idx := 0 to Pred(System.Length(Weights)) do
    Result[Idx] := Weights[Idx] / WeightSum;
end;

[delphidabbler]

Added Integer, Cardinal and Double overloads of GeoMean and WeightedGeoMean functions by merge commit 5c7623f

[delphidabbler]

⚠️ The geometric mean functions were originally named GeoMean and WeightedGeoMean. These were changed to GeometricMean and WeightedGeometricMean as at commit b50ec8a.