Transfers data between structures of different sizes or types (but the same modes i.e. numerical or text) or where transfer is not from single structure to single structure.
Options
OLDFORMAT = variate |
Format for values of OLDSTRUCTURES; within the variate, a positive value n means take n values, –n means skip n values and a missing value means skip to the next structure; default * i.e. take all the values in turn |
|---|---|
NEWFORMAT = variate |
Format for values of NEWSTRUCTURES; within the variate, a positive value n means fill the next n positions, –n means skip n positions and a missing value means skip to the next structure; default * i.e. fill all the positions in turn |
FREPRESENTATION = string token |
How to interpret factor values (labels, levels, ordinals); default leve |
Parameters
OLDSTRUCTURES = identifiers |
Structures whose values are to be transferred; if values of several structures are to be transferred to one item in the NEWSTRUCTURES list, they must be placed in a pointer |
|---|---|
NEWSTRUCTURES = identifiers |
Structures to take each set of transferred values; if several structures are to receive values from one item in the OLDSTRUCTURES list, they must be placed in a pointer |
Description
The EQUATE directive copies values from one set of data structures to another. For example, you may wish to copy the values from a one-way table into a variate, or from a matrix into a set of variates (one variate for each row, or for each column), or the other way round, from variates into a matrix. Alternatively, you may want to append values from several data structures into a single one. The only constraint is that the structures in the respective sets must all contain the same kind of values.
The general idea with EQUATE is that the values in the structures in the OLDSTRUCTURES list are copied into the structures in the NEWSTRUCTURES list. Each item in OLDSTRUCTURES list specifies a single data structure, or a single set of data structures, containing the values to be transferred. A single structure can be a factor, or a text, or any one of the structures that contain numbers (scalar, variate, rectangular matrix, diagonal matrix, symmetric matrix or table). If you want to give a set of structures you must put them into a pointer. As already mentioned, all the structures in the set must contain the same kind of values: that is, they must all be texts, or all factors, or must all contain numbers (but they need not all be the same kinds of numerical structure – they could, for example, be a mixture of variates and matrices).
The corresponding entry in the NEWSTRUCTURE list indicates where the transferred data are to be placed. It is either a single structure or a pointer to a set of structures; the structures must be of a type suitable to store the values to be transferred.
Except with a format Genstat ignores where each structure within a set from the OLDSTRUCTURES list ends and another one begins: that is, it treats the set as being a concatenated list of values. Similarly, it treats the structures in each NEWSTRUCTURES set as an unstructured list of positions that are to receive values. The old values are repeated as often as is necessary to traverse all the new positions.
You can use the OLDFORMAT and NEWFORMAT options to control how the old values and new positions are traversed. The setting for each of these is a variate whose values are interpreted as follows:
(a) a positive integer n means take the next n values (OLDFORMAT) or fill the next n positions (NEWFORMAT);
(b) a negative integer –n means skip the next n values or positions;
(c) a missing value * means skip to the end of the structure.
As usual, Genstat recycles when it runs out of values. That is, if the contents of one of the variates is exhausted before all the NEWSTRUCTURES positions have either been filled or skipped, then that variate is repeated.
If you are transferring values between factors, Genstat will check that each value to be transferred is valid for the factor in the NEWSTRUCTURES list. By default, Genstat will try to match the values using the levels of the factors, but you can set option FREPRESENTATION=labels to match by their labels, or FREPRESENTATION=ordinals to match them merely according to the ordinal position in the levels vector of each factor.
The values of factors that have labels can be copied into texts. In addition, values of texts can be copied into factors, provided all the strings are valid labels for the factor concerned.
Factor values can also be copied into variates; the FREPRESENTATION option controls whether Genstat uses the levels or the ordinal values.
Options: OLDFORMAT, NEWFORMAT, FREPRESENTATION.
Parameters: OLDSTRUCTURES, NEWSTRUCTURES.
Action with RESTRICT
Any restrictions on vectors in an EQUATE statement are ignored.
See also
Directive: CALCULATE.
Procedures: APPEND, STACK, UNSTACK, SUBSET, VEQUATE.
Commands for: Calculations and manipulation.
Example
" Example 1:4-3-1a " OPEN '%GENDIR%/Examples/GuidePart1/EMPLOYEE.DAT'; CHANNEL=2; FILE=input " Read values for the first 6 employees, in series, into Name1, Grade1 and Hours1." TEXT [NVALUES=6] Name1 FACTOR [NVALUES=6; LEVELS=3] Grade1 VARIATE [NVALUES=6] Hours1 READ [PRINT=data,errors; CHANNEL=2; SERIAL=yes] Name1,Grade1,Hours1 " Read values for the final 4 employees, in series, into Name2, Grade2 and Hours2." TEXT [NVALUES=4] Name2 FACTOR [NVALUES=4; LEVELS=3] Grade2 VARIATE [NVALUES=4] Hours2 READ [PRINT=data,errors; CHANNEL=2; SERIAL=yes] Name2,Grade2,Hours2 " Use EQUATE to put information about all the employees into single vectors Name, Grade and Hours." TEXT [NVALUES=10] Name FACTOR [NVALUES=10; LEVELS=3] Grade VARIATE [NVALUES=10] Hours EQUATE !P(Name1,Name2),!P(Grade1,Grade2),!P(Hours1,Hours2);\ NEWSTRUCTURES=Name,Grade,Hours PRINT Name,Grade,Hours CLOSE 2; FILE=input