NAG CL Interface
g02lcc (pls_​fit)

Settings help

CL Name Style:


1 Purpose

g02lcc calculates parameter estimates for a given number of factors given the output from an orthogonal scores PLS regression (g02lac or g02lbc).

2 Specification

#include <nag.h>
void  g02lcc (Nag_OrderType order, Integer ip, Integer my, Integer maxfac, Integer nfact, const double p[], Integer pdp, const double c[], Integer pdc, const double w[], Integer pdw, double rcond, double b[], Integer pdb, Nag_EstimatesOption orig, const double xbar[], const double ybar[], Nag_ScalePredictor iscale, const double xstd[], const double ystd[], double ob[], Integer pdob, Integer vipopt, const double ycv[], Integer pdycv, double vip[], Integer pdvip, NagError *fail)
The function may be called by the names: g02lcc, nag_correg_pls_fit or nag_pls_orth_scores_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×k (l) matrix of x-weights; P is the m×k matrix of x-loadings; and C is the r×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, g02lcc 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: order Nag_OrderType Input
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by order=Nag_RowMajor. See Section 3.1.3 in the Introduction to the NAG Library CL Interface for a more detailed explanation of the use of this argument.
Constraint: order=Nag_RowMajor or Nag_ColMajor.
2: ip Integer Input
On entry: m, the number of predictor variables in the fitted model.
Constraint: ip>1.
3: my Integer Input
On entry: r, the number of response variables.
Constraint: my1.
4: maxfac Integer Input
On entry: k, the number of factors available in the PLS model.
Constraint: 1maxfacip.
5: nfact Integer Input
On entry: l, the number of factors to include in the calculation of parameter estimates.
Constraint: 1nfactmaxfac.
6: p[dim] const double Input
Note: the dimension, dim, of the array p must be at least
  • max(1,pdp×maxfac) when order=Nag_ColMajor;
  • max(1,ip×pdp) when order=Nag_RowMajor.
the (i,j)th element of the matrix P is stored in
  • p[(j-1)×pdp+i-1] when order=Nag_ColMajor;
  • p[(i-1)×pdp+j-1] when order=Nag_RowMajor.
On entry: x-loadings as returned from g02lac and g02lbc.
7: pdp Integer Input
On entry: the stride separating row or column elements (depending on the value of order) in the array p.
Constraints:
  • if order=Nag_ColMajor, pdpip;
  • if order=Nag_RowMajor, pdpmaxfac.
8: c[dim] const double Input
Note: the dimension, dim, of the array c must be at least
  • max(1,pdc×maxfac) when order=Nag_ColMajor;
  • max(1,my×pdc) when order=Nag_RowMajor.
the (i,j)th element of the matrix C is stored in
  • c[(j-1)×pdc+i-1] when order=Nag_ColMajor;
  • c[(i-1)×pdc+j-1] when order=Nag_RowMajor.
On entry: y-loadings as returned from g02lac and g02lbc.
9: pdc Integer Input
On entry: the stride separating row or column elements (depending on the value of order) in the array c.
Constraints:
  • if order=Nag_ColMajor, pdcmy;
  • if order=Nag_RowMajor, pdcmaxfac.
10: w[dim] const double Input
Note: the dimension, dim, of the array w must be at least
  • max(1,pdw×maxfac) when order=Nag_ColMajor;
  • max(1,ip×pdw) when order=Nag_RowMajor.
the (i,j)th element of the matrix W is stored in
  • w[(j-1)×pdw+i-1] when order=Nag_ColMajor;
  • w[(i-1)×pdw+j-1] when order=Nag_RowMajor.
On entry: x-weights as returned from g02lac and g02lbc.
11: pdw Integer Input
On entry: the stride separating row or column elements (depending on the value of order) in the array w.
Constraints:
  • if order=Nag_ColMajor, pdwip;
  • if order=Nag_RowMajor, pdwmaxfac.
12: rcond double 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.
13: b[dim] double Output
Note: the dimension, dim, of the array b must be at least
  • max(1,pdb×my) when order=Nag_ColMajor;
  • max(1,ip×pdb) when order=Nag_RowMajor.
where B(i,j) appears in this document, it refers to the array element
  • b[(j-1)×pdb+i-1] when order=Nag_ColMajor;
  • b[(i-1)×pdb+j-1] when order=Nag_RowMajor.
On exit: B(i,j) 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.
14: pdb Integer Input
On entry: the stride separating row or column elements (depending on the value of order) in the array b.
Constraints:
  • if order=Nag_ColMajor, pdbip;
  • if order=Nag_RowMajor, pdbmy.
15: orig Nag_EstimatesOption Input
On entry: indicates how parameter estimates are calculated.
orig=Nag_EstimatesStand
Parameter estimates for the centred, and possibly, scaled data.
orig=Nag_EstimatesOrig
Parameter estimates for the original data.
Constraint: orig=Nag_EstimatesStand or Nag_EstimatesOrig.
16: xbar[ip] const double Input
On entry: if orig=Nag_EstimatesOrig, mean values of predictor variables in the model; otherwise xbar is not referenced.
17: ybar[my] const double Input
On entry: if orig=Nag_EstimatesOrig, mean value of each response variable in the model; otherwise ybar is not referenced.
18: iscale Nag_ScalePredictor Input
On entry: if orig=Nag_EstimatesOrig, iscale must take the value supplied to either g02lac or g02lbc; otherwise iscale is not referenced.
Constraint: if orig=Nag_EstimatesOrig, iscale=Nag_PredNoScale, Nag_PredStdScale or Nag_PredUserScale.
19: xstd[ip] const double Input
On entry: if orig=Nag_EstimatesOrig and iscaleNag_PredNoScale, the scalings of predictor variables in the model as returned from either g02lac or g02lbc; otherwise xstd is not referenced.
20: ystd[my] const double Input
On entry: if orig=Nag_EstimatesOrig and iscaleNag_PredNoScale, the scalings of response variables as returned from either g02lac or g02lbc; otherwise ystd is not referenced.
21: ob[dim] double Output
Note: the dimension, dim, of the array ob must be at least
  • pdob×my when orig=Nag_EstimatesOrig and order=Nag_ColMajor;
  • max(1,(ip+1)×pdob) when orig=Nag_EstimatesOrig and order=Nag_RowMajor;
  • 1 otherwise.
where OB(i,j) appears in this document, it refers to the array element
  • ob[(j-1)×pdob+i-1] when order=Nag_ColMajor;
  • ob[(i-1)×pdob+j-1] when order=Nag_RowMajor.
On exit: if orig=Nag_EstimatesOrig, OB(1,j) contains the intercept value for the jth response variable, and OB(i+1,j) 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.
22: pdob Integer Input
On entry: the stride separating row or column elements (depending on the value of order) in the array ob.
Constraints:
  • if order=Nag_ColMajor,
    • if orig=Nag_EstimatesOrig, pdobip+1;
    • otherwise pdob1;
  • if order=Nag_RowMajor,
    • if orig=Nag_EstimatesOrig, pdobmy;
    • otherwise pdob1.
23: 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.
24: ycv[dim] const double Input
Note: the dimension, dim, of the array ycv must be at least my when vipopt0.
where YCV(i,j) appears in this document, it refers to the array element
  • ycv[(j-1)×pdycv+i-1] when order=Nag_ColMajor;
  • ycv[(i-1)×pdycv+j-1] when order=Nag_RowMajor.
On entry: if vipopt0, YCV(i,j) 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.
25: pdycv Integer Input
On entry: the stride separating row or column elements (depending on the value of order) in the array ycv.
Constraints:
  • if order=Nag_ColMajor, if vipopt0, pdycvnfact;
  • if order=Nag_RowMajor,
    • if vipopt0, pdycvmy.
26: vip[dim] double Output
Note: the dimension, dim, of the array vip must be at least
  • max(1,pdvip×vipopt) when order=Nag_ColMajor;
  • max(1,ip×pdvip) when order=Nag_RowMajor and vipopt0.
where VIP(i,j) appears in this document, it refers to the array element
  • vip[(j-1)×pdvip+i-1] when order=Nag_ColMajor;
  • vip[(i-1)×pdvip+j-1] when order=Nag_RowMajor.
On exit: if vipopt=1, VIP(i,1) contains the VIP statistic for the ith predictor variable in the model for all response variables, for i=1,2,,ip.
If vipopt=my, VIP(i,j) 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.
27: pdvip Integer Input
On entry: the stride separating row or column elements (depending on the value of order) in the array vip.
Constraints:
  • if order=Nag_ColMajor, if vipopt0, pdvipip;
  • if order=Nag_RowMajor, pdvipvipopt.
28: fail NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_ENUM_INT
On entry, iscale=value.
Constraint: if orig=Nag_EstimatesOrig, iscale=Nag_PredNoScale or Nag_PredStdScale.
On entry, orig=value and my=value.
Constraint: my>0.
NE_ENUM_INT_2
On entry, orig=value, pdob=value and my=value.
Constraint: if orig=Nag_EstimatesOrig, pdobmy;
otherwise pdob1.
NE_INT
On entry, ip=value.
Constraint: ip>1.
On entry, my=value.
Constraint: my1.
On entry, pdb=value.
Constraint: pdb>0.
On entry, pdc=value.
Constraint: pdc>0.
On entry, pdob=value.
Constraint: pdob>0.
On entry, pdp=value.
Constraint: pdp>0.
On entry, pdvip=value.
Constraint: pdvip>0.
On entry, pdw=value.
Constraint: pdw>0.
On entry, pdycv=value.
Constraint: pdycv>0.
NE_INT_2
On entry, maxfac=value and ip=value.
Constraint: 1maxfacip.
On entry, nfact=value and maxfac=value.
Constraint: 1nfactmaxfac.
On entry, pdb=value and ip=value.
Constraint: pdbip.
On entry, pdb=value and my=value.
Constraint: pdbmy.
On entry, pdc=value and maxfac=value.
Constraint: pdcmaxfac.
On entry, pdc=value and my=value.
Constraint: pdcmy.
On entry, pdob=value and ip=value.
Constraint: if orig=Nag_EstimatesOrig, pdobip+1.
On entry, pdp=value and ip=value.
Constraint: pdpip.
On entry, pdp=value and maxfac=value.
Constraint: pdpmaxfac.
On entry, pdvip=value and ip=value.
Constraint: if vipopt0, pdvipip.
On entry, pdvip=value and vipopt=value.
Constraint: pdvipvipopt.
On entry, pdw=value and ip=value.
Constraint: pdwip.
On entry, pdw=value and maxfac=value.
Constraint: pdwmaxfac.
On entry, pdycv=value and nfact=value.
Constraint: if vipopt0, pdycvnfact.
On entry, vipopt=value and my=value.
Constraint: my>0.
On entry, vipopt=value and my=value.
Constraint: vipopt=0, 1 or my.
NE_INT_3
On entry, pdycv=value, vipopt=value and my=value.
Constraint:
if vipopt0, pdycvmy.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.

7 Accuracy

The calculations are based on the singular value decomposition of PTW.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
g02lcc is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g02lcc 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 function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

g02lcc allocates internally l(l+r+4)+max(2l,r) elements of double 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 (g02lcce.c)

10.2 Program Data

Program Data (g02lcce.d)

10.3 Program Results

Program Results (g02lcce.r)