Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_mv_z_scores (g03za)

## Purpose

nag_mv_z_scores (g03za) produces standardized values ($z$-scores) for a data matrix.

## Syntax

[z, ifail] = g03za(x, nvar, isx, s, e, 'n', n, 'm', m)
[z, ifail] = nag_mv_z_scores(x, nvar, isx, s, e, 'n', n, 'm', m)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 22: n was made optional

## Description

For a data matrix, $X$, consisting of $n$ observations on $p$ variables, with elements ${x}_{ij}$, nag_mv_z_scores (g03za) computes a matrix, $Z$, with elements ${z}_{ij}$ such that:
 $zij=xij-μjσj, i=1,2,…,n; j=1,2,…,p,$
where ${\mu }_{j}$ is a location shift and ${\sigma }_{j}$ is a scaling factor. Typically, ${\mu }_{j}$ will be the mean and ${\sigma }_{j}$ will be the standard deviation of the $j$th variable and therefore the elements in column $j$ of $Z$ will have zero mean and unit variance.

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}\left(\mathit{ldx},{\mathbf{m}}\right)$ – double array
ldx, the first dimension of the array, must satisfy the constraint $\mathit{ldx}\ge {\mathbf{n}}$.
${\mathbf{x}}\left(\mathit{i},\mathit{j}\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}}$.
2:     $\mathrm{nvar}$int64int32nag_int scalar
$p$, the number of variables to be standardized.
Constraint: ${\mathbf{nvar}}\ge 1$.
3:     $\mathrm{isx}\left({\mathbf{m}}\right)$int64int32nag_int array
${\mathbf{isx}}\left(j\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\right)\ne 0$, the observations from the $j$th variable are included.
If ${\mathbf{isx}}\left(j\right)=0$, the observations from the $j$th variable are not included.
Constraint: ${\mathbf{isx}}\left(j\right)\ne 0$ for nvar values of $j$.
4:     $\mathrm{s}\left({\mathbf{m}}\right)$ – double array
If ${\mathbf{isx}}\left(j\right)\ne 0$, ${\mathbf{s}}\left(j\right)$ must contain the scaling (standard deviation), ${\sigma }_{j}$, for the $j$th variable.
If ${\mathbf{isx}}\left(j\right)=0$, ${\mathbf{s}}\left(j\right)$ is not referenced.
Constraint: if ${\mathbf{isx}}\left(j\right)\ne 0$, ${\mathbf{s}}\left(\mathit{j}\right)>0.0$, for $\mathit{j}=1,2,\dots ,{\mathbf{m}}$.
5:     $\mathrm{e}\left({\mathbf{m}}\right)$ – double array
If ${\mathbf{isx}}\left(j\right)\ne 0$, ${\mathbf{e}}\left(j\right)$ must contain the location shift (mean), ${\mu }_{j}$, for the $j$th variable.
If ${\mathbf{isx}}\left(j\right)=0$, ${\mathbf{e}}\left(j\right)$ is not referenced.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array x.
$n$, the number of observations in the data matrix.
Constraint: ${\mathbf{n}}\ge 1$.
2:     $\mathrm{m}$int64int32nag_int scalar
Default: the dimension of the arrays isx, s, e and the second dimension of the array x. (An error is raised if these dimensions are not equal.)
The number of variables in the data array x.
Constraint: ${\mathbf{m}}\ge {\mathbf{nvar}}$.

### Output Parameters

1:     $\mathrm{z}\left(\mathit{ldz},{\mathbf{nvar}}\right)$ – double array
The matrix of standardized values ($z$-scores), $Z$.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{n}}<1$, or ${\mathbf{nvar}}<1$, or ${\mathbf{m}}<{\mathbf{nvar}}$, or $\mathit{ldx}<{\mathbf{n}}$, or $\mathit{ldz}<{\mathbf{n}}$.
${\mathbf{ifail}}=2$
 On entry, there are not precisely nvar elements of ${\mathbf{isx}}\ne 0$.
${\mathbf{ifail}}=3$
 On entry, ${\mathbf{isx}}\left(j\right)\ne 0$ and ${\mathbf{s}}\left(j\right)\le 0.0$ for some $j$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

Standard accuracy is achieved.

Means and standard deviations may be obtained using nag_stat_summary_onevar (g01at) or nag_correg_corrmat (g02bx).

## 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.
```function g03za_example

fprintf('g03za example results\n\n');

x = [15, 0, 1500;
12, 1, 1000;
18, 2, 1200;
14, 3, 500];
nvar = int64(2);
isx = [int64(1);0;1];

% shift and scaling
s = [ 2.50;     0;    420.3];
e = [14.75;    0;    1050.0];

% Standardize
[z, ifail] = g03za( ...
x, nvar, isx, s, e);

mtitle = 'Standardized values';
matrix = 'General';
diag   = ' ';
[ifail] = x04ca( ...
matrix, diag, z, mtitle);

```
```g03za example results

Standardized values
1          2
1      0.1000     1.0707
2     -1.1000    -0.1190
3      1.3000     0.3569
4     -0.3000    -1.3086
```