naginterfaces.library.rand.kfold_​xyw

naginterfaces.library.rand.kfold_xyw(k, fold, x, statecomm, sordx=1, y=None, w=None)

kfold_xyw generates training and validation datasets suitable for use in cross-validation or jack-knifing.

For full information please refer to the NAG Library document for g05pv

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g05/g05pvf.html

Parameters

kint

$K$, the number of folds.

foldint

The number of the fold to return as the validation dataset.

On the first call to kfold_xyw $fold$ should be set to $1$ and then incremented by one at each subsequent call until all $K$ sets of training and validation datasets have been produced.

See Further Comments for more details on how a different calling sequence can be used.

xfloat, ndarray, shape $(:,:)$, modified in place

Note: the required extent for this argument in dimension 1 is determined as follows: if $sordx=2$: $m$; otherwise: $n$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $sordx=1$: $m$; if $sordx=2$: $n$; otherwise: $0$.

The way the data is stored in $x$ is defined by $sordx$.

If $sordx=1$, $x[\text{i}-1,\text{j}-1]$ contains the $\text{i}$th observation for the $\text{j}$th variable, for $i=1,2,\dots ,n$ and $j=1,2,\dots ,m$.

If $sordx=2$, $x[\text{j}-1,\text{i}-1]$ contains the $\text{i}$th observation for the $\text{j}$th variable, for $i=1,2,\dots ,n$ and $j=1,2,\dots ,m$.

On entry: if $fold=1$, $x$ must hold $X_o$, the values of $X$ for the original dataset, otherwise, $x$ must not be changed since the last call to kfold_xyw.

On exit: values of $X$ for the training and validation datasets, with $X_t$ held in observations $1$ to $nt$ and $X_v$ in observations $nt+1$ to $n$.

statecommdict, RNG communication object, modified in place

RNG communication structure.

This argument must have been initialized by a prior call to init_repeat() or init_nonrepeat().

sordxint, optional

Determines how variables are stored in $x$.

yNone or float, ndarray, shape $(:)$, optional, modified in place

Note: the required length for this argument is determined as follows: if $y\text{is not}None$: $n$; otherwise: $0$.

If the original dataset does not include $y_o$ then $y$ must be set to None.

Optionally, on entry: $y_o$, the values of $y$ for the original dataset. If $fold\ne 1$, $y$ must hold the vector returned in $\text{sy}$ by the last call to kfold_xyw.

On exit, if not None on entry: values of $y$ for the training and validation datasets, with $y_t$ held in elements $1$ to $nt$ and $y_v$ in elements $nt+1$ to $n$.

wNone or float, ndarray, shape $(:)$, optional, modified in place

Note: the required length for this argument is determined as follows: if $w\text{is not}None$: $n$; otherwise: $0$.

Optionally, on entry: if $fold\ne 1$, $w$ must hold the vector returned in $\text{sw}$ by the last call to kfold_xyw.

On exit, if not None on entry: values of $w$ for the training and validation datasets, with $w_t$ held in elements $1$ to $nt$ and $w_v$ in elements $nt+1$ to $n$.

Returns

ntint

$n_t$, the number of observations in the training dataset.

Raises

NagValueError

(errno $11$)

On entry, $k=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $2\le k\le n$.

(errno $21$)

On entry, $fold=⟨value⟩$ and $k=⟨value⟩$.

Constraint: $1\le fold\le k$.

(errno $31$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $41$)

On entry, $m=⟨value⟩$.

Constraint: $m\ge 1$.

(errno $51$)

On entry, $sordx=⟨value⟩$.

Constraint: $sordx=1$ or $2$.

(errno $71$)

On entry, $\text{ldx}=⟨value⟩$ and $n=⟨value⟩$.

Constraint: if $sordx=1$, $\text{ldx}\ge n$.

(errno $72$)

On entry, $\text{ldx}=⟨value⟩$ and $m=⟨value⟩$.

Constraint: if $sordx=2$, $\text{ldx}\ge m$.

(errno $131$)

On entry, $statecomm$[‘state’] vector has been corrupted or not initialized.

Warns

NagAlgorithmicWarning

(errno $61$)

More than $50\%$ of the data did not move when the data was shuffled. $⟨value⟩$ of the $⟨value⟩$ observations stayed put.

Notes

Let $X_o$ denote a matrix of $n$ observations on $m$ variables and $y_o$ and $w_o$ each denote a vector of length $n$. For example, $X_o$ might represent a matrix of independent variables, $y_o$ the dependent variable and $w_o$ the associated weights in a weighted regression.

kfold_xyw generates a series of training datasets, denoted by the matrix, vector, vector triplet $(X_t,y_t,w_t)$ of $n_t$ observations, and validation datasets, denoted $(X_v,y_v,w_v)$ with $n_v$ observations. These training and validation datasets are generated as follows.

Each of the original $n$ observations is randomly assigned to one of $K$ equally sized groups or folds. For the $k$th sample the validation dataset consists of those observations in group $k$ and the training dataset consists of all those observations not in group $k$. Therefore, at most $K$ samples can be generated.

If $n$ is not divisible by $K$ then the observations are assigned to groups as evenly as possible, therefore, any group will be at most one observation larger or smaller than any other group.

When using $K=n$ the resulting datasets are suitable for leave-one-out cross-validation, or the training dataset on its own for jack-knifing. When using $K\ne n$ the resulting datasets are suitable for $K$-fold cross-validation. Datasets suitable for reversed cross-validation can be obtained by switching the training and validation datasets, i.e., use the $k$th group as the training dataset and the rest of the data as the validation dataset.

One of the initialization functions init_repeat() (for a repeatable sequence if computed sequentially) or init_nonrepeat() (for a non-repeatable sequence) must be called prior to the first call to kfold_xyw.

See also

naginterfaces.library.examples.correg.glm_binomial_ex.main()