nag_mv_z_scores (g03zac) (PDF version)
g03 Chapter Contents
g03 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_mv_z_scores (g03zac)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

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

2  Specification

#include <nag.h>
#include <nagg03.h>
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 μ 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 j th variable and therefore the elements in column j  of Z  will have zero mean and unit variance.

4  References

None.

5  Arguments

1:     nIntegerInput
On entry: the number of observations in the data matrix, n .
Constraint: n1 .
2:     mIntegerInput
On entry: the number of variables in the data array x.
Constraint: mnvar .
3:     x[n×tdx]doubleOutput
On exit: x[i-1×tdx+j-1]  must contain the i th sample point for the j th variable x ij , for i=1,2,,n and j=1,2,,m.
4:     tdxIntegerInput
On entry: the stride separating matrix column elements in the array x.
Constraint: tdxm .
5:     nvarIntegerInput
On entry: the number of variables to be standardized, p .
Constraint: nvar1 .
6:     isx[m]const IntegerInput
On entry: isx[j-1]  indicates whether or not the observations on the j th variable are included in the matrix of standardized values.
If isx[j-1] 0 , then the observations from the j th variable are included.
If isx[j-1] = 0 , then the observations from the j th variable are not included.
Constraint: isx[j-1] 0  for nvar values of j .
7:     s[m]const doubleInput
On entry: if isx[j-1] 0 , then s[j-1]  must contain the scaling (standard deviation), σ j , for the j th variable.
If isx[j-1] = 0 , then s[j-1]  is not referenced.
Constraint: if isx[j-1] 0 , s[j-1] > 0.0 , for j=1,2,,m.
8:     e[m]const doubleInput
On entry: if isx[j-1] 0 , then e[j-1]  must contain the location shift (mean), μ j , for the j th variable.
If isx[j-1] = 0 , then e[j-1]  is not referenced.
9:     z[n×tdz]doubleOutput
Note: the i,jth element of the matrix Z is stored in z[i-1×tdz+j-1].
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: tdznvar .
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, m=value  while nvar=value . These arguments must satisfy mnvar .
On entry, tdx=value  while m=value . These arguments must satisfy tdxm .
On entry, tdz=value  while nvar=value . These arguments must satisfy tdznvar .
NE_INT_ARG_LT
On entry, n=value.
Constraint: n1.
On entry, nvar=value.
Constraint: nvar1.
NE_INTARR_REALARR
On entry, isx[value] = value, s[value] = value.
Constraint: if isx[j-1] = 0 , s[j-1] > 0.0 , for j=1,2,,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 =value , while number of variables included in the analysis via array isx=value .
Constraint: these two numbers must be the same.

7  Accuracy

Standard accuracy is achieved.

8  Further Comments

Means and standard deviations may be obtained using nag_summary_stats_1var (g01aac) or nag_corr_cov (g02bxc).

9  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.

9.1  Program Text

Program Text (g03zace.c)

9.2  Program Data

Program Data (g03zace.d)

9.3  Program Results

Program Results (g03zace.r)


nag_mv_z_scores (g03zac) (PDF version)
g03 Chapter Contents
g03 Chapter Introduction
NAG C Library Manual

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