Subset

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

If «d» is an Index or a 1D array index by «i», Subset(d) returns a list of all the elements of the index for which «d» is true (1). The function is used to create a new index that is a subset of an existing index.

If «d» is not an Index or 1D array -- if it's scalar or has more than 1D -- it returns 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.

Example

Let:

Index Years := 2005..2009

Then:

Subset(Years < 2008) →

[2005, 2006, 2007]

Subset(Years > 2005 and Years < 2008) →

[2006, 2007]

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 resultIndex

The basic use of Subset does not allow d to contain more than one dimension, and will not evaluate or array abstract otherwise (since an unindexed list is returned). If you have a two- (or more-) dimensional array or are using Subset in calculations that are potentially array-based, 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.

The optional index parameter «i» together with «resultIndex» allow Subset to be used in a manner that fully array abstracts: «i» specifies which dimension to operate over, and «resultIndex» specifies the index of the result. For the individual subsets that contain more elements than the «resultIndex», 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.

When «i» and «resultIndex» are used in conjunction, the result is an array with fully explicit indexes.

When you use Subset to define an index, you should not use «resultIndex», «d» should be 1-dimensional, so «i» is superfluous.

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, i.e. it gives no warning.

Details & More Examples

Example 1

Let:

Index Years := 2005..2009

Then:

Subset(Years < 2008, position:true) →

[1, 2]

Subset(Years > 2005 and Years < 2008, position: true) →

[2, 3]

Example 2

Let:

Variable A :=

	I ▶
J ▼	1	2	3	4	5
1	73	23	19	54	12
2	11	1	98	76	52
3	22	33	49	87	22

Index K := [1, 2]

Then:

Subset(A > 50, i: I, resultIndex: K) →

	K ▶
J ▼	1	2
1	1	4
2	3	4
3	4	«null»

Notice that in the first row, J = 1</coed>, two elements, K=[1, 4], satisfy the condition, A > 50. In the second row there are three elements, K= [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, you should specify both indexes, although it is fine to use the same index for both. Since they are optional, use the the named calling convention as illustrated above.

See Also

• Abstracted Subset.ana example model
• Associative vs. Positional Indexing
• SubIndex
• Subscript
• Index..Do