COMBINE directive

Combines or omits "slices" of a multi-way data structure (table, matrix or variate).


Options

OLDSTRUCTURE = identifier
Structure whose values are to be combined; no default i.e. this option must be set

NEWSTRUCTURE = identifier
Structure to contain the combined values; no default i.e. this option must be set


Parameters

OLDDIMENSION = factors or scalars
Dimension number or factor indicating a dimension of the OLDSTRUCTURE

NEWDIMENSION = factors or scalars
Dimension number or factor indicating the corresponding dimension of the NEWSTRUCTURE; this can be omitted if the dimensions are in numerical order, while zero settings (each in conjunction with a single OLDPOSITION) allows a slice of an old table to be mapped into a new table with fewer dimensions

OLDPOSITIONS = pointers, texts, variates or scalars
These define positions in each OLDDIMENSION: pointers are appropriate for matrices whose rows or columns are indexed by a pointer; texts are for matrices indexed by a text, variates with a textual labels vector, or tables whose OLDDIMENSION factor has labels; and variates either refer to levels of table factors or numerical labels of matrices or variates, if these are present, otherwise they give the (ordinal) number of the position. If omitted, the positions are assumed to be in (ordinal) numerical order. Margins of tables are indicated by missing values

NEWPOSITIONS = pointers, texts, variates or scalars
These define positions in each NEWDIMENSION, specified similarly to OLDPOSITIONS; these indicate where the values from the corresponding OLDDIMENSION positions are to be entered (or added to any already entered there)

WEIGHTS = variates
Define weights by which the values from each OLDDIMENSION coordinate are to be multiplied before they are entered in the NEWDIMENSION


Description

Sometimes you may wish to reclassify a table to have factors different from those that you used in its declaration. COMBINE allows you to omit or to combine levels of the classifying factors. Furthermore, if you want to take just one level of a factor, you can copy the values into a table with one less dimensions.

   You specify the original table using the OLDSTRUCTURE option, and a table to contain the reclassified values using the NEWSTRUCTURE option; if you have not already declared the new table, it will be declared implicitly. You must specify both of these options.

   You can modify several of the classifying factors at a time. You list the factors of the original table with the OLDDIMENSION parameter, and the equivalent factors of the new table with NEWDIMENSION. An alternative way of doing this is to give a dimension number, specifying the position of the factor in the classifying set of the table; for the NEWDIMENSION list, this requires that you have already declared the new table. You can even omit the list of dimensions if they would be in ascending numerical order. NEWDIMENSION can also be set to 0 (to imply no corresponding new factor), allowing you to extract a single slice of a table into a table with fewer dimensions.

   You use the OLDPOSITIONS and NEWPOSITIONS parameters to specify how this combining is to be done. These parameters specify a pair of vectors for each pair of old and new dimensions, listing positions within the old dimension and the corresponding positions to which they are mapped in the new dimension. The positions can be defined in terms of either the levels or the labels of the factor that classifies the dimension. If you omit the vector for one of the dimensions, it is assumed to contain each value once only, taken in the order in which they occur in the levels vector of the factor. You indicate a margin of the table by a missing value in a variate, or by a null string in a text. Values in the original table can be allocated to more than one place. In parallel with the vectors of positions, you can also use the WEIGHTS parameter to specify a variate of weights by which the values are multiplied before being entered into the new table.

   Although the main way in which you will use COMBINE is likely to be for tables, you can also use it on rectangular matrices and even variates. For these, the dimensions can only be numbers: number 1 refers to the rows of a matrix, and 2 to the columns; number 1 refers to the rows (or units) of a variate. The position vectors refer to the labels vectors of matrices, which can be variates, texts or pointers; or they refer to the unit labels of a variate, which can be held in either a variate or a text. If a dimension has no labels vector, you use a variate to specify its positions; then each value of the variate gives the number of a row, column or unit. You can do the same also if the labels vector is something other than a variate: that is, a text or a pointer.

 

Options: OLDSTRUCTURE, NEWSTRUCTURE.

Parameters: OLDDIMENSION, NEWDIMENSION, OLDPOSITIONS, NEWPOSITIONS, WEIGHTS.


Action with RESTRICT

Any restrictions, for example on OLDPOSITIONS or NEWPOSITIONS variates, are ignored.