A scalar data structure stores a single number. The IDENTIFIER parameter lists the identifiers of the scalars that are to be declared.

Values can be assigned to the scalars by either the VALUE option or the VALUE parameter. The option defines a common value for all the structures in the declaration, while the parameter allows them each to be given a different value. If both the option and the parameter are specified, the parameter takes precedence. However, if you do not define a value explicitly for a scalar, Genstat gives it a missing value.

The DECIMALS parameter allows you to define a number of decimal places to be used by default when each symmetric matrix is printed. You can associate a text of extra annotation with each scalar using the EXTRA parameter. The MINIMUM and MAXIMUM parameters allow you to define lower and upper limits on the values in each symmetric matrix. Genstat then prints warnings if any values outside that range are allocated to the scalar.

If the MODIFY option is set to yes any existing attributes and values of the scalars are retained; otherwise these are lost.

TREATMENTSTRUCTURE = identifier

The default of SET is to do nothing: that is, each option by default leaves the corresponding attribute of the environment unchanged. Of course you have to start somewhere, so an initial environment is defined at the start of any Genstat program; the corresponding initial settings of the options of SET, known as the initial defaults, are described below.

The INPRINT option controls what parts of a Genstat job supplied in the current input channel are recorded in the current output file; the input channel can be either an input file or the keyboard. Three parts are distinguished: explicit statements; statements, or parts of statements, that you have supplied in macros using either the ## notation or the EXECUTE directive; and statements that you have supplied in procedures. The initial default is to record nothing if the output is to the screen, otherwise to record the statements. This aspect of the environment can be modified also by the PRINT option of the INPUT directive and by the INPRINT option of JOB.

The OUTPRINT option controls how the output from many Genstat directives starts: the output can be preceded by a move to the top of a new page, or by a line of dots beginning with the line number of the statement producing the analysis, or by both. If output is directly to the screen, no new pages are given. The initial default is to give neither if output is to the screen, otherwise to give a new page and a line of dots. Alternatively, this aspect can be modified by the PRINT option of the OUTPUT directive or by the OUTPRINT option of JOB. The lines of dots are produced by the directives for regression analysis, analysis of designed experiments, REML analysis, multivariate analysis, and time series; also from the FLRV, FSSPM, and SVD directives. If you give an analysis statement within a FOR loop, the line number preceding the line of dots is that of the ENDFOR statement rather than of the analysis statement. New pages are produced with any of the above, and with the GRAPH, HISTOGRAM, and CONTOUR directives.

The DIAGNOSTIC option lets you control the level of diagnostic reporting. You might want to do this within a procedure, to prevent faults being reported to a user who does not need to know in detail what is going on inside the procedure. By initial default, all diagnostics - messages, warnings, and faults - are printed. You can switch off messages by setting DIAGNOSTIC=warning, or switch off both messages and warnings by setting DIAGNOSTIC=fault. If you set DIAGNOSTIC=*, then no diagnostics will appear. The extra setting gives you extra information, in the form of a dump of the current state of the job; but this is likely to be useful only for developers of Genstat. Printing of diagnostics can also be controlled by the DIAGNOSTIC option of JOB.

The ERRORS option controls what Genstat does when many faults happen within a single job while in batch mode. By initial default, up to five errors per job are reported, and successive faults will not generate diagnostic messages. This ensures, for example, that input intended to be read by a READ statement will not generate many lines of diagnostics if execution halts because of a fault before the READ statement. Note, however, that this option does not affect the detailed error messages printed by the READ directive itself: these are controlled separately by the corresponding ERRORS option of READ. In interactive mode, the count of errors is restarted after each successful statement is issued, though the option is unlikely to be useful in this mode.

The FAULT option is provided primarily to allow procedure writers to modify the internal record that is kept of the most recent fault indicator. Setting FAULT=* clears the record; you can then use the GET directive to ascertain whether a fault has occurred since the record was cleared. You can also set the fault indicator to a particular diagnostic, for example

A subsequent DISPLAY statement will then report the chosen fault in the standard way. The fault indicator is automatically cleared at the start of each job.

The PAUSE option lets you specify how many lines of output are produced at a time; you might, for example, want to read the output on a terminal screen before more output replaces it. Obviously this is relevant only in interactive mode, and may not be needed in the implementations of Genstat that provide a scrollable output window. By initial default, all output is sent to the current output channel as soon as it is available. Some computers can store the output, irrespective of whether Genstat itself has a scrollable window, and let you scroll forward and back to read it at leisure: others just provide keys to freeze the output while you are reading a section, and then to continue to the next segment of output. If you set PAUSE=n, then after every n lines of output Genstat gives a prompt:

After you have read the displayed section of output, you can press the <RETURN> key to get the next n lines. The counting of lines is restarted each time you give a statement from the keyboard: it is not restarted between separate statements in a macro, procedure, or auxiliary input channel. If you have specified that Genstat should echo input lines, these are included among the n. Once all the output has been displayed, Genstat prompts for further statements.

The PROMPT option specifies the characters used to prompt for interactive input. The initial default is the greater-than character followed by a space "> ". The prompt can also be modified by the PROMPT option of JOB. Other prompts are used by READ, EDIT, HELP, and QUESTION, and these cannot be altered.

The NEWLINE option allows you to cancel the initial default whereby a newline (<RETURN>) is a terminator both for strings within a string list (1.6.2) and for a statement (1.8). Thus, for example, if you specify

you need no longer use a backslash (\) to continue a statement onto a new line, since <RETURN> is no longer interpreted as the end of a statement. But you will then have to terminate each statement explicitly with a colon.

The CASE option specifies whether upper-case and lower-case letters are to be treated as the same in identifiers. The initial default is that upper and lower case are not the same; thus, an identifier X is distinct from an identifier x. If CASE is set to ignored, then in later statements, both x and X are treated as the same identifier, X. Thus the structure with identifier x cannot be referenced, unless CASE is later reset to significant.

The RUN option controls whether Genstat interprets the program as being in batch or in interactive mode; this assumed mode is independent of whether the program really is being run in batch or interactively. Initially, a program is taken to be in interactive mode only if the first input channel and the first output channel are both connected to a terminal. The setting of the assumed mode has two effects - on recovery from faults, and on how HELP and EDIT operate.

The UNITS option provides another way of setting the units structure in addition to the UNITS directive. The setting can be the identifier of a variate or text structure; this will become the default labelling structure of other variates, texts, or factors with the same length, in those directives that use such labels. The setting can also be a scalar to specify the default number of units. The setting of the UNITS option is lost at the end of each job within a program.

The last eight options of the SET directive specify special save structures for graphical and analysis directives. You can set the options only to an identifier that you have previously established by the SPECIAL option of the GET directive or by the SAVE options of the various analysis directives themselves. For example, if two sets of regression analyses are in progress in one job, the SET directive can be used to switch between them:

This program fits the regression of Y1 on X1, using save structure S1, then the regression of Y2 on X1 with save structure S2. Finally, the regression of Y1 on X1 and X2 is fitted, because the current regression save structure is changed to S1 before the last FIT statement.

The SETOPTION directive changes the default settings of options of a directive or procedure for the remainder of the current job. If you use this directive in your start-up file you can make the changed default apply in all your use of Genstat.

To achieve any effect, the option and both parameters of the directive must be set. The DIRECTIVE option specifies the name of the directive or procedure that is affected, and the NAME parameter indicates the option whose default is to be changed. The settings are strings, so need not be quoted because all directive and procedure names are valid as unquoted strings. The DEFAULT parameter is then set to a data structure to provide the new default that you want to be assumed. For example, the following statement modifies the PRINT option of the FIT directive.

The usual default of the PRINT option in FIT is to print a statement of the model, a summary of the analysis, and the parameter estimates: this corresponds to the setting PRINT=model,summary,estimates. This SETOPTION statement therefore redefines the default so that any subsequent FIT statement in the job will report only the residual deviance unless you explicitly set the PRINT option.

The defined mode of the PRINT option of FIT is "strings" (8.1.2). However, the DEFAULT parameter of SETOPTION expects a data structure (to allow for all the other modes that might occur), and so it must be set to a text structure containing the string (or strings) that you want to be the default. Similarly, if the defined mode of the option is "numbers", "expression", or "formula", you must supply a variate, an expression structure, or a formula structure containing the new default. If the defined mode is "identifier", the setting of DEFAULT is simply an identifier, which must be of the required type if this is specified in the definition of the directive or procedure.

To reset the PRINT option of FIT back to its usual default, you would need to give the statement

The SETOPTION directive can also be used to change defaults of any procedure: this may be a procedure in the standard Procedure Library, the Site Library, or a personal library that you have already opened in the current program, or it may be a procedure that you have defined explicitly in the job.

The SETPARAMETER directive changes the default settings of parameters of a directive or procedure for the remainder of the current job. If you use this directive in your start-up file you can make the changed default apply in all your use of Genstat. The option and parameters are used in exactly the same way as by the SETOPTION directive to change the defaults of options of directives and procedures. For full details see the description of SETOPTION.

SKIP can be used with either input or output files. The FILETYPE and CHANNEL options indicate which file is to be skipped. By default this is the current input channel.

will skip the contents of the input file on channel 2 from the current position until the string Section 2 is found. The next line to be read from channel 2 will then be the one immediately after the line containing Section 2.

For output files you can use SKIP to print blank lines to separate one section of output from another. You might want to do this if you had set the PRINT option SQUASH=yes to suppress the automatic blank lines within a section of output. For example,

places two blank lines between Heading and Table when printing their values to channel 2.

The SORT directive allows you to reorder the units of a list of vectors or pointers according to one or more "index" vectors. These can be specified explicitly using the INDEX option (and they need not be among the vectors actually sorted). If you omit the INDEX option, Genstat uses the first vector in the OLDVECTOR list. The DECIMALS option allows you to define the number of decimal places that are taken into account for an index variate: for example DECIMALS=0 would round each value to the nearest integer. If you do not set this, there is no rounding. The DIRECTION option controls whether the ordering is into ascending or descending order; by default DIRECTION=ascending.

The vectors or pointers whose values are to be sorted are listed by the OLDVECTOR parameter. The units of each structure are permuted in exactly the same way, into an ordering determined from the index vectors. The NEWVECTOR parameter allows you to specify new vectors to contain the sorted values, and thus keep the unsorted values in the original vectors. For example

would place the sorted values of Age, Name, and Sex into A, N, and S; as there is a null entry (*) corresponding to Income in the NEWVECTOR list, the sorted incomes would replace the original values of Income. Any undeclared vector in the NEWVECTOR list is declared implicitly to match the corresponding OLDVECTOR.

The SPREADSHEET directive is available in some implementations of Genstat, opening a specially designed spreadsheet that allows the vectors specified by the STRUCTURE parameter to be edited. The FIELDWIDTH and DECIMALS parameters can be used to control the formats used to represent the data within the spreadsheet. The MINIMUM and MAXIMUM parameters allow limits to be set on numerical values, and the FREPRESENTATION parameter controls the way in which factor values are displayed.

The SSPM structure stores a matrix of corrected sums of squares and products, and associated information, as used for regression and some multivariate analyses. You can form values for SSPM structures by the FSSPM directive. However, most multivariate and regression analyses can be done without declaring and forming an SSPM explicitly.

[1] or ['SUMS'] is a symmetric matrix containing the sums of squares and products. The number of rows and columns of this matrix will equal the number of parameters defined by the expanded terms list: that is, the number of variates plus the number of dummy variates generated by the model formula. (See the TERMS directive.)

[2] or ['MEANS'] is a variate containing the mean for each variate or dummy variate.

[3] or ['NUNITS'] is a scalar holding the total number of units used in constructing the sums of squares and products matrix. If the SSPM is weighted, this scalar will hold the sum of the weights.

[4] or ['WMEANS'] is a pointer, pointing to variates holding within-group means. There is one variate for each row of the 'SUMS' matrix plus one extra. They are all of the same length, namely the number of levels of the GROUPS factor. The extra variate holds counts of the number of units in each group.

The TERMS option of the SSPM directive defines the model for whose components the sums of squares and products are to be calculated. In the simplest case the model is just a list of variates, but you can use more complex model formulae, involving variates and factors; this is done in conjunction with the FACTORIAL and FULL options.

You can form a within-group matrix of sums of squares and products by specifying the relevant factor with the GROUPS option.

Sometimes you may already have calculated values for the matrix of sums of squares and products. You can then assign them to the component structures of the SSPM for example by READ. You would still, however, need to set the number of degrees of freedom associated with the matrix, and for that you use the DF option.

STEP modifies the current regression model, which may be linear, generalized linear or generalized additive, in order to achieve the biggest "improvement". Terms in the specified formula are dropped from the current model if they are already there, or are added to it if they are not. For each term, the residual sum of squares (or deviance) and the residual degrees of freedom are recorded; then Genstat reverts to the original model before trying the next term.

The current model is finally modified by the best term, according to a criterion based on the variance (or deviance) ratios. In a linear model, suppose that the residual sum of squares and residual degrees of freedom of the current model are s₀ and d₀, and of the model after making a one-term change are s₁ and d₁. If the variance ratio for any term that is dropped is less than the value of the setting of the OUTRATIO option, then the term that most reduces the residual mean square is dropped. That is, a term will be dropped only if at least one term has

{(s₁-s₀) / (d₁-d₀)} / {s₀/d₀} < OUTRATIO

If you have set OUTRATIO=*, then no term is dropped. Note that, though the criteria are ratios of variances, you should not interpret them as F-statistics with the usual interpretation of significance. The probability levels would need be adjusted to take account of correlations between the explanatory variables concerned, and the number of changes being considered.

If no term satisfies the criterion for dropping, then the term that most reduces the residual mean square will be added to the model if its variance ratio is greater than the setting of the INRATIO option. That is, if

{(s₀-s₁) / (d₀-d₁)} / {s₁/d₁} > INRATIO

Likewise, if you have set INRATIO=*, no term will be added.

Usually, the effect of the STEP directive is to make one change of a stepwise regression search. You can make STEP do forward selection by setting the MAXCYCLE option to define a maximum number of changes; STEP will stop at this limit, or earlier if no further changes can be made.

The changes setting of the PRINT option produces a list of terms with the corresponding residual mean squares and residual degrees of freedom, ordered according to the sizes of the residual mean squares; this list is not available for display later by the RDISPLAY directive. The INRATIO and OUTRATIO options are explained above. The rest of the options are as in the FIT directive, except that there is no CONSTANT option.

The STOP directive indicates the end of a Genstat program, thus telling the computer that you have finished using Genstat. It also ends the existing job, so there is no need to give an ENDJOB statement beforehand. Any input that follows a STOP statement is ignored.

The STORE directive allows you to store data structures or procedures in a backing-store file. The file can be opened using the OPEN directive, and there is also a backing-store workfile attached to channel 0 which is automatically deleted at the end of a Genstat run.

Each backing-store file contains a number of subfiles. Each subfile starts with a catalogue, recording which structures it stores. Then come the attributes and the values of each data structure. A subfile name can be either an unsuffixed identifier or a suffixed identifier with a numerical suffix. The identifiers of subfiles are kept in a separate catalogue to the identifiers of data structures, so you do not need to worry about keeping the identifiers of data structures and subfiles distinct. However, if you use a suffixed identifier for a subfile, Sub[1] say, you cannot also use the identifier Sub. There are two types of subfiles. Ordinary subfiles can hold any type of structures except procedures; procedure subfiles hold only procedures (and their dependent structures).

creates a subfile containing factor F. The complete definition of factor F depends on text T to supply level names. So T is stored too. The text T depends on a system structure (indicating the length of each line), which is therefore also stored. Hence to save factor F, Genstat has actually saved three structures. However, this is all automatic, so you do not need to worry about any of the details of the system structures.

The first line sets up a pointer structure V, pointing to V[1] and V[2]. To store variate V[1], a pointer structure V has to be set up in the subfile, pointing to V[1] only. Thus two structures are saved on backing store, namely V and V[1]. The original pointer V in the program is left unchanged. (If the example had stored the whole of V, no such complications would have arisen.)

The structures to be stored are specified by the IDENTIFIER parameter. The CHANNEL option indicates the backing-store file to use, and the SUBFILE option specifies the subfile that is created. Both these options can be omitted; by default the file will be the workfile, and the subfile will be called SUBFILE. The structures that are stored in the subfile are merely copies of the structures in the job, so the original structures remain available for further use within the job.

The STOREDIDENTIFIER parameter allows you to give a structure a different name within the subfile: For example,

stores a structure with identifier Weight within Genstat as a structure with identifier WtWeek2 in the backing-store file. If you want to rename only some of the structures, you can either respecify the existing identifier, or insert * at the appropriate point in the list. For example, you could store X and Y, renaming only Y as Yy, by

Procedures that have been retrieved automatically from libraries cannot be stored by STORE.

You can set option PRINT=catalogue to obtain a catalogue of the subfiles in the backing-store file, and of the structures in the subfile just created. If you also set option UNNAMED=yes Genstat will also list any unnamed structures, with details of how they depend on each other.

The LIST option controls how the IDENTIFIER list is interpreted. The default setting inclusive simply stores the structures that have been listed.

Alternatively, if you set LIST=all Genstat will store all the structures in the current job that have identifiers and whose types have been defined. If the statement is inside a procedure, then only the structures defined within the procedure are stored. If you are storing procedures, then this setting will store all procedures that you have created explicitly in this job, by PROCEDURE or RETRIEVE statements.

Finally, you can set LIST=exclusive to store everything that you have not included in the IDENTIFIER parameter: that is, all the other named structures that are currently accessible, or all the other procedures that have been created in this job. Note, though, that some of the structures in the IDENTIFIER list may be stored if they are needed to complete the set of structures to be stored. If you use this setting, the STOREDIDENTIFIER parameter is ignored. For example

creates four named structures, T, F, V and Vt. The statement

stores the text T;

stores Vt and V; and

results in all four structures being saved, because V points to Vt, and F points to T.

If a subfile of the specified name already exists on the backing-store file, the storing operation will usually fail. You can then set option METHOD=overwrite to overwrite the old subfile, that is, to replace the old subfile with a new subfile; alternatively, you can put METHOD=replace to form a new backing-store file containing only the new subfile. Setting METHOD=update adds new structures to an existing subfile. The MERGE option then controls what happens if a data structure that is being added to the file is already present; by default it overwrites the previous version but, if you put MERGE=yes, only new structures are added to the file.

To make your files secure, you can specify a password using the PASSWORD option. Once you have done this, you must include the same password in any future use of STORE or MERGE with this same userfile; spaces, case, and newlines are significant in the password. You cannot change the password in a userfile once you have set it, but you can use the MERGE directive to create a new userfile with no password or with a new password. If you set the password to be a text whose values have been have restricted, the restriction is ignored.

The PROCEDURE option indicates whether the subfile is to store procedures (PROCEDURE=yes), or ordinary data structures.

The STRUCTURE directive allows you to define customized compound data structures for use, for example, in procedures. The NAME option supplies a single-valued text to define the name to be used for the new "type" of data structure. This can then be used as a setting for the TYPE parameter in either the OPTION or PARAMETER directives within a procedure, to indicate that the option or parameter concerned must be supplied with this type of structure. The case of the letters in the name is not significant. So they can be specified in capitals, or in lower case, or in any mixture.

The parameters of the directive define the contents of the structure. The LABEL parameter lists the labels to be used with each element of the structure, and the SUFFIX parameter lists the corresponding suffix numbers (by default the numbers 1, 2, etc.). The TYPE parameter allows you to define the types of structure that are allowed in each element (which may be any of the standard Genstat data structures, or other customized types), and the COMPATIBLE parameter allows you to define aspects that must be compatible with the first element of the structure similarly to the COMPATIBLE parameter of the OPTION and PARAMETER directives. These are checked when the structure is declared, and when it is used as an option or parameter setting of a procedure that requests that type.

A particular complex matrix, Cmat say, could then be declared using the DECLARE directive:

The elements of the compound structure can be referred to like those of an ordinary pointer declared using the POINTER directive with options CASE=ignored, ABBREVIATE=yes and FIXNVALUES=yes. So, the labels can be given in either upper- or lower-case or in any mixture, and each can be abbreviated to the minimum number of characters required to distinguish it from the previous labels. So the imaginary part of the complex matrix above could, for example, be referred to as Cmat['imaginary'] or Cmat['IMAGINARY'] or simply Cmat['i'].

The SUSPEND directive may not be implemented on all the types of computers for which Genstat is available. However, you can find out simply by typing the command

This will produce a message saying either that Genstat has been suspended, or that SUSPEND is not implemented. In the latter case, it is not possible to communicate between Genstat and other programs.

If SUSPEND is implemented, after the message you will get a prompt `SUSPEND>' for an operating-system command. You will also be told what command in the operating system will return you to Genstat. For example, with the VMS system on VAX computers you type

The SYSTEM option of SUSPEND allows you to give operating-system commands without explicitly returning to the operating system and, if you do not want to wait for an operating-system command to be executed before returning to Genstat, you can set the CONTINUE option together with the SYSTEM option.

Calculates singular value decompositions of matrices i.e. ( LEFT *+ SINGULAR *+ TRANSPOSE(RIGHT) ).

The diagonal matrix S contains the p singular values of A, ordered such that

The smaller of U and V will be orthogonal. So, if A has more rows than columns, m>n, p=n and VV¢ =I_p.

where U_r and V_r are the first r columns of U and V, and S_r contains the first r singular values of A (Eckart and Young 1936).

The INMATRIX parameter specifies the matrices to be decomposed. The algorithm uses Householder transformations to reduce A to bi-diagonal form, followed by a QR algorithm to find the singular values of the bi-diagonal matrix (Golub and Reinsch 1971). The other parameters allow you to save the component parts of the decomposition: LEFT, SINGULAR, and RIGHT for U, S, and V respectively.

The PRINT option allows you to print any of the components of the decomposition; by default, nothing is printed. If any of the matrices is to be printed, all p columns are shown, even if you are storing only the first r columns.

Genstat will decide how many columns and singular values r to store, and will store that number for any of the components that you specify. If none of the matrices in the LEFT, SINGULAR, and RIGHT lists has been declared in advance, the full number of singular values (r=p) is stored; otherwise Genstat sets r to the maximum number of columns contained in any of the matrices. If r<p, the first r singular values will be saved, along with the corresponding columns of singular vectors.

One practical application of the singular value decomposition is to form generalized inverses of matrices. If you use the singular value decomposition you obtain the Moore-Penrose generalized inverse, sometimes called the pseudo-inverse, and this is the method used by the GINVERSE procedure.

SWITCH modifies the current regression model, which may be linear, generalized linear, generalized additive, standard curve, or nonlinear. Terms in the specified formula are dropped from the current model if they are already there, or are added to it if they are not. It is best to give a TERMS statement before investigating sequences of models using SWITCH, in order to define a common set of units for the models to be explored. If no model is fitted after the TERMS statement, the current model is taken to be the null model.

The model fitted by SWITCH will include a constant term if the previous model included one, and will not include one if the previous model did not. You can, however, change this using the CONSTANT option.

The options of SWITCH are the same as those of the FIT directive, but with the extra NONLINEAR option which controls whether separate nonlinear parameters are fitted to different groups when fitting curves, as in FITCURVE.

Because of this symmetry, Genstat stores only the diagonal elements and those below it; this is called the lower triangle. So you must specify only these values, whether in the declaration by SSPM or in a READ statement. (As always, you give them in row order: so if there are n rows, then for the first you supply one value, for the second two, and so on.) Likewise, Genstat prints only the lower triangle in output, for example with PRINT.

The ROWS option defines both the number of rows and the number of columns. The simplest way of doing this is to use a scalar to define the number of rows and columns explicitly. Alternatively, you can set ROWS to a variate, text, or pointer, whose length then defines the number of rows and whose values will then be used as labels, for example when the symmetric matrix is printed. Finally, if you specify a factor, the number of levels defines the number of rows and the labels if available, or otherwise the levels, are used for labelling.

Values can be assigned to the symmetric matrices by either the VALUES option or the VALUES parameter. The option defines a common value for all the matrices in the declaration, while the parameter allows them each to be given a different value. If both the option and the parameter are specified, the parameter takes precedence.

If the MODIFY option is set to yes any existing attributes and values of the symmetric matrices are retained (if still appropriate); otherwise these are lost.

The DECIMALS parameter allows you to define a number of decimal places to be used by default when each symmetric matrix is printed. You can associate a text of extra annotation with each symmetric matrix using the EXTRA parameter. The MINIMUM and MAXIMUM parameters allow you to define lower and upper limits on the values in each symmetric matrix. Genstat then prints warnings if any values outside that range are allocated to the matrix.

Tables are declared using the TABLE directive. The CLASSIFICATION option specifies the factors classifying the table.

Values can be assigned to the tables by either the VALUES option or the VALUES parameter. The option defines a common value for all the tables in the declaration, while the parameter allows them each to be given a different value. If both the option and the parameter are specified, the parameter takes precedence.

If the MODIFY option is set to yes any existing attributes and values of the tables are retained (if still appropriate); otherwise these are lost.

The DECIMALS parameter allows you to define a number of decimal places to be used by default when each table is printed. You can associate a text of extra annotation with each table using the EXTRA parameter. The MINIMUM and MAXIMUM parameters allow you to define lower and upper limits on the values in each table. Genstat then prints warnings if any values outside that range are allocated to the table.

A table can also have margins. There is then a margin for each classifying factor; this contains some sort of summary over the levels of that factor. For example, if you have a table in which the cells contain totals of the observations, you would want the marginal cells to contain totals across the levels of the factor. You can define a table to have margins when you declare it, by setting the MARGINS option of the TABLE directive to yes. Alternatively you can add margins later by the MARGIN directive.

Tables also have an associated scalar which collects a summary of all the observations for which any of the classifying factors has a missing value; these observations cannot be assigned to any cell of the table itself. This scalar can be given an identifier, so that you can refer to it, using the UNKNOWN parameter of the TABLE directive.

TABULATE allows you to produce the various types of tabular summary listed in the settings of its PRINT option. The variates whose values are to be summarized are listed with the DATA parameter. If you want to save the summaries in tables, for manipulating or for printing later on, you should list identifiers of the tables in the appropriate parameter list: for example, you would save the totals in a table T by including T in the list for the TOTALS parameter. The other parameters similarly give the other kinds of summary: numbers of non-missing values, means, minima, maxima, variances, and quantiles.

The simplest quantile, and the one produced by default, is the median (50% quantile), but the PERCENTQUANTILE option allows you to request any percentage point (between 0 and 100, of course). Moreover, by specifying a variate as the setting for PERCENTQUANTILE, you can obtain several quantiles at the same time. However, if you then want to save the results the setting of the QUANTILE parameter must be a pointer with length equal to the required number of quantiles, instead of a single table.

If you merely want to print the summaries, you do not usually need to list any tables; you need only specify the PRINT option. The only exception to this is with sequential tabulation, described at the end of this subsection.

Any table that you have not declared in advance will be declared implicitly. If you have not declared any of the tables, the classifying factors are taken from the CLASSIFICATION option, which in that case you must have set; likewise, the MARGINS option determines whether or not the tables will have margins. Otherwise these two options are ignored, and the undeclared tables are defined to have the same classifying factors and status for margins as the tables that you have declared previously; all these previously declared tables must have the same set of classifying factors, and must be all with margins or all without margins.

In the tables that correspond to the parameters of TABULATE, missing values of the data variates are ignored. So the NOBSERVATIONS parameter and the nobservations setting of the PRINT option provide the numbers of non-missing units of the data variates for each factor combination. You can however obtain a count of the numbers of units that would have contributed to each group if no values had been missing: you use the COUNTS option if you want to save the table, or put PRINT=counts if you want to print it. If any of the factor values are missing Genstat ascribes the corresponding units to the unknown cell associated with the table (see the TABLE directive).

Weighted tables can be obtained by setting the WEIGHT option to a variate of weights. You can, in general, think of weights as a set of multipliers which are applied to the data before any operations are performed. Thus, for most aspects of weighted tabulation you can replace x by wx and 1 by w (that is, n by åw) in the standard formulae (see below). This is not quite what happens in the case of variances, but it is certainly true for all other functions (including counts).

A quick look at the formula used for weighted variance will show that it breaks down for åw<1, and, in fact, is valid only for integer values of w. If an invalid weight is found during the calculation of a variance it will be reported and the tabulation halted. Temporary tables will be deleted, but named tables may contain partial results. Non-integer weights are allowed in contexts other than variances.

If you have many observations to summarize, there may be insufficient space within Genstat for you to read them all and then form the tables. To cater for such situations, Genstat allows you to process the data in sections, using the SEQUENTIAL option of TABULATE in conjunction with the SEQUENTIAL option of READ. After READ, the absolute value of the option indicates the number of units that have been read in this particular section; the value is positive during interim sections and negative or zero once the terminator at the end of the data is reached. TABULATE will not print any tables until the final section has been processed. If you want to see the intermediate tables, you can include a PRINT statement after the TABULATE statement. To allow Genstat to keep contact with the working tables in which the results are accumulating, you must save at least one out of the various types of table for every DATA variate. Genstat can then link the working tables to this named table during the course of the sequential tabulation, so that the information is not lost between the successive uses of TABULATE.

The final five options of TABULATE (OWN, OWNFACTORS, OWNVARIATES, INCHANNEL, and INFILETYPE) allow you to link your own Fortran subroutine, G5XZIT, to Genstat to allow you to handle complicated arrangements of data, as can occur for example in hierarchical surveys. To implement this, you must get access to some of the Genstat source code. The relevant section of the code is named Module X, and is distributed with Genstat to all sites, probably in a file called X.FOR. The documentation of G5XZIT is included with the Fortran and so is not repeated here. G5XZIT is thus a Fortran subprogram, to be modified by you, which is called from within TABULATE for each unit to be tabulated. It contains switches to tell TABULATE when a data error occurs or when all the data have been read. To use it you have to link your own version of Genstat, as when using the OWN directive. Then your version of G5XZIT will be used instead of the standard version supplied as part of Genstat.

The OWN option should be set to a variate allowing you to communicate between your Genstat code and your G5XZIT subprogram. The OWNFACTORS option provides the list of factors to be read by G5XZIT. It must include the classifying factors needed in the current TABULATE instruction, but it may contain others as well. The OWNVARIATES option should provide a similar list of variates. The INCHANNEL option should be set to the Genstat channel number of the data file, as specified in a previous OPEN statement or in the Genstat command line. The INFILETYPE option specifies whether the data file is character (input) or binary (unformatted).

TABULATE allows only one classification set to be used at a time. If the data set is complicated enough to require G5XZIT, then several tabulations with different classifying sets are likely to be needed. Rather than have a separate branch in G5XZIT for each tabulation, you can put all the factors and all the variates that you will need into the settings of the OWNFACTORS and OWNVARIATES options, and leave TABULATE to extract the ones it needs each time. If you have several TABULATE statements as suggested, you will have to close the data file and re-open it between them.

Displays further output after an analysis by ESTIMATE.

You can use TDISPLAY to print further output from an ESTIMATE statement. The PRINT option has the same interpretation as in ESTIMATE, except that information is not available to monitor convergence. Also, if the ESTIMATE statement used the setting METHOD=initialize you will not be able to print the standard errors or correlations between the parameter estimates.

The CHANNEL option allows you to send the output to another output channel.

You can use the SAVE option to specify the time-series save structure (from ESTIMATE) from which the output is to be taken. By default TDISPLAY uses the structure from the most recent ESTIMATE statement.

You can use the TERMS directive before starting to explore different subsets of explanatory variables, to allow Genstat to define a common set of units for the regression and to carry out some initial calculations. TERMS thus initializes Genstat ready for an exploration using the directives ADD, DROP, SWITCH, TRY, or STEP. It overrules any model that has already been fitted with FIT, FITCURVE, or FITNONLINEAR and resets the current model to be the null model containing only the constant term.

TERMS need not be specified before exploring a linear, generalized linear or generalized additive model, that is one that is fitted initially using FIT with its CALCULATION option unset. However, it is essential before exploring a nonlinear model, that is one fitted initially by FIT with CALCULATION set, or by FITCURVE or FITNONLINEAR. Furthermore, if some of the explanatory variables to be used in a linear, generalized linear or generalized aditive model contain missing values or have restrictions, the use of TERMS ensures that the sequence of models are fitted using a common set of units. Otherwise, if a variate or factor which is introduced into the model has a missing value where previous explanatory variates or factors did not, or is restricted whereas previous ones were not, the set of units has to be changed. The previous model is automatically refitted with the new set of units before the new model is fitted, but the accumulated summary will then show only these two fits.

The formula specified by the parameter of TERMS should contain all the explanatory variables and model terms that you may wish to use in the subsets. The model containing all the terms specified in the formula, excluding the response variates, is called the maximal model.

The PRINT option allows you to display the sums of squares and products between the variates in the model (including the response variates and dummy variates set up to represent any factors and their interactions), the means of the variates, and the degrees of freedom. It can also display the corresponding matrix of correlations between variables, and group means if the regression is within groups. The calculations are weighted if you have specified weights in the MODEL statement, and they are made within groups if you have specified a grouping factor. All units of the variates are used unless there are restrictions or missing values. You are not allowed to have different restrictions on the different vectors. Thus you can define the set of units that Genstat uses for the regressions by putting a restriction on any one of: a response variate, an explanatory variate, the weight variate, the offset variate, or the grouping factor. A missing value in any of these structures except a response variate will also exclude the corresponding unit. You should not alter the restriction applied to the vectors between the TERMS statement and subsequent fitting statements.

The FACTORIAL option controls the inclusion of interaction terms in the model. All terms involving more than the specified number of factors and variates are omitted. By default FACTORIAL is set to three. The FULL option can be set to yes to ensure that Genstat allocates a parameter to each level of any factor in a linear, generalized linear or generalized additive model; otherwise it will include parameters only for levels 2 upwards (and their estimates will represent the differences between the estimated parameters for their levels and the estimate for level 1).

The SSPM option lets you use values that you have already calculated for an SSPM or DSSP structure. This is feasible only with ordinary linear regression but it can be useful when you are analysing very large sets of data: you can accumulate a DSSP sequentially with the FSSPM directive to avoid storing all the data at one time. Later regression calculations will be based on the supplied values of the DSSP, though no fitted values, residuals, or leverages will be available. However, the values of a supplied SSPM or DSSP are accepted without checking by the TERMS directive: Genstat simply assumes you are giving it something sensible.

The TOLERANCE option controls the detection of aliasing in subsequent model fitting. By default, a parameter in a linear or generalized linear model will be deemed to be aliased if the ratio between the original diagonal value of the SSPM corresponding to this parameter and the current diagonal value of the partially inverted SSPM is less than 10⁷e. The quantity e depends on the computer and is defined to be the smallest number such that the computer recognizes 1.0 + e as greater than 1.0 in double precision. Any positive value can be supplied by the TOLERANCE option to replace this default criterion in subsequent linear regression and generalized linear regression.

The DESIGNMATRIX option can be set to a matrix to save the design matrix corresponding to the maximal model.

Each unit of a Genstat text structure is a string which you can regard as a line of textual description. Texts can be used to label vectors and pointers, for captions or pieces of explanation within output, to store Genstat statements, and to store output.

The IDENTIFIER parameter lists the texts that are to be declared. Values can be assigned to the texts by either the VALUES option or the VALUES parameter. The option defines a common value for all the texts in the declaration, while the parameter allows them each to be given a different value. If both the option and the parameter are specified, the parameter takes precedence.

The NVALUES option allows the number of values in the texts to be defined. If this is not set, the lengths of the texts are defined from the numbers that are supplied by the VALUES option or parameter. If these too are unset, Genstat takes the length specified by the preceding UNITS statement, if any.

The CHARACTERS parameter allows you to define the number of characters to be printed by default when the strings of each text are printed. You can associate a text of extra annotation with each table using the EXTRA parameter.

If the MODIFY option is set to yes any existing attributes and values of the texts are retained (if still appropriate); otherwise these are lost.

Saves results after an analysis by ESTIMATE.

An ESTIMATE statement produces many quantities that you may want to use to assess, interpret, and apply the fitted model. The TKEEP directive allows you to copy these quantities into Genstat data structures. If the METHOD option of the ESTIMATE statement was set to initialize, then the results saved by the options SE, INVERSE, VCOVARIANCE, and SCORE are unavailable. However, you can save the estimates of the missing values and their standard errors. The residual degrees of freedom in this case does not make allowance for the number of parameters in the model, but does allow for the missing values that have been estimated.

The OUTPUTSERIES parameter specifies the variate that was supplied by the SERIES parameter of the ESTIMATE statement; this can be omitted.

You can use the RESIDUALS parameter to save the residuals in a variate, exactly as in the ESTIMATE directive.

The ESTIMATES parameter can supply a variate to store the estimated parameters of the TSM. Each estimated parameter is represented once, but the innovation variance is omitted entirely. Genstat includes only the first of any set of parameters constrained to be equal using the FIX option of ESTIMATE. The order of the parameters otherwise corresponds to their order in the variate of parameters in TSM, and is unaffected by any numbering used in the FIX option.

The SE parameter allows you to specify a variate to save the standard errors of the estimated parameters of the TSM. The values correspond exactly to those in the ESTIMATES variate. Parameters in a time series model may be aliased. This is detected when the equations for the estimates are being solved, and the message ALIASED is printed instead of the standard error when the PRINT option of ESTIMATE or TDISPLAY includes the setting estimates. The corresponding units of the SE variate are set to missing values.

The INVERSE parameter can provide a symmetric matrix to save the product (X¢ X)^-1, where X is the most recent design matrix derived from the linearized least-squares regressions that were used to minimize the deviance. The ordering of the rows and columns corresponds exactly to that used for the ESTIMATES variate. The row of this matrix corresponding to any aliased parameter is set to zero except that the diagonal element is set to the missing value.

The VCOVARIANCE parameter allows you to supply a symmetric matrix for the estimated variance-covariance matrix,  _a²(X¢ X)^-1, of the TSM parameters. The ordering of the rows and columns and the treatment of aliased parameters corresponds exactly to that used for the ESTIMATES variate.

The DEVIANCE parameter specifies a scalar to hold the final value of the deviance criterion defined by the LIKELIHOOD option of ESTIMATE.

The DF parameter saves the residual number of degrees of freedom, defined for a simple ARIMA model by N-d-(number of estimated parameters). If a seasonal model is used, this number is further reduced by Ds.

The MVESTIMATES parameter specifies a variate to hold estimates of the missing values of the series, in the order they appear in the series. You can thereby obtain forecasts of the series, by extending the SERIES in ESTIMATE with a set of missing values. This is less efficient than using the FORECAST directive, but it does have the advantage that the standard errors of the estimates take into account the finite extent of the data, and also the fact that the model parameters are estimated.

The SEMV parameter can supply a variate to hold the estimated standard errors of the missing values of the series, in the order they appear in the series.

The COMPONENTS parameter can be used after a multi-input model has been fitted using ESTIMATE to access the components of the output series that are due to the various input series; you can also access the output noise. In simple regression, the input components are proportional to the input series. But the component resulting from a transfer-function model may be quite different from this. You can examine these components separately, or sum them to show the total fit to the output series that is explained by the input series. Note that the fitted values may appear to be offset from that output series, because the constant term is part of the noise component, and so is not included. You may want to examine the output noise component. For example, if you thought that the ARIMA model for the output noise was inadequate, you could investigate the noise component with univariate ARIMA modelling.

The SCORE parameter can specify a variate to hold the model scores. The scores are usually defined as the first derivatives of the log likelihood with respect to the model parameters. To get these, the scores supplied by TKEEP should be scaled by dividing by the estimated residual variance and reversing its sign. The elements of the SCORE variate correspond exactly to the parameters as they appear in the ESTIMATES variate. After using ESTIMATE to fit a time series model, the scores should in theory be zero provided the model parameters do not lie on the boundary of their allowed range. The scores are used within ESTIMATE to calculate the parameter changes at each iteration.

You can use the SAVE option to specify the time-series save structure from which the output is to be taken. By default TKEEP uses the structure from the most recent ESTIMATE statement.

TRANSFERFUNCTION can be used to define input series and transfer-function models to be used by subsequent ESTIMATE statements.

In its simplest form, when the TRANSFERFUNCTION and PRIORMETHOD parameters are unset, TRANSFERFUNCTION can be used to specify the explanatory variables for a regression with autocorrelated errors.

The first parameter, SERIES, specifies a list of variates holding the time series of explanatory variables.

The BOXCOXMETHOD parameter allows you to estimate separate power transformations for the explanatory variables: the variable x_t is transformed to

The default is no transformation, corresponding to x_t⁽l) = x_t. You can choose whether the transformations are to be fixed or estimated, by specifying one string for each explanatory variable.

The ARIMA parameter allows you to associate with each explanatory variable a univariate ARIMA model for the time-series structure of that variable. If you think such a model is inappropriate, then you should give a missing value in place of the TSM identifier, or leave this parameter unset. You can use these models in any subsequent FORECAST statement to incorporate, into the error limits of the forecasts, an allowance for uncertainties in the predicted explanatory variables; the allowance assumes that the future values of the explanatory variables are forecasts obtained using these ARIMA models.

The TRANSFERFUNCTION and PRIORMETHOD parameters are used to define multi-input transfer-function models.

The TRANSFERFUNCTION parameter specifies the transfer-function TSMs that are to be associated with the input series. A missing value in place of a TSM identifier causes Genstat to treat the corresponding input series as a simple explanatory variable, equivalent to a transfer-function model with orders (0,0,0,0).

The PRIORMETHOD parameter specifies, for each input series, how Genstat is to treat the transients associated with the early values of the transfer-function response. In calculating the input component z_t from the input x_t, Genstat has to make assumptions about the unknown values of x_t which came before the observation period. The default is that x_t (or generally x_t⁽l)) is assumed to be equal to the reference constant c of the transfer-function model. The pattern of the transient can be controlled by introducing a number max(p+d,b+q) of nuisance parameters to represent the combined effects of all earlier input values on the observed output. Setting PRIORMETHOD=estimate specifies that these nuisance parameters are estimated so as to minimize the transients. You should, however, be careful in using this. Often all you will have to do is make a sensible choice of the reference constant c. Estimating the transients is best done as a final stage in refining the model; earlier, this may give poor numerical conditioning.

The SAVE option allows you to name the time-series save structure created by TRANSFERFUNCTION. You can use this identifier in a later ESTIMATE statement, and eventually in a FORECAST statement. If you do not name the save structure Genstat will use the most recent save structure, which will be overwritten each time a new TRANSFERFUNCTION statement is given.

Specifies the treatment terms to be fitted by subsequent ANOVA statements.

The TREATMENTSTRUCTURE directive defines the treatment formula which specifies treatment, or systematic, terms to be fitted in subsequent ANOVA statements. For a simple one-way analysis of variance this has the form

where Tfac is a factor which indicates which treatment was received by each unit in the design. Most experiments, however, are devised to study several treatment factors. For these factorial experiments TREATMENTSTRUCTURE specifies a model formula to define the model terms to be fitted. Each model term will then have its own line in the analysis-of-variance table and, for example, will have a table of means.

Initially in a job, there is no treatment formula. This situation can be restored by a TREATMENTSTRUCTURE directive with a null setting:

In its simplest form, a model formula is a list of model terms, linked by the operator "+". For example,

is a formula containing two terms, A and B, representing the main effects of factors A and B respectively. Higher-order terms (like interactions) are specified as series of factors separated by dots, but their precise meaning depends on which other terms the formula contains, as we explain below. The other operators provide ways of specifying a formula more succinctly, and of representing its structure more clearly.

The crossing operator * is used to specify factorial structures. For example, the treatment formula

which has three terms: Nitrogen for the nitrogen main effect, Sulphur for the main effect of sulphur, and Nitrogen.Sulphur for the nitrogen by sulphur interaction. Higher-order terms like Nitrogen.Sulphur represent all the joint effects of the factors Nitrogen and Sulphur that have not been removed by earlier terms in the formula. Thus here it represents the interaction between nitrogen and sulphur as both main effects have been removed.

The other most-commonly used operator is the nesting operator (/). This occurs most often in block models (specified by the BLOCKSTRUCTURE directive). For example, the formula

This could define the block model for a design in which there are several litters of rats. As the formula contains no "main effect" for rat, the term Litter.Rat represents rat-within-litter effects (that is the differences between individual rats after removing any overall similarity between rats that belong to the same litter).

The operators can also be mixed in the same formula. In general, if l and m are two model formulae:

(where l.m is the sum of all pairwise dot products of a term in l and a term in m, and fac(l) is the dot product of all factors in l). For example:

The other important operator for ANOVA is the pseudo-factorial operator //. This allows you to partition an unbalanced treatment term into pseudo-terms, which are each balanced.

Contrasts can be fitted by putting a function of a factor into the treatment formula, instead of the factor itself. Polynomial contrasts can be specified using the POL or POLND functions. Other, user-defined regression models can be defined using the REG or REGND functions. COMPARISON, the other function relevant to ANOVA allows comparisons to be calculated between levels of the factor.

TRY investigates modifications to the current regression model, which may be linear, generalized linear or generalized additive. Terms in the specified formula are dropped from the current model if they are already there, or are added to it if they are not. After each change, Genstat prints the requested output and then restores the original model before trying the next change. It is best to give a TERMS statement before using TRY to define a common set of units for the models to be investigated. If no model is fitted after the TERMS statement, the current model is taken to be the null model.

The options of TRY are the same as those of the FIT directive, except that there is no CONSTANT option. The accumulated setting of the PRINT option will show only one change at a time. Accumulated summaries produced by later statements will not have any entries for a TRY statement.

The TSM structure stores a time-series model which you can use with directives such as ESTIMATE for Box-Jenkins modelling of time series. The information that you give to specify the model is stored in two variates, called the orders and the parameters; an optional third variate contains lags. The elements of a TSM are thus

[1] or ['ORDERS'];

[2] or ['PARAMETERS'];

[3] or ['LAGS'].

To declare a TSM you use the TSM directive. You set the type of model by the MODEL option. The default setting defines an ARIMA model. This is an equation relating the present value y_t of an observed time series to past values. The equation includes lagged values not only of the series itself, but also of an unobserved series of innovations, a_t ; you can interpret the innovations as the error in predicting y_t from past values y_t-1, y_t-2 .... The usual statistical model assumes that the innovations are a series of independent Normal deviates with mean zero and constant variance. The residuals obtained from fitting the model can be used to estimate the innovations.

q(B) {Ñ ^dy_t⁽l) - c} = f(B)a_t

Ñ is the differencing operator Ñ y_t =y_t-y_t-1 , Ñ ^dy_t =Ñ ^d-1 (y_t-y_t-1 ), and

q(B) = 1 - q₁B - ... - q_pB^p

f(B) = 1 - f₁B - ... - f_qB^q

The parameter l specifies a Box-Cox power transformation defined by

y_t⁽l) = (y_t^l - 1) / l, l 0

However, in the default case when l is fixed and not estimated, the value l=1 implies no transformation and then y_t⁽¹⁾=y_t rather than y_t-1. If l 1 or if l is to be estimated, then Genstat will not let you have values of y_t £ 0. The usual case however is that l=1 and is not to be estimated, so that y_t may take any values.

The ORDERS parameter is a list of variates, one for each of the models. For each simple ARIMA model, the variate contains the three values p, d, and q.

The PARAMETERS parameter is a list of variates, one for each of the models. For each simple ARIMA model, the variate contains (3+p+q) values: l, c, s_a², q₁...q_p, f₁...f_q. You must always include the first three parameters. The parameter s_a² is the innovation variance.

Whenever a TSM is used, Genstat checks its values. The orders must all be non-negative. The parameters l and c can take any values, but s_a² must be non-negative. The next p+q values specify the autoregressive and moving-average parameters: they must satisfy the stationarity and invertibility conditions for ARIMA models (see Box and Jenkins 1970). An exception is that before estimation the model parameters may be unset, in which case Genstat sets them to default values. You can omit the PARAMETERS parameter, in which case an unnamed structure is defined to contain the default values. However, you should usually specify the variate of parameters, and if possible assign good preliminary values before estimation (see FTSM) as this will speed up the model fitting process.

The LAGS parameter is a list of variates, one for each of the models. For each simple ARIMA model, this variate contains p+q values, one corresponding to each of the autoregressive and moving-average parameters. Genstat then modifies the ARIMA model by defining

The LAGS parameter for this model contains l₁...l_p, m₁...m_q. The sequences of lags l₁...l_p must be positive integers that are strictly increasing; the default values are 1...p if LAGS is not set. The same rule applies to m₁...m_q.

When seasonal terms are to be included, you must extend the ORDERS parameter so that it contains p, d, q, P, D, Q, and s. Even if the non-seasonal part of the model has p=d=q=0, these parameters must still be included at the beginning of the list. The seasonal orders must satisfy P³ 0, D³ 0, Q³ 0 and s³ 1.

You must also extend the PARAMETERS parameter to contain:

l, c, s_a², q₁...q_p, f₁...f_q, F₁...F_P, Q₁...Q_Q

You can modify the seasonal model to allow other lags:

The sequence of lags L₁...L_P must be strictly increasing and must be positive-integer multiples of the period s; the default values are s, 2s ... Ps. The same rules apply to M₁...M_Q. For any seasonal model, you must extend the LAGS parameter, if supplied, so that it contains

You can use multiple seasonal periods, by extending the variate of ORDERS with further seasonal orders P¢ , D¢ , Q¢ , and s¢ . You must correspondingly extend the variates of PARAMETERS and LAGS. It is also possible to set the seasonal periods to 1, which means you can estimate non-seasonal models with factored operators.

You can declare an ORDERS variate to have more values than is necessary, provided that the extra values are filled with zeroes, and that the number of values is 3+4k, k being the number of seasonal periods. The same applies to PARAMETERS and LAGS variates, except that Genstat ignores the extra values whatever they may be. Thus you can extend a simple model to a seasonal model, simply by resetting the extra values.

Setting MODEL=transferfunction defines a transfer-function model. The simple non-seasonal transfer-function model relates a component z_t of the output series to the corresponding input series x_t, by the equation

The parameter l specifies a Box-Cox power transformation for the input series, and the parameter c specifies a reference level for the transformed input. There is no mean correction of the input series when transfer-function models are estimated, and you should use a value of c close to the series mean so as to improve the numerical conditioning of the estimation procedure. However, if the input series x_t is trend-like rather than stationary, you could alternatively use a value for c close to the early series values, because this reduces the transient errors that arise when the transfer function is applied. The PRIORMETHOD parameter of TRANSFERFUNCTION, described below, provides further means of handling these transients.

The parameters l and c are not estimated unless you specify otherwise by the BOXCOXMETHOD parameter of TRANSFERFUNCTION or the FIX option of ESTIMATE. Often c in the transfer-function model is aliased with the constant term in the ARIMA errors, and so they should not both be estimated. In some circumstances, however, they both could be estimated, for example in a differenced transfer-function model with stationary noise.

The ORDERS parameter for the simple transfer-function model described above specifies a variate containing the four values b, p, d, and q.

The PARAMETERS parameter specifies a variate containing 3+p+q values: l, c, d₁, ... d_p, w₀, w₁ ... w_q. You must always include the parameters l, c, and w₀. When you use a transfer-function model, Genstat will check its parameter values. In particular the operator d(B) must satisfy the stability or stationarity condition.

The LAGS parameter is optional, and may be used to change the lags associated with the parameters, from the default values of 1 ... p, 1 ... q. The variate of lags contains values corresponding to the parameters d₁ ... d_p, w₁ ... w_q. They have the same interpretation as the lags in ARIMA models, and must satisfy the same conditions. Note that there is no lag associated with w₀, because the delay b provides the necessary flexibility for this.

Note that there is no W₀ coefficient, because w₀ is always present in the model and provides sufficient flexibility.

The ORDERS parameter here contains b, p, d, q, P, D, Q, and s, and the PARAMETERS parameter contains l, c, d₁ ... d_p, w₀ ... w_q, D₁ ... D_P, W₁ ... W_Q. You can analogously extend the LAGS parameter. You can also have extensions to multiple seasonal periods, as for ARIMA models.

The TSUMMARIZE directive helps you investigate time-series models by displaying or saving various characteristics. These are the theoretical autocorrelation function of an ARIMA model, and the pi-weights and psi-weights; also the impulse-response function of a transfer-function model. TSUMMARIZE can derive the expanded form of a model, in which all seasonal terms are combined with the non-seasonal term.

For an ARIMA model in the TSM parameter, you can set only the AUTOCORRELATIONS, PSIWEIGHTS, and PIWEIGHTS parameters. Also, you can set the IMPULSERESPONSE parameter only for a transfer-function model. You can set the EXPAND parameter for either type of model. The TSMs in any TSUMMARIZE statement must be completely defined; that is, you must have set the orders and parameters, and the lags if you are using them. The only exceptions are that Genstat takes the transformation parameter to be 1.0 if it is missing, and that the innovation variance of an ARIMA model need not be set.

The MAXLAG option specifies the maximum lag to which Genstat is to do calculations: this applies to autocorrelations, psi-weights, pi-weights, and impulse responses. If MAXLAG is unset, the maximum lag is defined implicitly as the length of the first variate in the parameters. However, if the length of this variate is also undefined, the maximum lag cannot be defined and Genstat reports a fault.

You can set the PRINT and GRAPH options independently of the parameters: these store results, and display the various characteristics of models.

The AUTOCORRELATIONS parameter allows you to store the theoretical autocorrelation function of an ARIMA model. Such a model uniquely defines an autocorrelation function whose values r₀ ... r_m are assigned by Genstat to the variate R, where m is the maximum lag. If the model has differencing parameters d=D=0, then the autocorrelation function is that of a series y_t that follows this model.

The PSIWEIGHTS parameter allows you to store the theoretical psi-weights y₀ ... y_m of an ARIMA model. These are used internally by Genstat when error limits are calculated for forecasts obtained using the model. You will need them for example if you want to calculate the variance of the total of the forecast values up to some specified maximum lead time. They are defined for a non-seasonal model by

1 + y₁B + y₂B² + ... = f(B) / { q(B)Ñ ^d }

The PIWEIGHTS parameter allows you to store the theoretical pi-weights P₀ ... P_m of an ARIMA model: these show explicitly how past values contribute to a forecast. The weights are defined by:

1 - P₁B - P₂B² - ... = { q(B)Ñ ^d } / f(B)

The IMPULSERESPONSE parameter allows you to store the theoretical impulse-response function, v₀ ... v_m, of a transfer-function model. This function can help you interpret the model. The sequence is defined for a non-seasonal transfer-function model by:

v₀ + v₁B + v₂B² + ... = w(B)B^b / { d(B)Ñ ^d }

For an ARIMA model you can combine into one generalized autoregressive operator all the differencing operators, the non-seasonal autoregressive operators, and the seasonal autoregressive operators. The non-seasonal and seasonal moving-average operators may similarly be combined. This expanded model can be printed using the expansion setting of PRINT and saved using the EXPANSION parameter. It can be used to help you understand a series. But you might also want to re-estimate the parameters in the expanded model, to test whether the differencing operators or seasonal factors unnecessarily constrain the structure of the original model. If you have not previously defined one of the identifiers supplied by the EXPANSION parameter, Genstat will automatically define it to be a TSM, and its component variates will be set up to have the length defined by the corresponding model in the TSM parameter. The expansion does not change the transformation parameter of the model, nor the constant term, nor the innovation variance. If the model that you have supplied contains non-zero differencing orders, then the generalized model does not satisfy the stationarity constraint on the parameters; neither does the constant term have the same interpretation as it had in the supplied model. The expansion of transfer-function models exactly parallels that of ARIMA models.

The UNITS directive can be used to define a default length which will then be used, if necessary, for any new vectors encountered later in the job. For example, in the statements

the text Subject, the factor Drug, and the variates Age and Response are all defined to be of length 20. However, the length of the variate Dlev does not need to be set by default, but is deduced to be five from the number of values that have been specified by the VALUES option.

The READ directive will use UNITS if values are to be read into a previously undeclared vector, as will the RESTRICT directive if you use it to restrict a structure that has not yet been declared. The UNITS setting is also used by the CALCULATE directive with the EXPAND and URAND functions if their secondary argument is not specified.

The parameter of the UNITS directive allows you to specify the units structure, which is a variate or a text whose values will then be used as labels for output from regression or time-series directives, provided the vectors in the analysis have the same length as the units structure and provided also that these vectors do not have labels associated with them already.

The length of the units structure must match the value set by the NVALUES option if both are set. However, either one can be used to define the other. Thus, either

would specify the default length for vectors to be seven. In the second example this default would be applied to Day too but, of course, its (seven) values would need to be read or defined in some other way before it could be used for labelling. If the type of the units structure has not been declared, UNITS will define it as a variate.

You can cancel the effect of a UNITS statement by

The IDENTIFIER parameter lists the variates that are to be declared. Values can be assigned by either the VALUES option or the VALUES parameter. The option defines a common value for all the variates in the declaration, while the parameter allows them each to be given a different value. If both the option and the parameter are specified, the parameter takes precedence.

The NVALUES option allows the number of values in the variates to be defined. If this is not set, the lengths of the variates are defined from the numbers that are supplied by the VALUES option or parameter. If these too are unset, Genstat takes the length specified by the preceding UNITS statement, if any.

The DECIMALS parameter allows you to define a number of decimal places to be used by default when each variate is printed. You can associate a text of extra annotation with each variate using the EXTRA parameter. The MINIMUM and MAXIMUM parameters allow you to define lower and upper limits on the values in each variate. Genstat then prints warnings if any values outside that range are allocated to the variate.

If the MODIFY option is set to yes any existing attributes and values of the variates are retained (if still appropriate); otherwise these are lost.

Defines the variance-components model for REML.

The VCOMPONENTS directive specifies the linear mixed model to be fitted by subsequent REML statements.

For example, consider a split-plot experiment used to assess the effects on yield of three oat varieties with four levels of nitrogen application. Here specific levels of nitrogen application have been used and the aim is to estimate the effects of these levels; so they would be considered as fixed effects in the model, as would the three oat varieties. However, the effects of the actual blocks and plots in the experiment are not of interest in themselves, but they do provide a means of estimating the variability of the more general population of blocks and plots in order to get an estimate of background variation against which to compare the fixed effects. Blocks and plots would therefore be defined as random effects. In this case, the fixed effects correspond to the effects used as treatments in ANOVA and the random effects would correspond to the blocking factors in ANOVA.

The fixed terms in the model are defined by a model formula supplied using the FIXED option, and the random model terms are defined by a model formula supplied by the RANDOM parameter. Thus, for example, the model for the split-plot experiment described above would be specified by

where Nitrogen and Variety are factors indicating the treatments applied to each unit, and Block, Wplot, and Subplot are factors indicating the block, wholeplot (within block) and subplot (within wholeplot) to which each unit belongs.

The default fixed model consists of just the constant term, which then becomes the grand mean. The constant term can be omitted by setting option CONSTANT=omit, provided a fixed model has been specified. If the random model is unset, only a single source of variation (the residual component called *units*) is used.

When covariates are included in the fixed or random models, by default they are automatically centred before analysis. However, you can set option CADJUST=none to specify that the uncentred covariates are to be used instead.

The FACTORIAL option is used to set a limit on the number of factors and variates allowed in each fixed term; any term containing more than that number is deleted from the model.

The SPLINE option can be used to generate cubic spline terms to be fitted as part of the random model. The smoothing parameter is estimated by REML and the fitted spline is interpreted as a BLUP (best linear unbiased predictor). If a term consists of a single variate, for example SPLINE=X, a cubic spline will be generated using all distinct covariate values present as knots, with weighting for replicate points. If factors are included, for example SPLINE=N.V.X where N and V are factors, separate cubic splines will be generated from the distinct covariate values present at each level of the combined set of factors. In this case, a common smoothing parameter will be fit to all levels unless option SPLESTIMATE=separate is used to generate a separate smoothing parameter for each factor level. When replicate observations are available at each covariate value, option SPLDEVIATIONS can be used to fit a separate effect at each knot point (i.e. a saturated model). This can be used to assess the fit of the spline.

For random terms, initial values for the ratio of variance components to the error variance (the gamma ratios) are supplied using the INITIAL parameter, and you can impose constraints on the variance components using either the RELATIONSHIP option or the CONSTRAINTS parameter. By default, all the gamma ratios have initial values of one. The CONSTRAINTS parameter can request that any variance component should be held positive or fixed at its initial value. The default setting, none, allows the variance components to become negative, provided the overall estimated variance-covariance matrix for the data remains positive definite. The RELATIONSHIP option can be used to define linear relationships between the variance components, for example that component A should be constrained to be twice component B.

Covariance models for random terms, including unknown parameters to be estimated, can be specified using the VSTRUCTURE directive.

The ABSORB option allows you to specify a factor from either the fixed or the random model to act as an absorbing factor for the model. Note that the absorbing factor is ignored for the AI algorithm with sparse matrix methods: that is, either when VSTRUCTURE is used to define covariance models or when the REML option METHOD=AI is set. The absorbing factor is used to divide the model terms into two groups; this partition is then used in calculations during the fitting process to reduce the size of the matrices that have to be inverted and stored. Use of an absorbing factor can therefore save computing time and data space. However, although exactly the same model is fitted when an absorbing factor is used, some of the standard errors are unavailable. A good choice of absorbing factor might be a factor with a large number of levels, or any factor whose effects and standard errors are not of interest.

Displays further output from a REML analysis.

The VDISPLAY directive allows further output to be produced from one or more REML analyses without having to repeat all the calculations.

Information from a REML analysis can be stored using the parameter SAVE in the REML statement for use in the SAVE parameter of VDISPLAY. Several SAVE structures can be specified, corresponding to the analyses of several different variates. By default, the save structure for the last y-variate analysed is saved automatically and used by VDISPLAY.

The options of VDISPLAY are the same as those that control output from REML: PRINT, PTERMS and PSE, plus the CHANNEL option which allows output to be directed to another output channel or into a text structure. The available settings of PRINT are identical to those in REML. For example, the commands

Copies information from a REML analysis into Genstat data structures.