# NAG FL Interfaceg03zaf (z_​scores)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

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

## 2Specification

Fortran Interface
 Subroutine g03zaf ( n, m, x, ldx, nvar, isx, s, e, z, ldz,
 Integer, Intent (In) :: n, m, ldx, nvar, isx(m), ldz Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: x(ldx,m), s(m), e(m) Real (Kind=nag_wp), Intent (Inout) :: z(ldz,nvar)
#include <nag.h>
 void g03zaf_ (const Integer *n, const Integer *m, const double x[], const Integer *ldx, const Integer *nvar, const Integer isx[], const double s[], const double e[], double z[], const Integer *ldz, Integer *ifail)
The routine may be called by the names g03zaf or nagf_mv_z_scores.

## 3Description

For a data matrix, $X$, consisting of $n$ observations on $p$ variables, with elements ${x}_{ij}$, g03zaf 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.

## 5Arguments

1: $\mathbf{n}$Integer Input
On entry: $n$, the number of observations in the data matrix.
Constraint: ${\mathbf{n}}\ge 1$.
2: $\mathbf{m}$Integer Input
On entry: the number of variables in the data array x.
Constraint: ${\mathbf{m}}\ge {\mathbf{nvar}}$.
3: $\mathbf{x}\left({\mathbf{ldx}},{\mathbf{m}}\right)$Real (Kind=nag_wp) array Input
On entry: ${\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}}$.
4: $\mathbf{ldx}$Integer Input
On entry: the first dimension of the array x as declared in the (sub)program from which g03zaf is called.
Constraint: ${\mathbf{ldx}}\ge {\mathbf{n}}$.
5: $\mathbf{nvar}$Integer Input
On entry: $p$, the number of variables to be standardized.
Constraint: ${\mathbf{nvar}}\ge 1$.
6: $\mathbf{isx}\left({\mathbf{m}}\right)$Integer array Input
On entry: ${\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$.
7: $\mathbf{s}\left({\mathbf{m}}\right)$Real (Kind=nag_wp) array Input
On entry: 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}}$.
8: $\mathbf{e}\left({\mathbf{m}}\right)$Real (Kind=nag_wp) array Input
On entry: 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.
9: $\mathbf{z}\left({\mathbf{ldz}},{\mathbf{nvar}}\right)$Real (Kind=nag_wp) array Output
On exit: the matrix of standardized values ($z$-scores), $Z$.
10: $\mathbf{ldz}$Integer Input
On entry: the first dimension of the array z as declared in the (sub)program from which g03zaf is called.
Constraint: ${\mathbf{ldz}}\ge {\mathbf{n}}$.
11: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
On entry, ${\mathbf{ldx}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ldx}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{ldz}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ldz}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{nvar}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{m}}\ge {\mathbf{nvar}}$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 1$.
On entry, ${\mathbf{nvar}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nvar}}\ge 1$.
${\mathbf{ifail}}=2$
On entry, ${\mathbf{nvar}}=⟨\mathit{\text{value}}⟩$ and $⟨\mathit{\text{value}}⟩$ values of ${\mathbf{isx}}>0$.
Constraint: exactly nvar elements of ${\mathbf{isx}}>0$.
${\mathbf{ifail}}=3$
On entry, $j=⟨\mathit{\text{value}}⟩$ and ${\mathbf{s}}\left(i\right)\le 0.0$.
Constraint: ${\mathbf{s}}\left(\mathit{j}\right)>0.0$.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

Standard accuracy is achieved.

## 8Parallelism and Performance

g03zaf is not threaded in any implementation.

Means and standard deviations may be obtained using g01atf or g02bxf.

## 10Example

A $4×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 (g03zafe.f90)

### 10.2Program Data

Program Data (g03zafe.d)

### 10.3Program Results

Program Results (g03zafe.r)