Aggregators

Aggregation is the process of reducing a series of values to a single value that represents some property of the series. An aggregate function or aggregator is a function that performs this operation. This section describes predefined aggregators and a simple mechanism to create your own. Examples of aggregators are: count, largest value, mean...

A property like the number of elements or the number of elements that are not missing in a series is meaningful for all series regardless of their element type. The result is always an integer. A property like the first element is also universally relevant, but the type of the result depends on the element type. More than that, the type of the result is equal to the element type. These two examples illustrate the two main kinds of aggregators: those where the result is of a specific type, and those where the result type is the same as the element type.

The most common aggregators are defined as static properties or methods of the Aggregators class, and are listed below.

The above properties and methods return an aggregator group. An aggregator group represents an aggregation operation in a way that is independent of the element type of the series to which it is applied. When the aggregator group is applied to a series, an aggregator function for the element type of the series is selected to perform the actual operation.

AggregatorGroup is an abstract class that represents an aggregator group. It has two descendant classes corresponding to the two kinds of aggregators mentioned above: AggregatorGroup<TResult> represents an aggregator group where the generic type argument is the return type, and TypePreservingAggregatorGroup represents an aggregator group where the return type is the same as the element type.

Mean, Variance, and Sum preserve the input element type where that aggregation is supported. Element-type arithmetic matters: an integer result cannot represent a fractional statistic.

Use MeanAsDouble, VarianceAsDouble, or SumAsDouble when a double-precision result is required. Converting decimal or higher-precision data to double may lose precision. The descriptor helpers follow the same naming distinction between type-preserving and double-valued requests.

Aggregator groups and aggregators have an As<TNewResult>() method that returns an aggregator that uses a different type (supplied as the type argument to the method) for the intermediate values and the result.

For example, to compute the mean of a set of integers to quadruple precision, you can use:

int[] n = { 1, 4, 9 };
var avg = Aggregators.Mean.As<Quad>().Aggregate(n);
// avg = 4.666666666666666666666666666666667

Dim n As Integer() = { 1, 4, 9 }
Dim avg = Aggregators.Mean.As(Of Quad).Aggregate(n)
' avg = 4.666666666666666666666666666666667

No code example is currently available or this language may not be supported.

let n = [| 1; 4; 9 |];
let avg = Aggregators.Mean.As<Quad>().Aggregate(n)
// avg = 4.666666666666666666666666666666667

Some aggregations, such as the correlation between two variables, involve more than one series. The Aggregators class defines a number of aggregators that operate on more than one series:

The simplest way to define an aggregator that is not available from the Aggregators class is to use the Aggregators.Create method. This method takes a delegate that maps a vector to the aggregated value. The following creates an aggregator that computes the geometric mean:

var agg = Aggregators.Create(
    (Vector<double> x) => Stats.GeometricMean(x));

Dim agg = Aggregators.Create(
    Function(x As Vector(Of Double)) Stats.GeometricMean(x))

No code example is currently available or this language may not be supported.

let agg = Aggregators.Create(fun (x : Vector<float>) -> Stats.GeometricMean(x))

Missing-value handling depends on the input's policy. When no explicit skipping option is supplied, vector aggregation uses CheckForMissingValues to determine whether missing values are excluded. Overloads with an explicit skipping option let you choose this behavior. A value such as NaN is not a universal instruction to skip an observation regardless of the input policy.

Schema metadata describing whether a column allows missing values does not select an aggregation policy or report the number of valid observations. The result for an empty group or insufficient valid observations depends on the aggregator; do not assume every aggregation returns zero.