Add various averaging routines to csdb

[delphidabbler]

Add Mean, Median and Mode averages in various overloads of Int and Float.

All should operate on dynamic arrays.

[delphidabbler]

Median: middle value after sorting - if even number of elements then take mean of middle two => Median of integer array has to return float since mean of two integers could be fractional.

Mode: Result can be nothing if the is no value that has a greater number of instances then anything else; single value or multiple values if there is more than one value with same number of instances. Therefore Mode must return an array. Note that Mode can apply to any type, not just numbers.

[delphidabbler]

UPDATE: This comment has been extracted into its own issue: #30

---

Note that Delphi's Math unit has a Mean function, but only for Float arrays:

function Mean(const Data: array of Single): Single;
function Mean(const Data: array of Double): Double;
function Mean(const Data: array of Extended): Extended;

So we could define Mean for integers that returns a Double. Two possible implementations:

function MeanInt(const A: array of Integer): Double;
begin
  Result := 0.0;
  for var I := Low(A) to High(A) do
    Result := Result + A[I] / Length(A);
end;

function MeanInt2(const A: array of Integer): Double;
begin
  var Sum: Int64 := 0;
  for var Elem in A do
    Inc(Sum, Elem);
  Result := Sum / Length(A);
end;

[delphidabbler]

UPDATE: This comment has been extracted into its own issue: #31

---

Also, there is geometric mean:

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 only works if all numbers are > 0.

Two formula (source Wikipedia):

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).

Note the case 1 will overflow easily, so case 2 seems best algorithm.

E.g.:

function GeoMean(const A: array of Double): Double;
begin
  Assert(Length(A) > 0);
  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;

[delphidabbler]

UPDATE: this comment has been extracted into its own issue: #32

---

And there's the logarithmic mean of two +ve numbers (not same as log-mean), which is defined as:

Where x = y:

Mlm(x, y) = x

Where x ≠ y:

Mlm(x, y) = (y - x) / (ln(y) - ln(x))

So:

function LogarithmicMean(const X, Y: Double): Double;
begin
  Assert((X > 0) and (Y > 0));
  if SameValue(X, Y) then
    Result := X
  else
    Result := (Y - X) / (Ln(Y) - Ln(X));
end;

[delphidabbler]

UPDATE: this comment has been extracted into its own issue: #33

---

Generalised Mean / Power Mean:

A power mean is a mean of the form

where all x are >= 0.

Source: Statistics How To & Wolfram MathWorld

function PowerMean(const A: array of Extended; Lambda: Extended): Extended;
begin
  Assert(not IsZero(Lambda));
  Assert(Length(A) > 0);
  var Sum: Extended := 0.0;
  for var X in A do
  begin
    Assert(Sign(X) <> NegativeValue);
    Sum := Sum + Power(X, Lambda);
  end;
  Result := Power(Sum / Length(A), 1 / Lambda);
end;

[delphidabbler]

UPDATE: this comment has been added to issue #33

---

Weighted Generalised Mean / Power Mean

When all weights w sum to 1 then denominator is 1 and can be ignored.

Soure: Statistics How To and Wikipedia

[delphidabbler]

UPDATE: This comment has been included in issue #31

---

Weighted geometric mean

Source: Wikipedia

[delphidabbler]

UPDATE: This comment has been included in issue: #30

---

Weighted arithmetic mean

Source: Wikipedia

[delphidabbler]

UPDATE: this comment has been extracted into its own issue: #40

---

Useful helper functions for checking arrays for zero & negative entries:

// Check if all elements of a non-empty array are zero 
function ArrayIsZero(const A: array of Extended): Boolean;
begin
  Assert(Length(A) > 0);
  Result := False;
  for var Elem in A do
    if not IsZero(Elem) then
      Exit;
  Result := True;
end;

// Check if all elements of a non-empty array are <> 0 
function ArrayIsNonZero(const A: array of Extended): Boolean;
begin
  Assert(Length(A) > 0);
  Result := False;
  for var Elem in A do
    if IsZero(Elem) then
      Exit;
  Result := True;
end;

// Check if all elements of a non-empty array are > 0 
function ArrayIsPositive(const A: array of Extended): Boolean;
begin
  Assert(Length(A) > 0);
  Result := False;
  for var Elem in A do
    if Sign(Elem) <> PositiveValue then
      Exit;
  Result := True;
end;

// Check if all elements of a non-empty array are < 0 
function ArrayIsNegative(const A: array of Extended): Boolean;
begin
  Assert(Length(A) > 0);
  Result := False;
  for var Elem in A do
    if Sign(Elem) <> NegativeValue then
      Exit;
  Result := True;
end;

// Check if all elements of a non-empty array are <= 0 
function ArrayIsNonPositive(const A: array of Extended): Boolean;
begin
  Assert(Length(A) > 0);
  Result := False;
  for var Elem in A do
    if Sign(Elem) = PositiveValue then
      Exit;
  Result := True;
end;

// Check if all elements of a non-empty array are >= 0 
function ArrayIsNonNegative(const A: array of Extended): Boolean;
begin
  Assert(Length(A) > 0);
  Result := False;
  for var Elem in A do
    if Sign(Elem) = NegativeValue then
      Exit;
  Result := True;
end;

[delphidabbler]

UPDATE: This comment has been extracted into its own issue: #34

---

A related (helper) function is LogSumExp or LSE for a sequence x1,...,xn is is defined as the logarithm of the sum of the exponentials of the arguments:

LSE(x1,...,xn) = log(exp(x1) + ... + exp(xn))

Source: Wikipedia

function LSE(const A: array of Extended): Extended;
begin
  var Sum: Extended := 0.0;
  for var X in A do
    Sum := Sum + Exp(X):
  Result := Ln(Sum);
end;