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
A		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.

Subset

Contents