NAG FL Interface
g22ydf (lm_​submodel)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{what}$ – Character(*) Input

On entry: controls what labels are to be produced:

$\mathbf{what}=\text{'S'}$

Labels for a submodel are required. The submodel must be supplied in hform.

$\mathbf{what}=\text{'X'}$

Labels for the design matrix $X$.

If hxdesc was returned by g02jff in hlmm then $X$ is the design matrix associated with the fixed parameters.

$\mathbf{what}=\text{'Z'}$

Labels for the design matrix $Z$.

If hxdesc was returned by g02jff in hlmm then $Z$ is the part of the design matrix associated with the random parameters.

$\mathbf{what}=\text{'V'}$

Labels for the variance components.

Constraints:

• if hxdesc was returned by g02jff in hlmm, $\mathbf{what}=\text{'X'}$, $\text{'Z'}$ or $\text{'V'}$;
• otherwise $\mathbf{what}=\text{'S'}$ or $\text{'X'}$.

2: $\mathbf{hform}$ – Type (c_ptr) Input

On entry: a G22 handle to the internal data structure containing a description of the required submodel ${\mathcal{M}}_S$, as returned in hform by g22yaf. If $\mathbf{what}\ne \text{'S'}$ hform is not referenced and need not be set.

3: $\mathbf{hxdesc}$ – Type (c_ptr) Input

On entry: a G22 handle to the internal data structure containing a description of the design matrix, $D$.

Constraint: a G22 handle as returned by g22ycf in hxdesc or by g02jff and g02jgf in hlmm..

4: $\mathbf{intcpt}$ – Character(*) Output

On exit: if $\mathbf{intcpt}=\text{'M'}$, in order to fit the model ${\mathcal{M}}_S$ to $D$ using $X$, any analysis routine should include an implicit mean effect (intercept term).

$\mathbf{intcpt}=\text{'Z'}$, if ${\mathcal{M}}_S$ does not include a mean effect or the mean effect has been explicitly included in the design matrix.

5: $\mathbf{ip}$ – Integer Output

On exit: $p$, the number of parameters in the (sub)model, including the intercept if one is present. If $\mathbf{what}=\text{'S'}$, then the submodel is the one specified in hform otherwise the model is the one used when defining the design matrix described in hxdesc.

If $\mathbf{lisx}\ne 0$, if $\mathbf{intcpt}=\text{'Z'}$, $p={\sum }_{i=1}^{m_x}\mathbf{isx}\left(i\right)$, otherwise $p={\sum }_{i=1}^{m_x}\mathbf{isx}\left(i\right)+1$.

6: $\mathbf{lisx}$ – Integer Input

On entry: length of isx.

Constraint: $\mathbf{lisx}=0$ or $\mathbf{lisx}\ge m_x$, where $m_x$ is the number of columns in the design matrix $X$.

7: $\mathbf{isx}\left(\mathbf{lisx}\right)$ – Integer array Output

On exit: if $\mathbf{lisx}\ne 0$, an array indicating which columns of the design matrix from the model specified in hform are to be used.

$\mathbf{isx}\left(j\right)=0$

The $j$th column of the design matrix, $X$, should not be included in the analysis.

$\mathbf{isx}\left(j\right)=1$

The $j$th column of the design matrix, $X$, should be included in the analysis.

If $\mathbf{lisx}=0$, isx is not referenced.

8: $\mathbf{lplab}$ – Integer Input

On entry: the length of plab.

As $p\le m_x+1$, if labels are required, using $\mathbf{lplab}=m_x+1$ will always be sufficient.

Constraint: $\mathbf{lplab}=0$ or $\mathbf{lplab}\ge p$.

9: $\mathbf{plab}\left(\mathbf{lplab}\right)$ – Character(*) array Output

On exit: if $\mathbf{lplab}\ne 0$, the names associated with the $p$ parameters in the model.

If $\mathbf{intcpt}=\text{'Z'}$, the labels in plab are also the labels for the columns of design matrix used in the analysis.

If $\mathbf{intcpt}=\text{'M'}$, columns $\mathbf{plab}\left(2\right)$ to $\mathbf{plab}\left(p\right)$ are the corresponding column labels.

If a mean effect is present in $M_S$, the corresponding label is always in $\mathbf{plab}\left(1\right)$.

If $\mathbf{lplab}=0$, plab is not referenced.

10: $\mathbf{lvinfo}$ – Integer Input

On entry: the length of vinfo.

Let $n_T$ denote the number of terms in $M_S$, $n_{Tt}$ denote the number of variables in the $t$th term and $m_{xt}$ denote the number of columns of $X$ corresponding to the $t$th term. The required size of vinfo, denoted $a$ is given by:

$$a=\sum _{\mathit{t}=1}^{n_T}{m}_{xt}(1+3n_{Tt})\text{.}$$

If the model includes a mean effect, $a$ should be incremented by one.

The values $n_T$, $n_{Tt}$ and $m_{xt}$ are not trivial to calculate as they require the formula describing the model to be fully expanded and the contrast / dummy variable encoding to be known. Therefore, if lisx, lplab or lvinfo are too small and $\mathbf{lvinfo}\ge 3$, $\mathbf{ifail}=\mathbf{102}$ is returned and the required sizes for these arrays are returned in $\mathbf{vinfo}\left(1\right)$, $\mathbf{vinfo}\left(2\right)$ and $\mathbf{vinfo}\left(3\right)$ respectively.

Constraint: $\mathbf{lvinfo}=0$ or $\mathbf{lvinfo}\ge a$.

11: $\mathbf{vinfo}\left(\mathbf{lvinfo}\right)$ – Integer array Output

On exit: if $\mathbf{lvinfo}\ne 0$, information encoding a description of the parameters in the model.

The encoding information can be extracted as follows:

1. (i)Set $k=1$.
2. (ii)Iterate $j$ from $1$ to $p$.
   1. 1.Set $b=\mathbf{vinfo}\left(k\right)$.
   2. 2.Increment $k$.
   3. 3.Iterate $i$ from $1$ to $b$.
      1. (a)Set $v_i=\mathbf{vinfo}\left(k\right)$.
      2. (b)Set $l_i=\mathbf{vinfo}\left(k+1\right)$.
      3. (c)Set $c_i=\mathbf{vinfo}\left(k+2\right)$.
      4. (d)Increment $k$ by $3$.
   4. 4.The $j$th model parameter corresponds to the interaction between the $b$ variables held in columns $v_1,v_2,\dots ,v_b$ of $D$. Therefore, $b=1$ indicates a main effect, $b=2$ a two-way interaction, etc..
      If $b=0$, the $j$th model parameter corresponds to the mean effect.
      If $l_i=0$, the corresponding variable $v_i$ is binary, ordinal or continuous. Otherwise, $l_i$ is the level for the corresponding variable for model parameter $j$.
      $c_i$ is a numeric flag indicating the contrast used in the case of a categorical variable. With $c_i=0$ indicating that dummy variables were used for variable $v_i$ in this term. The remaining six types of contrast; treatment contrasts (with respect to the first and last levels), sum contrasts (with respect to the first and last levels), Helmert contrasts and polynomial contrasts, as described in g22ycf, are identified by the integers one to six respectively.

If $\mathbf{lvinfo}=0$, vinfo is not referenced.

12: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $\mathrm{-1}$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $\mathrm{-1}$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $\mathrm{-1}$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.

On exit: $\mathbf{ifail}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

$\mathbf{ifail}=11$

On entry, $\mathbf{what}=⟨\mathit{\text{value}}⟩$ was an illegal value.

$\mathbf{ifail}=12$

Supplied value of what is not valid for the G22 handle supplied in hxdesc.

$\mathbf{ifail}=21$

hform has not been initialized or is corrupt.

$\mathbf{ifail}=22$

hform is not a G22 handle as generated by g22yaf.

$\mathbf{ifail}=23$

A variable name used when creating hform is not present in hxdesc.
Variable name: $⟨\mathit{\text{value}}⟩$.

$\mathbf{ifail}=24$

The model and the design matrix are not consistent. The design matrix was constructed in the presence of a mean effect and the model does not include a mean effect.

$\mathbf{ifail}=25$

The model and the design matrix are not consistent. The model includes a term not present in the design matrix.
Term: $⟨\mathit{\text{value}}⟩$.

$\mathbf{ifail}=26$

The model and the design matrix are not consistent.
Term: $⟨\mathit{\text{value}}⟩$.
This is likely due to the design matrix being constructed in the presence of either a mean effect or main effect that is not present in the model.

$\mathbf{ifail}=27$

The model and the design matrix are not consistent. The model specifies different contrasts to those used when the design matrix was constructed. The contrasts specified in hform will be ignored.

$\mathbf{ifail}=28$

The model may not be as expected.
This is due to the model not containing the categorical variable adjusted to account for no mean effect when the design matrix was constructed.
Check the value of ip is as expected. If it is not then you will need to call g22ycf to reconstruct the design matrix for the model of interest.

$\mathbf{ifail}=31$

hxdesc has not been initialized or is corrupt.

$\mathbf{ifail}=32$

hxdesc is not a G22 handle as generated by g22ycf.

$\mathbf{ifail}=33$

hxdesc has not passed through the model fitting routine. The information returned by this routine may not be consistent with results returned from the model fitting routine if the data has been updated after the creation of hxdesc.

$\mathbf{ifail}=61$

On entry, $\mathbf{lisx}=⟨\mathit{\text{value}}⟩$ and $m_x=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lisx}=0$ or $\mathbf{lisx}\ge m_x$.

$\mathbf{ifail}=81$

On entry, $\mathbf{lplab}=⟨\mathit{\text{value}}⟩$ and $p=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lplab}=0$ or $\mathbf{lplab}\ge p$.

$\mathbf{ifail}=91$

On entry, plab is too short to hold the parameter labels. Long labels will be truncated.
The longest parameter label is $⟨\mathit{\text{value}}⟩$.

$\mathbf{ifail}=101$

On entry, lvinfo is too small.
$\mathbf{lvinfo}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lvinfo}=0$ or $\mathbf{lvinfo}\ge ⟨\mathit{\text{value}}⟩$.

$\mathbf{ifail}=102$

On entry, one or more of lisx, lplab or lvinfo are nonzero, but too small.
Minimum values are zero, or $⟨\mathit{\text{value}}⟩$, $⟨\mathit{\text{value}}⟩$ and $⟨\mathit{\text{value}}⟩$ respectively.
The minimum values are returned in the first three elements of vinfo.

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results