NAG Library Function Document

nag_mv_z_scores (g03zac)

void	nag_mv_z_scores (Integer n, Integer m, const double x[], Integer tdx, Integer nvar, const Integer isx[], const double s[], const double e[], double z[], Integer tdz, NagError *fail)

3 Description

For a data matrix,

X

, consisting of

n

observations on

p

variables, with elements

x_{i j}

, nag_mv_z_scores (g03zac) 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$ – IntegerInput: On entry: the number of observations in the data matrix, $n$ .

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

Constraint: $m \geq nvar$ .
3: $x [n \times tdx]$ – const doubleInput: On entry: $x [(i - 1) \times tdx + j - 1]$ 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: $tdx$ – IntegerInput: On entry: the stride separating matrix column elements in the array x.

Constraint: $tdx \geq m$ .
5: $nvar$ – IntegerInput: On entry: the number of variables to be standardized, $p$ .

Constraint: $nvar \geq 1$ .
6: $isx [m]$ – const IntegerInput: On entry: $isx [j - 1]$ indicates whether or not the observations on the $j$ th variable are included in the matrix of standardized values.
If $isx [j - 1] \neq 0$ , then the observations from the $j$ th variable are included.

If $isx [j - 1] = 0$ , then the observations from the $j$ th variable are not included.

Constraint: $isx [j - 1] \neq 0$ for nvar values of $j$ .
7: $s [m]$ – const doubleInput: On entry: if $isx [j - 1] \neq 0$ , then $s [j - 1]$ must contain the scaling (standard deviation), $σ_{j}$ , for the $j$ th variable.
If $isx [j - 1] = 0$ , then $s [j - 1]$ is not referenced.

Constraint: if $isx [j - 1] \neq 0$ , $s [j - 1] > 0.0$ , for $j = 1, 2, \dots, m$ .
8: $e [m]$ – const doubleInput: On entry: if $isx [j - 1] \neq 0$ , then $e [j - 1]$ must contain the location shift (mean), $μ_{j}$ , for the $j$ th variable.
If $isx [j - 1] = 0$ , then $e [j - 1]$ is not referenced.
9: $z [n \times tdz]$ – doubleOutput: Note: the $(i, j)$ th element of the matrix $Z$ is stored in $z [(i - 1) \times tdz + j - 1]$ .

On exit: the matrix of standardized values ( $z$ -scores), $Z$ .
10: $tdz$ – IntegerInput: On entry: the stride separating matrix column elements in the array z.

Constraint: $tdz \geq nvar$ .
11: $fail$ – NagError *Input/Output: The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_2_INT_ARG_LT: On entry, $m = 〈value〉$ while $nvar = 〈value〉$ . These arguments must satisfy $m \geq nvar$ .

On entry, $tdx = 〈value〉$ while $m = 〈value〉$ . These arguments must satisfy $tdx \geq m$ .

On entry, $tdz = 〈value〉$ while $nvar = 〈value〉$ . These arguments must satisfy $tdz \geq nvar$ .
NE_INT_ARG_LT: On entry, $n = 〈value〉$ .
Constraint: $n \geq 1$ .

On entry, $nvar = 〈value〉$ .
Constraint: $nvar \geq 1$ .
NE_INTARR_REALARR: On entry, $isx [〈value〉] = 〈value〉$ , $s [〈value〉] = 〈value〉$ .
Constraint: if $isx [j - 1] = 0$ , $s [j - 1] > 0.0$ , for $j = 1, 2, \dots, m$ .
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.
NE_VAR_INCL_INDICATED: The number of variables, nvar in the analysis $= 〈value〉$ , while number of variables included in the analysis via array $isx = 〈value〉$ .
Constraint: these two numbers must be the same.

7 Accuracy

Standard accuracy is achieved.

8 Parallelism and Performance

Not applicable.

9 Further Comments

Means and standard deviations may be obtained using nag_summary_stats_onevar (g01atc) or nag_corr_cov (g02bxc).

10 Example

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

NAG Library Function Documentnag_mv_z_scores (g03zac)

▸▿ Contents

1 Purpose

2 Specification