NAG FL Interface
g03zaf (z_​scores)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

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

2 Specification

Fortran Interface
Subroutine g03zaf ( n, m, x, ldx, nvar, isx, s, e, z, ldz, ifail)
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)
C Header Interface
#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.

3 Description

For a data matrix, X, consisting of n observations on p variables, with elements xij, g03zaf computes a matrix, Z, with elements zij such that:
zij=xij-μjσj,  i=1,2,,n;  j=1,2,,p,  
where μj is a location shift and σj is a scaling factor. Typically, μj will be the mean and σj will be the standard deviation of the jth variable and, therefore, the elements in column j of Z will have zero mean and unit variance.

4 References

None.

5 Arguments

1: n Integer Input
On entry: n, the number of observations in the data matrix.
Constraint: n1.
2: m Integer Input
On entry: the number of variables in the data array x.
Constraint: mnvar.
3: x(ldx,m) Real (Kind=nag_wp) array Input
On entry: x(i,j) must contain the ith sample point for the jth variable, xij, for i=1,2,,n and j=1,2,,m.
4: ldx Integer Input
On entry: the first dimension of the array x as declared in the (sub)program from which g03zaf is called.
Constraint: ldxn.
5: nvar Integer Input
On entry: p, the number of variables to be standardized.
Constraint: nvar1.
6: isx(m) Integer array Input
On entry: isx(j) indicates whether or not the observations on the jth variable are included in the matrix of standardized values.
If isx(j)0, the observations from the jth variable are included.
If isx(j)=0, the observations from the jth variable are not included.
Constraint: isx(j)0 for nvar values of j.
7: s(m) Real (Kind=nag_wp) array Input
On entry: if isx(j)0, s(j) must contain the scaling (standard deviation), σj, for the jth variable.
If isx(j)=0, s(j) is not referenced.
Constraint: if isx(j)0, s(j)>0.0, for j=1,2,,m.
8: e(m) Real (Kind=nag_wp) array Input
On entry: if isx(j)0, e(j) must contain the location shift (mean), μj, for the jth variable.
If isx(j)=0, e(j) is not referenced.
9: z(ldz,nvar) Real (Kind=nag_wp) array Output
On exit: the matrix of standardized values (z-scores), Z.
10: ldz Integer Input
On entry: the first dimension of the array z as declared in the (sub)program from which g03zaf is called.
Constraint: ldzn.
11: 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 -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry 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:
ifail=1
On entry, ldx=value and n=value.
Constraint: ldxn.
On entry, ldz=value and n=value.
Constraint: ldzn.
On entry, m=value and nvar=value.
Constraint: mnvar.
On entry, n=value.
Constraint: n1.
On entry, nvar=value.
Constraint: nvar1.
ifail=2
On entry, nvar=value and value values of isx>0.
Constraint: exactly nvar elements of isx>0.
ifail=3
On entry, j=value and s(i)0.0.
Constraint: s(j)>0.0.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
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.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

Standard accuracy is achieved.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
g03zaf is not threaded in any implementation.

9 Further Comments

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

10 Example

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.1 Program Text

Program Text (g03zafe.f90)

10.2 Program Data

Program Data (g03zafe.d)

10.3 Program Results

Program Results (g03zafe.r)