Difference between revisions of "Subset"

(Examples)
Line 1: Line 1:
 
[[Category:Functions that create lists]]
 
[[Category:Functions that create lists]]
 +
[[Catergory: Array Library]]
 
[[Category:Doc Status C]] <!-- For Lumina use, do not change -->
 
[[Category:Doc Status C]] <!-- For Lumina use, do not change -->
 
   
 
   
= Subset(D'', position, I, resultIndex, warnEmpty'') =
+
== Subset(d, ''position, i, resultIndex, warnEmpty'') ==
  
Returns a list containing all the index elements of the index of one-D array for which «D» is true.
+
Returns a list containing all the index elements of the index of 1-D array for which «d» is true. The function is used to create a new index that is a subset of an existing index.
  
(new in [[Analytica 4.2]]) The optional «position» parameter specifies whether the index position or index element should be returned. When omitted or when <code>position:false</code> is specified, the index element is returned.  <code>Position:true</code> returns the index position of true items.
+
The parameter to [[Subset]] must be one-dimensional; a scalar parameter or a parameter with two or more dimensions results in an error.
  
(new in [[Analytica 4.2]]) The optional index parameters «I» and «resultIndex» allow [[Subset]] to be used in a manner that fully array abstractions.  Normally, without these, «D» must be one-dimensional and will not evaluate or array abstract otherwise (since an unindexed list is returned).  «I» specifies which dimension to operate over, and «resultIndex» specifies an index to dimension the result by.  When these are used in conjunction, the result is an array with fully explicit indexes.  When you are using [[Subset]] to define an index, you should not be using «resultIndex», «D» should be 1-dimensional, and «I» is superfluous.  When you are using it in calculation that is potentially array-based, then you should be using «I» and «resultIndex». 
+
[[Subset]] in its standard one-parameter usage does not array abstract because it returns an unindexed list.  
 
+
(new in [[Analytica 4.2]]) The optional «warnEmpty» parameter controls whether [[Subset]] issues a warning when no true elements are found in «D».  In Analytica 4.2 and earlier this defaulted to True, in Analytica 4.3 and later it defaults to false.
+
 
+
= When to use =
+
 
+
Use [[Subset]] to create a new index that is a subset of an existing index.
+
 
+
= Variations =
+
  
 
When there is the possibility of having [[Null]] values in your array, you should consider whether you want those elements to be retained.  The following two uses respectively retain or remove [[Null]] elements:
 
When there is the possibility of having [[Null]] values in your array, you should consider whether you want those elements to be retained.  The following two uses respectively retain or remove [[Null]] elements:
 
  [[Subset]](Test [[Or]] Test=[[Null]])
 
  [[Subset]](Test [[Or]] Test=[[Null]])
 
  [[Subset]](Test [[And]] Test<>[[Null]])
 
  [[Subset]](Test [[And]] Test<>[[Null]])
Without the explicit test, [[Null]] elements are removed in release 4.2 and later, but retained prior to 4.2.
 
  
(''new to release 4.2'') The position (rather than the index value) of each non-zero element can be obtained using:
+
Without the explicit test, [[Null]] elements are removed.
[[Subset]](D,position:true)
+
See [[Associative vs. Positional Indexing]].
+
  
= Examples =
+
== Examples ==
 +
Index Years := 2005 .. 2009
 +
Subset(Years < 2008) &rarr; [2005, 2006, 2007]
 +
Subset(Years < 2008, position:true) &rarr; [1,2] 
 +
Subset(YearsAll>2005 and YearsAll<2008, position:true) &rarr; [2,3]
  
[[Subset]](Years < 1987) &rarr; [1985,1986]
+
==Optional parameters==
 +
===Position===
 +
The optional «position» parameter specifies whether the index element or the index position should be returned (see [[Associative vs. Positional Indexing]]).  When «position» is omitted or when <code>position: false</code> is specified, the index element is returned.  <code>'''position: true'''</code> returns the positions of each non-zero element along «d»’s index for which «d»’s values are true:
  
  [[Subset]](Years < 1987, position:true) &rarr; [1,2]                { ''requires 4.2'' }
+
  [[Subset]](D,position:true)  
  
= Array Considerations =
+
The need to specify positions arises when your index contains duplicate values, or when the input to the function is an array with an implicit index.
  
== Implicit indexes ==
+
In general, the one-dimensional array passed to [[Subset]] needs to be explicitly indexed because the index elements corresponding to true elements is returned.  Thus, an implicitly indexed array (e.g., a list) also results in an error.  Theoretically [[Subset]] could return a result in the implicitly indexed case, but it would be misleading since it would just be returning all the true values, for example:
 
+
The one-dimensional array passed to [[Subset]] needs to be explicitly indexed, since the index elements corresponding to true elements is returned.  Thus, an implicitly indexed array (e.g., a list) also results in an error.  Theoretically [[Subset]] could return a result in the implicitly indexed case, but it would be misleading since it would just be returning all the true values, for example:
+
 
  [[Subset]]( 1997..2008 > 2005 ) &rarr;? [1,1,1]      { Hypothetical only -- error reported }
 
  [[Subset]]( 1997..2008 > 2005 ) &rarr;? [1,1,1]      { Hypothetical only -- error reported }
 
In a case like this, you should use a local index, e.g.:
 
In a case like this, you should use a local index, e.g.:
 
  [[Index..Do|Index]] I := 1997..2008 do [[Subset]](I>2005) &rarr; [2006,2007,2008]
 
  [[Index..Do|Index]] I := 1997..2008 do [[Subset]](I>2005) &rarr; [2006,2007,2008]
  
However, if you use the ''position:true'' parameter setting, then you can pass an array with an implicit index, since element positions (and not index values) are returned.  Hence, the following does work (in ''Analytica 4.2 or better''):
+
However, if you use the ''position:true'' parameter setting, then you can pass an array with an implicit index, since element positions (and not index values) are returned:
 
  [[Subset]]( 1997..2008 > 2005, position:true ) &rarr; [10,11,12]
 
  [[Subset]]( 1997..2008 > 2005, position:true ) &rarr; [10,11,12]
  
== Array abstraction ==
 
  
An error will result if the parameter to [[Subset]] is not one-dimensional.  [[Subset]] in its standard one-parameter usage does not array abstractA scalar parameter or a parameter with two or more dimensions results in an error.
+
===I and ===
 +
The basic use of '''Subset '''does not allow '''d '''to contain more than one dimension.   
 +
The optional index parameter «i» together with «resultIndex» allow [[Subset]] to be used in a manner that fully array-abstracts.   
  
[[What's new in Analytica 4.2?|Analytica 4.2]] provides a variation of [[Subset]] that does array abstract.  If you have a two- (or more-) dimensional array, you'll need to identify one of those dimensions as the one that the subset is being taken over.  For each slice along the other dimensions, a [[Subset]] can then be separately computed, and each of those subsets may have a different number of elements.  To express the result, you must provide a «resultIndex» that will contain the index result.  For the individual subsets that contain more elements than the result index, only the first [[Size]](«resultIndex») members of the subset are retained.  For those subsets that are smaller than the «resultIndex», the remaining entries in the result are padded with [[«null»]] values.
+
Normally, without these, «d» must be one-dimensional and will not evaluate or array abstract otherwise (since an unindexed list is returned).  
 +
«i» specifies which dimension to operate over, and «resultIndex» specifies an index to dimension the result by. When these are used in conjunction, the result is an array with fully explicit indexes.  When you are using [[Subset]] to define an index, you should not be using «resultIndex», «d» should be 1-dimensional, and «i» is superfluous.  When you are using it in calculation that is potentially array-based, then you should be using «i» and «resultIndex». 
 +
 
 +
===ResultIndex===
 +
The basic use of '''Subset '''does not allow '''d '''to contain more than one dimension.  If you have a two- (or more-) dimensional array, you'll need to identify one of those dimensions as the one that the subset is being taken over.  For each slice along the other dimensions, a [[Subset]] can then be separately computed, and each of those subsets may have a different number of elements.   
 +
 
 +
To express the result, you must provide a «resultIndex» that will contain the index result.  For the individual subsets that contain more elements than the result index, only the first [[Size]](«resultIndex») members of the subset are retained.  For those subsets that are smaller than the «resultIndex», the remaining entries in the result are padded with [[«null»]] values.
  
 
Example:
 
Example:
:{| border="1"
+
:{| class="wikitable"
 
! rowspan=2 colspan=2 | A
 
! rowspan=2 colspan=2 | A
 
! colspan=5 align=center | I
 
! colspan=5 align=center | I
Line 71: Line 72:
 
:Index K := [1,2]
 
:Index K := [1,2]
  
:{|border="0" style="text-align:center"
+
:{|class="wikitable" style="text-align:center"
 
| [[Subset]](A>50,I:I,ResultIndex:K) &rarr;
 
| [[Subset]](A>50,I:I,ResultIndex:K) &rarr;
 
|
 
|
Line 95: Line 96:
  
 
For [[Subset]] to reliably array abstract, both indexes must be specified, although it is fine to use the same index for both.  Since they are optional, and not the second and third parameter, they should be specified using the named calling convention as illustrated above.
 
For [[Subset]] to reliably array abstract, both indexes must be specified, although it is fine to use the same index for both.  Since they are optional, and not the second and third parameter, they should be specified using the named calling convention as illustrated above.
 +
 +
===WarnEmpty===
 +
The optional «warnEmpty» parameter controls whether [[Subset]] issues a warning when no true elements are found in «d».  The default value for «warnEmpty» is false.
 +
 +
 +
==History==
 +
* Without the explicit test, [[Null]] elements are removed in release 4.2 and later, but retained prior to 4.2.
 +
* The optional parameters «position», index «I», «resultIndex» and «warnEmpty» were introduced in Analytica 4.2 and do not work in earlier versions.
 +
* In Analytica 4.2 and earlier, «warnEmpty» defaulted to True, in Analytica 4.3 and later it defaults to false.
 +
 +
  
 
= See Also =
 
= See Also =

Revision as of 01:36, 20 November 2015

Catergory: Array Library

Subset(d, position, i, resultIndex, warnEmpty)

Returns a list containing all the index elements of the index of 1-D array for which «d» is true. The function is used to create a new index that is a subset of an existing index.

The parameter to Subset must be one-dimensional; a scalar parameter or a parameter with two or more dimensions results in an error.

Subset in its standard one-parameter usage does not array abstract because it returns an unindexed list.

When there is the possibility of having Null values in your array, you should consider whether you want those elements to be retained. The following two uses respectively retain or remove Null elements:

Subset(Test Or Test=Null)
Subset(Test And Test<>Null)

Without the explicit test, Null elements are removed.

Examples

Index Years := 2005 .. 2009
Subset(Years < 2008) → [2005, 2006, 2007]
Subset(Years < 2008, position:true) → [1,2]  
Subset(YearsAll>2005 and YearsAll<2008, position:true) → [2,3]

Optional parameters

Position

The optional «position» parameter specifies whether the index element or the index position should be returned (see Associative vs. Positional Indexing). When «position» is omitted or when position: false is specified, the index element is returned. position: true returns the positions of each non-zero element along «d»’s index for which «d»’s values are true:

Subset(D,position:true) 

The need to specify positions arises when your index contains duplicate values, or when the input to the function is an array with an implicit index.

In general, the one-dimensional array passed to Subset needs to be explicitly indexed because the index elements corresponding to true elements is returned. Thus, an implicitly indexed array (e.g., a list) also results in an error. Theoretically Subset could return a result in the implicitly indexed case, but it would be misleading since it would just be returning all the true values, for example:

Subset( 1997..2008 > 2005 ) →? [1,1,1]      { Hypothetical only -- error reported }

In a case like this, you should use a local index, e.g.:

Index I := 1997..2008 do Subset(I>2005) → [2006,2007,2008]

However, if you use the position:true parameter setting, then you can pass an array with an implicit index, since element positions (and not index values) are returned:

Subset( 1997..2008 > 2005, position:true ) → [10,11,12]


I and

The basic use of Subset does not allow d to contain more than one dimension. The optional index parameter «i» together with «resultIndex» allow Subset to be used in a manner that fully array-abstracts.

Normally, without these, «d» must be one-dimensional and will not evaluate or array abstract otherwise (since an unindexed list is returned).

«i» specifies which dimension to operate over, and «resultIndex» specifies an index to dimension the result by.  When these are used in conjunction, the result is an array with fully explicit indexes.  When you are using Subset to define an index, you should not be using «resultIndex», «d» should be 1-dimensional, and «i» is superfluous.  When you are using it in calculation that is potentially array-based, then you should be using «i» and «resultIndex».  

ResultIndex

The basic use of Subset does not allow d to contain more than one dimension. If you have a two- (or more-) dimensional array, you'll need to identify one of those dimensions as the one that the subset is being taken over. For each slice along the other dimensions, a Subset can then be separately computed, and each of those subsets may have a different number of elements.

To express the result, you must provide a «resultIndex» that will contain the index result. For the individual subsets that contain more elements than the result index, only the first Size(«resultIndex») members of the subset are retained. For those subsets that are smaller than the «resultIndex», the remaining entries in the result are padded with «null» values.

Example:

A I
1 2 3 4 5
J 1 73 23 19 54 12
2 11 1 98 76 52
3 22 33 49 87 22
Index K := [1,2]
Subset(A>50,I:I,ResultIndex:K) →
  K
1 2
J 1 1 4
2 3 4
3 4 «null»

Notice that in the J=1 for, there are exactly two elements satisfying the condition, [1,4]. In the second row there are three elements, [3,4,5], but since our result index K has only two elements, we retain only the first two. In the third row of A, there is only one cell satisfying the condition, hence the second cell in the result is padded with «null».

For Subset to reliably array abstract, both indexes must be specified, although it is fine to use the same index for both. Since they are optional, and not the second and third parameter, they should be specified using the named calling convention as illustrated above.

WarnEmpty

The optional «warnEmpty» parameter controls whether Subset issues a warning when no true elements are found in «d». The default value for «warnEmpty» is false.


History

  • Without the explicit test, Null elements are removed in release 4.2 and later, but retained prior to 4.2.
  • The optional parameters «position», index «I», «resultIndex» and «warnEmpty» were introduced in Analytica 4.2 and do not work in earlier versions.
  • In Analytica 4.2 and earlier, «warnEmpty» defaulted to True, in Analytica 4.3 and later it defaults to false.


See Also

Comments


You are not allowed to post comments.