Other array functions
AddIndex(a, i)
Adds one or more indexes «i» to array «a». The result is constant (does not vary) along any of the indexes that are added.
A basic philosophy in Analytica is that a value only needs to contain an index if its data varies along that index; hence, this function is an unnecessary function in almost all “normal” cases. When arrays with different dimensionalities get combined, array abstraction treats the values as if they are constant across the missing dimensions, so there is no need for you to add the dimensions explicitly, and is generally undesirable to do so.
See also AddIndex().
Library: Array
Example: A vector on index ones, indexed by Period:
AddIndex(1, Period) →
Period ▶ Early Middle Late 1 1 1
AddIndex(Rate_of_inflation, Period) →
Years ▶ Period ▼ 2005 2006 2007 2008 2009 Early 1 1.01 1.02 1.03 1.04 Middle 1 1.01 1.02 1.03 1.04 Late 1 1.01 1.02 1.03 1.04
AddIndex(Miles, Period, MaintType)
A 4-D array indexed by Car_type, Years, Period and MaintType. Each slice along a given Period and MaintType contains the data from Miles.
AddIndex(Miles, ... IndexesOf(Cost_of_ownership))
Contains the data from Miles, with all the dimensions of Cost_of_ownership.
Aggregate(x, map, i, targetIndex)
Converts from an array «x» indexed by fine-grain index «i», to an array indexed by the coarser-grained index «targetIndex». Map is an array indexed by «i», specifying for each element if «i» the value of «targetIndex» that the «i»-value maps to. An optional parameter, positional: true, can be specified if map contains the target index position rather than the target index value.
Aggregate() is used when many index elements in «i» correspond to the same «targetIndex» element. By default, the values mapping to the same target position are aggregated by summing them. An optional parameter, «type», can be used to specify alternative aggregation methods. Common aggregation methods include: Sum, Max, Min, Average, Last, First, and Median, but in general any built-in or user-defined function able to accept two parameters, an array and index, such as with a declaration: (A : Array[I] ; I: Index), can be named.
An optional parameter, «defaultValue», specifies the value to use when no value maps to a given target position.
Library: Array
Example: To use Aggregate, you need to define the many-to-one map, here from Time to Period:
Index Period := ['Early', 'Middle', 'Late']Variable Time2Period :=\[Index_a]Array_s →
Time ▶ 0 1 2 3 4 'Early' 'Middle' 'Middle' 'Late' 'Late'
Aggregate(Cost_of_ownership, Time2Period, Time, Period) →
Period ▶ CarType ▼ Early Middle Late VW 2810 6049 6669 Honda 3535 7744 8531 BMW 3185 6703 7185
Aggregate(Cost_of_ownership, Time2Period, Time, Period, type: 'Average') →
Period ▶ CarType ▼ Early Middle Late VW 2810 3025 3335 Honda 3535 3872 4266 BMW 3185 3352 3593
Concat(a1, a2, i, j, k)
Appends array «a2» to array «a1». «i» and «j» are indexes of «a1» and «a2», respectively. «k» is the index of the resulting dimension, and usually consists of the list created by concatenating «i» and «j». When «k» is omitted and the result has two or more dimensions, a local index named «.k» will automatically be created by concatenating the elements of «i» and «j», and the result will be indexed by this «.k».
The parameter «i» (or «j») can be omitted when «a1» (or «a2») is one-dimensional, if «a1» (or «a2») is indexed by a local index «.k» created by a previous call to Concat(), when «a1» (or «a2») contains an implicit dimension, or when «a1» (or «a2») is atomic. The default to a local index «.k» makes it easy to nest calls to Concat() when concatenating three or more arrays (or indexes) together. When «a1» (or «a2») is not array valued an «i» (or «j») is omitted, a single element is concatenated to the front of «a2» (or to the end of «a1»).
Library: Array
Examples: These examples use these variables:
Index Years :=
2005 2006 2007 2008 2009
Index More_years :=
2010 2011 2012
Index All_years := Concat(Years, More_years) →
2005 2006 2007 2008 2009 2010 2011 2012
Variable More_prices :=
More_years ▶ CarType ▼ 2010 2011 2012 VW 21K 22K 24K Honda 25K 28K 29K BMW 32K 33K 35K
Concat(Car_prices, More_prices, Years, More_years, All_years) →
Car_type ▶ All_years ▼ VW Honda BMW 2005 16K 18K 25K 2006 17K 19K 26K 2007 18K 20K 28K 2008 19K 22K 30K 2009 20K 24K 32K 2010 21K 25K 32K 2011 22K 28K 33K 2012 24K 29K 35K
Example of nested usage and local «.k» index:
Concat(Car_prices, Concat(' ', Miles, , Years), Years) →
.K ▶ Car_type ▼ 2005 2006 2007 2008 2009 2005 2006 2007 2008 2009 VW 16K 17K 18K 19K 20K 8000 7000 10K 6000 9000 Honda 18K 19K 20K 22K 24K 10K 12K 11K 14K 13K BMW 25K 26K 28K 30K 32K 5000 8000 8000 7000 10K
See Array Function Example Variables for example array variables used here and below.
ConcatRows(a, rowIndex, colIndex, concatIndex)
Takes an array, a indexed by «rowIndex» and «colIndex», and concatenates each row, flattening the array by eliminating the row dimension. The result is indexed by the «concatIndex», which must be an index with Size(rowIndex) * Size(colIndex) elements. If «concatIndex» is omitted, a local index named .concatIndex is introduced defined as 1 .. N, where N is Size(rowIndex)*Size(colIndex).
See also ConcatRows().
Library: Array
Example:
ConcatRows(Car_prices, Car_type, Years) →
.ConcatIndex ▶ 1 2 3 4 5 ... 13 14 15 16K 17K 18K 19K 20K ... 28K 30K 32K
See Array Function Example Variables for example array variables used here and below.
Flatten(x, i..., resultIndex)
(New to Analytica 5.0)
Flattens a multi-dimensional array, reducing multiple indexes listed in «i...» to the «resultIndex». For example, Flatten(x, In1, In2, In3) returns a one-dimensional array having the same values as the 3-dimensional array «x». The flattening varies In1 most slowly and In3 most quickly.
Only the indexes listed in «i...» are flattened, so that any indexes in «x» not listed remain in the final result. However, if no indexes are listed for «i...», then all indexes of «x» are flattened.
When you omit «resultIndex», a local index named .K is created for you. When you supply an index for «resultIndex», this will be the index for the result. If «resultIndex» is too long, the result is Null-padded; if too short, it is truncated.
See Flatten() for examples.
Unflatten(x, i, resultIndexes...)
(New to Analytica 5.0)
Unflattens a 1-dimensional array «x» into a multi-dimensional array. «x» is indexed by «i». The result contains the same elements as «x», but is dimensioned by «resultIndexes...» instead of «i». For example, the result of Unflatten(x, I, J, K, L ) is indexed by J, K and L, and the elements of «x» along «i» are organized in the result with J varying most slowly and L varying fastest. Any number of result indexes can be listed.
The index «i» can be omitted only when «x» has an implicit dimension. Any indexes of «x» other than «i» are propagated to the result.
See Unflatten() for examples.
IndexLength(i)
(New to Analytica 5.0)
Returns the number of elements in index «i».
IndexLength(x) is equivalent to Size( IndexValue(x) ).
IndexLength cannot be used to obtain the length of the implicit dimension of an array, since there is no way to refer to the implicit dimension. The Size function with «listLen» set to true can be used to get the length of the implicit dimension.
See IndexLength().
IndexNames(a)
Returns a list of the identifiers of the indexes of the array a as text values. See also IndexNames().
Example:
IndexNames(Car_prices) → ['Car_type', 'Years']
IndexesOf(a)
Returns a list of the indexes of the array a as handles (see Handles to Objects). It is similar to IndexNames(), except that it returns handles instead of identifiers as text values. It is possible for an array to have more than one local index having identical names. This is not recommended, but where it occurs, the index handles returned by IndexesOf() are unambiguous.
Library: Array
Example:
IndexesOf(Car_prices) → [Car_type, Years]
IndexValue(i)
Some variables have both an index value and a result value. Examples include a self-indexed array; a variable or index defined as a list of identifiers or list of expressions; and a Choice list with a self-domain. IndexValue(i) returns the index value of «i», where «(i)» alone would return its result value.
Library: Array Functions
Example
Variable Cubes := [1, 2, 3, 4]^3IndexValue(Cubes) → [1, 2, 3, 4]CopyIndex(Cubes) →[1, 4, 9,16]
Variable Colors := Table(Self, Cubes)(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)- with Self index
['Red', 'Green', 'Blue']
- with Self index
Colors →
Colors ▶ Cubes ▼ Red Green Blue 1 16K 18K 25K 2 17K 19K 26K 3 18K 20K 28K 4 19K 22K 30K
IndexValue(Colors) → ['Red', 'Green', 'Blue']
Size(u, listLen)
Returns the number of atoms (elementary cells) in array «u». The size of an atom (including the special value Null) is 1. The size of an empty list is 0.
Although Size can be used to obtain the length of an index, you should use IndexLength(I) instead. It is best to use Size(u) for the total number of cells in an array, and IndexLength(I) for the total number of items in an index. When I is a pure index (or is declared as an index parameter), Size(I) does indeed return the index length. But more generally, a variable can contain a self-indexed array, in which case the index length and the array-length may not the same.
If an array A contains an implicit dimension, it is not possible to use IndexLength(???) or Size(IndexValue(???)) to obtain the length of the implicit dimension, since the implicit dimension has no name to refer to it by. Setting the optional parameter listLen: true returns the length of the implicit index, or null if there it has no implicit index.
See also Size() and IndexLength().
Examples:
Size(Years) → 5Size(Car_prices) → 15Size(10) → 1Size([]) → 0Size([Years, Car_prices]) → 30Size([Years, Car_prices], listLen: true) → 2
Subset(d, position, i, resultIndex)
Subset(d) returns the subset of «d»’s index values that correspond to true values in «d». This basic usage, explained in Subset(d), cannot be employed when «d» has more than one dimension, that is, it does not array abstract. The optional parameters «i» and «resultIndex» provide an array-abstractable form that can be applied to multi-dimensional arrays, where the parameter «i» specifies the index to take the subset over, and «resultIndex» specifies the index for the final result.
When the number of true elements exceeds N (the number of elements in «resultIndex»), the index values corresponding to the first N true values are returned. For the cases where there are fewer than N true values, the result is padded with null values. Setting the optional «position» parameter to true returns the index positions, rather than the index elements, of the true values.
Library: Array
Example:
Index MultiEventCars := 1 .. 4Subset(Miles > 8000, i: Car_type, resultindex: Car_type) →
Years ▶ Car_type ▼ 2005 2006 2007 2008 2009 VW Honda Honda VW Honda VW Honda «null» «null» Honda «null» Honda BMW «null» «null» «null» «null» Honda
In the above example, Miles values for Honda exceeded 8,000 in 2008 and 2009.
See Array Function Example Variables for example array variables used here and below.
See Also
- AddIndex()
- Aggregate()
- Concat()
- ConcatRows()
- IndexNames()
- IndexesOf()
- IndexValue()
- Size()
- Subset()
Enable comment auto-refresher