Array-reducing functions

Analytica User GuideArray functionsArray-reducing functions

An array-reducing function aggregates across an Index (dimension) of an array and returns a result without that Index. So it reduces the number of dimensions of that array by one (or more). Examples include, Sum(x, i), Product(x, i), Max(x, i), Min(x, i), and others described below. The subscript construct x[i = v] and related slice functions also reduce arrays by a dimension.

The function Sum(x, i) illustrates some properties of reducing functions.

Examples

Sum(Car_prices, Car_type) →

Years ▶
2005	2006	2007	2008	2009
59K	62K	66K	71K	76K

Sum(Car_prices, Years) →

Car_type ▶
VW	Honda	BMW
99K	103K	141K

Sum(Sum(Car_prices, Years), Car_type) → 334K

Or more simply:

Sum(Car_prices, Years, Car_type) → 334K

See Array Function Example Variables for example array variables used here and below.

Tip

The second parameter, «i», specifying the dimension over which to sum, is optional. But if the array, «x», has more than one dimension, Analytica might not sum over the dimension you expect. For this reason, it is safer always to specify the dimension index explicitly in Sum() or any other array-reducing function.

Key features

Reduce over multiple indexes

Most array-reducing functions, including Sum, Product, Average, Min, Max, ArgMin, and ArgMax, let you specify more than one index. This is a convenient way to operate over multiple indexes in a single call, for example:

Sum(x, i, j, k)

This is equivalent to:

Sum(Sum(Sum(x, i), j), k)

Reduce over all indexes

You can sum over all the indexes of an array without having to list them explicitly:

Sum(x, ... IndexesOf(x))

This necessarily returns a scalar -- i.e. value with no index. See Repeated Parameter Forwarding for details.

Below we describe the most common array-reducing functions.

Reducing over an unused index

If the index, «i», is not a dimension of «x», Sum(x, i) returns «x» unreduced (i.e., with the same number of indexes), but multiplied by the size (number of elements) of «i». The reason is that if «x» is not indexed by «i», it means that it has the same value for all values of «i». This is true even if «x» is an atom with no dimensions:

Variable x := 5

Sum(x, Car_type) → 15

This is because Car_type has three elements (3 x 5 = 15).

In this way, if we later decide to change the value for x for each value of Car_type, we can redefine «x» as an edit table indexed by Car_type. Any expression containing a Sum() or other reducing function on «x» works correctly whether it is indexed by Car_type or not.

Ignoring Null

These array-reducing functions ignore elements of an array that contain Null. For example, the Average(x, i) function sums all the non-null elements of «x» and divides by the number of non-null elements. This feature is very convenient when working with missing data.

Treatment of NAN

When the array contains a NaN value (an indeterminate number), the result of a function on the array is usually NaN as well. NaN values result from indeterminate operations such as 0/0. NaNs propagate in this fashion to ensure that you will not accidentally compute an indeterminate result without realizing it. However, if you wish to ignore NaN values, the functions Sum, Product, Average, Min, and Max all accept an optional parameter, «ignoreNaN» that can be set to True. «IgnoreNan» requires a named-parameter syntax, for example:

Max(x, i, ignoreNaN: True)

Text values

When the parameter contains both text and numbers, Sum, Min and Max normally return NaN. But you can instruct them to ignore non-numeric values (except NaN) using the optional «ignoreNonNumbers» parameter, for example:

Max(x, i, ignoreNonNumbers: True)

Functions Min, Max, ArgMin, ArgMax, CondMin and CondMax work on text values using alphabetical ordering. Min refers to the first item and Max the last item alphabetically.

Sum(x, i)

Returns the sum of array «x» over the dimension indexed by «i».

Library: Array

Examples:

Sum(Car_prices, Years) →

Car_type ▶
VW	Honda	BMW
99K	103K	141K

See Array Function Example Variables for example array variables used here and below.

Product(x,i)

Returns the product of all of the elements of «x», along the dimension indexed by «i». See also Product().

Library: Array

Examples:

Product(Car_prices, Car_type) →

Years ▶
2005	2006	2007	2008	2009
7.2T	8.398T	10.08Y	12.54T	15.36T

Average(x, i)

Returns the mean value of all of the elements of array «x», averaged over index «i». See also Average().

Library: Array

Examples:

Average(Miles, Years)→

Car_type ▶
VW	Honda	BMW
8000	12K	7600

Max(x, i)

Returns the highest valued element of «x» along index «i». See also Max().

Library: Array

Examples:

Max(Miles, Years) →

Car_type ▶
VW	Honda	BMW
10K	12K	10K

To obtain the maximum of two numbers, first turn them into an array:

Max([10, 5]) → 10

See Array Function Example Variables for example array variables used here and below.

Min(x, i)

Returns the lowest valued element of «x» along index «i». See also Min().

Library: Array

Examples:

Min(Miles, Years) →

Car_type ▶
VW	Honda	BMW
6000	10K	5000

To obtain the minimum of two numbers, first turn them into an array:

Min([10, 5]) → 5

ArgMax(a, i) and ArgMin(a, i)

ArgMax(a, i) an item of index «i» for which array «a» is the maximum. Similarly, ArgMin(a, i) returns a value of «i» for which «a» is minimum.

Position: If you specify optional parameter First: True, these functions return the position (integer number) isntead of the value of «i» of the maximum (or minimum) value in «a».

First: If «a» has more than one maximum (minimum) value, it normally returns the last one. Or you can specify optional parameter First: False if you prefer to return the first one.

Library: Array

Example:

ArgMax(Miles, Car_type) →

Years ▶
2005	2006	2007	2008	2009
Honda	Honda	Honda	Honda	Honda

ArgMin(Car_prices, Car_type) →

Years ▶
2005	2006	2007	2008	2009
BMW	VW	BMW	VW	VW

CondMin(x, cond, i) and CondMax(x, cond, i)

CondMin() "conditional min" returns the smallest value along a given index, «i», that satisfies condition «cond». Similarly, CondMax() returns the largest When «cond» is never satisfied, CondMin() returns INF and CondMax() returns -INF.

Library: none

Examples:

CondMin(Cost_of_ownership, Time >= 2, Time) →

Car_type ▶
VW	Honda	BMW
3098	3897	3409

SubIndex(a, u, i)

Does a lookup (similar to VLookup and Hlookup in Excel) returning the value of index «i» of array «a» for which «a» equals «u» -- in other words, it returns the value vi of index «i» for which array «a»[«i» = vi] = «u». If «a» contains multiple values equal to «u», it returns the last value of «i» that matches. If no value of «a» equals «u», it returns Null. If «a» has index(es) in addition to «i», or if «u» is an array with other indexes, those indexes also appear in the result. See also SubIndex().

Library: Array

Examples:

SubIndex(Car_prices, 18K, Car_type) →

Years ▶
2005	2006	2007	2008	2009
Honda	«null»	Honda	«null»	«null»

SubIndex(Car_prices, 18K, Years) →

Car_type ▶
VW	Honda	BMW
2007	2005	«null»

If «u» is an array of values, it returns an array with the same indexes.

SubIndex(Car_prices, [18K, 19K] Car_type) →

	Years ▶
Subindex ▼	2005	2006	2007	2008	2009
18K	Honda	«null»	VW	«null»	«null»
19K	«null»	Honda	«null»	VW	«null»

PositionInIndex(a, x, i)

Returns the position n in index «i» for which x[@i = n] = x — that is, a number from 1 to the size of index «i» — of the last element of array «a» equal to «x». If no element of «a» matches «x», it returns 0. See also PositionInIndex().

Example:

Index I := ['A', 'B', 'C']

Variable A := Array(I, [1, 2, 2])

PositionInIndex(A, 1, I) → 1

PositionInIndex(A, 2, I) → 3

PositionInIndex(A, 5, I) → 0

Tip

PositionInIndex() is the positional equivalent of Subindex(). It is useful when «i» contains duplicate values, in which case Subindex() would return an ambiguous result.

Tip

Parameter a is optional. When omitted, it returns the position of x in the index i, or 0 if not found. The syntax @[i = x] (see @: Index Position Operator) returns the same result as PositionInIndex(, x, i):

PositionInIndex(, 'B', I) → 2

@[I = 'B'] → 2

PositionInIndex(, 'D', I) → 0

@[I = 'D'] → 0

When the array is multidimensional: Taking the same example from above:

PositionInIndex(Car_prices, 18K, Car_type) →

Years ▶
2005	2006	2007	2008	2009
2	0	1	0	0

Area(y, x, x1, x2, i)

Returns the area (sum of trapezoids) under the piecewise-linear curve denoted by the points («x_i», «y_i»), landing in the region «x1» ≤ «x» ≤ «x2». The arrays «x» and «y» must share the common index «i», or when either «x» or «y» is itself an index, «i» can be safely omitted. «x» and «x2» are optional; if they are not specified, the area is calculated across all values of «x».

If «x1» or «x2» fall outside the range of values in «i», the first value (for «x1») or last value (for «x1») are used. Area() computes the total integral across «x», returning a value with one less dimension than «y». Compare Area() to Integrate().

Library: Array

Example

Area(Cost_of_ownership, Time, 0, 2) →

Car_type ▶
VW	Honda	BMW
5905	7563	6591

See Also

• Tutorial: Array Reducing Functions
• Category:Array-reducing functions
• Tutorial: Reducing an array using subscripts
• Sum()
• Product()
• Average()
• Functions Min and Max
• Max()
• Min()
• ArgMax()
• ArgMin()
• CondMin()
• CondMax()
• SubIndex()
• PositionInIndex()
• Area()
• Function calls and parameters
• Multidimensional array
• Relational tables and multiD arrays
• Reducing over all indexes

Functions that create arraysArray-reducing functionsTransforming functions