NAG FL Interface
g02lcf (pls_​fit)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{ip}$ – Integer Input

On entry: $m$, the number of predictor variables in the fitted model.

Constraint: $\mathbf{ip}>1$.

2: $\mathbf{my}$ – Integer Input

On entry: $r$, the number of response variables.

Constraint: $\mathbf{my}\ge 1$.

3: $\mathbf{maxfac}$ – Integer Input

On entry: $k$, the number of factors available in the PLS model.

Constraint: $1\le \mathbf{maxfac}\le \mathbf{ip}$.

4: $\mathbf{nfact}$ – Integer Input

On entry: $l$, the number of factors to include in the calculation of parameter estimates.

Constraint: $1\le \mathbf{nfact}\le \mathbf{maxfac}$.

5: $\mathbf{p}\left(\mathbf{ldp},\mathbf{maxfac}\right)$ – Real (Kind=nag_wp) array Input

On entry: $x$-loadings as returned from g02laf and g02lbf.

6: $\mathbf{ldp}$ – Integer Input

On entry: the first dimension of the array p as declared in the (sub)program from which g02lcf is called.

Constraint: $\mathbf{ldp}\ge \mathbf{ip}$.

7: $\mathbf{c}\left(\mathbf{ldc},\mathbf{maxfac}\right)$ – Real (Kind=nag_wp) array Input

On entry: $y$-loadings as returned from g02laf and g02lbf.

8: $\mathbf{ldc}$ – Integer Input

On entry: the first dimension of the array c as declared in the (sub)program from which g02lcf is called.

Constraint: $\mathbf{ldc}\ge \mathbf{my}$.

9: $\mathbf{w}\left(\mathbf{ldw},\mathbf{maxfac}\right)$ – Real (Kind=nag_wp) array Input

On entry: $x$-weights as returned from g02laf and g02lbf.

10: $\mathbf{ldw}$ – Integer Input

On entry: the first dimension of the array w as declared in the (sub)program from which g02lcf is called.

Constraint: $\mathbf{ldw}\ge \mathbf{ip}$.

11: $\mathbf{rcond}$ – Real (Kind=nag_wp) Input

On entry: singular values of $P^{\mathrm{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.

12: $\mathbf{b}\left(\mathbf{ldb},\mathbf{my}\right)$ – Real (Kind=nag_wp) array Output

On exit: $\mathbf{b}\left(\mathit{i},\mathit{j}\right)$ contains the parameter estimate for the $\mathit{i}$th predictor variable in the model for the $\mathit{j}$th response variable, for $\mathit{i}=1,2,\dots ,\mathbf{ip}$ and $\mathit{j}=1,2,\dots ,\mathbf{my}$.

13: $\mathbf{ldb}$ – Integer Input

On entry: the first dimension of the array b as declared in the (sub)program from which g02lcf is called.

Constraint: $\mathbf{ldb}\ge \mathbf{ip}$.

14: $\mathbf{orig}$ – Integer Input

On entry: indicates how parameter estimates are calculated.

$\mathbf{orig}=-1$

Parameter estimates for the centred, and possibly, scaled data.

$\mathbf{orig}=1$

Parameter estimates for the original data.

Constraint: $\mathbf{orig}=-1$ or $1$.

15: $\mathbf{xbar}\left(\mathbf{ip}\right)$ – Real (Kind=nag_wp) array Input

On entry: if $\mathbf{orig}=1$, mean values of predictor variables in the model; otherwise xbar is not referenced.

16: $\mathbf{ybar}\left(\mathbf{my}\right)$ – Real (Kind=nag_wp) array Input

On entry: if $\mathbf{orig}=1$, mean value of each response variable in the model; otherwise ybar is not referenced.

17: $\mathbf{iscale}$ – Integer Input

On entry: if $\mathbf{orig}=1$, iscale must take the value supplied to either g02laf or g02lbf; otherwise iscale is not referenced.

Constraint: if $\mathbf{orig}=1$, $\mathbf{iscale}=-1$, $1$ or $2$.

18: $\mathbf{xstd}\left(\mathbf{ip}\right)$ – Real (Kind=nag_wp) array Input

On entry: if $\mathbf{orig}=1$ and $\mathbf{iscale}\ne -1$, the scalings of predictor variables in the model as returned from either g02laf or g02lbf; otherwise xstd is not referenced.

19: $\mathbf{ystd}\left(\mathbf{my}\right)$ – Real (Kind=nag_wp) array Input

On entry: if $\mathbf{orig}=1$ and $\mathbf{iscale}\ne -1$, the scalings of response variables as returned from either g02laf or g02lbf; otherwise ystd is not referenced.

20: $\mathbf{ob}\left(\mathbf{ldob},\mathbf{my}\right)$ – Real (Kind=nag_wp) array Output

On exit: if $\mathbf{orig}=1$, $\mathbf{ob}\left(1,\mathit{j}\right)$ contains the intercept value for the $\mathit{j}$th response variable, and $\mathbf{ob}\left(\mathit{i}+1,\mathit{j}\right)$ contains the parameter estimate on the original scale for the $\mathit{i}$th predictor variable in the model, for $\mathit{i}=1,2,\dots ,\mathbf{ip}$ and $\mathit{j}=1,2,\dots ,\mathbf{my}$. Otherwise ob is not referenced.

21: $\mathbf{ldob}$ – Integer Input

On entry: the first dimension of the array ob as declared in the (sub)program from which g02lcf is called.

Constraints:

• if $\mathbf{orig}=1$, $\mathbf{ldob}\ge \mathbf{ip}+1$;
• otherwise $\mathbf{ldob}\ge 1$.

22: $\mathbf{vipopt}$ – Integer Input

On entry: a flag that determines variable influence on projections (VIP) options.

$\mathbf{vipopt}=0$

VIP are not calculated.

$\mathbf{vipopt}=1$

VIP are calculated for predictor variables using the mean explained variance in responses.

$\mathbf{vipopt}=\mathbf{my}$

VIP are calculated for predictor variables for each response variable in the model.

Note that setting $\mathbf{vipopt}=\mathbf{my}$ when $\mathbf{my}=1$ gives the same result as setting $\mathbf{vipopt}=1$ directly.

Constraint: $\mathbf{vipopt}=0$, $1$ or $\mathbf{my}$.

23: $\mathbf{ycv}\left(\mathbf{ldycv},\mathbf{my}\right)$ – Real (Kind=nag_wp) array Input

On entry: if $\mathbf{vipopt}\ne 0$, $\mathbf{ycv}\left(\mathit{i},\mathit{j}\right)$ is the cumulative percentage of variance of the $\mathit{j}$th response variable explained by the first $\mathit{i}$ factors, for $\mathit{i}=1,2,\dots ,\mathbf{nfact}$ and $\mathit{j}=1,2,\dots ,\mathbf{my}$; otherwise ycv is not referenced.

24: $\mathbf{ldycv}$ – Integer Input

On entry: the first dimension of the array ycv as declared in the (sub)program from which g02lcf is called.

Constraint: if $\mathbf{vipopt}\ne 0$, $\mathbf{ldycv}\ge \mathbf{nfact}$.

25: $\mathbf{vip}\left(\mathbf{ldvip},\mathbf{vipopt}\right)$ – Real (Kind=nag_wp) array Output

On exit: if $\mathbf{vipopt}=1$, $\mathbf{vip}\left(\mathit{i},1\right)$ contains the VIP statistic for the $\mathit{i}$th predictor variable in the model for all response variables, for $\mathit{i}=1,2,\dots ,\mathbf{ip}$.

If $\mathbf{vipopt}=\mathbf{my}$, $\mathbf{vip}\left(\mathit{i},\mathit{j}\right)$ contains the VIP statistic for the $\mathit{i}$th predictor variable in the model for the $\mathit{j}$th response variable, for $\mathit{i}=1,2,\dots ,\mathbf{ip}$ and $\mathit{j}=1,2,\dots ,\mathbf{my}$.

Otherwise vip is not referenced.

26: $\mathbf{ldvip}$ – Integer Input

On entry: the first dimension of the array vip as declared in the (sub)program from which g02lcf is called.

Constraint: if $\mathbf{vipopt}\ne 0$, $\mathbf{ldvip}\ge \mathbf{ip}$.

27: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.

On exit: $\mathbf{ifail}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

$\mathbf{ifail}=1$

On entry, $\mathbf{ip}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ip}>1$.

On entry, $\mathbf{iscale}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{orig}=1$, $\mathbf{iscale}=-1$ or $1$.

On entry, $\mathbf{my}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{my}\ge 1$.

On entry, $\mathbf{orig}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{orig}=-1$ or $1$.

On entry, $\mathbf{vipopt}=〈\mathit{\text{value}}〉$ and $\mathbf{my}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{vipopt}=0$, $1$ or $\mathbf{my}$.

$\mathbf{ifail}=2$

On entry, $\mathbf{ldb}=〈\mathit{\text{value}}〉$ and $\mathbf{ip}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldb}\ge \mathbf{ip}$.

On entry, $\mathbf{ldc}=〈\mathit{\text{value}}〉$ and $\mathbf{my}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldc}\ge \mathbf{my}$.

On entry, $\mathbf{ldob}=〈\mathit{\text{value}}〉$ and $\mathbf{ip}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{orig}=1$, $\mathbf{ldob}\ge \mathbf{ip}+1$.

On entry, $\mathbf{ldp}=〈\mathit{\text{value}}〉$ and $\mathbf{ip}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldp}\ge \mathbf{ip}$.

On entry, $\mathbf{ldvip}=〈\mathit{\text{value}}〉$ and $\mathbf{ip}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{vipopt}\ne 0$, $\mathbf{ldvip}\ge \mathbf{ip}$.

On entry, $\mathbf{ldw}=〈\mathit{\text{value}}〉$ and $\mathbf{ip}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldw}\ge \mathbf{ip}$.

On entry, $\mathbf{ldycv}=〈\mathit{\text{value}}〉$ and $\mathbf{nfact}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{vipopt}\ne 0$, $\mathbf{ldycv}\ge \mathbf{nfact}$.

On entry, $\mathbf{maxfac}=〈\mathit{\text{value}}〉$ and $\mathbf{ip}=〈\mathit{\text{value}}〉$.
Constraint: $1\le \mathbf{maxfac}\le \mathbf{ip}$.

On entry, $\mathbf{nfact}=〈\mathit{\text{value}}〉$ and $\mathbf{maxfac}=〈\mathit{\text{value}}〉$.
Constraint: $1\le \mathbf{nfact}\le \mathbf{maxfac}$.

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results