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, const 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:     n IntegerInput
On entry: the number of observations in the data matrix, n .
Constraint: n1 .
2:     m IntegerInput
On entry: the number of variables in the data array x.
Constraint: mnvar .
3:     x[n×tdx] const doubleInput
On entry: 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:     tdx IntegerInput
On entry: the stride separating matrix column elements in the array x.
Constraint: tdxm .
5:     nvar IntegerInput
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:   tdz IntegerInput
On entry: the stride separating matrix column elements in the array z.
Constraint: tdznvar .
11:   fail NagError *Input/Output
The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

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
Parallelism and Performance

nag_mv_z_scores (g03zac) is not threaded in any implementation.

9
Further Comments

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)

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