RESTRICT directive

Defines a restricted set of units of vectors for subsequent statements.

No options

Parameters

Description

The RESTRICT directive defines a restriction on the units of a vector, so that future operations will involve only a subset of the units.

   The VECTOR parameter specifies the vector or vectors that are to be restricted. These can be variates, factors or texts, but all the vectors listed must be of the same length.

   The CONDITION parameter specifies a logical expression which indicates which units of the vectors are in the defined subset. For example,

VARIATE [VALUES=1,2,3,2,3,4,3,4,5] V

RESTRICT V; CONDITION=V.EQ.2

restricts the vector V to those units with the value 2. GenStat evaluates the expression to generate internally a variate of zeroes and ones, of the same length as the vectors being restricted. A zero value indicates that the corresponding unit is to be excluded. The logical expression can involve any vector of the same length ar the vector to be restricted. For example, to restrict variate V and text T to the units with levels 1 or 2 or 4 of factor F, you could use the statement

RESTRICT V,T; CONDITION=(F.LE.2).OR.(F.EQ.4)

When using a text to define a restriction, remember that you cannot use logical operators like .EQ. and .NE. Instead you should use operators .IN., .NI., .EQS. and .NES.:

TEXT [VALUES=London,Madrid,Nairobi,Ottawa,Paris,Quito,Rome]\

     City

& [VALUES=London,Madrid,Paris,Rome] Europe

RESTRICT City; CONDITION=City.IN.Europe

restricts the text City to lines 1, 2, 5 and 7 only.

   Of course, the expression may just contain a single variate of the of the same length as the vectors to be restricted. Again a zero indicates that the corresponding unit in the vector to be restricted is excluded, while any non-zero entry causes inclusion. Thus the restriction above on the text City could also be specified by

RESTRICT T; CONDITION=!(1,1,0,0,1,0,1)

The same effect can be achieved by using the EXPAND function:

RESTRICT City; CONDITION=EXPAND(!(1,2,5,7))

Another function that may be useful is RESTRICTION; this allows you to generate a variate of ones and zeros indicating the units to which a vector is currently restricted. It thus provides a very convenient way of transferring a restriction from one vector to another. For example,

RESTRICT Timezone,Distance; CONDITION=RESTRICTION(City)

restricts the vectors Timezone and Distance to the same units as those to which City is currently restricted.

   Finally, if you omit the CONDITION parameter, this removes any restrictions on the vectors are removed. For example

RESTRICT City,Timezone,Distance

removes any restrictions that have been set on City, Timezone and Distance.

   Note that if the vectors used in the CONDITION expression are themselves restricted these restrictions will remain in force during the current calculation of the condition. A danger here, therefore, is that you may accidentally end up restricting out all the elements of a vector by using RESTRICT repeatedly. The safest way to avoid this is to remove the restrictions on any vectors to be used in the CONDITION expression before you use them to restrict vectors in some different way.

   The SAVESET parameter can be used to save the numbers of the units that are in the restricted set. These are saved in a variate with one value for each unit retained by the restriction. Thus, if the example above with variate V were to become

VARIATE [VALUES=1,2,3,2,3,4,3,4,5] V

RESTRICT V; CONDITION=V.EQ.2; SAVESET=S

S would be created as a variate of length 2, with values 2 and 4.

   Not all directives take account of RESTRICT. For those that do, usually only one vector in the list of parameters has to be restricted for the directive to treat them all as being restricted in the same way. A fault is reported if any vectors in such a list are restricted in different ways.

Options: none.

Parameters: VECTOR, CONDITION, SAVESET.