NAG FL Interface
g02lcf (pls_​fit)

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

Fortran Interface
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, 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 PTW-1 CT , B m×r ,  
where W is the m by k (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 X1 and response data Y1. 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: my1.
3: maxfac Integer Input
On entry: k, the number of factors available in the PLS model.
Constraint: 1maxfacip.
4: nfact Integer Input
On entry: l, the number of factors to include in the calculation of parameter estimates.
Constraint: 1nfactmaxfac.
5: pldpmaxfac 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: ldpip.
7: cldcmaxfac 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: ldcmy.
9: wldwmaxfac 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: ldwip.
11: rcond Real (Kind=nag_wp) Input
On entry: singular values of PTW 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: bldbmy Real (Kind=nag_wp) array Output
On exit: bij contains the parameter estimate for the ith predictor variable in the model for the jth response variable, for i=1,2,,ip and j=1,2,,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: ldbip.
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 or 1.
15: xbarip 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: ybarmy 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 or 2.
18: xstdip Real (Kind=nag_wp) array Input
On entry: if orig=1 and iscale-1, the scalings of predictor variables in the model as returned from either g02laf or g02lbf; otherwise xstd is not referenced.
19: ystdmy Real (Kind=nag_wp) array Input
On entry: if orig=1 and iscale-1, the scalings of response variables as returned from either g02laf or g02lbf; otherwise ystd is not referenced.
20: obldobmy Real (Kind=nag_wp) array Output
On exit: if orig=1, ob1j contains the intercept value for the jth response variable, and obi+1j contains the parameter estimate on the original scale for the ith predictor variable in the model, for i=1,2,,ip and j=1,2,,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, ldobip+1;
  • otherwise ldob1.
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 or my.
23: ycvldycvmy Real (Kind=nag_wp) array Input
On entry: if vipopt0, ycvij is the cumulative percentage of variance of the jth response variable explained by the first i factors, for i=1,2,,nfact and j=1,2,,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 vipopt0, ldycvnfact.
25: vipldvipvipopt Real (Kind=nag_wp) array Output
On exit: if vipopt=1, vipi1 contains the VIP statistic for the ith predictor variable in the model for all response variables, for i=1,2,,ip.
If vipopt=my, vipij contains the VIP statistic for the ith predictor variable in the model for the jth response variable, for i=1,2,,ip and j=1,2,,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 vipopt0, ldvipip.
27: ifail Integer Input/Output
On entry: ifail must be set to 0, -1 or 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 or 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 or -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: my1.
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: ldbip.
On entry, ldc=value and my=value.
Constraint: ldcmy.
On entry, ldob=value and ip=value.
Constraint: if orig=1, ldobip+1.
On entry, ldp=value and ip=value.
Constraint: ldpip.
On entry, ldvip=value and ip=value.
Constraint: if vipopt0, ldvipip.
On entry, ldw=value and ip=value.
Constraint: ldwip.
On entry, ldycv=value and nfact=value.
Constraint: if vipopt0, ldycvnfact.
On entry, maxfac=value and ip=value.
Constraint: 1maxfacip.
On entry, nfact=value and maxfac=value.
Constraint: 1nfactmaxfac.
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 PTW.

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 ll+r+4+max2l,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.

10.1 Program Text

Program Text (g02lcfe.f90)

10.2 Program Data

Program Data (g02lcfe.d)

10.3 Program Results

Program Results (g02lcfe.r)