nag_pls_orth_scores_wold (g02lbc) : NAG Library, Mark 23

2 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)

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

5 Arguments

1: 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.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

or Nag_ColMajor.

2: n – IntegerInput

On entry:

n

, the number of observations.

Constraint:

n > 1

3: mx – IntegerInput

On entry: the number of predictor variables.

Constraint:

mx > 1

4: 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

5: 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$ .

6: 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.

7: ip – IntegerInput

On entry:

m

, the number of predictor variables in the model.

Constraint:

1 < ip \leq mx

8: my – IntegerInput

On entry:

r

, the number of response variables.

Constraint:

my \geq 1

9: 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.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.

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 is not equal to the sum of isx elements:

ip = 〈value〉

sum (isx) = 〈value〉

NE_INT_ARRAY_VAL_1_OR_2

On entry, element

〈value〉

of isx is invalid.

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_REAL

On entry,

tau = 〈value〉

.
Constraint: if

my > 1

tau > 0.0

NAG 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 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Documentnag_pls_orth_scores_wold (g02lbc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_pls_orth_scores_wold (g02lbc)