g02lcc (Nag_OrderType order, Integer ip, Integer my, Integer maxfac, Integer nfact, const double p[], Integer pdp, const double c[], Integer pdc, const double w[], Integer pdw, double rcond, double b[], Integer pdb, Nag_EstimatesOption orig, const double xbar[], const double ybar[], Nag_ScalePredictor iscale, const double xstd[], const double ystd[], double ob[], Integer pdob, Integer vipopt, const double ycv[], Integer pdycv, double vip[], Integer pdvip, NagError *fail)

The function may be called by the names: g02lcc, nag_correg_pls_fit or nag_pls_orth_scores_fit.

3 Description

The parameter estimates

B

for a

l

-factor orthogonal scores PLS model with

m

predictor variables and

r

response variables are given by,

B = W {(P^{T} W)}^{- 1} C^{T}, B \in ℝ^{m \times r},

where

W

is the

m

k

(

\geq l

) matrix of

x

-weights;

P

is the

m

k

matrix of

x

-loadings; and

C

is the

r

k

matrix of

y

-loadings for a fitted PLS model.

The parameter estimates

B

are for centred, and possibly scaled, predictor data

X_{1}

and response data

Y_{1}

. Parameter estimates may also be given for the predictor data

X

and response data

Y

Optionally, g02lcc will calculate variable influence on projection (VIP) statistics, see Wold (1994).

4 References

Wold S (1994) PLS for multivariate linear modelling QSAR: chemometric methods in molecular design Methods and Principles in Medicinal Chemistry (ed van de Waterbeemd H) Verlag-Chemie

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

On entry:

m

, the number of predictor variables in the fitted model.

Constraint:

ip > 1

3: $my$ – Integer Input

On entry:

r

, the number of response variables.

Constraint:

my \geq 1

4: $maxfac$ – Integer Input

On entry:

k

, the number of factors available in the PLS model.

Constraint:

1 \leq maxfac \leq ip

5: $nfact$ – Integer Input

On entry:

l

, the number of factors to include in the calculation of parameter estimates.

Constraint:

1 \leq nfact \leq maxfac

6: $p [\dim]$ – const double Input

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

x

-loadings as returned from g02lac and g02lbc.

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

8: $c [\dim]$ – const double Input

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

y

-loadings as returned from g02lac and g02lbc.

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

10: $w [\dim]$ – const double Input

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

x

-weights as returned from g02lac and g02lbc.

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

12: $rcond$ – double Input

On entry: singular values of

P^{T} W

less than rcond times the maximum singular value are treated as zero when calculating parameter estimates. If rcond is negative, a value of

0.005

is used.

13: $b [\dim]$ – double Output

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

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

where

B (i, j)

appears in this document, it refers to the array element

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

On exit:

B (i, j)

contains the parameter estimate for the

i

th predictor variable in the model for the

j

th response variable, for

i = 1, 2, \dots, ip

and

j = 1, 2, \dots, my

14: $pdb$ – Integer Input

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

Constraints:

if $order = Nag_ColMajor$ , $pdb \geq ip$ ;
if $order = Nag_RowMajor$ , $pdb \geq my$ .

15: $orig$ – Nag_EstimatesOption Input

On entry: indicates how parameter estimates are calculated.

$orig = Nag_EstimatesStand$: Parameter estimates for the centred, and possibly, scaled data.
$orig = Nag_EstimatesOrig$: Parameter estimates for the original data.

Constraint:

orig = Nag_EstimatesStand

Nag_EstimatesOrig

16: $xbar [ip]$ – const double Input

On entry: if

orig = Nag_EstimatesOrig

, mean values of predictor variables in the model; otherwise xbar is not referenced.

17: $ybar [my]$ – const double Input

On entry: if

orig = Nag_EstimatesOrig

, mean value of each response variable in the model; otherwise ybar is not referenced.

18: $iscale$ – Nag_ScalePredictor Input

On entry: if

orig = Nag_EstimatesOrig

, iscale must take the value supplied to either g02lac or g02lbc; otherwise iscale is not referenced.

Constraint: if

orig = Nag_EstimatesOrig

iscale = Nag_PredNoScale

Nag_PredStdScale

Nag_PredUserScale

19: $xstd [ip]$ – const double Input

On entry: if

orig = Nag_EstimatesOrig

and

iscale \neq Nag_PredNoScale

, the scalings of predictor variables in the model as returned from either g02lac or g02lbc; otherwise xstd is not referenced.

20: $ystd [my]$ – const double Input

On entry: if

orig = Nag_EstimatesOrig

and

iscale \neq Nag_PredNoScale

, the scalings of response variables as returned from either g02lac or g02lbc; otherwise ystd is not referenced.

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

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

$pdob \times my$ when $orig = Nag_EstimatesOrig$ and $order = Nag_ColMajor$ ;
$\max (1, (ip + 1) \times pdob)$ when $orig = Nag_EstimatesOrig$ and $order = Nag_RowMajor$ ;
$1$ otherwise.

where

OB (i, j)

appears in this document, it refers to the array element

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

On exit: if

orig = Nag_EstimatesOrig

OB (1, j)

contains the intercept value for the

j

th response variable, and

OB (i + 1, j)

contains the parameter estimate on the original scale for the

i

th predictor variable in the model, for

i = 1, 2, \dots, ip

and

j = 1, 2, \dots, my

. Otherwise ob is not referenced.

22: $pdob$ – Integer Input

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

Constraints:

if $order = Nag_ColMajor$ ,
- if $orig = Nag_EstimatesOrig$ , $pdob \geq ip + 1$ ;
- otherwise $pdob \geq 1$ ;
if $order = Nag_RowMajor$ ,
- if $orig = Nag_EstimatesOrig$ , $pdob \geq my$ ;
- otherwise $pdob \geq 1$ .

23: $vipopt$ – Integer Input

On entry: a flag that determines variable influence on projections (VIP) options.

$vipopt = 0$: VIP are not calculated.
$vipopt = 1$: VIP are calculated for predictor variables using the mean explained variance in responses.
$vipopt = my$: VIP are calculated for predictor variables for each response variable in the model.

Note that setting

vipopt = my

when

my = 1

gives the same result as setting

vipopt = 1

directly.

Constraint:

vipopt = 0

1

my

24: $ycv [\dim]$ – const double Input

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

my

when

vipopt \neq 0

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 entry: if

vipopt \neq 0

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, nfact

and

j = 1, 2, \dots, my

; otherwise ycv is not referenced.

25: $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$ , if $vipopt \neq 0$ , $pdycv \geq nfact$ ;
if $order = Nag_RowMajor$ ,
- if $vipopt \neq 0$ , $pdycv \geq my$ .

26: $vip [\dim]$ – double Output

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

$\max (1, pdvip \times vipopt)$ when $order = Nag_ColMajor$ ;
$\max (1, ip \times pdvip)$ when $order = Nag_RowMajor$ and $vipopt \neq 0$ .

where

VIP (i, j)

appears in this document, it refers to the array element

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

On exit: if

vipopt = 1

VIP (i, 1)

contains the VIP statistic for the

i

th predictor variable in the model for all response variables, for

i = 1, 2, \dots, ip

vipopt = my

VIP (i, j)

contains the VIP statistic for the

i

th predictor variable in the model for the

j

th response variable, for

i = 1, 2, \dots, ip

and

j = 1, 2, \dots, my

Otherwise vip is not referenced.

27: $pdvip$ – Integer Input

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

Constraints:

if $order = Nag_ColMajor$ , if $vipopt \neq 0$ , $pdvip \geq ip$ ;
if $order = Nag_RowMajor$ , $pdvip \geq vipopt$ .

28: $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_ENUM_INT: On entry, $iscale = 〈value〉$ .
Constraint: if $orig = Nag_EstimatesOrig$ , $iscale = Nag_PredNoScale$ or $Nag_PredStdScale$ .

On entry, $orig = 〈value〉$ and $my = 〈value〉$ .
Constraint: $my > 0$ .
NE_ENUM_INT_2: On entry, $orig = 〈value〉$ , $pdob = 〈value〉$ and $my = 〈value〉$ .
Constraint: if $orig = Nag_EstimatesOrig$ , $pdob \geq my$ ;
otherwise $pdob \geq 1$ .
NE_INT: On entry, $ip = 〈value〉$ .
Constraint: $ip > 1$ .

On entry, $my = 〈value〉$ .
Constraint: $my \geq 1$ .

On entry, $pdb = 〈value〉$ .
Constraint: $pdb > 0$ .

On entry, $pdc = 〈value〉$ .
Constraint: $pdc > 0$ .

On entry, $pdob = 〈value〉$ .
Constraint: $pdob > 0$ .

On entry, $pdp = 〈value〉$ .
Constraint: $pdp > 0$ .

On entry, $pdvip = 〈value〉$ .
Constraint: $pdvip > 0$ .

On entry, $pdw = 〈value〉$ .
Constraint: $pdw > 0$ .

On entry, $pdycv = 〈value〉$ .
Constraint: $pdycv > 0$ .
NE_INT_2: On entry, $maxfac = 〈value〉$ and $ip = 〈value〉$ .
Constraint: $1 \leq maxfac \leq ip$ .

On entry, $nfact = 〈value〉$ and $maxfac = 〈value〉$ .
Constraint: $1 \leq nfact \leq maxfac$ .

On entry, $pdb = 〈value〉$ and $ip = 〈value〉$ .
Constraint: $pdb \geq ip$ .

On entry, $pdb = 〈value〉$ and $my = 〈value〉$ .
Constraint: $pdb \geq my$ .

On entry, $pdc = 〈value〉$ and $maxfac = 〈value〉$ .
Constraint: $pdc \geq maxfac$ .

On entry, $pdc = 〈value〉$ and $my = 〈value〉$ .
Constraint: $pdc \geq my$ .

On entry, $pdob = 〈value〉$ and $ip = 〈value〉$ .
Constraint: if $orig = Nag_EstimatesOrig$ , $pdob \geq ip + 1$ .

On entry, $pdp = 〈value〉$ and $ip = 〈value〉$ .
Constraint: $pdp \geq ip$ .

On entry, $pdp = 〈value〉$ and $maxfac = 〈value〉$ .
Constraint: $pdp \geq maxfac$ .

On entry, $pdvip = 〈value〉$ and $ip = 〈value〉$ .
Constraint: if $vipopt \neq 0$ , $pdvip \geq ip$ .

On entry, $pdvip = 〈value〉$ and $vipopt = 〈value〉$ .
Constraint: $pdvip \geq vipopt$ .

On entry, $pdw = 〈value〉$ and $ip = 〈value〉$ .
Constraint: $pdw \geq ip$ .

On entry, $pdw = 〈value〉$ and $maxfac = 〈value〉$ .
Constraint: $pdw \geq maxfac$ .

On entry, $pdycv = 〈value〉$ and $nfact = 〈value〉$ .
Constraint: if $vipopt \neq 0$ , $pdycv \geq nfact$ .

On entry, $vipopt = 〈value〉$ and $my = 〈value〉$ .
Constraint: $my > 0$ .

On entry, $vipopt = 〈value〉$ and $my = 〈value〉$ .
Constraint: $vipopt = 0$ , $1$ or $my$ .
NE_INT_3: On entry, $pdycv = 〈value〉$ , $vipopt = 〈value〉$ and $my = 〈value〉$ .
Constraint:
if $vipopt \neq 0$ , $pdycv \geq my$ .
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 calculations are based on the singular value decomposition of

P^{T} W

8 Parallelism and Performance

g02lcc is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.

g02lcc 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

g02lcc allocates internally

l (l + r + 4) + \max (2 l, r)

elements of double storage.

10 Example

This example reads in details of a PLS model, and a set of parameter estimates are calculated along with their VIP statistics.

g02lc: FL CL CPP AD

NAG CL Interfaceg02lcc (pls_​fit)

▸▿ 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
g02lcc (pls_fit)