g02lac (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, 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)

The function may be called by the names: g02lac, nag_correg_pls_svd or nag_pls_orth_scores_svd.

3 Description

Let

X_{1}

be the mean-centred

n \times m

data matrix

X

n

observations on

m

predictor variables. Let

Y_{1}

be the mean-centred

n \times 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

t_{1}

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

4 References

None.

5 Arguments

1: $order$ – Nag_OrderType Input

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.1.3 in the Introduction to the NAG Library CL Interface for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

Nag_ColMajor

2: $n$ – Integer Input

On entry:

n

, the number of observations.

Constraint:

n > 1

3: $mx$ – Integer Input

On entry: the number of predictor variables.

Constraint:

mx > 1

4: $x [\dim]$ – const double Input

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$ – Integer Input

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 Integer Input

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$ – Integer Input

On entry:

m

, the number of predictor variables in the model.

Constraint:

1 < ip \leq mx

8: $my$ – Integer Input

On entry:

r

, the number of response variables.

Constraint:

my \geq 1

9: $y [\dim]$ – const double Input

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$ – Integer Input

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]$ – double Output

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

12: $ybar [my]$ – double Output

On exit: the mean value of each response variable.

13: $iscale$ – Nag_ScalePredictor Input

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]$ – double Input/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]$ – double Input/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$ – Integer Input

On entry:

k

, the number of latent variables to calculate.

Constraint:

1 \leq maxfac \leq ip

17: $xres [\dim]$ – double Output

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}

18: $pdxres$ – Integer Input

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

19: $yres [\dim]$ – double Output

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}

20: $pdyres$ – Integer Input

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

21: $w [\dim]$ – double Output

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

22: $pdw$ – Integer Input

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

23: $p [\dim]$ – double Output

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

24: $pdp$ – Integer Input

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

25: $t [\dim]$ – double Output

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

26: $pdt$ – Integer Input

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

27: $c [\dim]$ – double Output

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

28: $pdc$ – Integer Input

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

29: $u [\dim]$ – double Output

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

30: $pdu$ – Integer Input

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

31: $xcv [maxfac]$ – double Output

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

32: $ycv [\dim]$ – double Output

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

33: $pdycv$ – Integer Input

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

34: $fail$ – NagError * Input/Output

The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface 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, $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 \geq 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$ or $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 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_NO_LICENCE: Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.

7 Accuracy

The computed singular value decomposition is nearly the exact singular value decomposition for a nearby matrix

(A + E)

, where

{‖ E ‖}_{2} = O (ε) {‖ A ‖}_{2},

and

ε

is the machine precision.

8 Parallelism and Performance

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

9 Further Comments

g02lac allocates internally

2 m r + A + \max (3 (A + B), 5 A) + r

elements of double storage, where

A = \min (m, r)

and

B = \max (m, r)

10 Example

This example reads in data from an experiment to measure the biological activity in a chemical compound, and a PLS model is estimated.

g02la: FL CL CPP AD

NAG CL Interfaceg02lac (pls_​svd)

▸▿ 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 CL Interface
g02lac (pls_svd)