G02 Chapter Contents
G02 Chapter Introduction
NAG Library Manual

NAG Library Routine DocumentG02LCF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

1  Purpose

G02LCF calculates parameter estimates for a given number of factors given the output from an orthogonal scores PLS regression (G02LAF or G02LBF).

2  Specification

 SUBROUTINE G02LCF ( IP, MY, MAXFAC, NFACT, P, LDP, C, LDC, W, LDW, RCOND, B, LDB, ORIG, XBAR, YBAR, ISCALE, XSTD, YSTD, OB, LDOB, VIPOPT, YCV, LDYCV, VIP, LDVIP, IFAIL)
 INTEGER IP, MY, MAXFAC, NFACT, LDP, LDC, LDW, LDB, ORIG, ISCALE, LDOB, VIPOPT, LDYCV, LDVIP, IFAIL REAL (KIND=nag_wp) P(LDP,MAXFAC), C(LDC,MAXFAC), W(LDW,MAXFAC), RCOND, B(LDB,MY), XBAR(IP), YBAR(MY), XSTD(IP), YSTD(MY), OB(LDOB,MY), YCV(LDYCV,MY), VIP(LDVIP,VIPOPT)

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 PTW-1 CT , B∈ ℝm×r ,$
where $W$ is the $m$ by $k$ ($\ge l$) matrix of $x$-weights; $P$ is the $m$ by $k$ matrix of $x$-loadings; and $C$ is the $r$ by $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:     $\mathrm{IP}$ – INTEGERInput
On entry: $m$, the number of predictor variables in the fitted model.
Constraint: ${\mathbf{IP}}>1$.
2:     $\mathrm{MY}$ – INTEGERInput
On entry: $r$, the number of response variables.
Constraint: ${\mathbf{MY}}\ge 1$.
3:     $\mathrm{MAXFAC}$ – INTEGERInput
On entry: $k$, the number of factors available in the PLS model.
Constraint: $1\le {\mathbf{MAXFAC}}\le {\mathbf{IP}}$.
4:     $\mathrm{NFACT}$ – INTEGERInput
On entry: $l$, the number of factors to include in the calculation of parameter estimates.
Constraint: $1\le {\mathbf{NFACT}}\le {\mathbf{MAXFAC}}$.
5:     $\mathrm{P}\left({\mathbf{LDP}},{\mathbf{MAXFAC}}\right)$ – REAL (KIND=nag_wp) arrayInput
On entry: $x$-loadings as returned from G02LAF and G02LBF.
6:     $\mathrm{LDP}$ – INTEGERInput
On entry: the first dimension of the array P as declared in the (sub)program from which G02LCF is called.
Constraint: ${\mathbf{LDP}}\ge {\mathbf{IP}}$.
7:     $\mathrm{C}\left({\mathbf{LDC}},{\mathbf{MAXFAC}}\right)$ – REAL (KIND=nag_wp) arrayInput
On entry: $y$-loadings as returned from G02LAF and G02LBF.
8:     $\mathrm{LDC}$ – INTEGERInput
On entry: the first dimension of the array C as declared in the (sub)program from which G02LCF is called.
Constraint: ${\mathbf{LDC}}\ge {\mathbf{MY}}$.
9:     $\mathrm{W}\left({\mathbf{LDW}},{\mathbf{MAXFAC}}\right)$ – REAL (KIND=nag_wp) arrayInput
On entry: $x$-weights as returned from G02LAF and G02LBF.
10:   $\mathrm{LDW}$ – INTEGERInput
On entry: the first dimension of the array W as declared in the (sub)program from which G02LCF is called.
Constraint: ${\mathbf{LDW}}\ge {\mathbf{IP}}$.
11:   $\mathrm{RCOND}$ – REAL (KIND=nag_wp)Input
On entry: singular values of ${P}^{\mathrm{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:   $\mathrm{B}\left({\mathbf{LDB}},{\mathbf{MY}}\right)$ – REAL (KIND=nag_wp) arrayOutput
On exit: ${\mathbf{B}}\left(\mathit{i},\mathit{j}\right)$ contains the parameter estimate for the $\mathit{i}$th predictor variable in the model for the $\mathit{j}$th response variable, for $\mathit{i}=1,2,\dots ,{\mathbf{IP}}$ and $\mathit{j}=1,2,\dots ,{\mathbf{MY}}$.
13:   $\mathrm{LDB}$ – INTEGERInput
On entry: the first dimension of the array B as declared in the (sub)program from which G02LCF is called.
Constraint: ${\mathbf{LDB}}\ge {\mathbf{IP}}$.
14:   $\mathrm{ORIG}$ – INTEGERInput
On entry: indicates how parameter estimates are calculated.
${\mathbf{ORIG}}=-1$
Parameter estimates for the centred, and possibly, scaled data.
${\mathbf{ORIG}}=1$
Parameter estimates for the original data.
Constraint: ${\mathbf{ORIG}}=-1$ or $1$.
15:   $\mathrm{XBAR}\left({\mathbf{IP}}\right)$ – REAL (KIND=nag_wp) arrayInput
On entry: if ${\mathbf{ORIG}}=1$, mean values of predictor variables in the model; otherwise XBAR is not referenced.
16:   $\mathrm{YBAR}\left({\mathbf{MY}}\right)$ – REAL (KIND=nag_wp) arrayInput
On entry: if ${\mathbf{ORIG}}=1$, mean value of each response variable in the model; otherwise YBAR is not referenced.
17:   $\mathrm{ISCALE}$ – INTEGERInput
On entry: if ${\mathbf{ORIG}}=1$, ISCALE must take the value supplied to either G02LAF or G02LBF; otherwise ISCALE is not referenced.
Constraint: if ${\mathbf{ORIG}}=1$, ${\mathbf{ISCALE}}=-1$, $1$ or $2$.
18:   $\mathrm{XSTD}\left({\mathbf{IP}}\right)$ – REAL (KIND=nag_wp) arrayInput
On entry: if ${\mathbf{ORIG}}=1$ and ${\mathbf{ISCALE}}\ne -1$, the scalings of predictor variables in the model as returned from either G02LAF or G02LBF; otherwise XSTD is not referenced.
19:   $\mathrm{YSTD}\left({\mathbf{MY}}\right)$ – REAL (KIND=nag_wp) arrayInput
On entry: if ${\mathbf{ORIG}}=1$ and ${\mathbf{ISCALE}}\ne -1$, the scalings of response variables as returned from either G02LAF or G02LBF; otherwise YSTD is not referenced.
20:   $\mathrm{OB}\left({\mathbf{LDOB}},{\mathbf{MY}}\right)$ – REAL (KIND=nag_wp) arrayOutput
On exit: if ${\mathbf{ORIG}}=1$, ${\mathbf{OB}}\left(1,\mathit{j}\right)$ contains the intercept value for the $\mathit{j}$th response variable, and ${\mathbf{OB}}\left(\mathit{i}+1,\mathit{j}\right)$ contains the parameter estimate on the original scale for the $\mathit{i}$th predictor variable in the model, for $\mathit{i}=1,2,\dots ,{\mathbf{IP}}$ and $\mathit{j}=1,2,\dots ,{\mathbf{MY}}$. Otherwise OB is not referenced.
21:   $\mathrm{LDOB}$ – INTEGERInput
On entry: the first dimension of the array OB as declared in the (sub)program from which G02LCF is called.
Constraints:
• if ${\mathbf{ORIG}}=1$, ${\mathbf{LDOB}}\ge {\mathbf{IP}}+1$;
• otherwise ${\mathbf{LDOB}}\ge 1$.
22:   $\mathrm{VIPOPT}$ – INTEGERInput
On entry: a flag that determines variable influence on projections (VIP) options.
${\mathbf{VIPOPT}}=0$
VIP are not calculated.
${\mathbf{VIPOPT}}=1$
VIP are calculated for predictor variables using the mean explained variance in responses.
${\mathbf{VIPOPT}}={\mathbf{MY}}$
VIP are calculated for predictor variables for each response variable in the model.
Note that setting ${\mathbf{VIPOPT}}={\mathbf{MY}}$ when ${\mathbf{MY}}=1$ gives the same result as setting ${\mathbf{VIPOPT}}=1$ directly.
Constraint: ${\mathbf{VIPOPT}}=0$, $1$ or ${\mathbf{MY}}$.
23:   $\mathrm{YCV}\left({\mathbf{LDYCV}},{\mathbf{MY}}\right)$ – REAL (KIND=nag_wp) arrayInput
On entry: if ${\mathbf{VIPOPT}}\ne 0$, ${\mathbf{YCV}}\left(\mathit{i},\mathit{j}\right)$ is the cumulative percentage of variance of the $\mathit{j}$th response variable explained by the first $\mathit{i}$ factors, for $\mathit{i}=1,2,\dots ,{\mathbf{NFACT}}$ and $\mathit{j}=1,2,\dots ,{\mathbf{MY}}$; otherwise YCV is not referenced.
24:   $\mathrm{LDYCV}$ – INTEGERInput
On entry: the first dimension of the array YCV as declared in the (sub)program from which G02LCF is called.
Constraint: if ${\mathbf{VIPOPT}}\ne 0$, ${\mathbf{LDYCV}}\ge {\mathbf{NFACT}}$.
25:   $\mathrm{VIP}\left({\mathbf{LDVIP}},{\mathbf{VIPOPT}}\right)$ – REAL (KIND=nag_wp) arrayOutput
On exit: if ${\mathbf{VIPOPT}}=1$, ${\mathbf{VIP}}\left(\mathit{i},1\right)$ contains the VIP statistic for the $\mathit{i}$th predictor variable in the model for all response variables, for $\mathit{i}=1,2,\dots ,{\mathbf{IP}}$.
If ${\mathbf{VIPOPT}}={\mathbf{MY}}$, ${\mathbf{VIP}}\left(\mathit{i},\mathit{j}\right)$ contains the VIP statistic for the $\mathit{i}$th predictor variable in the model for the $\mathit{j}$th response variable, for $\mathit{i}=1,2,\dots ,{\mathbf{IP}}$ and $\mathit{j}=1,2,\dots ,{\mathbf{MY}}$.
Otherwise VIP is not referenced.
26:   $\mathrm{LDVIP}$ – INTEGERInput
On entry: the first dimension of the array VIP as declared in the (sub)program from which G02LCF is called.
Constraint: if ${\mathbf{VIPOPT}}\ne 0$, ${\mathbf{LDVIP}}\ge {\mathbf{IP}}$.
27:   $\mathrm{IFAIL}$ – INTEGERInput/Output
On entry: IFAIL must be set to $0$, $-1\text{​ or ​}1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{​ or ​}1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is $0$. When the value $-\mathbf{1}\text{​ or ​}\mathbf{1}$ is used it is essential to test the value of IFAIL on exit.
On exit: ${\mathbf{IFAIL}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

If on entry ${\mathbf{IFAIL}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
${\mathbf{IFAIL}}=1$
On entry, ${\mathbf{IP}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{IP}}>1$.
On entry, ${\mathbf{ISCALE}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{ORIG}}=1$, ${\mathbf{ISCALE}}=-1$ or $1$.
On entry, ${\mathbf{MY}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{MY}}\ge 1$.
On entry, ${\mathbf{ORIG}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ORIG}}=-1$ or $1$.
On entry, ${\mathbf{VIPOPT}}=〈\mathit{\text{value}}〉$ and ${\mathbf{MY}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{VIPOPT}}=0$, $1$ or ${\mathbf{MY}}$.
${\mathbf{IFAIL}}=2$
On entry, ${\mathbf{LDB}}=〈\mathit{\text{value}}〉$ and ${\mathbf{IP}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{LDB}}\ge {\mathbf{IP}}$.
On entry, ${\mathbf{LDC}}=〈\mathit{\text{value}}〉$ and ${\mathbf{MY}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{LDC}}\ge {\mathbf{MY}}$.
On entry, ${\mathbf{LDOB}}=〈\mathit{\text{value}}〉$ and ${\mathbf{IP}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{ORIG}}=1$, ${\mathbf{LDOB}}\ge {\mathbf{IP}}+1$.
On entry, ${\mathbf{LDP}}=〈\mathit{\text{value}}〉$ and ${\mathbf{IP}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{LDP}}\ge {\mathbf{IP}}$.
On entry, ${\mathbf{LDVIP}}=〈\mathit{\text{value}}〉$ and ${\mathbf{IP}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{VIPOPT}}\ne 0$, ${\mathbf{LDVIP}}\ge {\mathbf{IP}}$.
On entry, ${\mathbf{LDW}}=〈\mathit{\text{value}}〉$ and ${\mathbf{IP}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{LDW}}\ge {\mathbf{IP}}$.
On entry, ${\mathbf{LDYCV}}=〈\mathit{\text{value}}〉$ and ${\mathbf{NFACT}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{VIPOPT}}\ne 0$, ${\mathbf{LDYCV}}\ge {\mathbf{NFACT}}$.
On entry, ${\mathbf{MAXFAC}}=〈\mathit{\text{value}}〉$ and ${\mathbf{IP}}=〈\mathit{\text{value}}〉$.
Constraint: $1\le {\mathbf{MAXFAC}}\le {\mathbf{IP}}$.
On entry, ${\mathbf{NFACT}}=〈\mathit{\text{value}}〉$ and ${\mathbf{MAXFAC}}=〈\mathit{\text{value}}〉$.
Constraint: $1\le {\mathbf{NFACT}}\le {\mathbf{MAXFAC}}$.
${\mathbf{IFAIL}}=-99$
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
${\mathbf{IFAIL}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
${\mathbf{IFAIL}}=-999$
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7  Accuracy

The calculations are based on the singular value decomposition of ${P}^{\mathrm{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.

G02LCF allocates internally $l\left(l+r+4\right)+\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(2l,r\right)$ 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.

10.1  Program Text

Program Text (g02lcfe.f90)

10.2  Program Data

Program Data (g02lcfe.d)

10.3  Program Results

Program Results (g02lcfe.r)