nag_pls_orth_scores_wold (g02lbc) : NAG C Library, Mark 26

Specification

#include <nag.h>

#include <nagg02.h>

void

nag_pls_orth_scores_wold (Nag_OrderType order, Integer n, Integer mx, const double x[], Integer pdx, const Integer isx[], Integer ip, Integer my, const double y[], Integer pdy, double xbar[], double ybar[], Nag_ScalePredictor iscale, double xstd[], double ystd[], Integer maxfac, Integer maxit, double tau, double xres[], Integer pdxres, double yres[], Integer pdyres, double w[], Integer pdw, double p[], Integer pdp, double t[], Integer pdt, double c[], Integer pdc, double u[], Integer pdu, double xcv[], double ycv[], Integer pdycv, NagError *fail)

Description

Let

X_{1}

be the mean-centred

n

m

data matrix

X

n

observations on

m

predictor variables. Let

Y_{1}

be the mean-centred

n

r

data matrix

Y

n

observations on

r

response variables.

The first of the

k

factors PLS methods extract from the data predicts both

X_{1}

and

Y_{1}

by regressing on a

t_{1}

column vector of

n

scores:

\begin{matrix} {\hat{X}}_{1} = t_{1} p_{1}^{T} \\ {\hat{Y}}_{1} = t_{1} c_{1}^{T}, & with ​ t_{1}^{T} t_{1} = 1, \end{matrix}

where the column vectors of

m

x

-loadings

p_{1}

and

r

y

-loadings

c_{1}

are calculated in the least squares sense:

\begin{matrix} p_{1}^{T} = t_{1}^{T} X_{1} \\ c_{1}^{T} = t_{1}^{T} Y_{1} . \end{matrix}

The

x

-score vector

t_{1} = X_{1} w_{1}

is the linear combination of predictor data

X_{1}

that has maximum covariance with the

y

-scores

u_{1} = Y_{1} c_{1}

, where the

x

-weights vector

w_{1}

is the normalised first left singular vector of

X_{1}^{T} Y_{1}

The method extracts subsequent PLS factors by repeating the above process with the residual matrices:

\begin{matrix} X_{i} = X_{i - 1} - {\hat{X}}_{i - 1} \\ Y_{i} = Y_{i - 1} - {\hat{Y}}_{i - 1}, i = 2, 3, \dots, k, \end{matrix}

and with orthogonal scores:

t_{i}^{T} t_{j} = 0, j = 1, 2, \dots, i - 1 .

Optionally, in addition to being mean-centred, the data matrices

X_{1}

and

Y_{1}

may be scaled by standard deviations of the variables. If data are supplied mean-centred, the calculations are not affected within numerical accuracy.

Arguments

order

– Nag_OrderTypeInput

On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by

order = Nag_RowMajor

. See Section 3.3.1.3 in How to Use the NAG Library and its Documentation for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

Nag_ColMajor

n

– IntegerInput

On entry:

n

, the number of observations.

Constraint:

n > 1

mx

– IntegerInput

On entry: the number of predictor variables.

Constraint:

mx > 1

x [\dim]

– const doubleInput

Note: the dimension, dim, of the array x must be at least

$\max (1, pdx \times mx)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdx)$ when $order = Nag_RowMajor$ .

Where

X (i, j)

appears in this document, it refers to the array element

$x [(j - 1) \times pdx + i - 1]$ when $order = Nag_ColMajor$ ;
$x [(i - 1) \times pdx + j - 1]$ when $order = Nag_RowMajor$ .

On entry:

X (i, j)

must contain the

i

th observation on the

j

th predictor variable, for

i = 1, 2, \dots, n

and

j = 1, 2, \dots, mx

pdx

– IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array x.

Constraints:

if $order = Nag_ColMajor$ , $pdx \geq n$ ;
if $order = Nag_RowMajor$ , $pdx \geq mx$ .

isx [mx]

– const IntegerInput

On entry: indicates which predictor variables are to be included in the model.

$isx [j - 1] = 1$: The $j$ th predictor variable (with variates in the $j$ th column of $X$ ) is included in the model.
$isx [j - 1] = 0$: Otherwise.

Constraint: the sum of elements in isx must equal ip.

ip

– IntegerInput

On entry:

m

, the number of predictor variables in the model.

Constraint:

1 < ip \leq mx

my

– IntegerInput

On entry:

r

, the number of response variables.

Constraint:

my \geq 1

y [\dim]

– const doubleInput

Note: the dimension, dim, of the array y must be at least

$\max (1, pdy \times my)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdy)$ when $order = Nag_RowMajor$ .

Where

Y (i, j)

appears in this document, it refers to the array element

$y [(j - 1) \times pdy + i - 1]$ when $order = Nag_ColMajor$ ;
$y [(i - 1) \times pdy + j - 1]$ when $order = Nag_RowMajor$ .

On entry:

Y (i, j)

must contain the

i

th observation for the

j

th response variable, for

i = 1, 2, \dots, n

and

j = 1, 2, \dots, my

10:

pdy

– IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array y.

Constraints:

if $order = Nag_ColMajor$ , $pdy \geq n$ ;
if $order = Nag_RowMajor$ , $pdy \geq my$ .

11:

xbar [ip]

– doubleOutput

On exit: mean values of predictor variables in the model.

12:

ybar [my]

– doubleOutput

On exit: the mean value of each response variable.

13:

iscale

– Nag_ScalePredictorInput

On entry: indicates how predictor variables are scaled.

$iscale = Nag_PredStdScale$: Data are scaled by the standard deviation of variables.
$iscale = Nag_PredUserScale$: Data are scaled by user-supplied scalings.
$iscale = Nag_PredNoScale$: No scaling.

Constraint:

iscale = Nag_PredNoScale

Nag_PredStdScale

Nag_PredUserScale

14:

xstd [ip]

– doubleInput/Output

On entry: if

iscale = Nag_PredUserScale

xstd [j - 1]

must contain the user-supplied scaling for the

j

th predictor variable in the model, for

j = 1, 2, \dots, ip

. Otherwise xstd need not be set.

On exit: if

iscale = Nag_PredStdScale

, standard deviations of predictor variables in the model. Otherwise xstd is not changed.

15:

ystd [my]

– doubleInput/Output

On entry: if

iscale = Nag_PredUserScale

ystd [j - 1]

must contain the user-supplied scaling for the

j

th response variable in the model, for

j = 1, 2, \dots, my

. Otherwise ystd need not be set.

On exit: if

iscale = Nag_PredStdScale

, the standard deviation of each response variable. Otherwise ystd is not changed.

16:

maxfac

– IntegerInput

On entry:

k

, the number of latent variables to calculate.

Constraint:

1 \leq maxfac \leq ip

17:

maxit

– IntegerInput

On entry: if

my = 1

, maxit is not referenced; otherwise the maximum number of iterations used to calculate the

x

-weights.

Suggested value:

maxit = 200

Constraint: if

my > 1

maxit > 1

18:

tau

– doubleInput

On entry: if

my = 1

, tau is not referenced; otherwise the iterative procedure used to calculate the

x

-weights will halt if the Euclidean distance between two subsequent estimates is less than or equal to tau.

Suggested value:

tau = 1.0e−4

Constraint: if

my > 1

tau > 0.0

19:

xres [\dim]

– doubleOutput

Note: the dimension, dim, of the array xres must be at least

$\max (1, pdxres \times ip)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdxres)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix is stored in

$xres [(j - 1) \times pdxres + i - 1]$ when $order = Nag_ColMajor$ ;
$xres [(i - 1) \times pdxres + j - 1]$ when $order = Nag_RowMajor$ .

On exit: the predictor variables' residual matrix

X_{k}

20:

pdxres

– IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array xres.

Constraints:

if $order = Nag_ColMajor$ , $pdxres \geq n$ ;
if $order = Nag_RowMajor$ , $pdxres \geq ip$ .

21:

yres [\dim]

– doubleOutput

Note: the dimension, dim, of the array yres must be at least

$\max (1, pdyres \times my)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdyres)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix is stored in

$yres [(j - 1) \times pdyres + i - 1]$ when $order = Nag_ColMajor$ ;
$yres [(i - 1) \times pdyres + j - 1]$ when $order = Nag_RowMajor$ .

On exit: the residuals for each response variable,

Y_{k}

22:

pdyres

– IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array yres.

Constraints:

if $order = Nag_ColMajor$ , $pdyres \geq n$ ;
if $order = Nag_RowMajor$ , $pdyres \geq my$ .

23:

w [\dim]

– doubleOutput

Note: the dimension, dim, of the array w must be at least

$\max (1, pdw \times maxfac)$ when $order = Nag_ColMajor$ ;
$\max (1, ip \times pdw)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

W

is stored in

$w [(j - 1) \times pdw + i - 1]$ when $order = Nag_ColMajor$ ;
$w [(i - 1) \times pdw + j - 1]$ when $order = Nag_RowMajor$ .

On exit: the

j

th column of

W

contains the

x

-weights

w_{j}

, for

j = 1, 2, \dots, maxfac

24:

pdw

– IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array w.

Constraints:

if $order = Nag_ColMajor$ , $pdw \geq ip$ ;
if $order = Nag_RowMajor$ , $pdw \geq maxfac$ .

25:

p [\dim]

– doubleOutput

Note: the dimension, dim, of the array p must be at least

$\max (1, pdp \times maxfac)$ when $order = Nag_ColMajor$ ;
$\max (1, ip \times pdp)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

P

is stored in

$p [(j - 1) \times pdp + i - 1]$ when $order = Nag_ColMajor$ ;
$p [(i - 1) \times pdp + j - 1]$ when $order = Nag_RowMajor$ .

On exit: the

j

th column of

P

contains the

x

-loadings

p_{j}

, for

j = 1, 2, \dots, maxfac

26:

pdp

– IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array p.

Constraints:

if $order = Nag_ColMajor$ , $pdp \geq ip$ ;
if $order = Nag_RowMajor$ , $pdp \geq maxfac$ .

27:

t [\dim]

– doubleOutput

Note: the dimension, dim, of the array t must be at least

$\max (1, pdt \times maxfac)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdt)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

T

is stored in

$t [(j - 1) \times pdt + i - 1]$ when $order = Nag_ColMajor$ ;
$t [(i - 1) \times pdt + j - 1]$ when $order = Nag_RowMajor$ .

On exit: the

j

th column of

T

contains the

x

-scores

t_{j}

, for

j = 1, 2, \dots, maxfac

28:

pdt

– IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array t.

Constraints:

if $order = Nag_ColMajor$ , $pdt \geq n$ ;
if $order = Nag_RowMajor$ , $pdt \geq maxfac$ .

29:

c [\dim]

– doubleOutput

Note: the dimension, dim, of the array c must be at least

$\max (1, pdc \times maxfac)$ when $order = Nag_ColMajor$ ;
$\max (1, my \times pdc)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

C

is stored in

$c [(j - 1) \times pdc + i - 1]$ when $order = Nag_ColMajor$ ;
$c [(i - 1) \times pdc + j - 1]$ when $order = Nag_RowMajor$ .

On exit: the

j

th column of

C

contains the

y

-loadings

c_{j}

, for

j = 1, 2, \dots, maxfac

30:

pdc

– IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array c.

Constraints:

if $order = Nag_ColMajor$ , $pdc \geq my$ ;
if $order = Nag_RowMajor$ , $pdc \geq maxfac$ .

31:

u [\dim]

– doubleOutput

Note: the dimension, dim, of the array u must be at least

$\max (1, pdu \times maxfac)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdu)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

U

is stored in

$u [(j - 1) \times pdu + i - 1]$ when $order = Nag_ColMajor$ ;
$u [(i - 1) \times pdu + j - 1]$ when $order = Nag_RowMajor$ .

On exit: the

j

th column of

U

contains the

y

-scores

u_{j}

, for

j = 1, 2, \dots, maxfac

32:

pdu

– IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array u.

Constraints:

if $order = Nag_ColMajor$ , $pdu \geq n$ ;
if $order = Nag_RowMajor$ , $pdu \geq maxfac$ .

33:

xcv [maxfac]

– doubleOutput

On exit:

xcv [j - 1]

contains the cumulative percentage of variance in the predictor variables explained by the first

j

factors, for

j = 1, 2, \dots, maxfac

34:

ycv [\dim]

– doubleOutput

Note: the dimension, dim, of the array ycv must be at least

$\max (1, pdycv \times my)$ when $order = Nag_ColMajor$ ;
$\max (1, maxfac \times pdycv)$ when $order = Nag_RowMajor$ .

Where

YCV (i, j)

appears in this document, it refers to the array element

$ycv [(j - 1) \times pdycv + i - 1]$ when $order = Nag_ColMajor$ ;
$ycv [(i - 1) \times pdycv + j - 1]$ when $order = Nag_RowMajor$ .

On exit:

YCV (i, j)

is the cumulative percentage of variance of the

j

th response variable explained by the first

i

factors, for

i = 1, 2, \dots, maxfac

and

j = 1, 2, \dots, my

35:

pdycv

– IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array ycv.

Constraints:

if $order = Nag_ColMajor$ , $pdycv \geq maxfac$ ;
if $order = Nag_RowMajor$ , $pdycv \geq my$ .

36:

fail

– NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.

NE_BAD_PARAM

On entry, argument

〈value〉

had an illegal value.

NE_INT

On entry,

mx = 〈value〉

.
Constraint:

mx > 1

On entry,

my = 〈value〉

.
Constraint:

my \geq 1

On entry,

n = 〈value〉

.
Constraint:

n > 1

On entry,

pdc = 〈value〉

.
Constraint:

pdc > 0

On entry,

pdp = 〈value〉

.
Constraint:

pdp > 0

On entry,

pdt = 〈value〉

.
Constraint:

pdt > 0

On entry,

pdu = 〈value〉

.
Constraint:

pdu > 0

On entry,

pdw = 〈value〉

.
Constraint:

pdw > 0

On entry,

pdx = 〈value〉

.
Constraint:

pdx > 0

On entry,

pdxres = 〈value〉

.
Constraint:

pdxres > 0

On entry,

pdy = 〈value〉

.
Constraint:

pdy > 0

On entry,

pdycv = 〈value〉

.
Constraint:

pdycv > 0

On entry,

pdyres = 〈value〉

.
Constraint:

pdyres > 0

NE_INT_2

On entry,

ip = 〈value〉

and

mx = 〈value〉

.
Constraint:

1 < ip \leq mx

On entry,

maxfac = 〈value〉

and

ip = 〈value〉

.
Constraint:

1 \leq maxfac \leq ip

On entry,

my = 〈value〉

and

maxit = 〈value〉

.
Constraint: if

my > 1

maxit > 1

On entry,

pdc = 〈value〉

and

maxfac = 〈value〉

.
Constraint:

pdc \geq maxfac

On entry,

pdc = 〈value〉

and

my = 〈value〉

.
Constraint:

pdc \geq

my

On entry,

pdp = 〈value〉

and

ip = 〈value〉

.
Constraint:

pdp \geq

ip

On entry,

pdp = 〈value〉

and

maxfac = 〈value〉

.
Constraint:

pdp \geq maxfac

On entry,

pdt = 〈value〉

and

maxfac = 〈value〉

.
Constraint:

pdt \geq maxfac

On entry,

pdt = 〈value〉

and

n = 〈value〉

.
Constraint:

pdt \geq

n

On entry,

pdu = 〈value〉

and

maxfac = 〈value〉

.
Constraint:

pdu \geq maxfac

On entry,

pdu = 〈value〉

and

n = 〈value〉

.
Constraint:

pdu \geq

n

On entry,

pdw = 〈value〉

and

ip = 〈value〉

.
Constraint:

pdw \geq

ip

On entry,

pdw = 〈value〉

and

maxfac = 〈value〉

.
Constraint:

pdw \geq maxfac

On entry,

pdx = 〈value〉

and

mx = 〈value〉

.
Constraint:

pdx \geq mx

On entry,

pdx = 〈value〉

and

n = 〈value〉

.
Constraint:

pdx \geq

n

On entry,

pdxres = 〈value〉

and

ip = 〈value〉

.
Constraint:

pdxres \geq ip

On entry,

pdxres = 〈value〉

and

n = 〈value〉

.
Constraint:

pdxres \geq

n

On entry,

pdy = 〈value〉

and

my = 〈value〉

.
Constraint:

pdy \geq my

On entry,

pdy = 〈value〉

and

n = 〈value〉

.
Constraint:

pdy \geq

n

On entry,

pdycv = 〈value〉

and

maxfac = 〈value〉

.
Constraint:

pdycv \geq

maxfac

On entry,

pdycv = 〈value〉

and

my = 〈value〉

.
Constraint:

pdycv \geq my

On entry,

pdyres = 〈value〉

and

my = 〈value〉

.
Constraint:

pdyres \geq my

On entry,

pdyres = 〈value〉

and

n = 〈value〉

.
Constraint:

pdyres <

n

NE_INT_ARG_CONS

On entry,

ip = 〈value〉

and

sum (isx) = 〈value〉

.
Constraint: the sum of elements in isx must equal ip.

NE_INT_ARRAY_VAL_1_OR_2

On entry,

isx (〈value〉)

is invalid.
Constraint:

isx [j - 1] = 0

1

, for all

j

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.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.

NE_REAL

On entry,

tau = 〈value〉

.
Constraint: if

my > 1

tau > 0.0

Parallelism and Performance

nag_pls_orth_scores_wold (g02lbc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

Please consult the x06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

NAG C Library Function Document

nag_pls_orth_scores_wold (g02lbc)

▸▿ Contents

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

6

Error Indicators and Warnings

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

10.2

Program Data

10.3

Program Results

NAG C Library Function Document

nag_pls_orth_scores_wold (g02lbc)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

6

Error Indicators and Warnings

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

10.2

Program Data

10.3

Program Results