NAG Library Function Document

nag_mv_z_scores (g03zac)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{n}$ – IntegerInput

On entry: the number of observations in the data matrix, $n$.

Constraint: $\mathbf{n}\ge 1$.

2:    $\mathbf{m}$ – IntegerInput

On entry: the number of variables in the data array x.

Constraint: $\mathbf{m}\ge \mathbf{nvar}$.

3:    $\mathbf{x}\left[\mathbf{n}\times \mathbf{tdx}\right]$ – const doubleInput

On entry: $\mathbf{x}\left[\left(\mathit{i}-1\right)\times \mathbf{tdx}+\mathit{j}-1\right]$ must contain the $\mathit{i}$th sample point for the $\mathit{j}$th variable $x_{\mathit{i}\mathit{j}}$, for $\mathit{i}=1,2,\dots ,n$ and $\mathit{j}=1,2,\dots ,\mathbf{m}$.

4:    $\mathbf{tdx}$ – IntegerInput

On entry: the stride separating matrix column elements in the array x.

Constraint: $\mathbf{tdx}\ge \mathbf{m}$.

5:    $\mathbf{nvar}$ – IntegerInput

On entry: the number of variables to be standardized, $p$.

Constraint: $\mathbf{nvar}\ge 1$.

6:    $\mathbf{isx}\left[\mathbf{m}\right]$ – const IntegerInput

On entry: $\mathbf{isx}\left[j-1\right]$ indicates whether or not the observations on the $j$th variable are included in the matrix of standardized values.

If $\mathbf{isx}\left[j-1\right]\ne 0$, then the observations from the $j$th variable are included.

If $\mathbf{isx}\left[j-1\right]=0$, then the observations from the $j$th variable are not included.

Constraint: $\mathbf{isx}\left[j-1\right]\ne 0$ for nvar values of $j$.

7:    $\mathbf{s}\left[\mathbf{m}\right]$ – const doubleInput

On entry: if $\mathbf{isx}\left[j-1\right]\ne 0$, then $\mathbf{s}\left[j-1\right]$ must contain the scaling (standard deviation), ${\sigma }_j$, for the $j$th variable.

If $\mathbf{isx}\left[j-1\right]=0$, then $\mathbf{s}\left[j-1\right]$ is not referenced.

Constraint: if $\mathbf{isx}\left[j-1\right]\ne 0$, $\mathbf{s}\left[\mathit{j}-1\right]>0.0$, for $\mathit{j}=1,2,\dots ,\mathbf{m}$.

8:    $\mathbf{e}\left[\mathbf{m}\right]$ – const doubleInput

On entry: if $\mathbf{isx}\left[j-1\right]\ne 0$, then $\mathbf{e}\left[j-1\right]$ must contain the location shift (mean), ${\mu }_j$, for the $j$th variable.

If $\mathbf{isx}\left[j-1\right]=0$, then $\mathbf{e}\left[j-1\right]$ is not referenced.

9:    $\mathbf{z}\left[\mathbf{n}\times \mathbf{tdz}\right]$ – doubleOutput

Note: the $\left(i,j\right)$th element of the matrix $Z$ is stored in $\mathbf{z}\left[\left(i-1\right)\times \mathbf{tdz}+j-1\right]$.

On exit: the matrix of standardized values ($z$-scores), $Z$.

10:  $\mathbf{tdz}$ – IntegerInput

On entry: the stride separating matrix column elements in the array z.

Constraint: $\mathbf{tdz}\ge \mathbf{nvar}$.

11:  $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_2_INT_ARG_LT

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$ while $\mathbf{nvar}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{m}\ge \mathbf{nvar}$.

On entry, $\mathbf{tdx}=〈\mathit{\text{value}}〉$ while $\mathbf{m}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{tdx}\ge \mathbf{m}$.

On entry, $\mathbf{tdz}=〈\mathit{\text{value}}〉$ while $\mathbf{nvar}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{tdz}\ge \mathbf{nvar}$.

NE_INT_ARG_LT

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 1$.

On entry, $\mathbf{nvar}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nvar}\ge 1$.

NE_INTARR_REALARR

On entry, $\mathbf{isx}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$, $\mathbf{s}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{isx}\left[\mathit{j}-1\right]=0$, $\mathbf{s}\left[\mathit{j}-1\right]>0.0$, for $\mathit{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 $=〈\mathit{\text{value}}〉$, while number of variables included in the analysis via array $\mathbf{isx}=〈\mathit{\text{value}}〉$.
Constraint: these two numbers must be the same.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (g03zace.c)

10.2

Program Data

Program Data (g03zace.d)

10.3

Program Results

Program Results (g03zace.r)