NAG C Library Function Document

nag_pls_orth_scores_fit (g02lcc)

1
Purpose

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

2
Specification

#include <nag.h>
#include <nagg02.h>
void  nag_pls_orth_scores_fit (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)

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, nag_pls_orth_scores_fit (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_OrderTypeInput
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.3.1.3 in How to Use the NAG Library and its Documentation for a more detailed explanation of the use of this argument.
Constraint: order=Nag_RowMajor or Nag_ColMajor.
2:     ip IntegerInput
On entry: m, the number of predictor variables in the fitted model.
Constraint: ip>1.
3:     my IntegerInput
On entry: r, the number of response variables.
Constraint: my1.
4:     maxfac IntegerInput
On entry: k, the number of factors available in the PLS model.
Constraint: 1maxfacip.
5:     nfact IntegerInput
On entry: l, the number of factors to include in the calculation of parameter estimates.
Constraint: 1nfactmaxfac.
6:     p[dim] const doubleInput
Note: the dimension, dim, of the array p must be at least
  • max1,pdp×maxfac when order=Nag_ColMajor;
  • max1,ip×pdp when order=Nag_RowMajor.
The i,jth 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.
7:     pdp IntegerInput
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 doubleInput
Note: the dimension, dim, of the array c must be at least
  • max1,pdc×maxfac when order=Nag_ColMajor;
  • max1,my×pdc when order=Nag_RowMajor.
The i,jth 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.
9:     pdc IntegerInput
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 doubleInput
Note: the dimension, dim, of the array w must be at least
  • max1,pdw×maxfac when order=Nag_ColMajor;
  • max1,ip×pdw when order=Nag_RowMajor.
The i,jth 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.
11:   pdw IntegerInput
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 doubleInput
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] doubleOutput
Note: the dimension, dim, of the array b must be at least
  • max1,pdb×my when order=Nag_ColMajor;
  • max1,ip×pdb when order=Nag_RowMajor.
Where Bi,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: Bi,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 IntegerInput
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_EstimatesOptionInput
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 doubleInput
On entry: if orig=Nag_EstimatesOrig, mean values of predictor variables in the model; otherwise xbar is not referenced.
17:   ybar[my] const doubleInput
On entry: if orig=Nag_EstimatesOrig, mean value of each response variable in the model; otherwise ybar is not referenced.
18:   iscale Nag_ScalePredictorInput
On entry: if orig=Nag_EstimatesOrig, iscale must take the value supplied to either nag_pls_orth_scores_svd (g02lac) or nag_pls_orth_scores_wold (g02lbc); otherwise iscale is not referenced.
Constraint: if orig=Nag_EstimatesOrig, iscale=Nag_PredNoScale, Nag_PredStdScale or Nag_PredUserScale.
19:   xstd[ip] const doubleInput
On entry: if orig=Nag_EstimatesOrig and iscaleNag_PredNoScale, the scalings of predictor variables in the model as returned from either nag_pls_orth_scores_svd (g02lac) or nag_pls_orth_scores_wold (g02lbc); otherwise xstd is not referenced.
20:   ystd[my] const doubleInput
On entry: if orig=Nag_EstimatesOrig and iscaleNag_PredNoScale, the scalings of response variables as returned from either nag_pls_orth_scores_svd (g02lac) or nag_pls_orth_scores_wold (g02lbc); otherwise ystd is not referenced.
21:   ob[dim] doubleOutput
Note: the dimension, dim, of the array ob must be at least
  • pdob×my when orig=Nag_EstimatesOrig and order=Nag_ColMajor;
  • max1,(ip+1)×pdob when orig=Nag_EstimatesOrig and order=Nag_RowMajor;
  • 1 otherwise.
Where OBi,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, OB1,j contains the intercept value for the jth response variable, and OBi+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 IntegerInput
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 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.
24:   ycv[dim] const doubleInput
Note: the dimension, dim, of the array ycv must be at least my when vipopt0.
Where YCVi,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, YCVi,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 IntegerInput
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] doubleOutput
Note: the dimension, dim, of the array vip must be at least
  • max1,pdvip×vipopt when order=Nag_ColMajor;
  • max1,ip×pdvip when order=Nag_RowMajor and vipopt0.
Where VIPi,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, VIPi,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, VIPi,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 IntegerInput
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 3.7 in How to Use the NAG Library and its Documentation).

6
Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation 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, 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: pdb or ip.
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: pdc or my.
On entry, pdob=value and ip=value.
Constraint: if orig=Nag_EstimatesOrig, pdobip+1.
On entry, pdp=value and ip=value.
Constraint: pdp or ip.
On entry, pdp=value and maxfac=value.
Constraint: pdpmaxfac.
On entry, pdvip=value and ip=value.
Constraint: if vipopt0, pdvip or ip.
On entry, pdvip=value and vipopt=value.
Constraint: pdvipvipopt.
On entry, pdw=value and ip=value.
Constraint: pdw or ip.
On entry, pdw=value and maxfac=value.
Constraint: pdwmaxfac.
On entry, pdycv=value and nfact=value.
Constraint: if vipopt0, pdycv or nfact.
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 2.7.6 in How to Use the NAG Library and its Documentation for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 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

nag_pls_orth_scores_fit (g02lcc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_pls_orth_scores_fit (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

nag_pls_orth_scores_fit (g02lcc) allocates internally ll+r+4+max2l,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)