NAG Library Routine Document

G01ANF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     IND – INTEGERInput/Output

On entry: indicates the action required in the current call to G01ANF.

$\mathbf{IND}=0$

Return the required length of RCOMM and ICOMM in $\mathbf{ICOMM}\left(1\right)$ and $\mathbf{ICOMM}\left(2\right)$ respectively. N and EPS must be set and LICOMM must be at least $2$.

$\mathbf{IND}=1$

Initialise the communication arrays and process the first NB values from the data stream as supplied in RV.

$\mathbf{IND}=2$

Process the next block of NB values from the data stream. The calling program must update RV and (if required) NB, and re-enter G01ANF with all other parameters unchanged.

$\mathbf{IND}=3$

Calculate the NQ $\epsilon$-approximate quantiles specified in Q. The calling program must set Q and NQ and re-enter G01ANF with all other parameters unchanged. This option can be chosen only when $\mathbf{NP}\ge ⌈\exp \left(1.0\right)/\mathbf{EPS}⌉$.

On exit: indicates output from a successful call.

$\mathbf{IND}=1$

Lengths of RCOMM and ICOMM have been returned in $\mathbf{ICOMM}\left(1\right)$ and $\mathbf{ICOMM}\left(2\right)$ respectively.

$\mathbf{IND}=2$

G01ANF has processed NP data points and expects to be called again with additional data (i.e., $\mathbf{NP}<\mathbf{N}$).

$\mathbf{IND}=3$

G01ANF has returned the requested $\epsilon$-approximate quantiles in QV. These quantiles are based on NP data points.

$\mathbf{IND}=4$

Routine has processed all N data points (i.e., $\mathbf{NP}=\mathbf{N}$).

Constraint: on entry $\mathbf{IND}=0$, $1$, $2$ or $3$.

2:     N – INTEGERInput

On entry: $n$, the total number of values in the data stream.

Constraint: $\mathbf{N}>0$.

3:     RV($*$) – REAL (KIND=nag_wp) arrayInput

Note: the dimension of the array RV must be at least $\mathbf{NB}$ if $\mathbf{IND}=1$ or $2$.

On entry: if $\mathbf{IND}=1$ or $2$, the vector containing the current block of data, otherwise RV is not referenced.

4:     NB – INTEGERInput

On entry: if $\mathbf{IND}=1$ or $2$, the size of the current block of data. The size of blocks of data in array RV can vary; therefore NB can change between calls to G01ANF.

Constraint: if $\mathbf{IND}=1$ or $2$, $\mathbf{NB}>0$.

5:     EPS – REAL (KIND=nag_wp)Input

On entry: approximation factor $\epsilon$.

Constraint: $\mathbf{EPS}\ge \exp \left(1.0\right)/\mathbf{N}\text{ and }\mathbf{EPS}\le 1.0$.

6:     NP – INTEGEROutput

On exit: the number of elements processed so far.

7:     Q($*$) – REAL (KIND=nag_wp) arrayInput

Note: the dimension of the array Q must be at least $\mathbf{NQ}$ if $\mathbf{IND}=3$.

On entry: if $\mathbf{IND}=3$, the quantiles to be calculated, otherwise Q is not referenced. Note that $\mathbf{Q}\left(i\right)=0.0$, corresponds to the minimum value and $\mathbf{Q}\left(i\right)=1.0$ to the maximum value.

Constraint: if $\mathbf{IND}=3$, $0.0\le \mathbf{Q}\left(\mathit{i}\right)\le 1.0$, for $\mathit{i}=1,2,\dots ,\mathbf{NQ}$.

8:     QV($*$) – REAL (KIND=nag_wp) arrayOutput

Note: the dimension of the array QV must be at least $\mathbf{NQ}$ if $\mathbf{IND}=3$.

On exit: if $\mathbf{IND}=3$, $\mathbf{QV}\left(i\right)$ contains the $\epsilon$-approximate quantiles specified by the value provided in $\mathbf{Q}\left(i\right)$.

9:     NQ – INTEGERInput

On entry: if $\mathbf{IND}=3$, the number of quantiles requested, otherwise NQ is not referenced.

Constraint: if $\mathbf{IND}=3$, $\mathbf{NQ}>0$.

10:   RCOMM(LRCOMM) – REAL (KIND=nag_wp) arrayCommunication Array

11:   LRCOMM – INTEGERInput

On entry: the dimension of the array RCOMM as declared in the (sub)program from which G01ANF is called.

Constraint: if $\mathbf{IND}\ne 0$, LRCOMM must be at least equal to the value returned in $\mathbf{ICOMM}\left(1\right)$ by a call to G01ANF with $\mathbf{IND}=0$. This will not be more than $x+2\times \min \left(x,⌈x/2.0⌉+1\right)\times {\log }_2\left(\mathbf{N}/x+1.0\right)+1$, where $x=\max \left(1,⌊\log \left(\mathbf{EPS}\times \mathbf{N}\right)/\mathbf{EPS}⌋\right)$.

12:   ICOMM(LICOMM) – INTEGER arrayCommunication Array

13:   LICOMM – INTEGERInput

On entry: the dimension of the array ICOMM as declared in the (sub)program from which G01ANF is called.

Constraints:

• if $\mathbf{IND}=0$, $\mathbf{LICOMM}\ge 2$;
• otherwise LICOMM must be at least equal to the value returned in $\mathbf{ICOMM}\left(2\right)$ by a call to G01ANF with $\mathbf{IND}=0$. This will not be more than $2\times \left(x+2\times \min \left(x,⌈x/2.0⌉+1\right)\times y\right)+y+6$, where $x=\max \left(1,⌊\log \left(\mathbf{EPS}\times \mathbf{N}\right)/\mathbf{EPS}⌋\right)$ and $y={\log }_2\left(\mathbf{N}/x+1.0\right)+1$.

14:   IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

On exit: $\mathbf{IFAIL}=\mathbf{0}$ unless the routine detects an error (see Section 6).

As an out-of-core routine G01ANF will only perform certain parameter checks when a data checkpoint (including completion of data input) is signaled. As such it will usually be inappropriate to halt program execution when an error is detected since any errors may be subsequently resolved without losing any processing already carried out. Therefore setting IFAIL to a value of $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. When the value $-\mathbf{1}\text{ or }\mathbf{1}$ is used it is essential to test the value of IFAIL on exit.

6  Error Indicators and Warnings

$\mathbf{IFAIL}=1$

On entry,

$\mathbf{IND}\ne 0$, $1$, $2$ or $3$.

$\mathbf{IFAIL}=2$

On entry,

$\mathbf{N}<1$.

$\mathbf{IFAIL}=3$

On entry,

$\mathbf{EPS}<\exp \left(1.0\right)/\mathbf{N}$ or $\mathbf{EPS}>1.0$.

$\mathbf{IFAIL}=4$

On entry,

$\mathbf{IND}=1$ or $2$ and $\mathbf{NB}<1$.

$\mathbf{IFAIL}=5$

On entry,

LICOMM is too small.

$\mathbf{IFAIL}=6$

On entry,

LRCOMM is too small.

$\mathbf{IFAIL}=7$

On entry, number of data elements streamed is not sufficient for the $\epsilon$-approximate quantile query. Supply more data or reprocess the data with a higher EPS value.

$\mathbf{IFAIL}=8$

On entry,

$\mathbf{IND}=3$ and $\mathbf{NQ}<1$.

$\mathbf{IFAIL}=9$

On entry,

$\mathbf{IND}=3$ and $\mathbf{Q}\left(i\right)<0.0$ or $\mathbf{Q}\left(i\right)>1.0$ for at least one $i$.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (g01anfe.f90)

9.2  Program Data

Program Data (g01anfe.d)

9.3  Program Results

Program Results (g01anfe.r)