Array-reducing functions

Revision as of 19:00, 9 February 2017 by Max (talk | contribs)
Analytica User GuideArray 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 (53 = 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)

Reducing over all indexes: You can also 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.

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 («xi», «yi»), 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


Functions that create arraysArray-reducing functionsTransforming functions
Comments


You are not allowed to post comments.