Report a bug
If you spot a problem with this page, click here to create a GitHub issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

mir.stat.descriptive.weighted

This module contains algorithms for descriptive statistics with weights.
License:
Authors:
John Michael Hall
enum AssumeWeights: bool;
Assumptions used for weighted moments
primary
Primary, does not assume weights sum to one
sumToOne
Assumes weights sum to one
struct WMeanAccumulator(T, Summation summation, AssumeWeights assumeWeights, U = T, Summation weightsSummation = summation);
Output range for wmean.
Examples:
Assume weights sum to 1
import mir.ndslice.slice: sliced;
import mir.stat.descriptive.univariate: Summation;

WMeanAccumulator!(double, Summation.pairwise, AssumeWeights.sumToOne) x;
x.put([0.0, 1, 2, 3, 4].sliced, [0.2, 0.2, 0.2, 0.2, 0.2].sliced);
assert(x.wmean == 2);
x.put(5, 0.0);
assert(x.wmean == 2);
Examples:
Do not assume weights sum to 1
import mir.math.common: approxEqual;
import mir.ndslice.slice: sliced;
import mir.stat.descriptive.univariate: Summation;

WMeanAccumulator!(double, Summation.pairwise, AssumeWeights.primary) x;
x.put([0.0, 1, 2, 3, 4].sliced, [1, 2, 3, 4, 5].sliced);
assert(x.wmean.approxEqual(40.0 / 15));
x.put(5, 6);
assert(x.wmean.approxEqual(70.0 / 21));
Examples:
Assume no weights, like MeanAccumulator
import mir.ndslice.slice: sliced;
import mir.stat.descriptive.univariate: Summation;

WMeanAccumulator!(double, Summation.pairwise, AssumeWeights.primary) x;
x.put([0.0, 1, 2, 3, 4].sliced);
assert(x.wmean == 2);
x.put(5);
assert(x.wmean == 2.5);
Summator!(T, summation) wsummator;
Summator!(U, weightsSummation) weights;
const pure nothrow @nogc @property @safe F wmean(F = T)();
const pure nothrow @nogc @property @safe F wsum(F = T)();
const pure nothrow @nogc @property @safe F weight(F = U)();
void put(Slice1, Slice2)(Slice1 s, Slice2 w)
if (isSlice!Slice1 && isSlice!Slice2);
void put(SliceLike1, SliceLike2)(SliceLike1 s, SliceLike2 w)
if (isConvertibleToSlice!SliceLike1 && !isSlice!SliceLike1 && isConvertibleToSlice!SliceLike2 && !isSlice!SliceLike2);
void put(Range)(Range r)
if (isIterable!Range && !assumeWeights);
void put(RangeA, RangeB)(RangeA r, RangeB w)
if (isInputRange!RangeA && !isConvertibleToSlice!RangeA && isInputRange!RangeB && !isConvertibleToSlice!RangeB);
void put()(T x, U w);
void put()(T x)
if (!assumeWeights);
void put(F = T, G = U)(WMeanAccumulator!(F, summation, assumeWeights, G, weightsSummation) wm)
if (!assumeWeights);
template wmean(F, Summation summation = Summation.appropriate, AssumeWeights assumeWeights = AssumeWeights.primary, G = F, Summation weightsSummation = Summation.appropriate) if (!is(F : AssumeWeights))

template wmean(Summation summation = Summation.appropriate, AssumeWeights assumeWeights = AssumeWeights.primary, Summation weightsSummation = Summation.appropriate)

template wmean(F, AssumeWeights assumeWeights, Summation summation = Summation.appropriate, G = F, Summation weightsSummation = Summation.appropriate) if (!is(F : AssumeWeights))

template wmean(F, bool assumeWeights, string summation = "appropriate", G = F, string weightsSummation = "appropriate") if (!is(F : AssumeWeights))

template wmean(bool assumeWeights, string summation = "appropriate", string weightsSummation = "appropriate")

template wmean(F, string summation, bool assumeWeights = false, G = F, string weightsSummation = "appropriate") if (!is(F : AssumeWeights))

template wmean(string summation, bool assumeWeights = false, string weightsSummation = "appropriate")

template wmean(F, string summation, G, string weightsSummation, bool assumeWeights) if (!is(F : AssumeWeights))

template wmean(string summation, string weightsSummation, bool assumeWeights = false)
Computes the weighted mean of the input.
By default, if F is not floating point type or complex type, then the result will have a double type if F is implicitly convertible to a floating point type or a type for which isComplex!F is true.
Parameters:
F controls type of output
summation algorithm for calculating sums (default: Summation.appropriate)
assumeWeights true if weights are assumed to add to 1 (default = AssumeWeights.primary)
G controls the type of weights
Returns:
The weighted mean of all the elements in the input, must be floating point or complex type
See Also:
Examples:
import mir.complex;
import mir.complex.math: capproxEqual = approxEqual;
import mir.math.common: approxEqual;
import mir.ndslice.slice: sliced;
alias C = Complex!double;

assert(wmean([1.0, 2, 3], [1, 2, 3]) == (1.0 + 4.0 + 9.0) / 6);
assert(wmean!true([1.0, 2, 3], [1.0 / 6, 2.0 / 6, 3.0 / 6]).approxEqual((1.0 + 4.0 + 9.0) / 6));
assert(wmean([C(1, 3), C(2), C(3)], [1, 2, 3]).capproxEqual(C((1.0 + 4.0 + 9.0) / 6, 3.0 / 6)));

assert(wmean!float([0, 1, 2, 3, 4, 5].sliced(3, 2), [1, 2, 3, 4, 5, 6].sliced(3, 2)).approxEqual(70.0 / 21));

static assert(is(typeof(wmean!float([1, 2, 3], [1, 2, 3])) == float));
Examples:
If weights are not provided, then behaves like mean
import mir.ndslice.slice: sliced;
import mir.complex;
alias C = Complex!double;

assert(wmean([1.0, 2, 3]) == 2);
assert(wmean([C(1, 3), C(2), C(3)]) == C(2, 1));

assert(wmean!float([0, 1, 2, 3, 4, 5].sliced(3, 2)) == 2.5);

static assert(is(typeof(wmean!float([1, 2, 3])) == float));
Examples:
Weighted mean of vector
import mir.ndslice.slice: sliced;
import mir.ndslice.topology: iota, map;

auto x = [0.0, 1.0, 1.5, 2.0, 3.5, 4.25,
          2.0, 7.5, 5.0, 1.0, 1.5, 0.0].sliced;
auto w = iota([12], 1);
auto w_SumToOne = w.map!(a => a / 78.0);

assert(x.wmean == 29.25 / 12);
assert(x.wmean(w) == 203.0 / 78);
assert(x.wmean!true(w_SumToOne) == 203.0 / 78);
Examples:
Weighted mean of matrix
import mir.ndslice.fuse: fuse;
import mir.ndslice.topology: iota, map;

auto x = [
    [0.0, 1.0, 1.5, 2.0, 3.5, 4.25],
    [2.0, 7.5, 5.0, 1.0, 1.5, 0.0]
].fuse;
auto w = iota([2, 6], 1);
auto w_SumToOne = w.map!(a => a / 78.0);

assert(x.wmean == 29.25 / 12);
assert(x.wmean(w) == 203.0 / 78);
assert(x.wmean!true(w_SumToOne) == 203.0 / 78);
Examples:
Column mean of matrix
import mir.algorithm.iteration: all;
import mir.math.common: approxEqual;
import mir.ndslice.fuse: fuse;
import mir.ndslice.topology: alongDim, byDim, iota, map, universal;

auto x = [
    [0.0, 1.0, 1.5, 2.0, 3.5, 4.25],
    [2.0, 7.5, 5.0, 1.0, 1.5, 0.0]
].fuse;
auto w = iota([2], 1).universal;
auto result = [4.0 / 3, 16.0 / 3, 11.5 / 3, 4.0 / 3, 6.5 / 3, 4.25 / 3];

// Use byDim or alongDim with map to compute mean of row/column.
assert(x.byDim!1.map!(a => a.wmean(w)).all!approxEqual(result));
assert(x.alongDim!0.map!(a => a.wmean(w)).all!approxEqual(result));

// FIXME
// Without using map, computes the mean of the whole slice
// assert(x.byDim!1.wmean(w) == x.sliced.wmean);
// assert(x.alongDim!0.wmean(w) == x.sliced.wmean);
Examples:
Can also set algorithm or output type
import mir.ndslice.slice: sliced;
import mir.ndslice.topology: repeat, universal;

//Set sum algorithm (also for weights) or output type

auto a = [1, 1e100, 1, -1e100].sliced;

auto x = a * 10_000;
auto w1 = [1, 1, 1, 1].sliced;
auto w2 = [0.25, 0.25, 0.25, 0.25].sliced;

assert(x.wmean!"kbn"(w1) == 20_000 / 4);
assert(x.universal.wmean!(true, "kbn")(w2.universal) == 20_000 / 4);
assert(x.universal.wmean!("kbn", true)(w2.universal) == 20_000 / 4);
assert(x.universal.wmean!("kbn", true, "pairwise")(w2.universal) == 20_000 / 4);
assert(x.universal.wmean!(true, "kbn", "pairwise")(w2.universal) == 20_000 / 4);
assert(x.wmean!"kb2"(w1) == 20_000 / 4);
assert(x.wmean!"precise"(w1) == 20_000 / 4);
assert(x.wmean!(double, "precise")(w1) == 20_000.0 / 4);

auto y = uint.max.repeat(3);
assert(y.wmean!ulong([1, 1, 1].sliced.universal) == 12884901885 / 3);
Examples:
For integral slices, can pass output type as template parameter to ensure output type is correct.
import mir.math.common: approxEqual;
import mir.ndslice.slice: sliced;

auto x = [0, 1, 1, 2, 4, 4,
          2, 7, 5, 1, 2, 0].sliced;
auto w = [1, 2, 3,  4,  5,  6,
          7, 8, 9, 10, 11, 12].sliced;

auto y = x.wmean(w);
assert(y.approxEqual(204.0 / 78, 1.0e-10));
static assert(is(typeof(y) == double));

assert(x.wmean!float(w).approxEqual(204f / 78, 1.0e-10));
Examples:
Mean works for complex numbers and other user-defined types (provided they can be converted to a floating point or complex type)
import mir.complex.math: approxEqual;
import mir.ndslice.slice: sliced;
import mir.complex;
alias C = Complex!double;

auto x = [C(1.0, 2), C(2, 3), C(3, 4), C(4, 5)].sliced;
auto w = [1, 2, 3, 4].sliced;
assert(x.wmean(w).approxEqual(C(3, 4)));
Examples:
Compute weighted mean tensors along specified dimention of tensors
import mir.ndslice.fuse: fuse;
import mir.ndslice.slice: sliced;
import mir.ndslice.topology: alongDim, as, iota, map, universal;
/++
  [[0,1,2],
   [3,4,5]]
 +/
auto x = [
    [0, 1, 2],
    [3, 4, 5]
].fuse.as!double;
auto w = [
    [1, 2, 3],
    [4, 5, 6]
].fuse;
auto w1 = [1, 2].sliced.universal;
auto w2 = [1, 2, 3].sliced;

assert(x.wmean(w) == (70.0 / 21));

auto m0 = [(0.0 + 6.0) / 3, (1.0 + 8.0) / 3, (2.0 + 10.0) / 3];
assert(x.alongDim!0.map!(a => a.wmean(w1)) == m0);
assert(x.alongDim!(-2).map!(a => a.wmean(w1)) == m0);

auto m1 = [(0.0 + 2.0 + 6.0) / 6, (3.0 + 8.0 + 15.0) / 6];
assert(x.alongDim!1.map!(a => a.wmean(w2)) == m1);
assert(x.alongDim!(-1).map!(a => a.wmean(w2)) == m1);

assert(iota(2, 3, 4, 5).as!double.alongDim!0.map!wmean == iota([3, 4, 5], 3 * 4 * 5 / 2));
meanType!F wmean(SliceA, SliceB)(SliceA s, SliceB w)
if (isConvertibleToSlice!SliceA && isConvertibleToSlice!SliceB);
Parameters:
SliceA s slice-like
SliceB w weights
meanType!F wmean(Range)(Range r)
if (isIterable!Range);
Parameters:
Range r range, must be finite iterable