# NAG Library Function Document

## 1Purpose

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

## 2Specification

 #include #include
 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)

## 3Description

For a data matrix, $X$, consisting of $n$ observations on $p$ variables, with elements ${x}_{ij}$, nag_mv_z_scores (g03zac) computes a matrix, $Z$, with elements ${z}_{ij}$ such that:
 $z ij = x ij - μ 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.

## 5Arguments

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}}×{\mathbf{tdx}}\right]$const doubleInput
On entry: ${\mathbf{x}}\left[\left(\mathit{i}-1\right)×{\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}}×{\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)×{\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).

## 6Error 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 $\text{}=〈\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.

## 7Accuracy

Standard accuracy is achieved.

## 8Parallelism and Performance

nag_mv_z_scores (g03zac) is not threaded in any implementation.

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

## 10Example

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.

### 10.1Program Text

Program Text (g03zace.c)

### 10.2Program Data

Program Data (g03zace.d)

### 10.3Program Results

Program Results (g03zace.r)

© The Numerical Algorithms Group Ltd, Oxford, UK. 2017