# NAG CL Interfaceg02jac (mixeff_​reml)

Note: this function is deprecated. Replaced by g02jfc followed by g02jhc.
For each of the routines g02jac, g02jbc, g02jcc, g02jdc and g02jec there is not a direct one-to-one replacement, rather they have been replaced with a new suite of routines. This new suite allows a linear mixed effects model to be specified using a modelling language; giving a more natural way of specifying the model, allowing interaction terms to be specified and means that it is no longer necessary to create dummy variables when the model contains categorical variables.
The new suite of routines consists of:
• g22ybc used to describe the dataset of interest. Calling this function allows labels to be assign to variables, which can then be used when specifying the model.
• g22yac multiple calls to this routine are used to specify the fixed and random part of the model. The model is specified using strings and a modelling language, for example the string: ${V}_{1}+{V}_{2}+{V}_{1}\dots {V}_{1}$ would specify a model with the main effects of variables ${V}_{1}$ and ${V}_{2}$ and the interaction term between them. The modelling language is explained in detail in Section 3 in g22yac.
• g02jfc pre-processes the dataset prior to calling the model fitting routine.
• g02jhc fits the model and returns the parameter estimates etc.
In addition to the routines listed above, the following can also be used:
• g02jgc combines information returned by multiple calls to g02jfc. This is useful for large problems as it allows the dataset to be split up into smaller subsets of data, pre-processing each one separately before combining them into a single set of information as if g02jfc had been called on the full dataset.
• g22ydc can be used to obtain labels for the parameter estimates returned by g02jhc.
• g22zmc can be used to set any optional arguments.
• g22znc can be used to return the value of any optional arguments.
By default, the model fitting routine, g02jhc, fits the linear mixed effects model using restricted maximum likelihood (REML). In order to fit the model using maximum likelihood (ML) you need to call the optional argument setting routine, g22zmc with optstr set to ${\mathbf{Likelihood}}=\mathrm{ML}$, between the call to g02jfc and the call to g02jhc.

Settings help

CL Name Style:

## 1Purpose

g02jac fits a linear mixed effects regression model using restricted maximum likelihood (REML).

## 2Specification

 #include
 void g02jac (Integer n, Integer ncol, const double dat[], Integer tddat, const Integer levels[], Integer yvid, Integer cwid, Integer nfv, const Integer fvid[], Integer fint, Integer nrv, const Integer rvid[], Integer nvpr, const Integer vpr[], Integer rint, Integer svid, double gamma[], Integer *nff, Integer *nrf, Integer *df, double *reml, Integer lb, double b[], double se[], Integer maxit, double tol, Integer *warn, NagError *fail)
The function may be called by the names: g02jac, nag_correg_mixeff_reml or nag_reml_mixed_regsn.

## 3Description

g02jac fits a model of the form:
 $y=Xβ+Zν+ε$
where
• $y$ is a vector of $n$ observations on the dependent variable,
• $X$ is a known $n×p$ design matrix for the fixed independent variables,
• $\beta$ is a vector of length $p$ of unknown fixed effects,
• $Z$ is a known $n×q$ design matrix for the random independent variables,
• $\nu$ is a vector of length $q$ of unknown random effects,
and
• $\epsilon$ is a vector of length $n$ of unknown random errors.
Both $\nu$ and $\epsilon$ are assumed to have a Gaussian distribution with expectation zero and
 $Var[ ν ε ] = [ G 0 0 R ]$
where $R={\sigma }_{R}^{2}I$, $I$ is the $n×n$ identity matrix and $G$ is a diagonal matrix. It is assumed that the random variables, $Z$, can be subdivided into $g\le q$ groups with each group being identically distributed with expectations zero and variance ${\sigma }_{i}^{2}$. The diagonal elements of matrix $G$, therefore, take one of the values $\left\{{\sigma }_{i}^{2}:i=1,2,\dots ,g\right\}$, depending on which group the associated random variable belongs to.
The model, therefore, contains three sets of unknowns, the fixed effects, $\beta$, the random effects $\nu$ and a vector of $g+1$ variance components, $\gamma$, where $\gamma =\left\{{\sigma }_{1}^{2},{\sigma }_{2}^{2},\dots ,{\sigma }_{g-1}^{2},{\sigma }_{g}^{2},{\sigma }_{R}^{2}\right\}$. Rather than working directly with $\gamma$, g02jac uses an iterative process to estimate ${\gamma }^{*}=\left\{{\sigma }_{1}^{2}/{\sigma }_{R}^{2},{\sigma }_{2}^{2}/{\sigma }_{R}^{2},\dots ,{\sigma }_{g-1}^{2}/{\sigma }_{R}^{2},{\sigma }_{g}^{2}/{\sigma }_{R}^{2},1\right\}$. Due to the iterative nature of the estimation a set of initial values, ${\gamma }_{0}$, for ${\gamma }^{*}$ is required. g02jac allows these initial values either to be supplied by you or calculated from the data using the minimum variance quadratic unbiased estimators (MIVQUE0) suggested by Rao (1972).
g02jac fits the model using a quasi-Newton algorithm to maximize the restricted log-likelihood function:
 $−2 l R = log(|V|) + (n-p) log( r ′ V-1r) + log| X ′ V-1X| + (n-p) (1+log(2π/(n-p)))$
where
 $V = ZG Z′ + R, r=y-Xb and b = ( X ′ V-1X) −1 X ′ V-1 y .$
Once the final estimates for ${\gamma }^{*}$ have been obtained, the value of ${\sigma }_{R}^{2}$ is given by:
 $σR2 = (r′V-1r) / (n-p) .$
Case weights, ${W}_{c}$, can be incorporated into the model by replacing ${X}^{\prime }X$ and ${Z}^{\prime }Z$ with ${X}^{\prime }{W}_{c}X$ and ${Z}^{\prime }{W}_{c}Z$ respectively, for a diagonal weight matrix ${W}_{c}$.
The log-likelihood, ${l}_{R}$, is calculated using the sweep algorithm detailed in Wolfinger et al. (1994).

## 4References

Goodnight J H (1979) A tutorial on the SWEEP operator The American Statistician 33(3) 149–158
Harville D A (1977) Maximum likelihood approaches to variance component estimation and to related problems JASA 72 320–340
Rao C R (1972) Estimation of variance and covariance components in a linear model J. Am. Stat. Assoc. 67 112–115
Stroup W W (1989) Predictable functions and prediction space in the mixed model procedure Applications of Mixed Models in Agriculture and Related Disciplines Southern Cooperative Series Bulletin No. 343 39–48
Wolfinger R, Tobias R and Sall J (1994) Computing Gaussian likelihoods and their derivatives for general linear mixed models SIAM Sci. Statist. Comput. 15 1294–1310

## 5Arguments

1: $\mathbf{n}$Integer Input
On entry: $n$, the number of observations.
Constraint: ${\mathbf{n}}\ge 1$.
2: $\mathbf{ncol}$Integer Input
On entry: the number of columns in the data matrix, DAT.
Constraint: ${\mathbf{ncol}}\ge 1$.
3: $\mathbf{dat}\left[{\mathbf{n}}×{\mathbf{tddat}}\right]$const double Input
Note: where ${\mathbf{DAT}}\left(i,j\right)$ appears in this document, it refers to the array element ${\mathbf{dat}}\left[\left(i-1\right)×{\mathbf{tddat}}+j-1\right]$.
On entry: array containing all of the data. For the $i$th observation:
• ${\mathbf{DAT}}\left(i,{\mathbf{yvid}}\right)$ holds the dependent variable, $y$;
• if ${\mathbf{cwid}}\ne 0$, ${\mathbf{DAT}}\left(i,{\mathbf{cwid}}\right)$ holds the case weights;
• if ${\mathbf{svid}}\ne 0$, ${\mathbf{DAT}}\left(i,{\mathbf{svid}}\right)$ holds the subject variable.
The remaining columns hold the values of the independent variables.
Constraints:
• if ${\mathbf{cwid}}\ne 0$, ${\mathbf{DAT}}\left(i,{\mathbf{cwid}}\right)\ge 0.0$;
• if ${\mathbf{levels}}\left[j-1\right]\ne 1$, $1\le {\mathbf{DAT}}\left(i,j\right)\le {\mathbf{levels}}\left[j-1\right]$.
4: $\mathbf{tddat}$Integer Input
On entry: the stride separating matrix column elements in the array dat.
Constraint: ${\mathbf{tddat}}\ge {\mathbf{ncol}}$.
5: $\mathbf{levels}\left[{\mathbf{ncol}}\right]$const Integer Input
On entry: ${\mathbf{levels}}\left[i-1\right]$ contains the number of levels associated with the $i$th variable of the data matrix DAT. If this variable is continuous or binary (i.e., only takes the values zero or one) then ${\mathbf{levels}}\left[i-1\right]$ should be $1$; if the variable is discrete then ${\mathbf{levels}}\left[i-1\right]$ is the number of levels associated with it and ${\mathbf{DAT}}\left(\mathit{j},i\right)$ is assumed to take the values $1$ to ${\mathbf{levels}}\left[i-1\right]$, for $\mathit{j}=1,2,\dots ,{\mathbf{n}}$.
Constraint: ${\mathbf{levels}}\left[\mathit{i}-1\right]\ge 1$, for $\mathit{i}=1,2,\dots ,{\mathbf{ncol}}$.
6: $\mathbf{yvid}$Integer Input
On entry: the column of DAT holding the dependent, $y$, variable.
Constraint: $1\le {\mathbf{yvid}}\le {\mathbf{ncol}}$.
7: $\mathbf{cwid}$Integer Input
On entry: the column of DAT holding the case weights.
If ${\mathbf{cwid}}=0$, no weights are used.
Constraint: $0\le {\mathbf{cwid}}\le {\mathbf{ncol}}$.
8: $\mathbf{nfv}$Integer Input
On entry: the number of independent variables in the model which are to be treated as being fixed.
Constraint: $0\le {\mathbf{nfv}}<{\mathbf{ncol}}$.
9: $\mathbf{fvid}\left[{\mathbf{nfv}}\right]$const Integer Input
On entry: the columns of the data matrix DAT holding the fixed independent variables with ${\mathbf{fvid}}\left[i-1\right]$ holding the column number corresponding to the $i$th fixed variable.
Constraint: $1\le {\mathbf{fvid}}\left[\mathit{i}-1\right]\le {\mathbf{ncol}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{nfv}}$.
10: $\mathbf{fint}$Integer Input
On entry: flag indicating whether a fixed intercept is included (${\mathbf{fint}}=1$).
Constraint: ${\mathbf{fint}}=0$ or $1$.
11: $\mathbf{nrv}$Integer Input
On entry: the number of independent variables in the model which are to be treated as being random.
Constraints:
• $0\le {\mathbf{nrv}}<{\mathbf{ncol}}$;
• ${\mathbf{nrv}}+{\mathbf{rint}}>0$.
12: $\mathbf{rvid}\left[{\mathbf{nrv}}\right]$const Integer Input
On entry: the columns of the data matrix ${\mathbf{dat}}$ holding the random independent variables with ${\mathbf{rvid}}\left[i-1\right]$ holding the column number corresponding to the $i$th random variable.
Constraint: $1\le {\mathbf{rvid}}\left[\mathit{i}-1\right]\le {\mathbf{ncol}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{nrv}}$.
13: $\mathbf{nvpr}$Integer Input
On entry: if ${\mathbf{rint}}=1$ and ${\mathbf{svid}}\ne 0$, nvpr is the number of variance components being $\text{estimated}-2$, ($g-1$), else ${\mathbf{nvpr}}=g$.
If ${\mathbf{nrv}}=0$, ${\mathbf{nvpr}}$ is not referenced.
Constraint: if ${\mathbf{nrv}}\ne 0$, $1\le {\mathbf{nvpr}}\le {\mathbf{nrv}}$.
14: $\mathbf{vpr}\left[{\mathbf{nrv}}\right]$const Integer Input
On entry: ${\mathbf{vpr}}\left[i-1\right]$ holds a flag indicating the variance of the $i$th random variable. The variance of the $i$th random variable is ${\sigma }_{j}^{2}$, where $j={\mathbf{vpr}}\left[i-1\right]+1$ if ${\mathbf{rint}}=1$ and ${\mathbf{svid}}\ne 0$ and $j={\mathbf{vpr}}\left[i-1\right]$ otherwise. Random variables with the same value of $j$ are assumed to be taken from the same distribution.
Constraint: $1\le {\mathbf{vpr}}\left[\mathit{i}-1\right]\le {\mathbf{nvpr}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{nrv}}$.
15: $\mathbf{rint}$Integer Input
On entry: flag indicating whether a random intercept is included (${\mathbf{rint}}=1$).
If ${\mathbf{svid}}=0$, rint is not referenced.
Constraint: ${\mathbf{rint}}=0$ or $1$.
16: $\mathbf{svid}$Integer Input
On entry: the column of DAT holding the subject variable.
If ${\mathbf{svid}}=0$, no subject variable is used.
Specifying a subject variable is equivalent to specifying the interaction between that variable and all of the random-effects. Letting the notation ${Z}_{1}×{Z}_{S}$ denote the interaction between variables ${Z}_{1}$ and ${Z}_{S}$, fitting a model with ${\mathbf{rint}}=0$, random-effects ${Z}_{1}+{Z}_{2}$ and subject variable ${Z}_{S}$ is equivalent to fitting a model with random-effects ${Z}_{1}×{Z}_{S}+{Z}_{2}×{Z}_{S}$ and no subject variable. If ${\mathbf{rint}}=1$ the model is equivalent to fitting ${Z}_{S}+{Z}_{1}×{Z}_{S}+{Z}_{2}×{Z}_{S}$ and no subject variable.
Constraint: $0\le {\mathbf{svid}}\le {\mathbf{ncol}}$.
17: $\mathbf{gamma}\left[{\mathbf{nvpr}}+2\right]$double Input/Output
On entry: holds the initial values of the variance components, ${\gamma }_{0}$, with ${\mathbf{gamma}}\left[\mathit{i}-1\right]$ the initial value for ${\sigma }_{\mathit{i}}^{2}/{\sigma }_{R}^{2}$, for $\mathit{i}=1,2,\dots ,g$. If ${\mathbf{rint}}=1$ and ${\mathbf{svid}}\ne 0$, $g={\mathbf{nvpr}}+1$, else $g={\mathbf{nvpr}}$.
If ${\mathbf{gamma}}\left[0\right]=-1.0$, the remaining elements of gamma are ignored and the initial values for the variance components are estimated from the data using MIVQUE0.
On exit: ${\mathbf{gamma}}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,g$, holds the final estimate of ${\sigma }_{\mathit{i}}^{2}$ and ${\mathbf{gamma}}\left[g\right]$ holds the final estimate for ${\sigma }_{R}^{2}$.
Constraint: ${\mathbf{gamma}}\left[0\right]=-1.0$ or ${\mathbf{gamma}}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,g$.
18: $\mathbf{nff}$Integer * Output
On exit: the number of fixed effects estimated (i.e., the number of columns, $p$, in the design matrix $X$).
19: $\mathbf{nrf}$Integer * Output
On exit: the number of random effects estimated (i.e., the number of columns, $q$, in the design matrix $Z$).
20: $\mathbf{df}$Integer * Output
On exit: the degrees of freedom.
21: $\mathbf{reml}$double * Output
On exit: $-2{l}_{R}\left(\stackrel{^}{\gamma }\right)$ where ${l}_{R}$ is the log of the restricted maximum likelihood calculated at $\stackrel{^}{\gamma }$, the estimated variance components returned in gamma.
22: $\mathbf{lb}$Integer Input
On entry: the size of the array b.
Constraint: ${\mathbf{lb}}\ge {\mathbf{fint}}+\sum _{i=1}^{{\mathbf{nfv}}}\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{levels}}\left[{\mathbf{fvid}}\left[i-1\right]-1\right]-1,1\right)+{L}_{S}×\left({\mathbf{rint}}+\sum _{i=1}^{{\mathbf{nrv}}}{\mathbf{levels}}\left[{\mathbf{rvid}}\left[i-1\right]-1\right]\right)$ where ${L}_{S}={\mathbf{levels}}\left[{\mathbf{svid}}-1\right]$ if ${\mathbf{svid}}\ne 0$ and $1$ otherwise.
23: $\mathbf{b}\left[{\mathbf{lb}}\right]$double Output
On exit: the parameter estimates, $\left(\beta ,\nu \right)$, with the first nff elements of b containing the fixed effect parameter estimates, $\beta$ and the next nrf elements of b containing the random effect parameter estimates, $\nu$.
Fixed effects
If ${\mathbf{fint}}=1$, ${\mathbf{b}}\left[0\right]$ contains the estimate of the fixed intercept. Let ${L}_{i}$ denote the number of levels associated with the $i$th fixed variable, that is ${L}_{i}={\mathbf{levels}}\left[{\mathbf{fvid}}\left[i-1\right]-1\right]$. Define
• if ${\mathbf{fint}}=1$, ${F}_{1}=2$ else if ${\mathbf{fint}}=0$, ${F}_{1}=1$;
• ${F}_{i+1}={F}_{i}+\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({L}_{i}-1,1\right)$, $i\ge 1$.
Then for $i=1,2,\dots ,{\mathbf{nfv}}$:
• if ${L}_{i}>1$, ${\mathbf{b}}\left[{F}_{i}+\mathit{j}-3\right]$ contains the parameter estimate for the $\mathit{j}$th level of the $i$th fixed variable, for $\mathit{j}=2,3,\dots ,{L}_{i}$;
• if ${L}_{i}\le 1$, ${\mathbf{b}}\left[{F}_{i}-1\right]$ contains the parameter estimate for the $i$th fixed variable.
Random effects
Redefining ${L}_{i}$ to denote the number of levels associated with the $i$th random variable, that is ${L}_{i}={\mathbf{levels}}\left[{\mathbf{rvid}}\left[i-1\right]-1\right]$. Define
• if ${\mathbf{rint}}=1$, ${R}_{1}=2$ else if ${\mathbf{rint}}=0$, ${R}_{1}=1$;
${R}_{i+1}={R}_{i}+{L}_{i}$, $i\ge 1$.
Then for $i=1,2,\dots ,{\mathbf{nrv}}$:
• if ${\mathbf{svid}}=0$,
• if ${L}_{i}>1$, ${\mathbf{b}}\left[{\mathbf{nff}}+{R}_{i}+\mathit{j}-2\right]$ contains the parameter estimate for the $\mathit{j}$th level of the $i$th random variable, for $\mathit{j}=1,2,\dots ,{L}_{i}$;
• if ${L}_{i}\le 1$, ${\mathbf{b}}\left[{\mathbf{nff}}+{R}_{i}-1\right]$ contains the parameter estimate for the $i$th random variable;
• if ${\mathbf{svid}}\ne 0$,
• let ${L}_{S}$ denote the number of levels associated with the subject variable, that is ${L}_{S}={\mathbf{levels}}\left[{\mathbf{svid}}-1\right]$;
• if ${L}_{i}>1$, ${\mathbf{b}}\left[{\mathbf{nff}}+\left(\mathit{s}-1\right){L}_{S}+{R}_{i}+\mathit{j}-2\right]$ contains the parameter estimate for the interaction between the $\mathit{s}$th level of the subject variable and the $\mathit{j}$th level of the $i$th random variable, for $\mathit{s}=1,2,\dots ,{L}_{S}$ and $\mathit{j}=1,2,\dots ,{L}_{i}$;
• if ${L}_{i}\le 1$, ${\mathbf{b}}\left[{\mathbf{nff}}+\left(\mathit{s}-1\right){L}_{S}+{R}_{i}-1\right]$ contains the parameter estimate for the interaction between the $\mathit{s}$th level of the subject variable and the $i$th random variable, for $\mathit{s}=1,2,\dots ,{L}_{S}$;
• if ${\mathbf{rint}}=1$, ${\mathbf{b}}\left[{\mathbf{nff}}\right]$ contains the estimate of the random intercept.
24: $\mathbf{se}\left[{\mathbf{lb}}\right]$double Output
On exit: the standard errors of the parameter estimates given in b.
25: $\mathbf{maxit}$Integer Input
On entry: the maximum number of iterations.
If ${\mathbf{maxit}}<0$, the default value of $100$ is used.
If ${\mathbf{maxit}}=0$, the parameter estimates $\left(\beta ,\nu \right)$ and corresponding standard errors are calculated based on the value of ${\gamma }_{0}$ supplied in gamma.
26: $\mathbf{tol}$double Input
On entry: the tolerance used to assess convergence.
If ${\mathbf{tol}}\le 0.0$, the default value of ${\epsilon }^{0.7}$ is used, where $\epsilon$ is the machine precision.
27: $\mathbf{warn}$Integer * Output
On exit: is set to $1$ if a variance component was estimated to be a negative value during the fitting process. Otherwise warn is set to $0$.
If ${\mathbf{warn}}=1$, the negative estimate is set to zero and the estimation process allowed to continue.
28: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
On entry, invalid data: categorical variable with value greater than that specified in levels.
NE_CONV
Routine failed to converge in maxit iterations: ${\mathbf{maxit}}=⟨\mathit{\text{value}}⟩$.
See Section 10 for advice.
NE_FAIL_TOL
Routine failed to converge to specified tolerance: ${\mathbf{tol}}=⟨\mathit{\text{value}}⟩$.
See Section 10 for advice.
NE_INT
On entry, ${\mathbf{fint}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{fint}}=0$ or $1$.
On entry, lb too small: ${\mathbf{lb}}=⟨\mathit{\text{value}}⟩$.
On entry, ${\mathbf{levels}}\left[\mathit{i}\right]<1$, for at least one $\mathit{i}$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: number of observations with nonzero weights must be greater than one.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 1$.
On entry, ${\mathbf{ncol}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{fvid}}\left[i\right]\le {\mathbf{ncol}}$, for all $i$.
On entry, ${\mathbf{ncol}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{rvid}}\left[i\right]\le {\mathbf{ncol}}$, for all $i$.
On entry, ${\mathbf{ncol}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ncol}}\ge 1$.
On entry, ${\mathbf{nvpr}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{vpr}}\left[i\right]\le {\mathbf{nvpr}}$, for all $i$.
On entry, ${\mathbf{rint}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{rint}}=0$ or $1$.
NE_INT_2
On entry, ${\mathbf{cwid}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ncol}}=⟨\mathit{\text{value}}⟩$.
Constraint: $0\le {\mathbf{cwid}}\le {\mathbf{ncol}}$ and any supplied weights must be $\text{}\ge 0.0$.
On entry, ${\mathbf{nfv}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ncol}}=⟨\mathit{\text{value}}⟩$.
Constraint: $0\le {\mathbf{nfv}}<{\mathbf{ncol}}$.
On entry, ${\mathbf{nrv}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ncol}}=⟨\mathit{\text{value}}⟩$.
Constraint: $0\le {\mathbf{nrv}}<{\mathbf{ncol}}$ and ${\mathbf{nrv}}+{\mathbf{rint}}>0$.
On entry, ${\mathbf{nvpr}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{nrv}}=⟨\mathit{\text{value}}⟩$.
Constraint: $0\le {\mathbf{nvpr}}\le {\mathbf{nrv}}$ and (${\mathbf{nrv}}\ne 0$ or ${\mathbf{nvpr}}\ge 1$).
On entry, ${\mathbf{svid}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ncol}}=⟨\mathit{\text{value}}⟩$.
Constraint: $0\le {\mathbf{svid}}\le {\mathbf{ncol}}$.
On entry, ${\mathbf{tddat}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ncol}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{tddat}}\ge {\mathbf{ncol}}$.
On entry, ${\mathbf{yvid}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ncol}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{yvid}}\le {\mathbf{ncol}}$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_REAL
On entry, ${\mathbf{gamma}}\left[i\right]<0.0$, for at least one $i$.
NE_ZERO_DOF_ERROR
Degrees of freedom $<1$: ${\mathbf{df}}=⟨\mathit{\text{value}}⟩$.
This is due to the number of parameters exceeding the effective number of observations.

## 7Accuracy

The accuracy of the results can be adjusted through the use of the tol argument.

## 8Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
g02jac is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g02jac makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

Wherever possible any block structure present in the design matrix $Z$ should be modelled through a subject variable, specified via svid, rather than being explicitly entered into dat.
g02jac uses an iterative process to fit the specified model and for some problems this process may fail to converge (see ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_CONV or NE_FAIL_TOL). If the function fails to converge then the maximum number of iterations (see maxit) or tolerance (see tol) may require increasing; try a different starting estimate in gamma. Alternatively, the model can be fit using maximum likelihood (see g02jbc) or using the noniterative MIVQUE0.
To fit the model just using MIVQUE0, the first element of gamma should be set to $-1.0$ and maxit should be set to zero.
Although the quasi-Newton algorithm used in g02jac tends to require more iterations before converging compared to the Newton–Raphson algorithm recommended by Wolfinger et al. (1994), it does not require the second derivatives of the likelihood function to be calculated and consequentially takes significantly less time per iteration.

## 10Example

The following dataset is taken from Stroup (1989) and arises from a balanced split-plot design with the whole plots arranged in a randomized complete block-design.
In this example the full design matrix for the random independent variable, $Z$, is given by:
 $Z = ( 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 )$
 $= ( A 0 0 0 0 A 0 0 0 0 A 0 0 0 0 A A 0 0 0 0 A 0 0 0 0 A 0 0 0 0 A ) ,$ (1)
where
 $A = ( 1 1 0 0 1 0 1 0 1 0 0 1 ) .$
The block structure evident in (1) is modelled by specifying a four-level subject variable, taking the values $\left\{1,1,1,2,2,2,3,3,3,4,4,4,1,1,1,2,2,2,3,3,3,4,4,4\right\}$. The first column of $1\mathrm{s}$ is added to $A$ by setting ${\mathbf{rint}}=1$. The remaining columns of $A$ are specified by a three level factor, taking the values, $\left\{1,2,3,1,2,3,1,\dots \right\}$.

### 10.1Program Text

Program Text (g02jace.c)

### 10.2Program Data

Program Data (g02jace.d)

### 10.3Program Results

Program Results (g02jace.r)