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  Parameters

1:     IP – INTEGERInput
On entry: $m$, the number of predictor variables in the fitted model.
Constraint: ${\mathbf{IP}}>1$.
2:     MY – INTEGERInput
On entry: $r$, the number of response variables.
Constraint: ${\mathbf{MY}}\ge 1$.
3:     MAXFAC – INTEGERInput
On entry: $k$, the number of factors available in the PLS model.
Constraint: $1\le {\mathbf{MAXFAC}}\le {\mathbf{IP}}$.
4:     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:     P(LDP,MAXFAC) – REAL (KIND=nag_wp) arrayInput
On entry: $x$-loadings as returned from G02LAF and G02LBF.
6:     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:     C(LDC,MAXFAC) – REAL (KIND=nag_wp) arrayInput
On entry: $y$-loadings as returned from G02LAF and G02LBF.
8:     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:     W(LDW,MAXFAC) – REAL (KIND=nag_wp) arrayInput
On entry: $x$-weights as returned from G02LAF and G02LBF.
10:   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:   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:   B(LDB,MY) – 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:   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:   ORIG – INTEGERInput
On entry: indicates how parameter estimates are calculated.
${\mathbf{ORIG}}=-1$
Parameter estimates for the centered, and possibly, scaled data.
${\mathbf{ORIG}}=1$
Parameter estimates for the original data.
Constraint: ${\mathbf{ORIG}}=-1$ or $1$.
15:   XBAR(IP) – 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:   YBAR(MY) – 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:   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:   XSTD(IP) – 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:   YSTD(MY) – 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:   OB(LDOB,MY) – 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:   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:   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:   YCV(LDYCV,MY) – 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:   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:   VIP(LDVIP,VIPOPT) – 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:   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:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to $0$, $-1\text{​ or ​}1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction 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 parameter, 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}}={\mathbf{0}}$ or $-{\mathbf{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}}<2$, or ${\mathbf{MY}}<1$, or ${\mathbf{ORIG}}\ne -1$ or $1$, or ${\mathbf{ORIG}}=1$ and ${\mathbf{ISCALE}}\ne -1$, $1$ or $2$, or ${\mathbf{VIPOPT}}\ne 0$, $1$ or ${\mathbf{MY}}$.
${\mathbf{IFAIL}}=2$
 On entry, ${\mathbf{MAXFAC}}<1$ or ${\mathbf{MAXFAC}}>{\mathbf{IP}}$, or ${\mathbf{NFACT}}<1$ or ${\mathbf{NFACT}}>{\mathbf{MAXFAC}}$, or ${\mathbf{LDP}}<{\mathbf{IP}}$, or ${\mathbf{LDC}}<{\mathbf{MY}}$, or ${\mathbf{LDW}}<{\mathbf{IP}}$, or ${\mathbf{LDB}}<{\mathbf{IP}}$, or ${\mathbf{ORIG}}=1$ and ${\mathbf{LDOB}}<{\mathbf{IP}}+1$, or ${\mathbf{LDYCV}}<{\mathbf{NFACT}}$, or ${\mathbf{VIPOPT}}\ne 0$ and ${\mathbf{LDVIP}}<{\mathbf{IP}}$.

## 7  Accuracy

The calculations are based on the singular value decomposition of ${P}^{\mathrm{T}}W$.

G02LCF allocates internally $l\left(l+r+4\right)+\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(2l,r\right)$ elements of real storage.

## 9  Example

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

### 9.1  Program Text

Program Text (g02lcfe.f90)

### 9.2  Program Data

Program Data (g02lcfe.d)

### 9.3  Program Results

Program Results (g02lcfe.r)