Integer, Intent (In)	::	ip, my, maxfac, nfact, ldp, ldc, ldw, ldb, orig, iscale, ldob, vipopt, ldycv, ldvip
Integer, Intent (Inout)	::	ifail
Real (Kind=nag_wp), Intent (In)	::	p(ldp,maxfac), c(ldc,maxfac), w(ldw,maxfac), rcond, xbar(ip), ybar(my), xstd(ip), ystd(my), ycv(ldycv,my)
Real (Kind=nag_wp), Intent (Inout)	::	b(ldb,my), ob(ldob,my), vip(ldvip,vipopt)

C Header Interface

#include <nag.h>

void

g02lcf_ (const Integer *ip, const Integer *my, const Integer *maxfac, const Integer *nfact, const double p[], const Integer *ldp, const double c[], const Integer *ldc, const double w[], const Integer *ldw, const double *rcond, double b[], const Integer *ldb, const Integer *orig, const double xbar[], const double ybar[], const Integer *iscale, const double xstd[], const double ystd[], double ob[], const Integer *ldob, const Integer *vipopt, const double ycv[], const Integer *ldycv, double vip[], const Integer *ldvip, Integer *ifail)

The routine may be called by the names g02lcf or nagf_correg_pls_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 \times k

(

\geq l

) matrix of

x

-weights;

P

is the

m \times k

matrix of

x

-loadings; and

C

is the

r \times 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, g02lcf 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: $ip$ – Integer Input

On entry:

m

, the number of predictor variables in the fitted model.

Constraint:

ip > 1

2: $my$ – Integer Input

On entry:

r

, the number of response variables.

Constraint:

my \geq 1

3: $maxfac$ – Integer Input

On entry:

k

, the number of factors available in the PLS model.

Constraint:

1 \leq maxfac \leq ip

4: $nfact$ – Integer Input

On entry:

l

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

Constraint:

1 \leq nfact \leq maxfac

5: $p (ldp, maxfac)$ – Real (Kind=nag_wp) array Input

On entry:

x

-loadings as returned from g02laf and g02lbf.

6: $ldp$ – Integer Input

On entry: the first dimension of the array p as declared in the (sub)program from which g02lcf is called.

Constraint:

ldp \geq ip

7: $c (ldc, maxfac)$ – Real (Kind=nag_wp) array Input

On entry:

y

-loadings as returned from g02laf and g02lbf.

8: $ldc$ – Integer Input

On entry: the first dimension of the array c as declared in the (sub)program from which g02lcf is called.

Constraint:

ldc \geq my

9: $w (ldw, maxfac)$ – Real (Kind=nag_wp) array Input

On entry:

x

-weights as returned from g02laf and g02lbf.

10: $ldw$ – Integer Input

On entry: the first dimension of the array w as declared in the (sub)program from which g02lcf is called.

Constraint:

ldw \geq ip

11: $rcond$ – Real (Kind=nag_wp) 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.

12: $b (ldb, my)$ – Real (Kind=nag_wp) array Output

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

13: $ldb$ – Integer Input

On entry: the first dimension of the array b as declared in the (sub)program from which g02lcf is called.

Constraint:

ldb \geq ip

14: $orig$ – Integer Input

On entry: indicates how parameter estimates are calculated.

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

Constraint:

orig = −1

1

15: $xbar (ip)$ – Real (Kind=nag_wp) array Input

On entry: if

orig = 1

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

16: $ybar (my)$ – Real (Kind=nag_wp) array Input

On entry: if

orig = 1

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

17: $iscale$ – Integer Input

On entry: if

orig = 1

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

Constraint: if

orig = 1

iscale = −1

1

2

18: $xstd (ip)$ – Real (Kind=nag_wp) array Input

On entry: if

orig = 1

and

iscale \neq −1

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

19: $ystd (my)$ – Real (Kind=nag_wp) array Input

On entry: if

orig = 1

and

iscale \neq −1

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

20: $ob (ldob, my)$ – Real (Kind=nag_wp) array Output

On exit: if

orig = 1

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.

21: $ldob$ – Integer Input

On entry: the first dimension of the array ob as declared in the (sub)program from which g02lcf is called.

Constraints:

if $orig = 1$ , $ldob \geq ip + 1$ ;
otherwise $ldob \geq 1$ .

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

23: $ycv (ldycv, my)$ – Real (Kind=nag_wp) array Input

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.

24: $ldycv$ – Integer Input

On entry: the first dimension of the array ycv as declared in the (sub)program from which g02lcf is called.

Constraint: if

vipopt \neq 0

ldycv \geq nfact

25: $vip (ldvip, vipopt)$ – Real (Kind=nag_wp) array Output

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.

26: $ldvip$ – Integer Input

On entry: the first dimension of the array vip as declared in the (sub)program from which g02lcf is called.

Constraint: if

vipopt \neq 0

ldvip \geq ip

27: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

−1

1

to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of

0

causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of

−1

means that an error message is printed while a value of

1

means that it is not.

If halting is not appropriate, the value

−1

1

is recommended. If message printing is undesirable, then the value

1

is recommended. Otherwise, the value

0

is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

−1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$: On entry, $ip = ⟨ value ⟩$ .
Constraint: $ip > 1$ .

On entry, $iscale = ⟨ value ⟩$ .
Constraint: if $orig = 1$ , $iscale = −1$ or $1$ .

On entry, $my = ⟨ value ⟩$ .
Constraint: $my \geq 1$ .

On entry, $orig = ⟨ value ⟩$ .
Constraint: $orig = −1$ or $1$ .

On entry, $vipopt = ⟨ value ⟩$ and $my = ⟨ value ⟩$ .
Constraint: $vipopt = 0$ , $1$ or $my$ .

$ifail = 2$: On entry, $ldb = ⟨ value ⟩$ and $ip = ⟨ value ⟩$ .
Constraint: $ldb \geq ip$ .

On entry, $ldc = ⟨ value ⟩$ and $my = ⟨ value ⟩$ .
Constraint: $ldc \geq my$ .

On entry, $ldob = ⟨ value ⟩$ and $ip = ⟨ value ⟩$ .
Constraint: if $orig = 1$ , $ldob \geq ip + 1$ .

On entry, $ldp = ⟨ value ⟩$ and $ip = ⟨ value ⟩$ .
Constraint: $ldp \geq ip$ .

On entry, $ldvip = ⟨ value ⟩$ and $ip = ⟨ value ⟩$ .
Constraint: if $vipopt \neq 0$ , $ldvip \geq ip$ .

On entry, $ldw = ⟨ value ⟩$ and $ip = ⟨ value ⟩$ .
Constraint: $ldw \geq ip$ .

On entry, $ldycv = ⟨ value ⟩$ and $nfact = ⟨ value ⟩$ .
Constraint: if $vipopt \neq 0$ , $ldycv \geq nfact$ .

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

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

The calculations are based on the singular value decomposition of

P^{T} W

8 Parallelism and Performance

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

g02lcf 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 routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

g02lcf allocates internally

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

elements of real 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 FL Interfaceg02lcf (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 FL Interface
g02lcf (pls_fit)