View source for Functions that create arrays

[[Category:Analytica User Guide]]
[[Category:Functions that create arrays]]
<breadcrumbs>Analytica User Guide > Array functions > {{PAGENAME}}</breadcrumbs>

__TOC__

Usually, the most convenient way to create an array of numbers or text values is as an [[edit table]]. When viewing the definition of the variable, choose '''Table''' from the [[expr]] menu to create an edit table (see [[Defining a variable as an edit table]]). If you want to define a table by explicitly listing its indexes and providing expressions to generate its values or sub-arrays, you might find [[Array]] more convenient.

:[[File:Chapter12_1.png]]

If you select '''expr''' from the [[expr]] menu, it displays it as a table expression in the '''Definition''' field (rather than a separate edit table), listing the indexes and values.

:[[File:Chapter12_2.png]]

==Array(i1, ''i2, … in'', a)==
Assigns a set of indexes, «i1», «i2», … «in», as the indexes of the array «a», with «i1» as the index of the outermost dimension (changing least rapidly), «i2» as the second outermost, and so on. «a» is an expression returning an array which typically has at least «n» dimensions, each dimension with the number of elements matching the corresponding index. You can use array to change the index variable(s) from one to another with the same number(s) of elements. [[Array]] is one of the few places where you actually need to worry about the order of the indexes in the array representation.

Use [[Array]] to specify an array directly as an expression. [[Array]] is similar to [[Functions that create arrays#Table()|Table]]; in addition, it lets you define an array with repeated values (see Example 3 below), and change indexes of a previously defined array (see Example 4).

'''Library:''' Array

'''Example 1'''

Definition viewed as an expression:

:<code>Index Car_type := ['VW', 'Honda', 'BMW']</code>
:<code>Array(Car_type, [32, 34, 18])</code>

Definition viewed as a table:
:{| class="wikitable"
!VW
!Honda
!BMW
|-
|32
|34
|18
|}

'''Example 2'''

If an array has multiple dimensions, then the elements are listed in nested brackets, following the structure of the array as an array of arrays (of arrays..., and so on, according to the number of dimensions).

Definition viewed as an expression:

:<code>Array(Car_type, Years, [[8K, 7K, 10K, 6K, 9K], [10K, 12K, 11K, 14K, 13k], [5K, 8K, 8K, 7K, 10k]])</code>

Definition viewed as a table:

:{| class="wikitable" border="1" 
! !! colspan="5" style="text-align: left;" | Years &#9654;
|-
! style="width:100px;" |'''Car_type &#9660; '''
! style="width:75px;" |'''2005            '''
! style="width:75px;" |'''2006            '''
! style="width:75px;" |'''2007            '''
! style="width:75px;" |'''2008            '''
! style="width:75px;" |'''2009            '''
|-
!'''VW''' 
| 8000
| 7000
| 10K
| 6000
| 9000
|-
!'''Honda '''
| 10K
| 12K
| 11K
| 14K
| 13K
|-
!'''BMW''' 
| 5000
| 8000
| 8000
| 7000
| 10K
|}

The size of each array in square brackets must match the size of the corresponding index. In this case, there is an array of three elements (for the three car types), and each element is an array of four elements (for the four years). An error message displays if these sizes don’t match. See also [[Functions that create arrays#Size(u, listLen)|Size(u, listLen)]].

'''Example 3'''

If an element is a scalar where an array is expected, [[Array]]() expands it to create an array with the scalar value repeated across a dimension.

Definition viewed as an expression:

:<code>Array(Car_type, Years, [[8K, 7K, 10K, 6K, 9K], 13K, [5K, 8K, 8K, 7K, 10k]])</code>

Definition viewed as a table:

:{| class="wikitable" border="1" 
! !! colspan="5" style="text-align: left;" | Years &#9654;
|-
! style="width:100px;" |'''Car_type &#9660; '''
! style="width:75px;" |'''2005            '''
! style="width:75px;" |'''2006            '''
! style="width:75px;" |'''2007            '''
! style="width:75px;" |'''2008            '''
! style="width:75px;" |'''2009            '''
|-
!'''VW''' 
| 8000
| 7000
| 10K
| 6000
| 9000
|-
!'''Honda '''
| 13K
| 13K
| 13K
| 13K
| 13K
|-
!'''BMW''' 
| 5000
| 8000
| 8000
| 7000
| 10K
|}

'''Example 4'''

Use [[Array]]() to change an index of a previously defined array.

:<code>Index Car_model := ['Jetta', 'Accord', '320']</code>
:<code>Variable Table_a:= Table(Car_type) (32, 34, 18)</code>
:<code>Variable Table_b:= Array(Car_model, Table_a) &rarr;</code>
:{| class="wikitable"
!Jetta
!Accord
!320
|-
|32
|34
|18
|}

<tip title="Tip">There are some significant disadvantages to using the [[Array]] function to change the index of an array in the fashion demonstrated in Example 4. Specifically, if a second dimension were later added to <code>Table_a</code>, the index that the [[Array]]() function changes might not be the one you intended. The preferred method for changing the index, which does fully generalize when <code>Table_a</code> has many dimensions, is to use the slice operator (see Tip on re-indexing) as follows: 
:<code>Table_a [@Car_type = @car_model]</code>
</Tip>

==Table(i1, ''i2, … in'') (u, u2, u3, … um)==

This function is automatically created when you select '''Table''' from the [[expr]] menu to create an edit table. You can view it as an expression in this form in the definition of the variable by selecting '''expression''' from the '''expr''' menu. It. creates an <code>n</code>-dimensional array of <code>m</code> elements, indexed by the indexes «i1», «i2», … «in». In the set of indexes, «i1» is the index of the outermost dimension, varying the least rapidly.

The second set of parameters, «u1», «u2» … «um», specifies the values in the array. The number of values, <code>m</code>, must equal the product of the sizes of all of the dimensions.

Each «u» is an expression that evaluates to a number, text value or probability distribution. It can also evaluate to an array, causing the dimensions of the entire table to increase. «u» cannot be a literal list.

Both sets of parameters are enclosed in parentheses; the separating commas are optional except if the table values are negative.

Use [[Table]]() to specify an array directly as an expression. [[Table]]() is similar to [[Functions_that_create_arrays#Array(i1, ''i2, … in'', a)|Array()]]; [[Table]]() requires <code>m</code> numeric or text values.

A definition created as a table from the '''expr''' menu uses [[Table]]() in expression view.

'''Library:''' Array

'''Example 1:''' Definition viewed as an expression:
:<code>Table(Car_type) (32, 34, 18)</code>

Definition viewed as a table:
:{| class="wikitable"
!VW
!Honda
!BMW
|-
|32
|34
|18
|}

'''Example 2''' 

Definition viewed as an expression:
:<code>Table(Car_type, Years) (8K, 7K, 10K, 6K, 9K, 10K, 12K, 11K, 14K, 13K, 5K, 8K, 8K, 7K, 10K)</code>

Definition viewed as a table:
:{| class="wikitable" border="1" 
! !! colspan="5" style="text-align: left;" | Years &#9654;
|-
! style="width:100px;" |'''Car_type &#9660; '''
! style="width:75px;" |'''2005            '''
! style="width:75px;" |'''2006            '''
! style="width:75px;" |'''2007            '''
! style="width:75px;" |'''2008            '''
! style="width:75px;" |'''2009            '''
|-
!'''VW''' 
| 8000
| 7000
| 10K
| 6000
| 9000
|-
!'''Honda '''
| 10K
| 12K
| 11K
| 14K
| 13K
|-
!'''BMW''' 
| 5000
| 8000
| 8000
| 7000
| 10K
|}

It looks like this when viewed as an edit table:
:{| class="wikitable" border="1" 
! !! colspan="5" style="text-align: left;" | Years &#9654;
|-
! style="width:100px;" |'''Car_type &#9660; '''
! style="width:75px;" |'''2005            '''
! style="width:75px;" |'''2006            '''
! style="width:75px;" |'''2007            '''
! style="width:75px;" |'''2008            '''
! style="width:75px;" |'''2009            '''
|-
!'''VW''' 
| 0
| 0
| 0
| 0
| 0
|-
!'''Honda '''
| 0
| 0
| 0
| 0
| 0
|-
!'''BMW''' 
| 0
| 0
| 0
| 0
| 0
|}


==IntraTable(i1,'' i2, … in'') (u1, u2, u3, … um)==
[[IntraTable]]() generalizes the [[Table]] function to permit functional dependencies between cells. These dependencies can be denoted as ''intra-cell'' dependencies, and hence, the table as a whole as an ''IntraTable''. An '''IntraTable''' behaves identically to an edit table in all other respects.

The presence of intra-cell dependencies produces a table that is reminiscent of a spreadsheet, with dependencies between individual cells. As such, it is advisable to avoid '''IntraTable''' if you don’t need to, since it can easily be abused and lead to inflexible and hard-to-maintain models.

To create an '''IntraTable''', while editing a definition select ''Other...'' on the [[expr]] menu and select '''IntraTable''' in the '''Array Functions''' library.

Within cells, you can apply [[slice]] and [[subscript]] notation to the [[Self]] keyword to reference other cells within the table. The intra-cell dependencies must not form a directed loop, which would imply that a cell is defined indirectly in terms of itself, otherwise an error will result when the table is evaluated.

The following example contains two cells that illustrate intra-cell references, with examples of both subscript and slice notation.

:{| class="wikitable" border="1" 
! !! colspan="5" style="text-align: left;" | Years &#9654;
|-
! style="width:100px;" |'''Car_type &#9660; '''
! style="width:75px;" |'''2005            '''
! style="width:75px;" |'''2006            '''
! style="width:75px;" |'''2007            '''
! style="width:75px;" |'''2008            '''
! style="width:75px;" |'''2009            '''
|-
!'''VW''' 
| 8000
| 7000
| 10K
| 6000
| 9000
|-
!'''Honda '''
| 10K
| <code>Self[Years = Years - 1]*1.05</code>
| 11K
| 14K
| 13K
|-
!'''BMW''' 
| 5000
| <code>(Self[Car_type = ’VW’] +
Self[Years = 2005, 
@Car_type = @Car_Type - 2])/2</code>
| 8000
| 7000
| 10K
|}

When evaluated, the following array results:
:{| class="wikitable" border="1" 
! !! colspan="5" style="text-align: left;" | Years &#9654;
|-
! style="width:100px;" |'''Car_type &#9660; '''
! style="width:75px;" |'''2005            '''
! style="width:75px;" |'''2006            '''
! style="width:75px;" |'''2007            '''
! style="width:75px;" |'''2008            '''
! style="width:75px;" |'''2009            '''
|-
!'''VW''' 
| 8000
| 7000
| 10K
| 6000
| 9000
|-
!'''Honda '''
| 10K
| 10.5K
| 11K
| 14K
| 13K
|-
!'''BMW''' 
| 5000
| 7500
| 8000
| 7000
| 10K
|}

==See Also==
* [[Array]]
* [[Table]]
* [[IntraTable]]
* [[To make an edit table]]
* [[Definition]]


<footer>Array Function Example Variables / {{PAGENAME}} / Array-reducing functions</footer>