Common parameters

loss_functionloss_function

Command-line: --loss-function

Alias: objective

DescriptionDescription

The metric to use in training. The specified value also determines the machine learning problem to solve. Some metrics support optional parameters (see the Objectives and metrics section for details on each metric).

Format:

<Metric>[:<parameter 1>=<value>;..;<parameter N>=<value>]

A custom python object can also be set as the value of this parameter (see an example).

For example, use the following construction to calculate the value of Quantile with the coefficient $\alpha = 0.1$:

Quantile:alpha=0.1

Type

• string
• object

Default value

Supported processing units

CPU and GPU

custom_metriccustom_metric

Command-line: --custom-metric

DescriptionDescription

Metric values to output during training. These functions are not optimized and are displayed for informational purposes only. Some metrics support optional parameters (see the Objectives and metrics section for details on each metric).

Format:

<Metric>[:<parameter 1>=<value>;..;<parameter N>=<value>]

Supported metrics

Values of all custom metrics for learn and validation datasets are saved to the Metric output files (learn_error.tsv and test_error.tsv respectively). The directory for these files is specified in the --train-dir (train_dir) parameter.

Use the visualization tools to see a live chart with the dynamics of the specified metrics.

Type

• string
• list of strings

Default value

Supported processing units

CPU and GPU

eval_metriceval_metric

Command-line: --eval-metric

DescriptionDescription

The metric used for overfitting detection (if enabled) and best model selection (if enabled). Some metrics support optional parameters (see the Objectives and metrics section for details on each metric).

Format:

<Metric>[:<parameter 1>=<value>;..;<parameter N>=<value>]

Supported metrics

A user-defined function can also be set as the value (see an example).

Examples:

R2

Type

• string
• object

Default value

Optimized objective is used

Supported processing units

CPU and GPU

iterationsiterations

Command-line: -i, --iterations

Aliases: num_boost_round, n_estimators, num_trees

DescriptionDescription

The maximum number of trees that can be built when solving machine learning problems.

When using other parameters that limit the number of iterations, the final number of trees may be less than the number specified in this parameter.

Type

int

Default value

1000

Supported processing units

CPU and GPU

learning_ratelearning_rate

Command-line: -w, --learning-rate

Alias: eta

DescriptionDescription

The learning rate.

Used for reducing the gradient step.

Type

float

Default value

The default value is defined automatically for Logloss, MultiClass & RMSE loss functions depending on the number of iterations if none of parameters leaf_estimation_iterations, --leaf-estimation-method,l2_leaf_reg is set. In this case, the selected learning rate is printed to stdout and saved in the model.

In other cases, the default value is 0.03.

Supported processing units

CPU and GPU

random_seedrandom_seed

Command-line: -r, --random-seed

Alias:random_state

DescriptionDescription

The random seed used for training.

Type

int

Default value

Supported processing units

CPU and GPU

l2_leaf_regl2_leaf_reg

Command-line: --l2-leaf-reg, l2-leaf-regularizer

Alias: reg_lambda

DescriptionDescription

Coefficient at the L2 regularization term of the cost function.

Any positive value is allowed.

Type

float

Default value

3.0

Supported processing units

CPU and GPU

bootstrap_typebootstrap_type

Command-line: --bootstrap-type

DescriptionDescription

Bootstrap type. Defines the method for sampling the weights of objects.

Supported methods:

• Bayesian
• Bernoulli
• MVS
• Poisson (supported for GPU only)
• No

Type

string

Default value

The default value depends on objective, task_type, bagging_temperature and sampling_unit:

• When the objective parameter is QueryCrossEntropy, YetiRankPairwise, PairLogitPairwise and the bagging_temperature parameter is not set: Bernoulli with the subsample parameter set to 0.5.
• Neither MultiClass nor MultiClassOneVsAll, task_type = CPU and sampling_unit = Object: MVS with the subsample parameter set to 0.8.
• Otherwise: Bayesian.

Supported processing units

CPU and GPU

bagging_temperaturebagging_temperature

Command-line: --bagging-temperature

DescriptionDescription

Defines the settings of the Bayesian bootstrap. It is used by default in classification and regression modes.

Use the Bayesian bootstrap to assign random weights to objects.

The weights are sampled from exponential distribution if the value of this parameter is set to 1. All weights are equal to 1 if the value of this parameter is set to 0.

Possible values are in the range $[0; \inf)$. The higher the value the more aggressive the bagging is.

This parameter can be used if the selected bootstrap type is Bayesian.

Type

float

Default value

1

Supported processing units

CPU and GPU

subsamplesubsample

Command-line: --subsample

DescriptionDescription

Sample rate for bagging.

This parameter can be used if one of the following bootstrap types is selected:

• Poisson
• Bernoulli
• MVS

Type

float

Default value

The default value depends on the dataset size and the bootstrap type:

• Datasets with less than 100 objects — 1
• Datasets with 100 objects or more:
  • Poisson, Bernoulli — 0.66
  • MVS — 0.8

Supported processing units

CPU and GPU

sampling_frequencysampling_frequency

Command-line: --sampling-frequency

DescriptionDescription

Frequency to sample weights and objects when building trees.

Supported values:

• PerTree — Before constructing each new tree
• PerTreeLevel — Before choosing each new split of a tree

Type

string

Default value

PerTreeLevel

Supported processing units

CPU

sampling_unitsampling_unit

Command-line: --sampling-unit

DescriptionDescription

The sampling scheme.

Possible values:

• Object — The weight $w_{i}$ of the i-th object $o_{i}$ is used for sampling the corresponding object.
• Group — The weight $w_{j}$ of the group $g_{j}$ is used for sampling each object $o_{i_{j}}$ from the group $g_{j}$.

Type

String

Default value

Object

Supported processing units

CPU and GPU

mvs_regmvs_reg

Command-line: --mvs-reg

DescriptionDescription

Affects the weight of the denominator and can be used for balancing between the importance and Bernoulli sampling (setting it to 0 implies importance sampling and to $\infty$ - Bernoulli).

Type

float

Default value

The value is set based on the gradient distribution on the current iteration

Supported processing units

CPU

random_strengthrandom_strength

Command-line: --random-strength

DescriptionDescription

The amount of randomness to use for scoring splits when the tree structure is selected. Use this parameter to avoid overfitting the model.

The value of this parameter is used when selecting splits. On every iteration each possible split gets a score (for example, the score indicates how much adding this split will improve the loss function for the training dataset). The split with the highest score is selected.

The scores have no randomness. A normally distributed random variable is added to the score of the feature. It has a zero mean and a variance that decreases during the training. The value of this parameter is the multiplier of the variance.

Type

float

Default value

1

Supported processing units

CPU

use_best_modeluse_best_model

Command-line: --use-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.

Type

bool

Default value

True if a validation set is input (the eval_set parameter is defined) and at least one of the label values of objects in this set differs from the others. False otherwise.

Supported processing units

CPU and GPU

best_model_min_treesbest_model_min_trees

Command-line: --best-model-min-trees

DescriptionDescription

The minimal number of trees that the best model should have. If set, the output model contains at least the given number of trees even if the optimal value of the evaluation metric on the validation dataset is achieved with smaller number of trees.

Should be used with the --use-best-model parameter.

Type

int

Default value

Supported processing units

CPU and GPU

depthdepth

Command-line: -n, --depth

Alias: max_depth

DescriptionDescription

Depth of the trees.

The range of supported values depends on the processing unit type and the type of the selected loss function:

• CPU — Any integer up to  16.

• GPU — Any integer up to 8 for pairwise modes (YetiRank, PairLogitPairwise, and QueryCrossEntropy), and up to 16 for all other loss functions.

Type

int

Default value

6 (16 if the growing policy is set to Lossguide)

Supported processing units

CPU and GPU

grow_policygrow_policy

Command-line: --grow-policy

DescriptionDescription

The tree growing policy. Defines how to perform greedy tree construction.

Possible values:

• SymmetricTree —A tree is built level by level until the specified depth is reached. On each iteration, all leaves from the last tree level are split with the same condition. The resulting tree structure is always symmetric.

• Depthwise — A tree is built level by level until the specified depth is reached. On each iteration, all non-terminal leaves from the last tree level are split. Each leaf is split by condition with the best loss improvement.

  Note

  Models with this growing policy can not be analyzed using the PredictionDiff feature importance and can be exported only to json and cbm.

• Lossguide — A tree is built leaf by leaf until the specified maximum number of leaves is reached. On each iteration, non-terminal leaf with the best loss improvement is split.

  Note

  Models with this growing policy can not be analyzed using the PredictionDiff feature importance and can be exported only to json and cbm.

Type

string

Default value

SymmetricTree

Supported processing units

CPU and GPU

min_data_in_leafmin_data_in_leaf

Command-line: --min-data-in-leaf

Alias: min_child_samples

DescriptionDescription

The minimum number of training samples in a leaf. CatBoost does not search for new splits in leaves with samples count less than the specified value.
Can be used only with the Lossguide and Depthwise growing policies.

Type

int

Default value

1

Supported processing units

CPU and GPU

max_leavesmax_leaves

Command-line: --max-leaves

Alias:num_leaves

DescriptionDescription

The maximum number of leafs in the resulting tree. Can be used only with the Lossguide growing policy.

Type

int

Default value

31

Supported processing units

CPU and GPU

ignored_featuresignored_features

Command-line: -I, --ignore-features

DescriptionDescription

Feature indices to exclude from the training.

Default value

Supported processing units

CPU and GPU

one_hot_max_sizeone_hot_max_size

Command-line: --one-hot-max-size

DescriptionDescription

Use one-hot encoding for all categorical features with a number of different values less than or equal to the given parameter value. Ctrs are not calculated for such features.

See details.

Type

int

Default value

The default value depends on various conditions:

• N/A if training is performed on CPU in Pairwise scoring mode

  Read more about Pairwise scoring

  The following loss functions use Pairwise scoring:

  • YetiRankPairwise
  • PairLogitPairwise
  • QueryCrossEntropy

  Pairwise scoring is slightly different from regular training on pairs, since pairs are generated only internally during the training for the corresponding metrics. One-hot encoding is not available for these loss functions.

• 255 if training is performed on GPU and the selected Ctr types require target data that is not available during the training

• 10 if training is performed in Ranking mode

• 2 if none of the conditions above is met

Supported processing units

CPU and GPU

has_timehas_time

Command-line: --has-time

DescriptionDescription

Use the order of objects in the input data (do not perform random permutations during the Transforming categorical features to numerical features and Choosing the tree structure stages).

The Timestamp column type is used to determine the order of objects if specified in the input data.

Type

bool

Default value

False (not used; generates random permutations)

Supported processing units

CPU and GPU

rsmrsm

Command-line: --rsm

Alias:colsample_bylevel

DescriptionDescription

Random subspace method. The percentage of features to use at each split selection, when features are selected over again at random.

The value must be in the range (0;1].

Type

float (0;1]

Default value

None (set to 1)

Supported processing units

CPU; GPU for pairwise ranking

nan_modenan_mode

Command-line: --nan-mode

DescriptionDescription

The method for  processing missing values in the input dataset.

Possible values:

• "Forbidden" — Missing values are not supported, their presence is interpreted as an error.
• "Min" — Missing values are processed as the minimum value (less than all other values) for the feature. It is guaranteed that a split that separates missing values from all other values is considered when selecting trees.
• "Max" — Missing values are processed as the maximum value (greater than all other values) for the feature. It is guaranteed that a split that separates missing values from all other values is considered when selecting trees.

Using the  Min or Max value of this parameter guarantees that a split between missing values and other values is considered when selecting a new split in the tree.

Type

string

Default value

Min

Supported processing units

CPU and GPU

input_bordersinput_borders

Command-line: --input-borders-file

DescriptionDescription

Load Custom quantization borders and missing value modes from a file (do not generate them).

Borders are automatically generated before training if this parameter is not set.

Type

string

Default value

Supported processing units

CPU and GPU

output_bordersoutput_borders

Command-line: --output-borders-file

DescriptionDescription

Save quantization borders for the current dataset to a file.

Refer to the file format description.

Type

string

Default value

Supported processing units

CPU and GPU

fold_permutation_blockfold_permutation_block

Command-line: --fold-permutation-block

DescriptionDescription

Objects in the dataset are grouped in blocks before the random permutations. This parameter defines the size of the blocks. The smaller is the value, the slower is the training. Large values may result in quality degradation.

Type

int

Default value

Supported processing units

CPU and GPU

leaf_estimation_methodleaf_estimation_method

Command-line: --leaf-estimation-method

DescriptionDescription

The method used to calculate the values in leaves.

Possible values:

• Newton
• Gradient
• Exact

Type

string

Default value

Depends on the mode and the selected loss function:

• Regression with Quantile or MAE loss functions — One Exact iteration.
• Regression with any loss function but Quantile or MAE – One Gradient iteration.
• Classification mode – Ten Newton iterations.
• Multiclassification mode – One Newton iteration.

Supported processing units

CPU and GPU

leaf_estimation_iterationsleaf_estimation_iterations

Command-line: --leaf-estimation-iterations

DescriptionDescription

CatBoost might calculate leaf values using several gradient or newton steps instead of a single one.

This parameter regulates how many steps are done in every tree when calculating leaf values.

Type

int

Default value

Supported processing units

CPU and GPU

leaf_estimation_backtrackingleaf_estimation_backtracking

Command-line: --leaf-estimation-backtracking

DescriptionDescription

When the value of the leaf_estimation_iterations parameter is greater than 1, CatBoost makes several gradient or newton steps when calculating the resulting leaf values of a tree.

The behaviour differs depending on the value of this parameter:

• No — Every next step is a regular gradient or newton step: the gradient step is calculated and added to the leaf.
• Any other value —Backtracking is used.
  In this case, before adding a step, a condition is checked. If the condition is not met, then the step size is reduced (divided by 2), otherwise the step is added to the leaf.

When leaf_estimation_iterations for the Command-line version is set to n, the leaf estimation iterations are calculated as follows: each iteration is either an addition of the next step to the leaf value, or it's a scaling of the leaf value. Scaling counts as a separate iteration. Thus, it is possible that instead of having n gradient steps, the algorithm makes a single gradient step that is reduced n times, which means that it is divided by $2\cdot n$ times.

Possible values:

• No — Do not use backtracking. Supported on CPU and GPU.
• AnyImprovement — Reduce the descent step up to the point when the loss function value is smaller than it was on the previous step. The trial reduction factors are 2, 4, 8, and so on. Supported on CPU and GPU.
• Armijo — Reduce the descent step until the Armijo condition is met. Supported only on GPU.

Type

string

Default value

AnyImprovement

Supported processing units

Depends on the selected value

fold_len_multiplierfold_len_multiplier

Command-line: --fold-len-multiplier

DescriptionDescription

Coefficient for changing the length of folds.

The value must be greater than 1. The best validation result is achieved with minimum values.

With values close to 1 (for example, $1+\epsilon$), each iteration takes a quadratic amount of memory and time for the number of objects in the iteration. Thus, low values are possible only when there is a small number of objects.

Type

float

Default value

2

Supported processing units

CPU and GPU

approx_on_full_historyapprox_on_full_history

Command-line:--approx-on-full-history

DescriptionDescription

The principles for calculating the approximated values.

Possible values:

• False — Use only а fraction of the fold for calculating the approximated values. The size of the fraction is calculated as follows: $\frac{1}X$, where X is the specified coefficient for changing the length of folds. This mode is faster and in rare cases slightly less accurate
• True — Use all the preceding rows in the fold for calculating the approximated values. This mode is slower and in rare cases slightly more accurate.

Type

bool

Default value

Supported processing units

CPU

class_weightsclass_weights

Command-line: --class-weights

DescriptionDescription

Class weights. The values are used as multipliers for the object weights. This parameter can be used for solving binary classification and multiclassification problems.

<value for class 1>,..,<values for class N>

0.85,1.2,1

Type

• list
• dict
• collections.OrderedDict

Default value

None (the weight for all classes is set to 1)

Supported processing units

CPU and GPU

class_namesclass_names

DescriptionDescription

Classes names. Allows to redefine the default values when using the MultiClass and Logloss metrics.

If the upper limit for the numeric class label is specified, the number of classes names should match this value.

Format:

<name for class 1>,..,<name for class N>

For example:

smartphone,touchphone,tablet

Type

list of strings

Default value

None

Supported processing units

CPU and GPU

auto_class_weightsauto_class_weights

Command-line: --auto-class-weights

DescriptionDescription

Automatically calculate class weights based either on the total weight or the total number of objects in each class. The values are used as multipliers for the object weights.

Supported values:

• None — All class weights are set to 1

• Balanced:

  $CW_k=\displaystyle\frac{max_{c=1}^K(\sum_{t_{i}=c}{w_i})}{\sum_{t_{i}=k}{w_{i}}}$

• SqrtBalanced:

  $CW_k=\sqrt{\displaystyle\frac{max_{c=1}^K(\sum_{t_i=c}{w_i})}{\sum_{t_i=k}{w_i}}}$

Type

string

Default value

None — All class weights are set to 1

Supported processing units

CPU and GPU

scale_pos_weightscale_pos_weight

DescriptionDescription

The weight for class 1 in binary classification. The value is used as a multiplier for the weights of objects from class 1.

Type

float

Default value

1.0

Supported processing units

CPU and GPU

boosting_typeboosting_type

Command-line: --boosting-type

DescriptionDescription

Boosting scheme.

Possible values:

• Ordered — Usually provides better quality on small datasets, but it may be slower than the Plain scheme.
• Plain — The classic gradient boosting scheme.

Type

string

Default value

Supported processing units

CPU and GPU

Only the Plain mode is supported for the MultiClass loss on GPU

boost_from_averageboost_from_average

Command-line: --boost-from-average

DescriptionDescription

Initialize approximate values by best constant value for the specified loss function. Sets the value of bias to the initial best constant value.

Available for the following loss functions:

• RMSE
• Logloss
• CrossEntropy
• Quantile
• MAE
• MAPE

Type

bool

Default value

Depends on the selected loss function:

• True for RMSE, Quantile, MAE, MAPE
• False for all other loss functions

Supported processing units

CPU and GPU

langevinlangevin

Command-line: --langevin

DescriptionDescription

Enables the Stochastic Gradient Langevin Boosting mode.

Refer to the SGLB: Stochastic Gradient Langevin Boosting paper for details.

Type

bool

Default value

False

Supported processing units

CPU

diffusion_temperaturediffusion_temperature

Command-line: --diffusion-temperature

DescriptionDescription

The diffusion temperature of the Stochastic Gradient Langevin Boosting mode.

Only non-negative values are supported.

Type

float

Default value

10000

Supported processing units

CPU

posterior_samplingposterior_sampling

Command-line: --posterior-sampling

DescriptionDescription

If this parameter is set several options are specified as follows and model parameters are checked to obtain uncertainty predictions with good theoretical properties.
Specifies options:

• Langevin: true,
• DiffusionTemperature: objects in learn pool count,
• ModelShrinkRate: 1 / (2. * objects in learn pool count).

Type

bool

Default value

False

Supported processing units

CPU only

allow_const_labelallow_const_label

Command-line: --allow-const-label

DescriptionDescription

Use it to train models with datasets that have equal label values for all objects.

Type

bool

Default value

False

Supported processing units

CPU and GPU

score_functionscore_function

Command-line: --score-function

DescriptionDescription

The score type used to select the next split during the tree construction.

Possible values:

• Cosine (do not use this score type with the Lossguide tree growing policy)
• L2
• NewtonCosine (do not use this score type with the Lossguide tree growing policy)
• NewtonL2

Type

string

Default value

Cosine

Supported processing units

The supported score functions vary depending on the processing unit type:

• GPU — All score types

• CPU — Cosine, L2

monotone_constraintsmonotone_constraints

Command-line: --monotone-constraints

DescriptionDescription

Impose monotonic constraints on numerical features.

Possible values:

• 1 — Increasing constraint on the feature. The algorithm forces the model to be a non-decreasing function of this features.

• -1 — Decreasing constraint on the feature. The algorithm forces the model to be a non-increasing function of this features.

• 0 — constraints are disabled.

Supported formats for setting the value of this parameter (all feature indices are zero-based):

• Set constraints individually for each feature as a string (the number of features is n).

  Format

  "(<constraint_0>, <constraint_2>, .., <constraint_n-1>)"
  

  Zero constraints for features at the end of the list may be dropped.

  In monotone_constraints = "(1,0,-1)"an increasing constraint is set on the first feature and a decreasing one on the third. Constraints are disabled for all other features.

• Set constraints individually for each explicitly specified feature as a string (the number of features is n).

  "<feature index or name>:<constraint>, .., <feature index or name>:<constraint>"
  

  These examples

  monotone-constraints = "2:1,4:-1"
  

  monotone-constraints = "Feature2:1,Feature4:-1"
  

  are identical, given that the name of the feature index 2 is Feature2 and the name of the feature indexed 4 is Feature4.

• Set constraints individually for each required feature as an array or a dictionary (the number of features is n).

  Format

  [<constraint_0>, <constraint_2>, .., <constraint_n-1>]
  

  {"<feature index or name>":<constraint>, .., "<feature index or name>":<constraint>}
  

  Array examples

  monotone_constraints = [1, 0, -1]
  

  These dictionary examples

  monotone_constraints = {"Feature2":1,"Feature4":-1}
  

  monotone_constraints = {"2":1, "4":-1}
  

  are identical, given that the name of the feature indexed 2 is Feature2 and the name of the feature indexed 4 is Feature4.

Type

• list of strings
• string
• dict
• list

Default value

Supported processing units

CPU

feature_weightsfeature_weights

Command-line: --feature-weights

DescriptionDescription

Per-feature multiplication weights used when choosing the best split. The score of each candidate is multiplied by the weights of features from the current split.

Non-negative float values are supported for each weight.

Supported formats for setting the value of this parameter:

• Set the multiplication weight for each feature as a string (the number of features is n).

  Format

  "(<feature-weight_0>,<feature-weight_2>,..,<feature-weight_n-1>)"
  

  Note

  Spaces between values are not allowed.

  Values should be passed as a parenthesized string of comma-separated values. Multiplication weights equal to 1 at the end of the list may be dropped.

  In this

  example

  feature_weights = "(0.1,1,3)"
  

  the multiplication weight is set to 0.1, 1 and 3 for the first, second and third features respectively. The multiplication weight for all other features is set to 1.

• Set the multiplication weight individually for each explicitly specified feature as a string (the number of features is n).

  Format

  "<feature index or name>:<weight>, .., <feature index or name>:<weight>"
  

  Note

  Spaces between values are not allowed.

  These examples

  feature_weights = "2:1.1,4:0.1"
  

  feature_weights = "Feature2:1.1,Feature4:0.1"
  

  are identical, given that the name of the feature indexed 2 is Feature2 and the name of the feature indexed 4 is Feature4.

• Set the multiplication weight individually for each required feature as an array or a dictionary (the number of features is n).

  Format

  [<feature-weight_0>, <feature-weight_2>, .., <feature-weight_n-1>]
  

  {"<feature index or name>":<weight>, .., "<feature index or name>":<weight>}
  

  Array examples

  feature_weights = [0.1, 1, 3]
  

  These dictionary examples

  feature_weights = {"Feature2":1.1,"Feature4":0.3}
  

  feature_weights = {"2":1.1, "4":0.3}
  

  are identical, given that the name of the feature indexed 2 is Feature2 and the name of the feature indexed 4 is Feature4.

Type

• list
• numpy.ndarray
• string
• dict

Default value

1 for all features

Supported processing units

CPU

first_feature_use_penaltiesfirst_feature_use_penalties

Command-line: --first-feature-use-penalties

DescriptionDescription

Per-feature penalties for the first occurrence of the feature in the model. The given value is subtracted from the score if the current candidate is the first one to include the feature in the model.

Refer to the Per-object and per-feature penalties section for details on applying different score penalties.

Non-negative float values are supported for each penalty.

• Set the penalty for each feature as a string (the number of features is n).

  Format

  "(<feature-penalty_0>, <feature-penalty_2>, .., <feature-penalty_n-1>)"
  

  Note

  Spaces between values are not allowed.

  Values should be passed as a parenthesized string of comma-separated values. Penalties equal to 0 at the end of the list may be dropped.

  In this example

  first_feature_use_penalties parameter:

  first_feature_use_penalties = "(0.1,1,3)"
  

  per_object_feature_penalties parameter:

  per_object_feature_penalties = "(0.1,1,3)"
  

  Note

  Spaces between values are not allowed.

  the multiplication weight is set to 0.1, 1 and 3 for the first, second and third features respectively. The multiplication weight for all other features is set to 1.

• Set the penalty individually for each explicitly specified feature as a string (the number of features is n).

  Format

  "<feature index or name>:<penalty>,..,<feature index or name>:<penalty>"
  

  Note

  Spaces between values are not allowed.

  These examples first_feature_use_penalties parameter:

  first_feature_use_penalties = "2:1.1,4:0.1"
  

  first_feature_use_penalties = "Feature2:1.1,Feature4:0.1"
  

  per_object_feature_penalties parameter:

  per_object_feature_penalties = "2:1.1,4:0.1"
  

  per_object_feature_penalties = "Feature2:1.1,Feature4:0.1"
  

  are identical, given that the name of the feature indexed 2 is Feature2 and the name of the feature indexed 4 is Feature4.

• Set the penalty individually for each required feature as an array or a dictionary (the number of features is n).

  Format

  [<feature-penalty_0>, <feature-penalty_2>, .., <feature-penalty_n-1>]
  

  {"<feature index or name>":<penalty>, .., "<feature index or name>":<penalty>}
  

  Array examples.

  first_feature_use_penalties parameter:

  first_feature_use_penalties = [0.1, 1, 3]
  

  per_object_feature_penalties parameter:

  per_object_feature_penalties = [0.1, 1, 3]
  

  These dictionary examples

  first_feature_use_penalties parameter:

  first_feature_use_penalties = {"Feature2":1.1,"Feature4":0.1}
  

  first_feature_use_penalties = {"2":1.1, "4":0.1}
  

  per_object_feature_penalties parameter:

  per_object_feature_penalties = {"Feature2":1.1,"Feature4":0.1}
  

  per_object_feature_penalties = {"2":1.1, "4":0.1}
  

  are identical, given that the name of the feature indexed 2 is Feature2 and the name of the feature indexed 4 is Feature4.

Type

• list
• numpy.ndarray
• string
• dict

Default value

0 for all features

Supported processing units

CPU

fixed_binary_splitsfixed_binary_splits

Command-line: --fixed-binary-splits

DescriptionDescription

A list of indices of binary features to put at the top of each tree; ignored if grow_policy is Symmetric.

Type

list

Default value

None

Supported processing units

GPU

penalties_coefficientpenalties_coefficient

Command-line: --penalties-coefficient

DescriptionDescription

A single-value common coefficient to multiply all penalties.

Non-negative values are supported.

Type

float

Default value

1

Supported processing units

CPU

per_object_feature_penaltiesper_object_feature_penalties

Command-line: --per-object-feature-penalties

DescriptionDescription

Per-object penalties for the first use of the feature for the object. The given value is multiplied by the number of objects that are divided by the current split and use the feature for the first time.

Refer to the Per-object and per-feature penalties section for details on applying different score penalties.

Non-negative float values are supported for each penalty.

Type

• list
• numpy.ndarray
• string
• dict

Default value

0 for all objects

Supported processing units

CPU

model_shrink_ratemodel_shrink_rate

Command-line: --model-shrink-rate

DescriptionDescription

The constant used to calculate the coefficient for multiplying the model on each iteration.
The actual model shrinkage coefficient calculated at each iteration depends on the value of the --model-shrink-modefor the Command-line version parameter. The resulting value of the coefficient should be always in the range (0, 1].

Type

float

Default value

The default value depends on the values of the following parameters:

• --model-shrink-mode for the Command-line version

• --monotone-constraints for the Command-line version

Supported processing units

CPU

model_shrink_modemodel_shrink_mode

Command-line: model_shrink_mode

DescriptionDescription

Determines how the actual model shrinkage coefficient is calculated at each iteration.

Possible values:

• Constant:

  $1 - model\_shrink\_rate \cdot learning\_rate {,}$

  • $model\_shrink\_rate$ is the value of the --model-shrink-ratefor the Command-line version parameter.
  • $learning\_rate$ is the value of the --learning-ratefor the Command-line version parameter

• Decreasing:

  $1 - \frac{model\_shrink\_rate}{i} {,}$

  • $model\_shrink\_rate$ is the value of the --model-shrink-ratefor the Command-line version parameter.
  • $i$ is the identifier of the iteration.

Type

string

Default value

Constant

Supported processing units

CPU