nag_pls_orth_scores_fit (g02lcc) : NAG Library, Mark 25

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 {(P^{T} W)}^{- 1} C^{T}, B \in ℝ^{m \times r},

where

W

is the

m

k

(

\geq 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

X_{1}

and response data

Y_{1}

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

5 Arguments

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.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

Nag_ColMajor

ip

– IntegerInput

On entry:

m

, the number of predictor variables in the fitted model.

Constraint:

ip > 1

my

– IntegerInput

On entry:

r

, the number of response variables.

Constraint:

my \geq 1

maxfac

– IntegerInput

On entry:

k

, the number of factors available in the PLS model.

Constraint:

1 \leq maxfac \leq ip

nfact

– IntegerInput

On entry:

l

, the number of factors to include in the calculation of parameter estimates.

Constraint:

1 \leq nfact \leq maxfac

p [\dim]

– const doubleInput

Note: the dimension, dim, of the array p must be at least

$\max (1, pdp \times maxfac)$ when $order = Nag_ColMajor$ ;
$\max (1, ip \times pdp)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

P

is stored in

$p [(j - 1) \times pdp + i - 1]$ when $order = Nag_ColMajor$ ;
$p [(i - 1) \times pdp + j - 1]$ when $order = Nag_RowMajor$ .

On entry:

x

-loadings as returned from nag_pls_orth_scores_svd (g02lac) and nag_pls_orth_scores_wold (g02lbc).

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$ , $pdp \geq ip$ ;
if $order = Nag_RowMajor$ , $pdp \geq maxfac$ .

c [\dim]

– const doubleInput

Note: the dimension, dim, of the array c must be at least

$\max (1, pdc \times maxfac)$ when $order = Nag_ColMajor$ ;
$\max (1, my \times pdc)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

C

is stored in

$c [(j - 1) \times pdc + i - 1]$ when $order = Nag_ColMajor$ ;
$c [(i - 1) \times pdc + j - 1]$ when $order = Nag_RowMajor$ .

On entry:

y

-loadings as returned from nag_pls_orth_scores_svd (g02lac) and nag_pls_orth_scores_wold (g02lbc).

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$ , $pdc \geq my$ ;
if $order = Nag_RowMajor$ , $pdc \geq maxfac$ .

10:

w [\dim]

– const doubleInput

Note: the dimension, dim, of the array w must be at least

$\max (1, pdw \times maxfac)$ when $order = Nag_ColMajor$ ;
$\max (1, ip \times pdw)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

W

is stored in

$w [(j - 1) \times pdw + i - 1]$ when $order = Nag_ColMajor$ ;
$w [(i - 1) \times pdw + j - 1]$ when $order = Nag_RowMajor$ .

On entry:

x

-weights as returned from nag_pls_orth_scores_svd (g02lac) and nag_pls_orth_scores_wold (g02lbc).

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$ , $pdw \geq ip$ ;
if $order = Nag_RowMajor$ , $pdw \geq maxfac$ .

12:

rcond

– doubleInput

On entry: singular values of

P^{T} W

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

$\max (1, pdb \times my)$ when $order = Nag_ColMajor$ ;
$\max (1, ip \times pdb)$ when $order = Nag_RowMajor$ .

Where

B (i, j)

appears in this document, it refers to the array element

$b [(j - 1) \times pdb + i - 1]$ when $order = Nag_ColMajor$ ;
$b [(i - 1) \times pdb + j - 1]$ when $order = Nag_RowMajor$ .

On exit:

B (i, j)

contains the parameter estimate for the

i

th predictor variable in the model for the

j

th response variable, for

i = 1, 2, \dots, ip

and

j = 1, 2, \dots, 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$ , $pdb \geq ip$ ;
if $order = Nag_RowMajor$ , $pdb \geq my$ .

15:

orig

– Nag_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

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

Nag_PredUserScale

19:

xstd [ip]

– const doubleInput

On entry: if

orig = Nag_EstimatesOrig

and

iscale \neq Nag_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

iscale \neq Nag_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 \times my$ when $orig = Nag_EstimatesOrig$ and $order = Nag_ColMajor$ ;
$\max (1, (ip + 1) \times 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) \times pdob + i - 1]$ when $order = Nag_ColMajor$ ;
$ob [(i - 1) \times pdob + j - 1]$ when $order = Nag_RowMajor$ .

On exit: if

orig = Nag_EstimatesOrig

OB (1, j)

contains the intercept value for the

j

th response variable, and

OB (i + 1, j)

contains the parameter estimate on the original scale for the

i

th predictor variable in the model, for

i = 1, 2, \dots, ip

and

j = 1, 2, \dots, 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$ , $pdob \geq ip + 1$ ;
- otherwise $pdob \geq 1$ ;
if order=Nag_RowMajor,
- if $orig = Nag_EstimatesOrig$ , $pdob \geq my$ ;
- otherwise $pdob \geq 1$ .

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

my

24:

ycv [\dim]

– const doubleInput

Note: the dimension, dim, of the array ycv must be at least

my

when

vipopt \neq 0

Where

YCV (i, j)

appears in this document, it refers to the array element

$ycv [(j - 1) \times pdycv + i - 1]$ when $order = Nag_ColMajor$ ;
$ycv [(i - 1) \times pdycv + j - 1]$ when $order = Nag_RowMajor$ .

On entry: if

vipopt \neq 0

YCV (i, j)

is the cumulative percentage of variance of the

j

th response variable explained by the first

i

factors, for

i = 1, 2, \dots, nfact

and

j = 1, 2, \dots, 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 $vipopt \neq 0$ , $pdycv \geq nfact$ ;
if order=Nag_RowMajor,
- if $vipopt \neq 0$ , $pdycv \geq my$ .

26:

vip [\dim]

– doubleOutput

Note: the dimension, dim, of the array vip must be at least

$\max (1, pdvip \times vipopt)$ when $order = Nag_ColMajor$ ;
$\max (1, ip \times pdvip)$ when $order = Nag_RowMajor$ and $vipopt \neq 0$ .

Where

VIP (i, j)

appears in this document, it refers to the array element

$vip [(j - 1) \times pdvip + i - 1]$ when $order = Nag_ColMajor$ ;
$vip [(i - 1) \times pdvip + j - 1]$ when $order = Nag_RowMajor$ .

On exit: if

vipopt = 1

VIP (i, 1)

contains the VIP statistic for the

i

th predictor variable in the model for all response variables, for

i = 1, 2, \dots, ip

vipopt = my

VIP (i, j)

contains the VIP statistic for the

i

th predictor variable in the model for the

j

th response variable, for

i = 1, 2, \dots, ip

and

j = 1, 2, \dots, 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 $vipopt \neq 0$ , $pdvip \geq ip$ ;
if $order = Nag_RowMajor$ , $pdvip \geq vipopt$ .

28:

fail

– NagError *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.
See Section 3.2.1.2 in the Essential Introduction 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

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

pdob \geq my

;
otherwise

pdob \geq 1

NE_INT

On entry,

ip = 〈value〉

.
Constraint:

ip > 1

On entry,

my = 〈value〉

.
Constraint:

my \geq 1

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:

1 \leq maxfac \leq ip

On entry,

nfact = 〈value〉

and

maxfac = 〈value〉

.
Constraint:

1 \leq nfact \leq maxfac

On entry,

pdb = 〈value〉

and

ip = 〈value〉

.
Constraint:

pdb \geq ip

On entry,

pdb = 〈value〉

and

my = 〈value〉

.
Constraint:

pdb \geq my

On entry,

pdc = 〈value〉

and

maxfac = 〈value〉

.
Constraint:

pdc \geq maxfac

On entry,

pdc = 〈value〉

and

my = 〈value〉

.
Constraint:

pdc \geq my

On entry,

pdob = 〈value〉

and

ip = 〈value〉

.
Constraint: if

orig = Nag_EstimatesOrig

pdob \geq ip + 1

On entry,

pdp = 〈value〉

and

ip = 〈value〉

.
Constraint:

pdp \geq ip

On entry,

pdp = 〈value〉

and

maxfac = 〈value〉

.
Constraint:

pdp \geq maxfac

On entry,

pdvip = 〈value〉

and

ip = 〈value〉

.
Constraint: if

vipopt \neq 0

pdvip \geq ip

On entry,

pdvip = 〈value〉

and

vipopt = 〈value〉

.
Constraint:

pdvip \geq vipopt

On entry,

pdw = 〈value〉

and

ip = 〈value〉

.
Constraint:

pdw \geq ip

On entry,

pdw = 〈value〉

and

maxfac = 〈value〉

.
Constraint:

pdw \geq maxfac

On entry,

pdycv = 〈value〉

and

nfact = 〈value〉

.
Constraint: if

vipopt \neq 0

pdycv \geq nfact

On entry,

vipopt = 〈value〉

and

my = 〈value〉

.
Constraint:

my > 0

On entry,

vipopt = 〈value〉

and

my = 〈value〉

.
Constraint:

vipopt = 0

1

my

NE_INT_3

On entry,

pdycv = 〈value〉

vipopt = 〈value〉

and

my = 〈value〉

.
Constraint:
if

vipopt \neq 0

pdycv \geq my

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.

An unexpected error has been triggered by this function. Please contact NAG.
See Section 3.6.6 in the Essential Introduction for further information.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 3.6.5 in the Essential Introduction for further information.

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.

NAG Library Function Document

nag_pls_orth_scores_fit (g02lcc)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG Library Function Documentnag_pls_orth_scores_fit (g02lcc)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG Library Function Document

nag_pls_orth_scores_fit (g02lcc)