Integer, Intent (In)	::	n, m, ldx, nvar, isx(m), ldz
Integer, Intent (Inout)	::	ifail
Real (Kind=nag_wp), Intent (In)	::	x(ldx,m), s(m), e(m)
Real (Kind=nag_wp), Intent (Inout)	::	z(ldz,nvar)

C Header Interface

#include <nag.h>

void	g03zaf_ (const Integer n, const Integer m, const double x[], const Integer ldx, const Integer nvar, const Integer isx[], const double s[], const double e[], double z[], const Integer ldz, Integer ifail)

The routine may be called by the names g03zaf or nagf_mv_z_scores.

3 Description

For a data matrix,

X

, consisting of

n

observations on

p

variables, with elements

x_{i j}

, g03zaf computes a matrix,

Z

, with elements

z_{i j}

such that:

z_{i j} = \frac{x_{i j} - μ_{j}}{σ_{j}}, i = 1, 2, \dots, n; j = 1, 2, \dots, p,

where

μ_{j}

is a location shift and

σ_{j}

is a scaling factor. Typically,

μ_{j}

will be the mean and

σ_{j}

will be the standard deviation of the

j

th variable and, therefore, the elements in column

j

Z

will have zero mean and unit variance.

4 References

None.

5 Arguments

1: $n$ – Integer Input: On entry: $n$ , the number of observations in the data matrix.

Constraint: $n \geq 1$ .
2: $m$ – Integer Input: On entry: the number of variables in the data array x.

Constraint: $m \geq nvar$ .
3: $x (ldx, m)$ – Real (Kind=nag_wp) array Input: On entry: $x (i, j)$ must contain the $i$ th sample point for the $j$ th variable, $x_{i j}$ , for $i = 1, 2, \dots, n$ and $j = 1, 2, \dots, m$ .
4: $ldx$ – Integer Input: On entry: the first dimension of the array x as declared in the (sub)program from which g03zaf is called.

Constraint: $ldx \geq n$ .
5: $nvar$ – Integer Input: On entry: $p$ , the number of variables to be standardized.

Constraint: $nvar \geq 1$ .
6: $isx (m)$ – Integer array Input: On entry: $isx (j)$ indicates whether or not the observations on the $j$ th variable are included in the matrix of standardized values.
If $isx (j) \neq 0$ , the observations from the $j$ th variable are included.

If $isx (j) = 0$ , the observations from the $j$ th variable are not included.

Constraint: $isx (j) \neq 0$ for nvar values of $j$ .
7: $s (m)$ – Real (Kind=nag_wp) array Input: On entry: if $isx (j) \neq 0$ , $s (j)$ must contain the scaling (standard deviation), $σ_{j}$ , for the $j$ th variable.
If $isx (j) = 0$ , $s (j)$ is not referenced.

Constraint: if $isx (j) \neq 0$ , $s (j) > 0.0$ , for $j = 1, 2, \dots, m$ .
8: $e (m)$ – Real (Kind=nag_wp) array Input: On entry: if $isx (j) \neq 0$ , $e (j)$ must contain the location shift (mean), $μ_{j}$ , for the $j$ th variable.
If $isx (j) = 0$ , $e (j)$ is not referenced.
9: $z (ldz, nvar)$ – Real (Kind=nag_wp) array Output: On exit: the matrix of standardized values ( $z$ -scores), $Z$ .
10: $ldz$ – Integer Input: On entry: the first dimension of the array z as declared in the (sub)program from which g03zaf is called.

Constraint: $ldz \geq n$ .
11: $ifail$ – Integer Input/Output: On entry: ifail must be set to $0$ , $−1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $−1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $−1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit: $ifail = 0$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

−1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$: On entry, $ldx = ⟨ value ⟩$ and $n = ⟨ value ⟩$ .
Constraint: $ldx \geq n$ .

On entry, $ldz = ⟨ value ⟩$ and $n = ⟨ value ⟩$ .
Constraint: $ldz \geq n$ .

On entry, $m = ⟨ value ⟩$ and $nvar = ⟨ value ⟩$ .
Constraint: $m \geq nvar$ .

On entry, $n = ⟨ value ⟩$ .
Constraint: $n \geq 1$ .

On entry, $nvar = ⟨ value ⟩$ .
Constraint: $nvar \geq 1$ .

$ifail = 2$: On entry, $nvar = ⟨ value ⟩$ and $⟨ value ⟩$ values of $isx > 0$ .
Constraint: exactly nvar elements of $isx > 0$ .

$ifail = 3$: On entry, $j = ⟨ value ⟩$ and $s (i) \leq 0.0$ .
Constraint: $s (j) > 0.0$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.

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

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

Standard accuracy is achieved.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.

g03zaf is not threaded in any implementation.

9 Further Comments

Means and standard deviations may be obtained using g01atf or g02bxf.

10 Example

4 \times 3

data matrix is input along with location and scaling values. The first and third columns are scaled and the results printed.

g03za: FL CL CPP AD PY MB

NAG FL Interfaceg03zaf (z_​scores)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG FL Interface
g03zaf (z_scores)