Array-reducing functions

Analytica User GuideMore Array FunctionsArray-reducing functions

An array-reducing function operates across a dimension of an array and returns a result that has one dimension less than the number of dimensions of its input array. When applied to an array of n dimensions, a reducing function produces an array that contains n-1 dimensions. 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 subscript and slice functions also reduce arrays by a dimension (see Subscript and slice of a subarray).

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

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.

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 (3x5 = 15). For Product:

Product(x, Car_type) → 125

That is, it multiplies x three times (5³ = 125).

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.

Elements that are ignored: The array-reducing functions described in this section ignore elements of an array that have the special value Null. For example, the Average(x, i) function sums all the non-null elements of «x» and divide by the number of elements that are not Null.

When a NaN value (signifying an indeterminate number) appears as an element of an array, the result of the function that operates on the array will usually be NaN as well. NaN values result from indeterminate operations such as 0/0, and the fact that they propagate forward in this fashion helps ensure that you will not accidentally compute an indeterminate result without realizing it. However, in some cases you might wish to ignore NaN values in an array-reducing operation. The array-reducing 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)

When you operate over an array containing some text and some numeric values, the Sum, Min and Max functions can be instructed to ignore all the non-numeric values using an optional «ignoreNonNumbers» parameter, for example:

Max(x, i, ignoreNonNumbers: True)

Reducing over multiple indexes: The array-reducing functions Sum, Product, Average, Min, Max, ArgMin, and ArgMax all allow you to specify more than one index as a convenient way to reduce 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)

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)

Returns the item of index «i» for which array «a» is the maximum. If «a» has more than one value equal to the maximum, it returns the index of the last one. See also ArgMax().

Library: Array

Example:

ArgMax(Miles, Car_type) →

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

ArgMin(a, i)

Returns the corresponding value in index «i» for which array «a» is the minimum. If more than one value equals the minimum, returns the index of the last occurrence. See also ArgMin().

Library: Array

Example:

ArgMin(Car_prices, Car_type) →

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

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

Conditional Min and Max. CondMin() returns the smallest, and CondMax() returns the largest values along a given index, «i», that satisfies condition cond. When «cond» is never satisfied, CondMin() returns INF, 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)

Returns the value of index «i» for which array «a» (indexed by «i») is equal to «u». If more than one value of a equals «u», it returns the last value of «i» that matches «u». 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, an array of index values is returned.

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 in index «i» — 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 is equal, it returns 0. See also PositionInIndex().

When array «a» is multidimensional, the result is reduced by one dimension, dimension «i».

Library: Array

Example: When the array is one-dimensional:

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

More examples and tips: 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

• Sum()
• Product()
• Average()
• Functions Min and Max
• Max()
• Min()
• ArgMax()
• ArgMin()
• CondMin()
• CondMax()
• Subindex()
• PositionInIndex()
• Area()

Functions that create arraysArray-reducing functionsTransforming functions