# NAG FL Interfaceg02jgf (lmm_​init_​combine)

## 1Purpose

g02jgf combines output from multiple calls to g02jff or g02jcf.

## 2Specification

Fortran Interface
 Subroutine g02jgf ( hlmm,
 Integer, Intent (In) :: xlrcomm, xlicomm, yicomm(*) Integer, Intent (Inout) :: xicomm(xlicomm), ifail Real (Kind=nag_wp), Intent (In) :: yrcomm(*) Real (Kind=nag_wp), Intent (Inout) :: xrcomm(xlrcomm) Type (c_ptr), Intent (In) :: hlmm
#include <nag.h>
 void g02jgf_ (void **hlmm, double xrcomm[], const Integer *xlrcomm, Integer xicomm[], const Integer *xlicomm, const double yrcomm[], const Integer yicomm[], Integer *ifail)
The routine may be called by the names g02jgf or nagf_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 g02jff or g02jcf from datasets ${D}_{x}$ and ${D}_{y}$ respectively. Then, given ${C}_{x}$ and ${C}_{y}$, g02jgf 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 g02jff or g02jcf, 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, g02jff or g02jcf, 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 g02jff or g02jcf, the ordering of that information may change. In practice, this means that whilst an analysis run using a set of communication arrays constructed using g02jgf should give similar results to an analysis run using a set of communication arrays constructed directly from g02jff or g02jcf they will not necessarily be identical. In addition, the order of the parameter estimates, $\nu$ and $\beta$ may differ.

None.

## 5Arguments

1: $\mathbf{hlmm}$Type (c_ptr) Input
On entry: if the two sets of communication arrays were generated using g02jff, then a G22 handle as generated by one of the calls to g02jff.
If the two sets of communication arrays were generated using g02jcf, then this argument is not referenced and need not be set.
2: $\mathbf{xrcomm}\left({\mathbf{xlrcomm}}\right)$Real (Kind=nag_wp) array Communication Array
On entry: communication array as returned by g02jff or g02jcf 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 as declared in the (sub)program from which g02jgf is called. 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{ifail}}={\mathbf{52}}$ is returned and the minimum size for xicomm is returned in ${\mathbf{xicomm}}\left(1\right)$ and the minimum size for xrcomm in ${\mathbf{xicomm}}\left(2\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 routine called again.
4: $\mathbf{xicomm}\left({\mathbf{xlicomm}}\right)$Integer array Communication Array
On entry: communication array as returned by g02jff or g02jcf 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 as declared in the (sub)program from which g02jgf is called. 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{ifail}}={\mathbf{52}}$ is returned and the minimum size for xicomm is returned in ${\mathbf{xicomm}}\left(1\right)$ and the minimum size for xrcomm in ${\mathbf{xicomm}}\left(2\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 routine called again.
6: $\mathbf{yrcomm}\left(*\right)$Real (Kind=nag_wp) array Communication Array
On entry: communication array as returned by g02jff or g02jcf for the dataset, ${D}_{y}$.
7: $\mathbf{yicomm}\left(*\right)$Integer array Communication Array
On entry: communication array as returned by g02jff or g02jcf for the dataset, ${D}_{y}$.
8: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, . If you are unfamiliar with this argument you should refer to Section 4 in the Introduction to the NAG Library FL Interface for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is $0$. When the value 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).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=11$
hlmm has not been initialized or is corrupt.
${\mathbf{ifail}}=12$
hlmm is not a G22 handle as generated by g02jff.
${\mathbf{ifail}}=31$
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$.
${\mathbf{ifail}}=41$
On entry, xicomm has not been initialized correctly.
${\mathbf{ifail}}=42$
On entry, the information stored in xicomm and yicomm is not compatible.
Check that the same model was used when generating xicomm and yicomm.
${\mathbf{ifail}}=51$
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$.
${\mathbf{ifail}}=52$
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(1\right)$ and the minimum size for xrcomm in ${\mathbf{xicomm}}\left(2\right)$. The parameters xicomm and xrcomm must be reallocated to these new sizes, preserving their contents, and the routine called again.
${\mathbf{ifail}}=53$
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.
${\mathbf{ifail}}=71$
On entry, yicomm has not been initialized correctly.
${\mathbf{ifail}}=-99$
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.

Not applicable.

## 8Parallelism and Performance

g02jgf is not threaded in any implementation.

The data preprocessing routines, g02jcf and g02jff 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 g02zlf after the call to g02jgf. Valid values for optstr are:
• FNLSV, in which case g02zlf will return fnlsv for the combined dataset ${D}_{z}$.
• NFF, in which case g02zlf will return nff for the combined dataset ${D}_{z}$.
• RNLSV, in which case g02zlf will return rnlsv for the combined dataset ${D}_{z}$.
• NRF, in which case g02zlf will return nrf for the combined dataset ${D}_{z}$.
• NVPR, in which case g02zlf 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 g02jff and then combined using g02jgf. Once all four blocks have been processed the model is fitted using g02jhf and the results are printed.

### 10.1Program Text

Program Text (g02jgfe.f90)

### 10.2Program Data

Program Data (g02jgfe.d)

### 10.3Program Results

Program Results (g02jgfe.r)