NAG Library Routine Document

H05ABF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     $\mathrm{MINCR}$ – INTEGERInput

On entry: flag indicating whether the scoring function $f$ is increasing or decreasing.

$\mathbf{MINCR}=1$

$f\left(S_i\right)\le f\left(S_j\right)$, i.e., the subsets with the largest score will be selected.

$\mathbf{MINCR}=0$

$f\left(S_i\right)\ge f\left(S_j\right)$, i.e., the subsets with the smallest score will be selected.

For all $S_j\subseteq \Omega$ and $S_i\subseteq S_j$.

Constraint: $\mathbf{MINCR}=0$ or $1$.

2:     $\mathrm{M}$ – INTEGERInput

On entry: $m$, the number of features in the full feature set.

Constraint: $\mathbf{M}\ge 2$.

3:     $\mathrm{IP}$ – INTEGERInput

On entry: $p$, the number of features in the subset of interest.

Constraint: $1\le \mathbf{IP}\le \mathbf{M}$.

4:     $\mathrm{NBEST}$ – INTEGERInput

On entry: $n$, the maximum number of best subsets required. The actual number of subsets returned is given by LA on final exit. If on final exit $\mathbf{LA}\ne \mathbf{NBEST}$ then $\mathbf{IFAIL}=\mathbf{42}$ is returned.

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

5:     $\mathrm{LA}$ – INTEGEROutput

On exit: the number of best subsets returned.

6:     $\mathrm{BSCORE}\left(\mathbf{NBEST}\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit: holds the score for the LA best subsets returned in BZ.

7:     $\mathrm{BZ}\left(\mathbf{M}-\mathbf{IP},\mathbf{NBEST}\right)$ – INTEGER arrayOutput

On exit: the $j$th best subset is constructed by dropping the features specified in $\mathbf{BZ}\left(\mathit{i},\mathit{j}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{M}-\mathbf{IP}$ and $\mathit{j}=1,2,\dots ,\mathbf{LA}$, from the set of all features, $\Omega$. The score for the $j$th best subset is given in $\mathbf{BSCORE}\left(j\right)$.

8:     $\mathrm{F}$ – SUBROUTINE, supplied by the user.External Procedure

F must evaluate the scoring function $f$.

The specification of F is:

SUBROUTINE F ( M, DROP, LZ, Z, LA, A, SCORE, IUSER, RUSER, INFO) INTEGER  M, DROP, LZ, Z(LZ), LA, A(LA), IUSER(*), INFO REAL (KIND=nag_wp)  SCORE(max(LA,1)), RUSER(*)

1:     $\mathrm{M}$ – INTEGERInput

On entry: $m=\left|\Omega \right|$, the number of features in the full feature set.

2:     $\mathrm{DROP}$ – INTEGERInput

On entry: flag indicating whether the intermediate subsets should be constructed by dropping features from the full set ($\mathbf{DROP}=1$) or adding features to the empty set ($\mathbf{DROP}=0$). See SCORE for additional details.

3:     $\mathrm{LZ}$ – INTEGERInput

On entry: the number of features stored in Z.

4:     $\mathrm{Z}\left(\mathbf{LZ}\right)$ – INTEGER arrayInput

On entry: $\mathbf{Z}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{LZ}$, contains the list of features which, along with those specified in A, define the subsets whose score is required. See SCORE for additional details.

5:     $\mathrm{LA}$ – INTEGERInput

On entry: if $\mathbf{LA}>0$, the number of subsets for which a score must be returned.

If $\mathbf{LA}=0$, the score for a single subset should be returned. See SCORE for additional details.

6:     $\mathrm{A}\left(\mathbf{LA}\right)$ – INTEGER arrayInput

On entry: $\mathbf{A}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{LA}$, contains the list of features which, along with those specified in Z, define the subsets whose score is required. See SCORE for additional details.

7:     $\mathrm{SCORE}\left(\max \left(\mathbf{LA},1\right)\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit: the value $f\left(S_{\mathit{j}}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{LA}$, the score associated with the $j$th subset. $S_j$ is constructed as follows:

$\mathbf{DROP}=1$

$S_j$ is constructed by dropping the features specified in the first LZ elements of Z and the single feature given in $\mathbf{A}\left(j\right)$ from the full set of features, $\Omega$. The subset will therefore contain $\mathbf{M}-\mathbf{LZ}-1$ features.

$\mathbf{DROP}=0$

$S_j$ is constructed by adding the features specified in the first LZ elements of Z and the single feature specified in $\mathbf{A}\left(j\right)$ to the empty set, $\varnothing$. The subset will therefore contain $\mathbf{LZ}+1$ features.

In both cases the individual features are referenced by the integers $1$ to M with $1$ indicating the first feature, $2$ the second, etc., for some arbitrary ordering of the features, chosen by you prior to calling H05ABF. For example, $1$ might refer to the first variable in a particular set of data, $2$ the second, etc..

If $\mathbf{LA}=0$, the score for a single subset should be returned. This subset is constructed by adding or removing only those features specified in the first LZ elements of Z. If $\mathbf{LZ}=0$, this subset will either be $\Omega$ or $\varnothing$.

8:     $\mathrm{IUSER}\left(*\right)$ – INTEGER arrayUser Workspace

9:     $\mathrm{RUSER}\left(*\right)$ – REAL (KIND=nag_wp) arrayUser Workspace

F is called with the parameters IUSER and RUSER as supplied to H05ABF. You are free to use the arrays IUSER and RUSER to supply information to F as an alternative to using COMMON global variables.

10:   $\mathrm{INFO}$ – INTEGERInput/Output

On entry: $\mathbf{INFO}=0$.

On exit: set INFO to a nonzero value if you wish H05ABF to terminate with $\mathbf{IFAIL}=\mathbf{82}$.

F must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which H05ABF is called. Parameters denoted as Input must not be changed by this procedure.

9:     $\mathrm{MINCNT}$ – INTEGERInput

On entry: $k$, the minimum number of times the effect of each feature, $x_i$, must have been observed before $f\left(S-\left\{x_i\right\}\right)$ is estimated from $f\left(S\right)$ as opposed to being calculated directly.

If $k=0$ then $f\left(S-\left\{x_i\right\}\right)$ is never estimated. If $\mathbf{MINCNT}<0$ then $k$ is set to $1$.

10:   $\mathrm{GAMMA}$ – REAL (KIND=nag_wp)Input

On entry: $\gamma$, the scaling factor used when estimating scores. If $\mathbf{GAMMA}<0$ then $\gamma =1$ is used.

11:   $\mathrm{ACC}\left(2\right)$ – REAL (KIND=nag_wp) arrayInput

On entry: a measure of the accuracy of the scoring function, $f$.

Letting $a_i={\epsilon }_1\left|f\left(S_i\right)\right|+{\epsilon }_2$, then when confirming whether the scoring function is strictly increasing or decreasing (as described in MINCR), or when assessing whether a node defined by subset $S_i$ can be trimmed, then any values in the range $f\left(S_i\right)\pm a_i$ are treated as being numerically equivalent.

If $0\le \mathbf{ACC}\left(1\right)\le 1$ then ${\epsilon }_1=\mathbf{ACC}\left(1\right)$, otherwise ${\epsilon }_1=0$.

If $\mathbf{ACC}\left(2\right)\ge 0$ then ${\epsilon }_2=\mathbf{ACC}\left(2\right)$, otherwise ${\epsilon }_2=0$.

In most situations setting both ${\epsilon }_1$ and ${\epsilon }_2$ to zero should be sufficient. Using a nonzero value, when one is not required, can significantly increase the number of subsets that need to be evaluated.

12:   $\mathrm{IUSER}\left(*\right)$ – INTEGER arrayUser Workspace

13:   $\mathrm{RUSER}\left(*\right)$ – REAL (KIND=nag_wp) arrayUser Workspace

IUSER and RUSER are not used by H05ABF, but are passed directly to F and may be used to pass information to this routine as an alternative to using COMMON global variables.

14:   $\mathrm{IFAIL}$ – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is $0$. When the value $-\mathbf{1}\text{ 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}=11$

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

$\mathbf{IFAIL}=21$

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

$\mathbf{IFAIL}=31$

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

$\mathbf{IFAIL}=41$

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

$\mathbf{IFAIL}=42$

On entry, $\mathbf{NBEST}=〈\mathit{\text{value}}〉$.
But only $〈\mathit{\text{value}}〉$ best subsets could be calculated.

$\mathbf{IFAIL}=81$

On exit from F, $\mathbf{SCORE}\left(〈\mathit{\text{value}}〉\right)=〈\mathit{\text{value}}〉$, which is inconsistent with the score for the parent node. Score for the parent node is $〈\mathit{\text{value}}〉$.

$\mathbf{IFAIL}=82$

A nonzero value for INFO has been returned: $\mathbf{INFO}=〈\mathit{\text{value}}〉$.

$\mathbf{IFAIL}=-99$

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

See Section 3.8 in the Essential Introduction for further information.

$\mathbf{IFAIL}=-399$

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

See Section 3.7 in the Essential Introduction for further information.

$\mathbf{IFAIL}=-999$

Dynamic memory allocation failed.

See Section 3.6 in the Essential Introduction for further information.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (h05abfe.f90)

10.2  Program Data

Program Data (h05abfe.d)

10.3  Program Results

Program Results (h05abfe.r)