Forms a classification set for each term in a formula, breaks a formula up into separate formulae (one for each term), and applies a limit to the number of factors and variates in the terms of a formula.

### Options

`FACTORIAL` = scalar |
Limit on the number of factors and variates in each term; default `*` i.e. no limit |
---|---|

`NTERMS` = scalar |
Outputs the number of terms in the formula |

`CLASSIFICATION` = pointer |
Saves a list of all the factors and variates in the `TERMS` formula |

`OUTFORMULA` = formula structure |
Identifier of a formula to store a new formula, omitting terms with too many factors and variates |

`INCLUDEFUNCTIONS` = string token |
Whether or not to include functions in the formulae saved by the `OUTFORMULA` option or the `OUTTERMS` parameter (`yes` , `no` ); default `no` |

`REORDER` = string token |
Whether to reorder the terms in the model, so that any term that is marginal to an earlier term will be moved to come before it, rather than being deleted (`yes` , `no` ); default `no` |

`DROPTERMS` = string token |
Whether to include only terms that can be dropped individually from the formula (`yes` , `no` ); default `no` |

`CHECKFUNCTIONS` = scalar |
Indicator, set to one if the `TERMS` formula contains any functions, and zero if it contains none |

`FUNCTIONDEFINITIONS` = pointer |
Saves details of the functions defined for each factor and variate in the `TERMS` formula |

### Parameters

`TERMS` = formula |
Formula from which the classification sets, individual model terms and so on are to be formed |
---|---|

`CLASSIFICATION` = pointers |
Identifiers giving a pointer to store the factors and variates composing each model term of the `TERMS` formula |

`OUTTERMS` = formula structures |
Identifiers giving a formula to store each individual term of the `TERMS` formula |

### Description

If you are writing procedures, for example for statistical analyses, the model to be fitted will often be specified by a Genstat formula structure. Unless the algorithm within the procedure merely involves straightforward use of one of Genstat’s statistical directives, you may wish to know more about the formula: how many model terms does it contain, which factors do they involve, and so on. The `FCLASSIFICATION`

directive is designed to provide the answers to these questions. The formula is specified using the `TERMS`

parameter.

When Genstat uses a formula in a statistical analysis, it is expanded into a series of model terms, linked by the operator `+`

. `FCLASSIFICATION`

lets you save this expanded form, in another formula, using the `OUTFORMULA`

option.

You can use the `FACTORIAL`

option to apply a limit to the number of factors and variates in the resulting terms, similarly to the `FACTORIAL`

option in the `ANOVA`

, `FIT`

or `REML`

directives. The number of terms in the formula can be saved (in a scalar) using the `NTERMS`

option, and a list of the factors and variates that occur in the formula can be saved (in a pointer) using the `CLASSIFICATION`

option.

The other parameters allow you to save information about the individual model terms in the formula. The identifiers in the lists that they specify are taken in parallel with the model terms in the expanded form of the formula. For each model term, the corresponding identifier in the list for the `CLASSIFICATION`

parameter is defined as a pointer storing the factors that occur in the term; and the identifier in the `OUTTERMS`

list is defined as a formula containing just that model term.

By default any functions such as `POL`

or `REG`

are omitted from the formulae saved by `OUTFORMULA`

or `OUTTERMS`

, but these will be included if you set option `INCLUDEFUNCTIONS=yes`

. The `CHECKFUNCTIONS`

option lets you save a scalar containing one if the `TERMS`

formula contains any functions, and zero if it does not.

The `FUNCTIONDEFINITIONS`

option lets you obtain details of the functions. This saves a pointer which contains a pointer for each factor and variate in the formula (in the same order as in the `CLASSIFICATION`

pointer). If the factor or variate has no function, its pointer contains just a text with a single missing value (`''`

). Otherwise the first element of the pointer is a text containing the name of the function (either `'POL'`

, `'POLND'`

, `'REG'`

, `'REGND'`

, `'COMP'`

, `'SSPLINE'`

or `'LOESS'`

). It then contains elements to store the second and subsequent arguments of the function (if any).

Model terms involving several factors are regarded by Genstat as representing all the joint effects of these factors that are not removed by earlier terms in the formula. So, in the formula

`A + B + A.B`

`A.B`

is the interaction of factors A and B, as both main effects occur earlier in the formula. Alternatively, in the formula

`A.B + A + B`

`A.B`

still represents all the joint effects of factors `A`

and `B`

, and the later terms `A`

and `B`

are redundant as they are now “contained” in `A.B`

. Thus `FCLASSIFICATION`

usually deletes any term in the model that is contained in an earlier term. However, if you set option `REORDER=yes`

, the model is reordered instead, so that each term comes before any term that would contain it. So the model would again be

`A + B + A.B`

The rules about terms that contain other terms are also relevant when you are dropping terms from a model, for example in a regression analysis. You cannot drop a term, for example using the `DROP`

directive, until all the terms that contain it have been dropped. To simplify the process, if you set option `DROPTERMS=yes`

, the formulae saved by `OUTFORMULA`

or `OUTTERMS`

will contain only terms that are not contained in any other terms (i.e. only the terms that can be dropped).

Options: `FACTORIAL`

, `NTERMS`

, `CLASSIFICATION`

, `OUTFORMULA`

, `INCLUDEFUNCTIONS`

, `REORDER`

, `DROPTERMS`

, `CHECKFUNCTIONS`

, `FUNCTIONDEFINITIONS`

.

Parameters: `TERMS`

, `CLASSIFICATION`

, `OUTTERMS`

.

### See also

Directives: `FORMULA`

, `FARGUMENTS`

, `REFORMULATE`

, `SETCALCULATE`

, `SETRELATE`

, `SET2FORMULA`

.

Commands for: Calculations and manipulation.

### Example

" Example FCLA-1: Examples of the FCLASSIFICATION directive FCLASSIFICATION expands a formula and allows the following to be saved: 1) the expanded version, 2) any individual term of the formula, 3) the sets of variates and factors classifying the individual terms." FACTOR A,B,C FORMULA [VALUE=A*B] AstarB " expand AstarB " FCLASSIFICATION [OUTFORMULA=Expanded] #AstarB PRINT AstarB, Expanded " expand A*B*C imposing a limit of 2 on the number of factors or variates in the resulting terms (default for FACTORIAL is 3) " FCLASSIFICATION [FACTORIAL=2; OUTFORMULA=Expanded] A*B*C PRINT Expanded " calculate the number of terms N in the expanded formula, then save the terms in separate formulae T[1...N] and their classification sets in pointers S[1...N] " FCLASSIFICATION [FACTORIAL=2; NTERMS=N] A*B*C & A*B*C; CLASSIFICATION=S[1...N]; OUTTERMS=T[1...N] FOR Si=S[1...N]; Ti=T[1...N] PRINT Si,Ti ENDFOR