Difference between revisions of "Array-reducing functions"

m
m
Line 5: Line 5:
 
__TOC__
 
__TOC__
  
−
An '''array-reducing function''' aggregates across an Index (dimension) of an array and returns a result without that Index, and so reduces the number of dimensions of that array by one. Examples include, [[Sum]](x, i), [[Product]](x, i), [[Max]](x, i), [[Min]](x, i), and others described below. The subscript construct [[Subscript-Slice_Operator|x[i = v]]] and related subscript and slice functions also reduce arrays by a dimension (see [[Subscript and slice of a subarray]]).
+
An '''array-reducing function''' aggregates across an Index (dimension) of an array and returns a result without that Index. So 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 and slice of a subarray |subscript]] construct [[Subscript-Slice_Operator|x[i = v]]] and related slice functions also reduce arrays by a dimension.
  
 
The function [[Sum]](x, i) illustrates some properties of reducing functions.
 
The function [[Sum]](x, i) illustrates some properties of reducing functions.
Line 56: Line 56:
 
In this way, if we later decide to change the value for <code>x</code> for each value of <code>Car_type</code>, we can redefine «x» as an edit table indexed by <code>Car_type</code>. Any expression containing a [[Sum]]() or other reducing function on «x» works correctly whether it is indexed by <code>Car_type</code> or not.
 
In this way, if we later decide to change the value for <code>x</code> for each value of <code>Car_type</code>, we can redefine «x» as an edit table indexed by <code>Car_type</code>. Any expression containing a [[Sum]]() or other reducing function on «x» works correctly whether it is indexed by <code>Car_type</code> 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]].
+
'''Elements that are ignored:''' 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.
  
−
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 <code>0/0</code>, 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:
+
'''IgnoreNaN''': When a '''NaN''' value (an indeterminate number) appears as an element of an array, the result of a function that operates on the array is usually '''NaN''' as well. '''NaN''' values result from indeterminate operations such as <code>0/0</code>. They propagate forward in this fashion to 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 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:
  
 
:<code>Max(x, i, ignoreNaN: True)</code>
 
:<code>Max(x, i, ignoreNaN: True)</code>
  
−
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:
+
'''ignoreNonNumbers''': When the parameter contains both text and numbers, you can instruct [[Sum]], [[Min]] and [[Max]] to ignore the non-numeric values using the optional «ignoreNonNumbers» parameter, for example:
  
 
:<code>Max(x, i, ignoreNonNumbers: True)</code>
 
:<code>Max(x, i, ignoreNonNumbers: True)</code>
  
−
'''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 reduce over multiple indexes in a single cal, for example:
+
'''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 reduce over multiple indexes in a single call, for example:
  
 
:Sum(x, i, j, k)
 
:Sum(x, i, j, k)
Line 76: Line 76:
 
:Sum(x, ... IndexesOf(x))
 
:Sum(x, ... IndexesOf(x))
 
This necessarily returns a scalar -- i.e. value with no index. See [[Repeated Parameter Forwarding]] for details.
 
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.
  
 
==Sum(x, ''i'')==
 
==Sum(x, ''i'')==
Line 240: Line 242:
 
|}
 
|}
  
−
==CondMin(x, cond, i), CondMax(x, cond, i)==
+
==CondMin(x, cond, i) and 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 <code>-INF</code>.
+
[[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 <code>-INF</code>.
  
 
'''Library:''' none
 
'''Library:''' none

Revision as of 19:19, 23 November 2024

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 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

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 (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.

Elements that are ignored: 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.

IgnoreNaN: When a NaN value (an indeterminate number) appears as an element of an array, the result of a function that operates on the array is usually NaN as well. NaN values result from indeterminate operations such as 0/0. They propagate forward in this fashion to 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 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)

ignoreNonNumbers: When the parameter contains both text and numbers, you can instruct Sum, Min and Max to ignore the non-numeric values using the optional «ignoreNonNumbers» parameter, for example:

Max(x, i, ignoreNonNumbers: True)

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 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)

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.

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) 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, 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 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 («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.