NAG Library Routine Document

g02lcf  (pls_fit)

 Contents

    1  Purpose
    7  Accuracy

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 nagmk26.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)

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 – IntegerInput
On entry: m, the number of predictor variables in the fitted model.
Constraint: ip>1.
2:     my – IntegerInput
On entry: r, the number of response variables.
Constraint: my1.
3:     maxfac – IntegerInput
On entry: k, the number of factors available in the PLS model.
Constraint: 1maxfacip.
4:     nfact – IntegerInput
On entry: l, the number of factors to include in the calculation of parameter estimates.
Constraint: 1nfactmaxfac.
5:     pldpmaxfac – 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: ldpip.
7:     cldcmaxfac – 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: ldcmy.
9:     wldwmaxfac – 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: 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) arrayOutput
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 – IntegerInput
On entry: the first dimension of the array b as declared in the (sub)program from which g02lcf is called.
Constraint: ldbip.
14:   orig – IntegerInput
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) arrayInput
On entry: if orig=1, mean values of predictor variables in the model; otherwise xbar is not referenced.
16:   ybarmy – Real (Kind=nag_wp) arrayInput
On entry: if orig=1, mean value of each response variable in the model; otherwise ybar is not referenced.
17:   iscale – IntegerInput
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) arrayInput
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) arrayInput
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) arrayOutput
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 – IntegerInput
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 – IntegerInput
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) arrayInput
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 – IntegerInput
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) arrayOutput
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 – IntegerInput
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 – IntegerInput/Output
On entry: ifail must be set to 0, -1​ 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​ 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 -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 3.9 in How to Use the NAG Library and its Documentation for further information.
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.
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 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)

© The Numerical Algorithms Group Ltd, Oxford, UK. 2017