NAG Toolbox: nag_mv_z_scores (g03za)

Purpose

Syntax

Description

References

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

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

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g03za_example

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