naginterfaces.library.blgm.lm_​submodel

naginterfaces.library.blgm.lm_submodel(what, hform, hxdesc, lisx, lplab, lvinfo, lenlab=210)

lm_submodel produces labels for the columns of a design matrix, model parameters and a vector of column inclusion flags suitable for use with functions in submodule correg. Thus allowing for submodels to be fit using the same design matrix.

For full information please refer to the NAG Library document for g22yd

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/g22/g22ydf.html

Parameters

whatstr

Controls what labels are to be produced:

$what=\text{‘S'}$

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

$what=\text{‘X'}$

Labels for the design matrix $X$.

If $hxdesc$ was returned by correg.lmm_init in $\text{hlmm}$ then $X$ is the design matrix associated with the fixed parameters.

$what=\text{‘Z'}$

Labels for the design matrix $Z$.

If $hxdesc$ was returned by correg.lmm_init in $\text{hlmm}$ then $Z$ is the part of the design matrix associated with the random parameters.

$what=\text{‘V'}$

Labels for the variance components.

hformHandle

A G22 handle to the internal data structure containing a description of the required submodel $M_S$, as returned in $\text{hform}$ by lm_formula(). If $what!=\text{‘S'}$ $hform$ is not referenced and need not be set.

hxdescHandle

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

lisxint

Length of $isx$.

lplabint

The length of $plab$.

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

lvinfoint

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 _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 $lvinfo\ge 3$, $errno$ = 102 is returned and the required sizes for these arrays are returned in $vinfo\left[0\right]$, $vinfo\left[1\right]$ and $vinfo\left[2\right]$ respectively.

lenlabint, optional

Length of the strings allocated in $plab$. At most $lenlab$ characters will be written into each element of $plab$.

Returns

intcptstr

If $intcpt=\text{‘M'}$, in order to fit the model $M_S$ to $D$ using $X$, any analysis function should include an implicit mean effect (intercept term).

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

ipint

$p$, the number of parameters in the (sub)model, including the intercept if one is present. If $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 $lisx\ne 0$, if $intcpt=\text{‘Z'}$, $p={\sum }_{i=1}^{m_x}isx[i-1]$, otherwise $p={\sum }_{i=1}^{m_x}isx[i-1]+1$.

isxNone or int, ndarray, shape $\left(lisx\right)$

If $lisx\ne 0$, an array indicating which columns of the design matrix from the model specified in $hform$ are to be used.

$isx[j-1]=0$

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

$isx[j-1]=1$

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

If $lisx=0$, $isx$ is not referenced.

plabNone or str, ndarray, shape $(min(ip,lplab))$

If $lplab\ne 0$, the names associated with the $p$ parameters in the model.

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

If $intcpt=\text{‘M'}$, columns $plab\left[1\right]$ to $plab[p-1]$ are the corresponding column labels.

If a mean effect is present in $M_S$, the corresponding label is always in $plab\left[0\right]$.

If $lplab=0$, $plab$ is not referenced.

vinfoNone or int, ndarray, shape $\left(lvinfo\right)$

If $lvinfo\ne 0$, information encoding a description of the parameters in the model.

The encoding information can be extracted as follows:

1. Set $k=1$.

2. Iterate $j$ from $1$ to $p$.

   1. Set $b=vinfo[k-1]$.

   2. Increment $k$.

   3. Iterate $i$ from $1$ to $b$.

      1. Set $v_i=vinfo[k-1]$.

      2. Set $l_i=vinfo\left[k\right]$.

      3. Set $c_i=vinfo[k+1]$.

      4. Increment $k$ by $3$.

   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 lm_design_matrix(), are identified by the integers one to six respectively.

If $lvinfo=0$, $vinfo$ is not referenced.

Raises

NagValueError

(errno $11$)

On entry, $what=⟨value⟩$ was an illegal value.

(errno $12$)

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

(errno $21$)

$hform$ has not been initialized or is corrupt.

(errno $22$)

$hform$ is not a G22 handle as generated by lm_formula().

(errno $23$)

A variable name used when creating $hform$ is not present in $hxdesc$.

Variable name: $⟨value⟩$.

(errno $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.

(errno $25$)

The model and the design matrix are not consistent. The model includes a term not present in the design matrix.

Term: $⟨value⟩$.

(errno $26$)

The model and the design matrix are not consistent.

Term: $⟨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.

(errno $31$)

$hxdesc$ has not been initialized or is corrupt.

(errno $32$)

$hxdesc$ is not a G22 handle as generated by lm_design_matrix().

(errno $61$)

On entry, $lisx=⟨value⟩$ and $m_x=⟨value⟩$.

Constraint: $lisx=0$ or $lisx\ge m_x$.

(errno $81$)

On entry, $lplab=⟨value⟩$ and $p=⟨value⟩$.

Constraint: $lplab=0$ or $lplab\ge p$.

(errno $91$)

On entry, $plab$ is too short to hold the parameter labels. Long labels will be truncated.

The longest parameter label is $⟨value⟩$.

(errno $101$)

On entry, $lvinfo$ is too small.

$lvinfo=⟨value⟩$.

Constraint: $lvinfo=0$ or $lvinfo\ge ⟨value⟩$.

Warns

NagAlgorithmicWarning

(errno $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.

(errno $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.

(errno $33$)

$hxdesc$ has not passed through the model fitting function.

(errno $102$)

On entry, one or more of $lisx$, $lplab$ or $lvinfo$ are nonzero, but too small.

Minimum values are zero, or $⟨value⟩$, $⟨value⟩$ and $⟨value⟩$ respectively.

The minimum values are returned in the first three elements of $vinfo$.

Notes

lm_submodel is a utility function for use with lm_formula(), lm_describe_data() and lm_design_matrix(). It can be used to construct labels for the columns for an $n\times m_x$ design matrix, $X$, created by lm_design_matrix() and return additional input vectors and flags required by a number of NAG Library model fitting functions.

Many of the analysis functions that require a design matrix to be supplied allow submodels to be defined through the use of a vector of ones or zeros indicating whether a column of $X$ should be included or excluded from the analyses (see for example $\text{isx}$ in correg.linregm_fit or correg.glm_normal). This allows nested models to be fit without having to reconstructed the design matrix for each analysis.

Let $M$ denote a model constructed by lm_formula(), $D$ a data matrix as described by lm_describe_data() and $X$ be the corresponding design matrix constructed by lm_design_matrix() from $M$ and $D$. A different model, $M_S$ is a submodel of $M$ if each term in $M_S$, including the mean effect (intercept term) is also present in $M$.

If $M_S$ is a submodel of $M$, you can fit $M_S$ to $D$ using a design matrix whose columns are a subset of the columns of $X$.

See also

naginterfaces.library.examples.correg.glm_binomial_ex.main()

naginterfaces.library.examples.correg.lmm_init_combine_ex.main()