Difference between revisions of "Functions that create indexes"

 
(24 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Category:Analytica User Guide]]
+
[[Category: Analytica User Guide]]
 +
[[Category: Array Functions]]
 +
 
 
<breadcrumbs>Analytica User Guide > Arrays and Indexes > {{PAGENAME}}</breadcrumbs>
 
<breadcrumbs>Analytica User Guide > Arrays and Indexes > {{PAGENAME}}</breadcrumbs>
  
 +
==Using a function to create an index==
 +
It is usually easiest to define an index as a list, list of labels, or sequence. Sometimes, you need to define an index using a more general expression, as a list of expressions, a list of variables, or a function such as [[Subset]](), [[Concat]](), and [[SortIndex]](). This section describes these and other functions that you can use to create indexes.
  
It is usually easiest to define an index as a list, list of labels, or sequence. Sometimes, you need to define an index using a more general expression, as a list of expressions, a list of variables, or a function such as '''Subset()''', '''Concat()''', and '''SortIndex()'''. This section describes these and other functions that you can use to create indexes.
+
==[''u1, u2, u3, … um'']==
 
 
==[ ''u1, u2, u3, … um '']==
 
 
A simple way to define an index is specify its definition as a list of values separated by commas and surrounded by square brackets. The values can be numbers, text values, or other expressions.
 
A simple way to define an index is specify its definition as a list of values separated by commas and surrounded by square brackets. The values can be numbers, text values, or other expressions.
  
 
===Examples===
 
===Examples===
<code>[8000, 12K, 15K]</code>
+
:<code>[8000, 12K, 15K]</code>
 
+
:<code>['VW', 'Honda', 'BMW']</code>
<code>['VW', 'Honda', 'BMW']</code>
 
  
These lists are equivalent to using the '''List '''or '''List of Labels '''options in the '''''expr '''''menu.
+
These lists are equivalent to using the '''List '''or '''List of Labels '''options in the [[expr]] menu.
  
 
==List of variables==
 
==List of variables==
Line 34: Line 35:
 
The result of <code>CompareVars</code> is an array of the values of the variables it contains, with a self index, also called <code>CompareVars</code>, that usually shows the titles of the variables.
 
The result of <code>CompareVars</code> is an array of the values of the variables it contains, with a self index, also called <code>CompareVars</code>, that usually shows the titles of the variables.
  
If any or all the variables contain arrays, the result contains the union of the indexes of the con- tained variables. For example if '''A '''is an atom (not an array) and '''C '''is indexed by '''c''', the result will be indexed by '''I'''. The slice of <code>CompareVars</code> for '''A '''will have the same value of '''A '''repeated for each value of '''A'''.  
+
If any or all the variables contain arrays, the result contains the union of the indexes of the contained variables. For example if '''A '''is an atom (not an array) and '''C '''is indexed by '''c''', the result will be indexed by '''I'''. The [[slice]] of <code>CompareVars</code> for '''A '''will have the same value of '''A '''repeated for each value of '''A'''.  
  
'''Self index''': The result will contain an extra index, a '''''self index '''''of <code>CompareVars</code>, comprising the list of the variables.
+
'''Self index''': The result will contain an extra index, a [[Self]] index of <code>CompareVars</code>, comprising the list of the variables.
  
'''Clickable titles or identifiers in table''': Usually these display the titles of the variables in a table or graph result. (If you select '''Show by Identifier '''from the '''Object '''menu (or press ''Control+y'') it toggles to show the identifiers instead of titles. If you double-click a title (or identifier) in a table, it will open the '''Object '''window for that variable. The values in the self index are actually '''''handles '''''to the variables.  
+
'''Clickable titles or identifiers in table''': Usually these display the titles of the variables in a table or graph result. (If you select '''Show by Identifier '''from the [[Object menu]] (or press ''Control+y'') it toggles to show the identifiers instead of titles. If you double-click a title (or identifier) in a table, it will open the [[Object window]] for that variable. The values in the self index are actually [[handle]]s to the variables.
  
== m .. n ==
+
==m .. n ==
Returns a sequence of successive integers from '''m '''to '''n '''— increasing if '''n < m''', or decreasing if '''n'''> '''m'''. For example:
+
Returns a sequence of successive integers from «m» to «n» — increasing if «n» < «m», or decreasing if «n» > «m». For example:
  
 
:<code>2003..2006 &rarr; [2003, 2004, 2005, 2006]</code>
 
:<code>2003..2006 &rarr; [2003, 2004, 2005, 2006]</code>
 
 
:<code>5 .. 1 &rarr; [5, 4, 3, 2, 1]</code>
 
:<code>5 .. 1 &rarr; [5, 4, 3, 2, 1]</code>
  
It is equivalent to '''Sequence(m, n)'''.
+
It is equivalent to [[Sequence]](m, n).
  
<tip title="Tip">The parameters '''n '''and '''m '''must be atoms, that is single numbers. Otherwise, it would result in a non-rectangular array.  
+
<tip title="Tip">The parameters «n» and «m» must be atoms, that is single numbers. Otherwise, it would result in a non-rectangular array. </tip>
  
==Sequence(start, end'', stepSize, strict, dateUnit'')==
+
==Other functions==
Creates a list of numbers increasing or decreasing from '''start '''to '''end '''by increments (or decrements) of '''stepSize''', which is optional and defaults to 1. When the '''strict '''parameter is omitted or false, '''stepSize '''must be a positive number and the sequence will decrement by '''stepSize '''when '''end '''is less than '''start''', guaranteeing at least one element. When '''strict '''is specified as true, a positive '''stepSize '''increments and negative '''stepSize '''returns a decrementing sequence, possibly with zero elements if '''end '''would come before '''start'''.
+
'''Sequence(start, end, ''step'')''': Creates a list of numbers from «start» to «end» by increments of «step». See also [[Sequence]]().
  
The optional '''dateUnit '''parameter is used when creating a sequence of dates, with increments in units of Years (<code>dateUnit:'Y'</code>), Months (<code>'M'</code>), Days (<code>'D' </code>or omitted), Weekdays (<code>'WD'<7code>), Hours (<code>'h'</code>), minutes (<code>'m'</code>) or seconds (<code>'s'</code>).
+
'''Concat(i, j)''': Concatenates two arrays or lists (1-D arrays) «i» and «j» to create a new array or list with a longer index. See also [[Concat]]().
  
All parameters must be deterministic scalar numbers, not arrays.
+
'''Subset(d)''': Returns a list containing all the elements of «d»’s index for which «d»’s values are true. See also [[Subset]]().
  
You can also select this function using the '''Sequence '''option from the '''''expr '''''menu.
+
'''CopyIndex(i)''': Makes a copy of the values of index «i» so that they can be assigned to a new / separate index variable. See also [[CopyIndex]]().
  
The expression '''m .. n '''using the operator '''".." '''is equivalent to '''Sequence(m, n, 1)'''.
+
'''SortIndex(d, i)''': returns the elements of index «i», reordered so that the corresponding values in array «d» go from smallest to largest value. See also [[SortIndex]]().
  
===Library===
+
'''Unique(a, i)''': Returns a maximal subset of index «i» such that each indicated slice of array «a» along «i»  is unique. See also [[Unique]]().
Array
 
  
===Examples===
+
==See Also==
If <code>end</code> is greater than <code>start</code>, the sequence is increasing:
+
* [[Function calls and parameters]]
 
+
* [[Array-reducing functions]]
:<code>Sequence(1,5) &rarr;</code>
+
* [[Array functions]]
 
+
* [[Creating Arrays (Tables)]]
[[File:Chapter11_77.jpg]]
+
* [[Tutorial: Arrays]]
 
 
If <code>start</code> is greater than <code>end</code>, the sequence is decreasing:
 
 
 
:<code>Sequence(5, 1) &rarr; [5, 4, 3, 2, 1]</code>
 
 
 
Unless <code>strict</code> is true:
 
 
 
:<code>Sequence(5, 1, strict:true) &rarr; []</code>
 
 
 
:<code>Sequence(5, 1, -2, strict:true ) &rarr; [5, 3, 1]</code>
 
 
 
If <code>start</code> and <code>end</code> are not integers, and you omit <code>stepSize</code>, it rounds them:
 
 
 
:<code>Sequence(1.2, 4.8) &rarr; [1, 2, 3, 4, 5]</code>
 
 
 
If you specify <code>stepSize</code>, it can create non-integer values:
 
 
 
:<code>Sequence(0.5, 2.5, 0.5) &rarr; [0.5, 1, 1.5, 2, 2.5]</code>
 
 
 
==Concat(i, j)==
 
Returns a list containing the elements of index '''i '''concatenated to the elements of index '''j'''. Thus the number of items in the result is the sum of the number of items in '''i '''and the number of items in '''j'''.
 
 
 
:<code>Index Year1 := 2006 .. 2008</code>
 
 
 
:<code>Index Years2 := 2009 .. 2010</code>
 
 
 
:<code>Index YearsAll := Concat(Years1, Years2)</code>
 
 
 
:<code>YearsAll &rarr; [2006, 2007, 2008, 2009, 2010]</code>
 
 
 
==Subset(d)==
 
Returns a list containing all the elements of '''d'''’s index for which '''d'''’s values are true (that is, non- zero). '''d '''must be a one-dimensional array.
 
 
 
The optional parameter '''position:true '''can be specified to return the positions along '''d'''’s index for which '''d'''’s values are true. You would need to use positions if your index might contain duplicate values.
 
 
 
The basic use of '''Subset '''does not allow '''d '''to contain more than one dimension.
 
 
 
===When to use===
 
Use Subset() to create a new index that is a subset of an existing index.
 
 
 
===Library===
 
Array
 
 
 
===Examples===
 
:<code>Subset(YearsAll < 2010) &rarr; [2006, 2007, 2008, 2009]</code>
 
 
 
:<code>Subset(YearsAll>2007 and YearsAll<2010, position:true) &rarr; [3,4]</code>
 
 
 
==CopyIndex(i)==
 
Makes a copy of the values of index '''i''', to be assigned to a new index variable, global or local. For example, suppose you want to create a matrix of distances between a set of origins and destinations, which are each the same set of cities:
 
 
 
:<code>Index Origins</code>
 
 
 
:<code>Definition:= ['London', 'New York', 'Tokyo', 'Paris', 'Delhi'] </code>
 
 
 
:<code>Index Destinations</code>
 
 
 
:<code>Definition:= CopyIndex(Origins)</code>
 
 
 
:<code>Variable Flight_times := Table(Origins, Destinations)</code>
 
 
 
If you defined <code>Destinations</code> as equal to <code>Origins</code>, without using '''Copyindex()''', <code>Destinations</code> would be indexed by <code>Origins</code>, and the resulting table would have only one dimension index. By defining <code>Destinations</code> with '''CopyIndex()''', it becomes a separate index, so that the table has two dimensions.
 
 
 
== Sortindex(d, i) ==
 
Assuming '''d '''is an array indexed by '''i''''', '''''SortIndex() '''returns the elements of index '''i''', reordered so that the corresponding values in '''d '''would go from smallest to largest value. The result is indexed by '''i'''''. ''If '''d '''is indexed by dimensions other than '''i''', each “column” is individually sorted, with the resulting sort order being indexed by the extra dimensions. To obtain the sorted array '''d''', use this:
 
 
 
:<code>d[i=Sortindex(d, i)]</code>
 
 
 
When '''d '''is a one-dimensional array, the index parameter '''i '''is optional. When omitted, the result is an unindexed list. Use the one-parameter form only when you want an unindexed result, for example to define an index variable. The one-parameter form does array abstract when a new dimension is added to '''d'''.
 
 
 
===Library===
 
Array
 
 
 
===Examples===
 
 
 
<code>Maint_costs →</code>
 
{| class="wikitable"
 
!
 
! colspan="3" |Car_type ▶
 
|-
 
!
 
!'''VW'''
 
!'''Honda'''
 
!'''BMW'''
 
|-
 
|
 
|1950
 
|1800
 
|2210
 
|}
 
<code>SortIndex(Maint_costs, Car_type) →</code>
 
{| class="wikitable"
 
!
 
! colspan="3" |Car_type ▶
 
|-
 
!
 
!'''VW'''
 
!'''Honda'''
 
!'''BMW'''
 
|-
 
|
 
|Honda
 
|VW
 
|BMW
 
|}
 
 
 
<code>SortIndex(Maint_costs) →</code>
 
{| class="wikitable"
 
!
 
! colspan="3" |SortIndex ▶
 
|-
 
|
 
|Honda
 
|VW
 
|BMV
 
|}
 
 
 
Define <code>Sorted_cars</code> as an index node:
 
 
 
<code>INDEX Sorted_cars := Sortindex(Maint_costs)</code>
 
 
 
<code>Maint_costs[Car_type = Sorted_cars] →</code>
 
{| class="wikitable"
 
!
 
!Honda
 
!VW
 
!BMW
 
|-
 
|
 
|1800
 
|1950
 
|2210
 
|}
 
 
 
 
 
== Unique(a, i) ==
 
 
 
Returns a maximal subset of '''i '''such that each indicated slice of '''a '''along '''i '''is unique.
 
 
 
The optional parameter '''position:true '''returns the positions of element in '''i''', rather than the elements themselves. Specifying '''caseInsensitive:true '''ignores differences in upper and lower case in text values when determining if values are unique.
 
 
 
===When to use===
 
Use '''Unique() '''to remove duplicate slices from an array, or to identify a single member of each equivalence class.
 
  
===Library===
 
Array
 
  
<code>DataSet →</code>
+
<footer>Creating an index / {{PAGENAME}} / To make an edit table</footer>
{| class="wikitable"
 
!
 
!colspan="3" | Field ▶
 
|-
 
!PersonNum '''▼'''
 
!LastName
 
!FirstName
 
!Company
 
|-
 
! scope="row" |1
 
|Smith
 
|Bob
 
|Acme
 
|-
 
! scope="row" |2
 
|Jones
 
|John
 
|Acme
 
|-
 
! scope="row" |3
 
|Johnson
 
|Bob
 
|Floorworks
 
|-
 
! scope="row" |4
 
|Smith
 
|Bob
 
|Acme
 
|}
 
 
 
<code>Unique(DataSet, PersonNum) → [1, 2, 3]</code>
 
 
 
<code>Unique(DataSet[Field='Company'], PersonNum) → [1, 3]</code>
 
 
 
==See Also==
 
{| style="margin: 1em auto 1em auto;width: 100%;border:0;table-layout: fixed;" cellpadding="5"
 
|- style="text-align: center"
 
| [[Creating an index]] <- || [[Functions that create indexes]] || -> [[Defining a variable as an edit table]]
 
|}
 
<nowiki><footer>Creating an index / </nowiki>{{PAGENAME}} / Defining a variable as an edit table<nowiki></footer></nowiki></code>
 
<footer>Creating an index / {{PAGENAME}} / Defining a variable as an edit table</footer></code>
 

Latest revision as of 01:07, 1 June 2016


Using a function to create an index

It is usually easiest to define an index as a list, list of labels, or sequence. Sometimes, you need to define an index using a more general expression, as a list of expressions, a list of variables, or a function such as Subset(), Concat(), and SortIndex(). This section describes these and other functions that you can use to create indexes.

[u1, u2, u3, … um]

A simple way to define an index is specify its definition as a list of values separated by commas and surrounded by square brackets. The values can be numbers, text values, or other expressions.

Examples

[8000, 12K, 15K]
['VW', 'Honda', 'BMW']

These lists are equivalent to using the List or List of Labels options in the expr menu.

List of variables

A list of variables contains identifiers of variables in square brackets, separated by commas. Usually, the simplest way to create a list of variables is to define the variable initially as an empty list, for example:

Variable CompareVars := []

When you draw an arrow from a variable, A, into CompareVars, it will automatically add A as the next item in the list:

CompareVars := [A]

Suppose you draw arrows from B and C, the definition will become:

CompareVars := [A, B, C]

When you draw an arrow from a variable already in the list, it removes it from the list. Suppose we draw an arrow from B to CompareVars, it will become:

CompareVars := [A, C]

The result of CompareVars is an array of the values of the variables it contains, with a self index, also called CompareVars, that usually shows the titles of the variables.

If any or all the variables contain arrays, the result contains the union of the indexes of the contained variables. For example if A is an atom (not an array) and C is indexed by c, the result will be indexed by I. The slice of CompareVars for A will have the same value of A repeated for each value of A.

Self index: The result will contain an extra index, a Self index of CompareVars, comprising the list of the variables.

Clickable titles or identifiers in table: Usually these display the titles of the variables in a table or graph result. (If you select Show by Identifier from the Object menu (or press Control+y) it toggles to show the identifiers instead of titles. If you double-click a title (or identifier) in a table, it will open the Object window for that variable. The values in the self index are actually handles to the variables.

m .. n

Returns a sequence of successive integers from «m» to «n» — increasing if «n» < «m», or decreasing if «n» > «m». For example:

2003..2006 → [2003, 2004, 2005, 2006]
5 .. 1 → [5, 4, 3, 2, 1]

It is equivalent to Sequence(m, n).

Tip
The parameters «n» and «m» must be atoms, that is single numbers. Otherwise, it would result in a non-rectangular array.

Other functions

Sequence(start, end, step): Creates a list of numbers from «start» to «end» by increments of «step». See also Sequence().

Concat(i, j): Concatenates two arrays or lists (1-D arrays) «i» and «j» to create a new array or list with a longer index. See also Concat().

Subset(d): Returns a list containing all the elements of «d»’s index for which «d»’s values are true. See also Subset().

CopyIndex(i): Makes a copy of the values of index «i» so that they can be assigned to a new / separate index variable. See also CopyIndex().

SortIndex(d, i): returns the elements of index «i», reordered so that the corresponding values in array «d» go from smallest to largest value. See also SortIndex().

Unique(a, i): Returns a maximal subset of index «i» such that each indicated slice of array «a» along «i» is unique. See also Unique().

See Also


Comments


You are not allowed to post comments.