Difference between revisions of "Array-reducing functions"
| Line 4: | Line 4: | ||
__TOC__ | __TOC__ | ||
| − | 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 <code>n</code> dimensions, a reducing function produces an array that contains <code>n-1</code> 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]]). | + | 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 <code>n</code> dimensions, a reducing function produces an array that contains <code>n-1</code> 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. | The function '''Sum(x, i)''' illustrates some properties of reducing functions. | ||
| Line 56: | Line 56: | ||
That is, it multiplies <code>x</code> three times (5<sup>3</sup> = 125). | That is, it multiplies <code>x</code> three times (5<sup>3</sup> = 125). | ||
| − | In this way, if we later decide to change the value for x 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 x 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:''' 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 | + | 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: |
| − | 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: | ||
Max(x, i, ignoreNaN: True) | Max(x, i, ignoreNaN: True) | ||
| − | When you operate over an array containing some text and some numeric values, the Sum, Min | + | 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 '''ignoreNonNumber'''s parameter, for example: |
| − | and Max functions can be instructed to ignore all the non-numeric values using an optional | ||
| − | |||
Max(x, i, ignoreNonNumbers: True) | Max(x, i, ignoreNonNumbers: True) | ||
'''Reducing over multiple indexes:''' | '''Reducing over multiple indexes:''' | ||
| − | The array-reducing functions '''Sum, Product, Average, Min, Max, ArgMin''', and '''ArgMax''' all allow | + | 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: |
| − | 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) | Sum(x, i, j, k) | ||
This is equivalent to: | This is equivalent to: | ||
| Line 223: | Line 217: | ||
==ArgMin(a, i)== | ==ArgMin(a, i)== | ||
| − | Returns the corresponding value in index '''i''' for which array '''a''' is the minimum. If more than one | + | 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. |
| − | value equals the minimum, returns the index of the last occurrence. | ||
'''Library:''' Array | '''Library:''' Array | ||
| Line 248: | Line 241: | ||
|} | |} | ||
| − | ==CondMin(x, cond, i) | + | ==CondMin(x, cond, i), CondMax(x, cond, i)== |
| − | + | Conditional Min and Max. '''[[CondMin]]()''' returns the smallest, and '''[[CondMax()]]''' returns the largest | |
| − | 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 <code>INF</code>, '''CondMax()''' returns <code>-INF</code>. | values along a given index, '''i''', that satisfies condition cond. When '''cond''' is never satisfied, '''CondMin()''' returns <code>INF</code>, '''CondMax()''' returns <code>-INF</code>. | ||
| Line 355: | Line 347: | ||
PositionInIndex(A, 5, I) → 0 | PositionInIndex(A, 5, I) → 0 | ||
| − | <tip title="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> | + | <tip title="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> |
<tip title="Tip">Parameter a is optional. When omitted, it returns the position of x in the index i, or 0 if not found. The syntax <code>@[i = x]</code> (see [[Subscript and slice of a subarray#@: Index Position Operator|@: Index Position Operator]]) returns the same result as <code>PositionInIndex(, x, i)</code>: | <tip title="Tip">Parameter a is optional. When omitted, it returns the position of x in the index i, or 0 if not found. The syntax <code>@[i = x]</code> (see [[Subscript and slice of a subarray#@: Index Position Operator|@: Index Position Operator]]) returns the same result as <code>PositionInIndex(, x, i)</code>: | ||
| Line 384: | Line 376: | ||
| 0 | | 0 | ||
|} | |} | ||
| − | |||
==Area(y, x, ''x1, x2, i'')== | ==Area(y, x, ''x1, x2, i'')== | ||
| Line 390: | Line 381: | ||
'''(x<sub>i</sub>, y<sub>i</sub>)''', landing in the region <code>x1 ≤ x ≤ x2</code>. 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. '''x1''' and '''x2''' are optional; if they are not specified, the area is calculated across all values of '''x'''. | '''(x<sub>i</sub>, y<sub>i</sub>)''', landing in the region <code>x1 ≤ x ≤ x2</code>. 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. '''x1''' 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 '''[[Transforming functions#Integrate()|Integrate()]]'''. | + | 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 '''[[Transforming functions#Integrate()|Integrate()]]'''. |
'''Library:''' Array | '''Library:''' Array | ||
| Line 408: | Line 399: | ||
| 6591 | | 6591 | ||
|} | |} | ||
| − | |||
==See Also== | ==See Also== | ||
| + | * [[Sum]]() | ||
| + | * [[Product]]() | ||
| + | * [[Average]]() | ||
| + | * [[Max]]() | ||
| + | * [[Min]]() | ||
| + | * [[ArgMax]]() | ||
| + | * [[ArgMin]]() | ||
| + | * [[CondMin]]() | ||
| + | * [[CondMax]]() | ||
| + | * [[Subindex]]() | ||
| + | * [[PositionInIndex]]() | ||
| + | * [[Area]]() | ||
<footer>Functions that create arrays / {{PAGENAME}} / Transforming functions</footer> | <footer>Functions that create arrays / {{PAGENAME}} / Transforming functions</footer> | ||
Revision as of 08:12, 15 December 2015
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.
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)
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.
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.
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.
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.
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.
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.
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.
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.
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
@[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. x1 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 |
Enable comment auto-refresher