fit

Train a model.

Method call formatMethod call format

fit(X,
    y=None,
    cat_features=None,
    text_features=None,
    embedding_features=None,
    pairs=None,
    graph=None,
    sample_weight=None,
    group_id=None,
    group_weight=None,
    subgroup_id=None,
    pairs_weight=None,
    baseline=None,
    use_best_model=None,
    eval_set=None,
    verbose=None,
    logging_level=None,
    plot=False,
    plot_file=None,
    column_description=None,
    verbose_eval=None,
    metric_period=None,
    silent=None,
    early_stopping_rounds=None,
    save_snapshot=None,
    snapshot_file=None,
    snapshot_interval=None,
    init_model=None,
    log_cout=sys.stdout,
    log_cerr=sys.stderr)

ParametersParameters

Some parameters duplicate the ones specified in the constructor of the CatBoost class. In these cases the values specified for the fit method take precedence. The rest of the training parameters must be set in the constructor of the CatBoost class.

XX

DescriptionDescription

The description is different for each group of possible types.

Possible types

Default value

Required parameter

Supported processing units

CPU and GPU

yy

DescriptionDescription

The target variables (in other words, the objects' label values) for the training dataset.

Must be in the form of a one- or two- dimensional array. The type of data in the array depends on the machine learning task being solved:

• Regression and ranking — One-dimensional array of numeric values.

• Multiregression - Two-dimensional array of numeric values. The first index is for a dimension, the second index is for an object.

• Binary classification
  One-dimensional array containing one of:

  • Booleans, integers or strings that represent the labels of the classes (only two unique values).

  • Numeric values.
    The interpretation of numeric values depends on the selected loss function:

    • Logloss — The value is considered a positive class if it is strictly greater than the value of the target_border training parameter. Otherwise, it is considered a negative class.
    • CrossEntropy — The value is interpreted as the probability that the dataset object belongs to the positive class. Possible values are in the range [0; 1].

• Multiclassification — One-dimensional array of integers or strings that represent the labels of the classes.

• Multi label classification
  Two-dimensional array. The first index is for a label/class, the second index is for an object.

  Possible values depend on the selected loss function:

  • MultiLogloss — Only {0, 1} or {False, True} values are allowed that specify whether an object belongs to the class corresponding to the first index.
  • MultiCrossEntropy — Numerical values in the range [0; 1] that are interpreted as the probability that the dataset object belongs to the class corresponding to the first index.

Possible types

• list
• numpy.ndarray
• pandas.DataFrame
• pandas.Series

Default value

None

Supported processing units

CPU and GPU

cat_featurescat_features

DescriptionDescription

A one-dimensional array of categorical columns indices.

Use it only if the X parameter is a two-dimensional feature matrix (has one of the following types: list, numpy.ndarray, pandas.DataFrame, pandas.Series).

Possible types

• list
• numpy.ndarray

Default value

None (all features are either considered numerical or of other types if specified precisely)

Supported processing units

CPU and GPU

text_featurestext_features

DescriptionDescription

A one-dimensional array of text columns indices (specified as integers) or names (specified as strings).

Use only if the data parameter is a two-dimensional feature matrix (has one of the following types: list, numpy.ndarray, pandas.DataFrame, pandas.Series).

If any elements in this array are specified as names instead of indices, names for all columns must be provided. To do this, either use the feature_names parameter of this constructor to explicitly specify them or pass a pandas.DataFrame with column names specified in the data parameter.

Possible types

• list
• numpy.ndarray

Default value

None (all features are either considered numerical or of other types if specified precisely)

Supported processing units

CPU and GPU

embedding_featuresembedding_features

DescriptionDescription

A one-dimensional array of embedding columns indices (specified as integers) or names (specified as strings).

Use only if the data parameter is a two-dimensional feature matrix (has one of the following types: list, numpy.ndarray, pandas.DataFrame, pandas.Series).

If any elements in this array are specified as names instead of indices, names for all columns must be provided. To do this, either use the feature_names parameter of this constructor to explicitly specify them or pass a pandas.DataFrame with column names specified in the data parameter.

Possible types

• list
• numpy.ndarray

Default value

Default value

None (all features are either considered numerical or of other types if specified precisely)

Supported processing units

CPU and GPU

pairspairs

DescriptionDescription

The pairs description in the form of a two-dimensional matrix of shape N by 2:

• N is the number of pairs.
• The first element of the pair is the zero-based index of the winner object from the input dataset for pairwise comparison.
• The second element of the pair is the zero-based index of the loser object from the input dataset for pairwise comparison.

This information is used for calculation and optimization of Pairwise metrics.

Possible types

• list
• numpy.ndarray
• pandas.DataFrame

Default value

None

Pairwise metrics require pairs data. If this data is not provided explicitly by specifying this parameter, pairs are generated automatically in each group using object label values.

Supported processing units

CPU and GPU

graphgraph

DescriptionDescription

The graph description in the form of a two-dimensional matrix of shape N by 2:

• N is the number of edges.
• The first element of the edge is the zero-based index of start vertex (object) from the input dataset.
• The second element of the edge is the zero-based index of end vertex (object) from the input dataset.

Graph information is used to calculate the graph aggregated features.

Possible types

• list
• numpy.ndarray
• pandas.DataFrame

Default value

None

Supported processing units

CPU and GPU

sample_weightsample_weight

DescriptionDescription

The weight of each object in the input data in the form of a one-dimensional array-like data.

By default, it is set to 1 for all objects.

Possible types

• list
• numpy.ndarray
• pandas.DataFrame
• pandas.Series

Default value

None

Supported processing units

CPU and GPU

group_idgroup_id

DescriptionDescription

Group identifiers for all input objects. Supported identifier types are:

• int
• string types (string or unicode for Python 2 and bytes or string for Python 3).

Possible types

• list
• numpy.ndarray

Default value

None

Supported processing units

CPU

group_weightgroup_weight

DescriptionDescription

The weights of all objects within the defined groups from the input data in the form of one-dimensional array-like data.

Used for calculating the final values of trees. By default, it is set to 1 for all objects in all groups.

Possible types

• list
• numpy.ndarray

Default value

None

Supported processing units

CPU

subgroup_idsubgroup_id

DescriptionDescription

Subgroup identifiers for all input objects. Supported identifier types are:

• int
• string types (string or unicode for Python 2 and bytes or string for Python 3).

Possible types

• list
• numpy.ndarray

Default value

None

Supported processing units

CPU

pairs_weightpairs_weight

DescriptionDescription

The weight of each input pair of objects in the form of one-dimensional array-like pairs. The number of given values must match the number of specified pairs.

This information is used for calculation and optimization of Pairwise metrics.

By default, it is set to 1 for all pairs.

Possible types

• list
• numpy.ndarray

Default value

None

Supported processing units

CPU and GPU

baselinebaseline

DescriptionDescription

Array of formula values for all input objects. The training starts from these values for all input objects instead of starting from zero.

Possible types

• list
• numpy.ndarray

Default value

None

Supported processing units

CPU and GPU

use_best_modeluse_best_model

DescriptionDescription

If this parameter is set, the number of trees that are saved in the resulting model is defined as follows:

1. Build the number of trees defined by the training parameters.
2. Use the validation dataset to identify the iteration with the optimal value of the metric specified in  --eval-metric (--eval-metric).

No trees are saved after this iteration.

This option requires a validation dataset to be provided.

Possible types

bool

Default value

True if validation sets are specified (the eval_set parameter is defined) and at least one of the label values of objects in the last validation dataset differs from the others. False otherwise.

Supported processing units

CPU and GPU

eval_seteval_set

DescriptionDescription

The validation dataset or datasets used for the following processes:

• overfitting detector
• best iteration selection
• monitoring metrics' changes

Possible types

• catboost.Pool
• list of catboost.Pool
• tuple (X, y)
• list of tuples (X, y)
• string (path to the dataset file)
• list of strings (paths to dataset files)

Default value

None

Supported processing units

CPU and GPU

verboseverbose

Alias:verbose_eval

DescriptionDescription

The purpose of this parameter depends on the type of the given value:

• bool — Defines the logging level:

  • True  corresponds to the Verbose logging level
  • False corresponds to the Silent logging level

• int — Use the Verbose logging level and set the logging period to the value of this parameter.

Possible types

• bool
• int

Default value

1

Supported processing units

CPU and GPU

logging_levellogging_level

DescriptionDescription

The logging level to output to stdout.

Possible values:

• Silent — Do not output any logging information to stdout.

• Verbose — Output the following data to stdout:

  • optimized metric
  • elapsed time of training
  • remaining time of training

• Info — Output additional information and the number of trees.

• Debug — Output debugging information.

Possible types

string

Default value

None (corresponds to the Verbose logging level)

Supported processing units

CPU and GPU

plotplot

DescriptionDescription

Plot the following information during training:

• the metric values;
• the custom loss values;
• the loss function change during feature selection;
• the time has passed since training started;
• the remaining time until the end of training.
  This option can be used if training is performed in Jupyter notebook.

Possible types

bool

Default value

False

Supported processing units

CPU

plot_fileplot_file

DescriptionDescription

Save a plot with the training progress information (metric values, custom loss values) to the file specified by this parameter.

Possible types

File-like object or string

Default value

None

Supported processing units

CPU and GPU

column_descriptioncolumn_description

DescriptionDescription

The path to the input file that contains the columns description.

The given file is used to build pools from the train and/or validation datasets, which are input from files.

Possible types:

string

Default value

None

Supported processing units

CPU and GPU

metric_periodmetric_period

DescriptionDescription

The frequency of iterations to calculate the values of objectives and metrics. The value should be a positive integer.

The usage of this parameter speeds up the training.

Possible types

int

Default value

1

Supported processing units

CPU and GPU

silentsilent

DescriptionDescription

Defines the logging level:

• True — corresponds to the Silent logging level
• False — corresponds to the Verbose logging level

Possible types

bool

Default value

False

Supported processing units

CPU and GPU

early_stopping_roundsearly_stopping_rounds

DescriptionDescription

Sets the overfitting detector type to Iter and stops the training after the specified number of iterations since the iteration with the optimal metric value.

Possible types

int

Default value

False

Supported processing units

CPU and GPU

save_snapshotsave_snapshot

DescriptionDescription

Enable snapshotting for restoring the training progress after an interruption. If enabled, the default period for making snapshots is 600 seconds. Use the snapshot_interval parameter to change this period.

Possible types

bool

Default value

None

Supported processing units

CPU and GPU

snapshot_filesnapshot_file

DescriptionDescription

The name of the file to save the training progress information in. This file is used for recovering training after an interruption.

Depending on whether the specified file exists in the file system:

• Missing — Write information about training progress to the specified file.
• Exists — Load data from the specified file and continue training from where it left off.

Possible types

string

Default value

experiment.cbsnapshot

Supported processing units

CPU and GPU

snapshot_intervalsnapshot_interval

DescriptionDescription

The interval between saving snapshots in seconds.

The first snapshot is taken after the specified number of seconds since the start of training. Every subsequent snapshot is taken after the specified number of seconds since the previous one. The last snapshot is taken at the end of the training.

Possible types

int

Default value

600

Supported processing units

CPU and GPU

init_modelinit_model

DescriptionDescription

The description is different for each group of possible types.

The model to continue learning from.

Possible types

Default value

None (incremental learning is not used)

Supported processing units

CPU

log_coutlog_cout

Output stream or callback for logging.

Possible types

• callable Python object
• python object providing the write() method

Default value

sys.stdout

log_cerrlog_cerr

Error stream or callback for logging.

Possible types

• callable Python object
• python object providing the write() method

Default value

sys.stderr