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.

(new in Analytica 4.2) The optional «position» parameter specifies whether the index position or index element should be returned. When omitted or when position:false is specified, the index element is returned. Position:true returns the index position of true items.

(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».

(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:

Subset(Test Or 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:

Subset(D,position:true)

See Associative vs. Positional Indexing.

Examples

Subset(Years < 1987) → [1985,1986]

Subset(Years < 1987, position:true) → [1,2]                 { requires 4.2 }

Array Considerations

Implicit indexes

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 ) →? [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. Hence, the following does work (in Analytica 4.2 or better):

Subset( 1997..2008 > 2005, position:true ) → [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 abstract. A scalar parameter or a parameter with two or more dimensions results in an error.

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.

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.

Subset

Contents