nag_pls_orth_scores_fit (g02lcc) (PDF version)
g02 Chapter Contents
g02 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_pls_orth_scores_fit (g02lcc)

+ Contents

    1  Purpose
    7  Accuracy

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:     orderNag_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.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: order=Nag_RowMajor or Nag_ColMajor.
2:     ipIntegerInput
On entry: m, the number of predictor variables in the fitted model.
Constraint: ip>1.
3:     myIntegerInput
On entry: r, the number of response variables.
Constraint: my1.
4:     maxfacIntegerInput
On entry: k, the number of factors available in the PLS model.
Constraint: 1maxfacip.
5:     nfactIntegerInput
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:     pdpIntegerInput
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:     pdcIntegerInput
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:   pdwIntegerInput
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:   rconddoubleInput
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:   pdbIntegerInput
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:   origNag_EstimatesOptionInput
On entry: indicates how parameter estimates are calculated.
orig=Nag_EstimatesStand
Parameter estimates for the centered, 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:   iscaleNag_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:   pdobIntegerInput
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:   vipoptIntegerInput
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
  • pdycv×my when vipopt0 and order=Nag_ColMajor;
  • max1,nfact×pdycv when vipopt0 and order=Nag_RowMajor.
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:   pdycvIntegerInput
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:   pdvipIntegerInput
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:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
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.
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.

7  Accuracy

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

8  Further Comments

nag_pls_orth_scores_fit (g02lcc) allocates internally ll+r+4+max2l,r elements of double 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 (g02lcce.c)

9.2  Program Data

Program Data (g02lcce.d)

9.3  Program Results

Program Results (g02lcce.r)


nag_pls_orth_scores_fit (g02lcc) (PDF version)
g02 Chapter Contents
g02 Chapter Introduction
NAG C Library Manual

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