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$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:
Mark 22: n has been made optional
.

## Description

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

None.

## Parameters

### Compulsory Input Parameters

1:     x(ldx,m) – double array
ldx, the first dimension of the array, must satisfy the constraint ldxn$\mathit{ldx}\ge {\mathbf{n}}$.
x(i,j)${\mathbf{x}}\left(\mathit{i},\mathit{j}\right)$ must contain the i$\mathit{i}$th sample point for the j$\mathit{j}$th variable, xij${x}_{\mathit{i}\mathit{j}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$ and j = 1,2,,m$\mathit{j}=1,2,\dots ,{\mathbf{m}}$.
2:     nvar – int64int32nag_int scalar
p$p$, the number of variables to be standardized.
Constraint: nvar1${\mathbf{nvar}}\ge 1$.
3:     isx(m) – int64int32nag_int array
m, the dimension of the array, must satisfy the constraint ${\mathbf{m}}\ge {\mathbf{nvar}}$.
isx(j)${\mathbf{isx}}\left(j\right)$ indicates whether or not the observations on the j$j$th variable are included in the matrix of standardized values.
If isx(j)0${\mathbf{isx}}\left(j\right)\ne 0$, the observations from the j$j$th variable are included.
If isx(j) = 0${\mathbf{isx}}\left(j\right)=0$, the observations from the j$j$th variable are not included.
Constraint: isx(j)0${\mathbf{isx}}\left(j\right)\ne 0$ for nvar values of j$j$.
4:     s(m) – double array
m, the dimension of the array, must satisfy the constraint ${\mathbf{m}}\ge {\mathbf{nvar}}$.
If isx(j)0${\mathbf{isx}}\left(j\right)\ne 0$, s(j)${\mathbf{s}}\left(j\right)$ must contain the scaling (standard deviation), σj${\sigma }_{j}$, for the j$j$th variable.
If isx(j) = 0${\mathbf{isx}}\left(j\right)=0$, s(j)${\mathbf{s}}\left(j\right)$ is not referenced.
Constraint: if isx(j)0${\mathbf{isx}}\left(j\right)\ne 0$, s(j) > 0.0${\mathbf{s}}\left(\mathit{j}\right)>0.0$, for j = 1,2,,m$\mathit{j}=1,2,\dots ,{\mathbf{m}}$.
5:     e(m) – double array
m, the dimension of the array, must satisfy the constraint ${\mathbf{m}}\ge {\mathbf{nvar}}$.
If isx(j)0${\mathbf{isx}}\left(j\right)\ne 0$, e(j)${\mathbf{e}}\left(j\right)$ must contain the location shift (mean), μj${\mu }_{j}$, for the j$j$th variable.
If isx(j) = 0${\mathbf{isx}}\left(j\right)=0$, e(j)${\mathbf{e}}\left(j\right)$ is not referenced.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the array x.
n$n$, the number of observations in the data matrix.
Constraint: n1${\mathbf{n}}\ge 1$.
2:     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}}$.

ldx ldz

### Output Parameters

1:     z(ldz,nvar) – double array
ldzn$\mathit{ldz}\ge {\mathbf{n}}$.
The matrix of standardized values (z$z$-scores), Z$Z$.
2:     ifail – int64int32nag_int scalar
${\mathrm{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:
ifail = 1${\mathbf{ifail}}=1$
 On entry, n < 1${\mathbf{n}}<1$, or nvar < 1${\mathbf{nvar}}<1$, or ${\mathbf{m}}<{\mathbf{nvar}}$, or ldx < n$\mathit{ldx}<{\mathbf{n}}$, or ldz < n$\mathit{ldz}<{\mathbf{n}}$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, there are not precisely nvar elements of isx ≠ 0${\mathbf{isx}}\ne 0$.
ifail = 3${\mathbf{ifail}}=3$
 On entry, isx(j) ≠ 0${\mathbf{isx}}\left(j\right)\ne 0$ and s(j) ≤ 0.0${\mathbf{s}}\left(j\right)\le 0.0$ for some j$j$.

## Accuracy

Standard accuracy is achieved.

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

## Example

```function nag_mv_z_scores_example
x = [15, 0, 1500;
12, 1, 1000;
18, 2, 1200;
14, 3, 500];
nvar = int64(2);
isx = [int64(1);0;1];
s = [2.5;
0;
420.3];
e = [14.75;
0;
1050];
[z, ifail] = nag_mv_z_scores(x, nvar, isx, s, e)
```
```

z =

0.1000    1.0707
-1.1000   -0.1190
1.3000    0.3569
-0.3000   -1.3086

ifail =

0

```
```function g03za_example
x = [15, 0, 1500;
12, 1, 1000;
18, 2, 1200;
14, 3, 500];
nvar = int64(2);
isx = [int64(1);0;1];
s = [2.5;
0;
420.3];
e = [14.75;
0;
1050];
[z, ifail] = g03za(x, nvar, isx, s, e)
```
```

z =

0.1000    1.0707
-1.1000   -0.1190
1.3000    0.3569
-0.3000   -1.3086

ifail =

0

```