Main Content

resume

Resume training learners on cross-validation folds

expand all in page

Syntax

ens1 = resume(ens,nlearn)
ens1 = resume(ens,nlearn,Name,Value)

Description

ens1 = resume(ens,nlearn) trains ens in every fold for nlearn more cycles. resume uses the same training options fitcensemble used to create ens, except for parallel training options. If you want to resume training in parallel, pass the 'Options' name-value pair.

ens1 = resume(ens,nlearn,Name,Value) trains ens with additional options specified by one or more Name,Value pair arguments.

Input Arguments

ens

A cross-validated classification ensemble. ens is the result of either:

  • The fitcensemble function with a cross-validation name-value pair. The names are 'crossval', 'kfold', 'holdout', 'leaveout', or 'cvpartition'.

  • The crossval method applied to a classification ensemble.

nlearn

A positive integer, the number of cycles for additional training of ens.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

NPrint

Printout frequency, a positive integer scalar or 'off' (no printouts). When NPrint is a positive integer, displays a message to the command line after training NPrint folds.

Tip

For fastest training of some boosted decision trees, set NPrint to the default value 'off'. This tip holds when the classification Method is 'AdaBoostM1', 'AdaBoostM2', 'GentleBoost', or 'LogitBoost', or when the regression Method is 'LSBoost'.

Default: 'off'

Options

Options for computing in parallel and setting random numbers, specified as a structure. Create the Options structure with statset.

Note

You need Parallel Computing Toolbox™ to compute in parallel.

You can use the same parallel options for resume as you used for the original training. However, you can change the parallel options as needed. This table lists the option fields and their values.

Field NameValueDefault
UseParallel

Set this value to true to compute in parallel. Parallel ensemble training requires you to set the 'Method' name-value argument to 'Bag'. Parallel training is available only for tree learners, the default type for 'Bag'.

false
UseSubstreams

Set this value to true to run computations in parallel in a reproducible manner.

To compute reproducibly, set Streams to a type that allows substreams: 'mlfg6331_64' or 'mrg32k3a'.

false
StreamsSpecify this value as a RandStream object or cell array of such objects. Use a single object except when the UseParallel value is true and the UseSubstreams value is false. In that case, use a cell array that has the same size as the parallel pool.If you do not specify Streams, then resume uses the default stream or streams.

For dual-core systems and above, resume parallelizes training using Intel® Threading Building Blocks (TBB). Therefore, specifying the UseParallel option as true might not provide a significant speedup on a single computer. For details on Intel TBB, see https://www.intel.com/content/www/us/en/developer/tools/oneapi/onetbb.html.

Example: 'Options',statset('UseParallel',true)

Output Arguments

ens1

The cross-validated classification ensemble ens, augmented with additional training.

Examples

expand all

Open Live Script

Train a partitioned classification ensemble for 10 cycles, and compare the classification loss obtained after training the ensemble for more cycles.

Load the ionosphere data set.

load ionosphere

Train a partitioned classification ensemble for 10 cycles and examine the error.

t = templateTree('MaxNumSplits',1); % Weak learner template tree object
cvens = fitcensemble(X,Y,'Method','GentleBoost','NumLearningCycles',10,'Learners',t,'crossval','on');
rng(10,'twister') % For reproducibility
L = kfoldLoss(cvens)
L = 0.0940

Train for 10 more cycles and examine the new error.

cvens = resume(cvens,10);
L = kfoldLoss(cvens)
L = 0.0712

The cross-validation error is lower in the ensemble after training for 10 more cycles.

Extended Capabilities

See Also

| | | |