g03 Chapter Contents
g03 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_mv_z_scores (g03zac)

## 1  Purpose

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

## 2  Specification

 #include #include
 void nag_mv_z_scores (Integer n, Integer m, double x[], Integer tdx, Integer nvar, const Integer isx[], const double s[], const double e[], double z[], Integer tdz, NagError *fail)

## 3  Description

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.

## 5  Arguments

1:     nIntegerInput
On entry: the number of observations in the data matrix, $n$.
Constraint: ${\mathbf{n}}\ge 1$.
2:     mIntegerInput
On entry: the number of variables in the data array x.
Constraint: ${\mathbf{m}}\ge {\mathbf{nvar}}$.
3:     x[${\mathbf{n}}×{\mathbf{tdx}}$]doubleOutput
On exit: ${\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:     tdxIntegerInput
On entry: the stride separating matrix column elements in the array x.
Constraint: ${\mathbf{tdx}}\ge {\mathbf{m}}$.
5:     nvarIntegerInput
On entry: the number of variables to be standardized, $p$.
Constraint: ${\mathbf{nvar}}\ge 1$.
6:     isx[m]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:     s[m]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:     e[m]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:     z[${\mathbf{n}}×{\mathbf{tdz}}$]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:   tdzIntegerInput
On entry: the stride separating matrix column elements in the array z.
Constraint: ${\mathbf{tdz}}\ge {\mathbf{nvar}}$.
11:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

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

## 7  Accuracy

Standard accuracy is achieved.

## 8  Parallelism and Performance

Not applicable.

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

## 10  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.

### 10.1  Program Text

Program Text (g03zace.c)

### 10.2  Program Data

Program Data (g03zace.d)

### 10.3  Program Results

Program Results (g03zace.r)