# NAG CL Interfaceg02jgc (lmm_​init_​combine)

Settings help

CL Name Style:

## 1Purpose

g02jgc combines output from multiple calls to g02jfc or g02jcc.

## 2Specification

 #include
 void g02jgc (void *hlmm, double xrcomm[], Integer xlrcomm, Integer xicomm[], Integer xlicomm, const double yrcomm[], const Integer yicomm[], NagError *fail)
The function may be called by the names: g02jgc or nag_correg_lmm_init_combine.

## 3Description

Let ${D}_{x}$ and ${D}_{y}$ denote two sets of data, each with $m$ variables and ${n}_{x}$ and ${n}_{y}$ observations respectively. Let ${C}_{x}$ and ${C}_{y}$ denote two sets of communication arrays constructed by g02jfc or g02jcc from datasets ${D}_{x}$ and ${D}_{y}$ respectively. Then, given ${C}_{x}$ and ${C}_{y}$, g02jgc constructs a set of communication arrays, ${C}_{w}$, as if a dataset ${D}_{z}$, with $m$ variables and ${n}_{x}+{n}_{y}$ observations were supplied to g02jfc or g02jcc, with ${D}_{z}$ constructed as
 $Dz = ( Dx Dy ) .$
Splitting, and then recombining, the data in this manner allows for datasets with an arbitrarily large number of observations ($n$) to be analysed and the preprocessing routines, g02jfc or g02jcc, to be run in parallel.
It should be noted that, while the information in ${C}_{z}$, should be consistent with the information in the communication arrays obtained by supplying ${D}_{z}$ to g02jfc or g02jcc, the ordering of that information may change. In practice, this means that whilst an analysis run using a set of communication arrays constructed using g02jgc should give similar results to an analysis run using a set of communication arrays constructed directly from g02jfc or g02jcc they will not necessarily be identical. In addition, the order of the parameter estimates, $\nu$ and $\beta$ may differ.

None.

## 5Arguments

1: $\mathbf{hlmm}$void * Input
On entry: if the two sets of communication arrays were generated using g02jfc, then a G22 handle as generated by one of the calls to g02jfc.
If the two sets of communication arrays were generated using g02jcc, then this argument is not referenced and need not be set.
2: $\mathbf{xrcomm}\left[{\mathbf{xlrcomm}}\right]$double Communication Array
On entry: communication array as returned by g02jfc or g02jcc for the dataset, ${D}_{x}$.
On exit: communication array for the combined dataset, ${D}_{W}$.
3: $\mathbf{xlrcomm}$Integer Input
On entry: the dimension of the array xrcomm. Ideally this should be large enough to hold the information for the combined dataset ${D}_{w}$.
If xlicomm or xlrcomm are not large enough to hold the information for the combined dataset then ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NW_ARRAY_SIZE is returned and the minimum size for xicomm is returned in ${\mathbf{xicomm}}\left[0\right]$ and the minimum size for xrcomm in ${\mathbf{xicomm}}\left[1\right]$. In this case xicomm and xrcomm must be reallocated to these new sizes, preserving their contents, for example by allocating two new arrays and copying the old values across, and the function called again.
4: $\mathbf{xicomm}\left[{\mathbf{xlicomm}}\right]$Integer Communication Array
On entry: communication array as returned by g02jfc or g02jcc for the dataset, ${D}_{x}$.
On exit: communication array for the combined dataset, ${D}_{z}$.
5: $\mathbf{xlicomm}$Integer Input
On entry: the dimension of the array xicomm. Ideally this should be large enough to hold the information for the combined dataset ${D}_{w}$.
If xlicomm or xlrcomm are not large enough to hold the information for the combined dataset then ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NW_ARRAY_SIZE is returned and the minimum size for xicomm is returned in ${\mathbf{xicomm}}\left[0\right]$ and the minimum size for xrcomm in ${\mathbf{xicomm}}\left[1\right]$. In this case xicomm and xrcomm must be reallocated to these new sizes, preserving their contents, for example by allocating two new arrays and copying the old values across, and the function called again.
6: $\mathbf{yrcomm}\left[\mathit{dim}\right]$const double Communication Array
On entry: communication array as returned by g02jfc or g02jcc for the dataset, ${D}_{y}$.
7: $\mathbf{yicomm}\left[\mathit{dim}\right]$const Integer Communication Array
On entry: communication array as returned by g02jfc or g02jcc for the dataset, ${D}_{y}$.
8: $\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.
NE_ARRAY_SIZE
On entry, ${\mathbf{xlicomm}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{xlrcomm}}=⟨\mathit{\text{value}}⟩$
Constraint: ${\mathbf{xlicomm}}\ge ⟨\mathit{\text{value}}⟩$ and ${\mathbf{xlrcomm}}\ge ⟨\mathit{\text{value}}⟩$.
The communication arrays must be large enough to hold the information for the combined dataset ${D}_{w}$. In addition, ${\mathbf{xlicomm}}<2$ and so the minimum sizes cannot be returned.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_HANDLE
hlmm has not been initialized or is corrupt.
hlmm is not a G22 handle as generated by g02jfc.
NE_ILLEGAL_COMM
On entry, xicomm has not been initialized correctly.
On entry, yicomm has not been initialized correctly.
NE_INCOMPAT_PARAM
On entry, the information stored in xicomm and yicomm is not compatible.
Check that the same model was used when generating xicomm and yicomm.
On entry, ${\mathbf{xlicomm}}=⟨\mathit{\text{value}}⟩$ and $k=⟨\mathit{\text{value}}⟩$.
Constraint: xlicomm is not compatible with information stored in xicomm, was expecting ${\mathbf{xlicomm}}\ge k$.
On entry, ${\mathbf{xlrcomm}}=⟨\mathit{\text{value}}⟩$ and $k=⟨\mathit{\text{value}}⟩$.
Constraint: xlrcomm is not compatible with information stored in xicomm, was expecting ${\mathbf{xlrcomm}}\ge k$.
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.
NW_ARRAY_SIZE
On entry, ${\mathbf{xlicomm}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{xlrcomm}}=⟨\mathit{\text{value}}⟩$
Constraint: ${\mathbf{xlicomm}}\ge ⟨\mathit{\text{value}}⟩$ and ${\mathbf{xlrcomm}}\ge ⟨\mathit{\text{value}}⟩$.
The communication arrays must be large enough to hold the information for the combined dataset ${D}_{w}$. The minimum size for xicomm is returned in ${\mathbf{xicomm}}\left[0\right]$ and the minimum size for xrcomm in ${\mathbf{xicomm}}\left[1\right]$. The parameters xicomm and xrcomm must be reallocated to these new sizes, preserving their contents, and the function called again.

Not applicable.

## 8Parallelism and Performance

g02jgc is not threaded in any implementation.

The data preprocessing routines, g02jcc and g02jfc return the quantities, fnlsv, nff, rnlsv, nrf and nvpr. These values are data dependent and, therefore, the values obtained when preprocessing the datasets, ${D}_{x}$ and ${D}_{y}$ are likely to be different to those obtained if you had preprocessed the combined dataset ${D}_{z}$. In order to obtain these values for ${D}_{z}$ you can call g02zlc after the call to g02jgc. Valid values for optstr are:
• FNLSV, in which case g02zlc will return fnlsv for the combined dataset ${D}_{z}$.
• NFF, in which case g02zlc will return nff for the combined dataset ${D}_{z}$.
• RNLSV, in which case g02zlc will return rnlsv for the combined dataset ${D}_{z}$.
• NRF, in which case g02zlc will return nrf for the combined dataset ${D}_{z}$.
• NVPR, in which case g02zlc will return nvpr for the combined dataset ${D}_{z}$.

## 10Example

This example fits a random effects model to a simulated dataset. The dataset is split into four blocks, with $10,31$, $40$ and $9$ observations respectively. Each block is read in, processed by g02jfc and then combined using g02jgc. Once all four blocks have been processed the model is fitted using g02jhc and the results are printed.

### 10.1Program Text

Program Text (g02jgce.c)

### 10.2Program Data

Program Data (g02jgce.d)

### 10.3Program Results

Program Results (g02jgce.r)