---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.5
alternate:
  - https://catboost.ai/docs/en/references/training-parameters/common.md
  - href: en/references/training-parameters/common.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://catboost.ai/docs/en/llms.txt

# Common parameters

## loss_function {#loss_function}

Command-line: `--loss-function`

_Alias:_ `objective`

#### Description

<!-- source: en/_includes/work_src/reusage/loss-function-short-desc.md -->
The [metric](https://catboost.ai/docs/en/concepts/loss-functions.md) 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](https://catboost.ai/docs/en/concepts/loss-functions.md) section for details on each metric).
<!-- endsource: en/_includes/work_src/reusage/loss-function-short-desc.md -->


<!-- source: en/_includes/work_src/reusage/loss-function-format.md -->
Format:
```
<Metric>[:<parameter 1>=<value>;..;<parameter N>=<value>]
```
<!-- endsource: en/_includes/work_src/reusage/loss-function-format.md -->


{% cut "Supported metrics" %}

- RMSE
- Logloss
- MAE
- CrossEntropy
- Quantile
- LogLinQuantile
- Lq
- MultiRMSE
- MultiClass
- MultiClassOneVsAll
- MultiLogloss
- MultiCrossEntropy
- MAPE
- Poisson
- PairLogit
- PairLogitPairwise
- QueryRMSE
- QuerySoftMax
- GroupQuantile
- Tweedie

- YetiRank
- YetiRankPairwise
- StochasticFilter
- StochasticRank

{% endcut %}

A custom python object can also be set as the value of this parameter (see an [example](https://catboost.ai/docs/en/concepts/python-usages-examples.md)).

<!-- source: en/_includes/work_src/reusage/loss-function--example.md -->
For example, use the following construction to calculate the value of Quantile with the coefficient $\alpha = 0.1$:
```
Quantile:alpha=0.1
```
<!-- endsource: en/_includes/work_src/reusage/loss-function--example.md -->

**Type**

- string
- object

**Default value**

{% cut "Python package" %}

Depends on the class:

- [CatBoostClassifier](https://catboost.ai/docs/en/concepts/python-reference_catboostclassifier.md): Logloss if the `target_border` parameter value differs from None. Otherwise, the default loss function depends on the number of unique target values and is either set to Logloss or MultiClass.
- [CatBoost](https://catboost.ai/docs/en/concepts/python-reference_catboost.md) and [CatBoostRegressor](https://catboost.ai/docs/en/concepts/python-reference_catboostregressor.md): RMSE

{% endcut %}

{% cut "R package, Command-line" %}

RMSE

{% endcut %}

**Supported processing units**

 CPU and GPU

## custom_metric {#custom_metric}

Command-line: `--custom-metric`

#### Description

<!-- source: en/_includes/work_src/reusage/custom-loss--basic.md -->
[Metric](https://catboost.ai/docs/en/concepts/loss-functions.md) 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](https://catboost.ai/docs/en/concepts/loss-functions.md) section for details on each metric).
<!-- endsource: en/_includes/work_src/reusage/custom-loss--basic.md -->

<!-- source: en/_includes/work_src/reusage/loss-function-format.md -->
Format:
```
<Metric>[:<parameter 1>=<value>;..;<parameter N>=<value>]
```
<!-- endsource: en/_includes/work_src/reusage/loss-function-format.md -->


[Supported metrics](https://catboost.ai/docs/en/references/custom-metric__supported-metrics.md)

{% cut "Examples" %}

- Calculate the value of CrossEntropy:

    ```
    CrossEntropy
    ```

- Calculate the value of Quantile with the coefficient $\alpha = 0.1$
    ```
    Quantile:alpha=0.1
    ```

- Calculate the values of Logloss and AUC:
    ```python
    ['Logloss', 'AUC']


    ```
{% endcut %}

<!-- source: en/_includes/work_src/reusage/custom-loss--values-saved-to.md -->
Values of all custom metrics for learn and validation datasets are saved to the [Metric](https://catboost.ai/docs/en/concepts/output-data_loss-function.md) output files (`learn_error.tsv` and `test_error.tsv` respectively). The directory for these files is specified in the `--train-dir` (`train_dir`) parameter.
<!-- endsource: en/_includes/work_src/reusage/custom-loss--values-saved-to.md -->


Use the [visualization tools](https://catboost.ai/docs/en/features/visualization.md) to see a live chart with the dynamics of the specified metrics.

**Type**

- string
- list of strings

**Default value**

{% cut "Python package" %}

None

{% endcut %}


{% cut "R package" %}

None

{% endcut %}


{% cut "Command-line" %}

None (do not output additional metric values)

{% endcut %}

**Supported processing units**

 CPU and GPU


## eval_metric {#eval_metric}

Command-line: `--eval-metric`

#### Description

<!-- source: en/_includes/work_src/reusage/eval-metric--basic.md -->
The metric used for overfitting detection (if enabled) and best model selection (if enabled). Some metrics support optional parameters (see the [Objectives and metrics](https://catboost.ai/docs/en/concepts/loss-functions.md) section for details on each metric).
<!-- endsource: en/_includes/work_src/reusage/eval-metric--basic.md -->

<!-- source: en/_includes/work_src/reusage/eval-metric--format.md -->
Format:
```
<Metric>[:<parameter 1>=<value>;..;<parameter N>=<value>]
```
<!-- endsource: en/_includes/work_src/reusage/eval-metric--format.md -->

[Supported metrics](https://catboost.ai/docs/en/references/eval-metric__supported-metrics.md)

A user-defined function can also be set as the value (see an [example](https://catboost.ai/docs/en/concepts/python-usages-examples.md)).

<!-- source: en/_includes/work_src/reusage/eval-metric--examples.md -->
Examples:
```
R2
```
<!-- endsource: en/_includes/work_src/reusage/eval-metric--examples.md -->

**Type**

- string
- object

**Default value**

  Optimized objective is used

**Supported processing units**

 CPU and GPU

## iterations {#iterations}

Command-line: `-i`, `--iterations`

_Aliases:_ `num_boost_round`, `n_estimators`, `num_trees`

#### Description

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_rate {#learning_rate}

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

_Alias:_ `eta`

#### Description

The learning rate.

Used for reducing the gradient step.

**Type**

float

**Default value**

The default value is defined automatically for [`Logloss`](https://catboost.ai/docs/en/concepts/loss-functions-classification.md#Logit), [`MultiClass`](https://catboost.ai/docs/en/concepts/loss-functions-multiclassification.md#MultiClass) and [`RMSE`](https://catboost.ai/docs/en/concepts/loss-functions-regression.md#RMSE) loss functions depending on the number of iterations if none of parameters [`leaf_estimation_iterations`](#leaf_estimation_iterations), [`leaf_estimation_method`](#leaf_estimation_method), [`l2_leaf_reg`](#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_seed {#random_seed}

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

_Alias:_`random_state`

#### Description

The random seed used for training.

**Type**

int

**Default value**

{% cut "Python package" %}

None (0)

{% endcut %}

{% cut "R package, Command-line" %}

0

{% endcut %}

**Supported processing units**

 CPU and GPU

## l2_leaf_reg {#l2_leaf_reg}

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

_Alias:_ `reg_lambda`

#### Description

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_type {#bootstrap_type}

Command-line: `--bootstrap-type`

#### Description

[Bootstrap type](https://catboost.ai/docs/en/concepts/algorithm-main-stages_bootstrap-options.md). 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_temperature {#bagging_temperature}

Command-line: `--bagging-temperature`

#### Description

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 <q>1</q>. All weights are equal to 1 if the value of this parameter is set to <q>0</q>.

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

## subsample {#subsample}

Command-line: `--subsample`

#### Description

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**

<!-- source: en/_includes/work_src/reusage-default-values/subsample__default.md -->
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
<!-- endsource: en/_includes/work_src/reusage-default-values/subsample__default.md -->

**Supported processing units**

 CPU and GPU

## sampling_frequency {#sampling_frequency}

Command-line: `--sampling-frequency`

#### Description

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_unit {#sampling_unit}

Command-line: `--sampling-unit`

#### Description


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_reg {#mvs_reg}

Command-line: `--mvs-reg`

#### Description

<!-- source: en/_includes/work_src/reusage/cli__mvs-head-fraction__div.md -->
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).
<!-- endsource: en/_includes/work_src/reusage/cli__mvs-head-fraction__div.md -->

{% note info %}

This parameter is supported only for the MVS sampling method (the `bootstrap_type` parameter must be set to MVS).

{% endnote %}

**Type**

float

**Default value**

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

**Supported processing units**

 CPU

## random_strength {#random_strength}

Command-line: `--random-strength`

#### Description

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.

{% note info %}

This parameter is not supported for the following loss functions:

- QueryCrossEntropy
- YetiRankPairwise
- PairLogitPairwise

{% endnote %}

**Type**

float

**Default value**

 1

**Supported processing units**

 CPU

## use_best_model {#use_best_model}

Command-line: `--use-best-model`

#### Description

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.
1. 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_trees {#best_model_min_trees}

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

#### Description

<!-- source: en/_includes/work_src/reusage/clii__best-model-min-trees__short-desc.md -->
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.
<!-- endsource: en/_includes/work_src/reusage/clii__best-model-min-trees__short-desc.md -->

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

**Type**

int

**Default value**

{% cut "Python package, R package" %}

None (The minimal number of trees for the best model is not set)

{% endcut %}

{% cut "Command-line" %}

The minimal number of trees for the best model is not set

{% endcut %}

**Supported processing units**

 CPU and GPU

## depth {#depth}

Command-line: `-n`, `--depth`

_Alias:_ `max_depth`

#### Description

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_policy {#grow_policy}

Command-line: `--grow-policy`

#### Description

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 info %}

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

  {% endnote %}

- 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.

  <!-- source: en/_includes/work_src/reusage/cli__grow-policy__note.md -->
  {% note info %}

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

  {% endnote %}
  <!-- endsource: en/_includes/work_src/reusage/cli__grow-policy__note.md -->

**Type**

string

**Default value**

 SymmetricTree

**Supported processing units**

 CPU and GPU

## min_data_in_leaf {#min_data_in_leaf}

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

_Alias:_ `min_child_samples`

#### Description

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_leaves {#max_leaves}

Command-line: `--max-leaves`

_Alias:_`num_leaves`

#### Description

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

{% note info %}

It is not recommended to use values greater than 64, since it can significantly slow down the training process.

{% endnote %}

**Type**

int

**Default value**

31

**Supported processing units**

CPU and GPU

## ignored_features {#ignored_features}

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

#### Description

Feature indices to exclude from the training.

{% cut "Python package" %}

 <!-- source: en/_includes/work_src/reusage/ignored-features.md -->
 It is assumed that all passed values are feature names if at least one of the passed values can not be converted to a number or a range of numbers.  Otherwise, it is assumed that all passed values are feature indices.
 <!-- endsource: en/_includes/work_src/reusage/ignored-features.md -->

 <!-- source: en/_includes/work_src/reusage/cli__ignored_features__specifics.md -->
 Specifics:

 - Non-negative indices that do not match any features are successfully ignored. For example, if five features are defined for the objects in the dataset and this parameter is set to <q>42</q>, the corresponding non-existing feature is successfully ignored.

 - The identifier corresponds to the feature's index. Feature indices used in train and feature importance are numbered from 0 to `featureCount – 1`. If a file is used as [input data](https://catboost.ai/docs/en/concepts/input-data.md) then any non-feature column types are ignored when calculating these indices. For example, each row in the input file contains data in the following order: `cat feature<\t>label value<\t>num feature`. So for the row `rock<\t>0<\t>42`, the identifier for the <q>rock</q> feature is 0, and for the <q>42</q> feature it's 1.
 <!-- endsource: en/_includes/work_src/reusage/cli__ignored_features__specifics.md -->

 For example, use the following construction if features indexed 1, 2, 7, 42, 43, 44, 45, should be ignored: `[1,2,7,42,43,44,45]`

{% endcut %}

{% cut "R package" %}

 <!-- source: en/_includes/work_src/reusage/cli__ignored_features__specifics.md -->
 Specifics:

 - Non-negative indices that do not match any features are successfully ignored. For example, if five features are defined for the objects in the dataset and this parameter is set to <q>42</q>, the corresponding non-existing feature is successfully ignored.

 - The identifier corresponds to the feature's index. Feature indices used in train and feature importance are numbered from 0 to `featureCount – 1`. If a file is used as [input data](https://catboost.ai/docs/en/concepts/input-data.md) then any non-feature column types are ignored when calculating these indices. For example, each row in the input file contains data in the following order: `cat feature<\t>label value<\t>num feature`. So for the row `rock<\t>0<\t>42`, the identifier for the <q>rock</q> feature is 0, and for the <q>42</q> feature it's 1.
 <!-- endsource: en/_includes/work_src/reusage/cli__ignored_features__specifics.md -->

 For example, if training should exclude features with the identifiers 1, 2, 7, 42, 43, 44, 45, the value of this parameter should be set to c(1,2,7,42,43,44,45).

{% endcut %}

{% cut "Command-line" %}

 <!-- source: en/_includes/work_src/reusage/ignored-features.md -->
 It is assumed that all passed values are feature names if at least one of the passed values can not be converted to a number or a range of numbers.  Otherwise, it is assumed that all passed values are feature indices.
 <!-- endsource: en/_includes/work_src/reusage/ignored-features.md -->

 <!-- source: en/_includes/work_src/reusage/cli__ignored_features__specifics.md -->
 Specifics:

 - Non-negative indices that do not match any features are successfully ignored. For example, if five features are defined for the objects in the dataset and this parameter is set to <q>42</q>, the corresponding non-existing feature is successfully ignored.

 - The identifier corresponds to the feature's index. Feature indices used in train and feature importance are numbered from 0 to `featureCount – 1`. If a file is used as [input data](https://catboost.ai/docs/en/concepts/input-data.md) then any non-feature column types are ignored when calculating these indices. For example, each row in the input file contains data in the following order: `cat feature<\t>label value<\t>num feature`. So for the row `rock<\t>0<\t>42`, the identifier for the <q>rock</q> feature is 0, and for the <q>42</q> feature it's 1.
 <!-- endsource: en/_includes/work_src/reusage/cli__ignored_features__specifics.md -->

 For example, if training should exclude features with the identifiers 1, 2, 7, 42, 43, 44, 45, use the following construction: `1:2:7:42-45`.

{% endcut %}

**Default value**

{% cut "Python package, R package" %}

 None

{% endcut %}

{% cut "Command-line" %}

 Omitted

{% endcut %}

**Supported processing units**

CPU and GPU

## one_hot_max_size {#one_hot_max_size}

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

#### Description

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](https://catboost.ai/docs/en/features/categorical-features.md).

**Type**

int

**Default value**

<!-- source: en/_includes/work_src/reusage-default-values/one-hot-max-size-default.md -->
The default value depends on various conditions:

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

    {% cut "Read more about  Pairwise scoring" %}


    <!-- source: en/_includes/work_src/reusage-default-values/metrics_parwise_scoring.md -->
    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.
    <!-- endsource: en/_includes/work_src/reusage-default-values/metrics_parwise_scoring.md -->


    {% endcut %}

- 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](https://catboost.ai/docs/en/concepts/loss-functions-ranking.md) mode
- 2 if none of the conditions above is met
<!-- endsource: en/_includes/work_src/reusage-default-values/one-hot-max-size-default.md -->

**Supported processing units**

 CPU and GPU


## has_time {#has_time}

Command-line: `--has-time`

#### Description

Use the order of objects in the input data (do not perform random permutations during the [Transforming categorical features to numerical features](https://catboost.ai/docs/en/concepts/algorithm-main-stages_cat-to-numberic.md) and [Choosing the tree structure](https://catboost.ai/docs/en/concepts/algorithm-main-stages_choose-tree-structure.md) stages).

The Timestamp column type is used to determine the order of objects if specified in the [input data](https://catboost.ai/docs/en/concepts/input-data.md).

**Type**

bool

**Default value**

False (not used; generates random permutations)

**Supported processing units**

CPU and GPU

## rsm {#rsm}

Command-line: `--rsm`

_Alias:_`colsample_bylevel`

#### Description

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_mode {#nan_mode}

Command-line: `--nan-mode`

#### Description

The method for  [processing missing values](https://catboost.ai/docs/en/concepts/algorithm-missing-values-processing.md) in the input dataset.

<!-- source: en/_includes/work_src/reusage/cmd__nan-mode__div.md -->
Possible values:

<!-- source: en/_includes/work_src/reusage-missing-values/mv-processing-methods.md -->
- "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.
<!-- endsource: en/_includes/work_src/reusage-missing-values/mv-processing-methods.md -->

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.

{% note info %}

The method for processing missing values can be set individually for each feature in the [Custom quantization borders and missing value modes](https://catboost.ai/docs/en/concepts/input-data_custom-borders.md) input file. Such values override the ones specified in this parameter.

{% endnote %}
<!-- endsource: en/_includes/work_src/reusage/cmd__nan-mode__div.md -->

**Type**

string

**Default value**

 Min

**Supported processing units**

 CPU and GPU


## input_borders {#input_borders}

Command-line: `--input-borders-file`

#### Description

Load [Custom quantization borders and missing value modes](https://catboost.ai/docs/en/concepts/input-data_custom-borders.md) from a file (do not generate them).

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

**Type**

string

**Default value**

{% cut "Python package" %}

None

{% endcut %}

{% cut "Command-line" %}

The file is not loaded, the values are generated

{% endcut %}

**Supported processing units**

 CPU and GPU


## output_borders {#output_borders}

Command-line: `--output-borders-file`

#### Description

Save quantization borders for the current dataset to a file.

Refer to the [file format description](https://catboost.ai/docs/en/concepts/output-data_custom-borders.md).

**Type**

string

**Default value**

{% cut "Python package" %}

None

{% endcut %}

{% cut "Command-line" %}

The file is not saved

{% endcut %}

**Supported processing units**

 CPU and GPU


## fold_permutation_block {#fold_permutation_block}

Command-line: `--fold-permutation-block`

#### Description


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**

{% cut "Python package" %}

1

{% endcut %}

{% cut "R package, Command-line" %}

Default value differs depending on the dataset size and ranges from 1 to 256 inclusively

{% endcut %}

**Supported processing units**

 CPU and GPU

## leaf_estimation_method {#leaf_estimation_method}

Command-line: `--leaf-estimation-method`

#### Description

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_iterations {#leaf_estimation_iterations}

Command-line: `--leaf-estimation-iterations`

#### Description

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**

{% cut "Python package" %}

None (Depends on the training objective)

{% endcut %}

{% cut "R package, Command-line" %}

Depends on the training objective

{% endcut %}

**Supported processing units**

CPU and GPU


## leaf_estimation_backtracking {#leaf_estimation_backtracking}

Command-line: `--leaf-estimation-backtracking`

#### Description

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_multiplier {#fold_len_multiplier}

Command-line: `--fold-len-multiplier`

#### Description

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_history {#approx_on_full_history}

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

#### Description


The principles for calculating the approximated values.

Possible values:
- <q>False</q> — 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
- <q>True</q> — 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**

{% cut "Python package, Command-line" %}

False

{% endcut %}

{% cut "R package" %}

True

{% endcut %}

**Supported processing units**

 CPU


## class_weights {#class_weights}

Command-line: `--class-weights`

#### Description


<!-- source: en/_includes/work_src/reusage/class-weights__short-desc-intro.md -->
Class weights. The values are used as multipliers for the object weights. This parameter can be used for solving binary classification and multiclassification problems.
<!-- endsource: en/_includes/work_src/reusage/class-weights__short-desc-intro.md -->


{% cut "Python package" %}

{% note info %}

<!-- source: en/_includes/work_src/reusage/imbalanced-datasets-description.md -->
For imbalanced datasets with binary classification the weight multiplier can be set to 1 for class 0 and to $\left(\frac{sum\_negative}{sum\_positive}\right)$ for class 1.
<!-- endsource: en/_includes/work_src/reusage/imbalanced-datasets-description.md -->

{% endnote %}

For example, `class_weights=[0.1, 4]`multiplies the weights of objects from class 0 by 0.1 and the weights of objects from class 1 by 4.

If class labels are not standard consecutive integers [0, 1 ... class_count-1], use the dict or collections.OrderedDict type with label to weight mapping.

For example, `class_weights={'a': 1.0, 'b': 0.5, 'c': 2.0}` multiplies the weights of objects with class label `a` by 1.0, the weights of objects with class label `b` by 0.5 and the weights of objects with class label `c` by 2.0.

The dictionary form can also be used with standard consecutive integers class labels for additional readability. For example: `class_weights={0: 1.0, 1: 0.5, 2: 2.0}`.

{% note info %}

Class labels are extracted from dictionary keys for the following types of class_weights:

- dict
- collections.OrderedDict (when the order of classes in the model is important)

The class_names parameter can be skipped when using these types.

{% endnote %}

{% note alert %}

Do not use this parameter with auto_class_weights and scale_pos_weight.

{% endnote %}

{% endcut %}

{% cut "R package" %}

For example, `class_weights <- c(0.1, 4)` multiplies the weights of objects from class 0 by 0.1 and the weights of objects from class 1 by 4.

{% note alert %}

Do not use this parameter with auto_class_weights.

{% endnote %}

{% endcut %}

{% cut "Command-line" %}

{% note info %}

The quantity of class weights must match the quantity of class names specified in the `--class-names` parameter and the number of classes specified in the `--classes-count parameter`.

<!-- source: en/_includes/work_src/reusage/imbalanced-datasets-description.md -->
For imbalanced datasets with binary classification the weight multiplier can be set to 1 for class 0 and to $\left(\frac{sum\_negative}{sum\_positive}\right)$ for class 1.
<!-- endsource: en/_includes/work_src/reusage/imbalanced-datasets-description.md -->

{% endnote %}

Format:

```
<value for class 1>,..,<values for class N>
```
For example:

```
0.85,1.2,1
```

{% note alert %}

Do not use this parameter with auto_class_weights.

{% endnote %}

{% endcut %}

**Type**

- list
- dict
- collections.OrderedDict

**Default value**

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

**Supported processing units**

 CPU and GPU


## class_names {#class_names}

#### Description


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.

{% note warning %}

The quantity of classes names must match the quantity of classes weights specified in the `--class-weights` parameter and the number of classes specified in the `--classes-count` parameter.

{% endnote %}

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_weights {#auto_class_weights}

Command-line: `--auto-class-weights`

#### Description


<!-- source: en/_includes/work_src/reusage/cli__auto-class-weights__div.md -->
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}}}$
<!-- endsource: en/_includes/work_src/reusage/cli__auto-class-weights__div.md -->

{% note alert %}

Do not use this parameter with `class_weights` and `scale_pos_weight`.

{% endnote %}

**Type**

string

**Default value**

 None — All class weights are set to 1

**Supported processing units**

 CPU and GPU

## scale_pos_weight {#scale_pos_weight}

#### Description


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

{% note info %}

For imbalanced datasets, the weight multiplier can be set to $\left(\frac{sum\_negative}{sum\_positive}\right)$

{% endnote %}

{% note alert %}

Do not use this parameter with `auto_class_weights` and `class_weights`.

{% endnote %}

**Type**

float

**Default value**

 1.0

**Supported processing units**

 CPU and GPU

## boosting_type {#boosting_type}

Command-line: `--boosting-type`

#### Description


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**

{% cut "Depends on the processing unit type, the number of objects in the training dataset and the selected learning mode" %}

- CPU

  Plain

-  GPU

    - Any number of objects, MultiClass or MultiClassOneVsAll mode: Plain
    - More than 50 thousand objects, any mode: Plain
    - Less than or equal to 50 thousand objects, any mode but MultiClass or MultiClassOneVsAll: Ordered

{% endcut %}

**Supported processing units**

 CPU and GPU

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


## boost_from_average {#boost_from_average}

Command-line: `--boost-from-average`

#### Description


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**

<!-- source: en/_includes/work_src/reusage-default-values/boost-from-average.md -->
Depends on the selected loss function:
- True for RMSE, Quantile, MAE, MAPE
- False for all other loss functions
<!-- endsource: en/_includes/work_src/reusage-default-values/boost-from-average.md -->

**Supported processing units**

 CPU and GPU

## langevin {#langevin}

Command-line: `--langevin`

#### Description


Enables the Stochastic Gradient Langevin Boosting mode.

Refer to the [SGLB: Stochastic Gradient Langevin Boosting](https://arxiv.org/abs/2001.07248) paper for details.

**Type**

bool

**Default value**

 False

**Supported processing units**

 CPU

## diffusion_temperature {#diffusion_temperature}

Command-line: `--diffusion-temperature`

#### Description


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_sampling {#posterior_sampling}

Command-line: `--posterior-sampling	`

#### Description


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_label {#allow_const_label}

Command-line: `--allow-const-label`

#### Description


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_function {#score_function}

Command-line: `--score-function`

#### Description


The [score type](https://catboost.ai/docs/en/concepts/algorithm-score-functions.md) 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_constraints {#monotone_constraints}

Command-line: `--monotone-constraints`

#### Description

<!-- source: en/_includes/work_src/reusage/cli__monotone-constraints__desc__div.md -->
Impose monotonic constraints on numerical features.

Possible values:

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

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

- <q>0</q> — constraints are disabled.
<!-- endsource: en/_includes/work_src/reusage/cli__monotone-constraints__desc__div.md -->

<!-- source: en/_includes/work_src/reusage/monotone-constraints__formats__intro.md -->
Supported formats for setting the value of this parameter (all feature indices are zero-based):
<!-- endsource: en/_includes/work_src/reusage/monotone-constraints__formats__intro.md -->

- <!-- source: en/_includes/work_src/reusage/set-individual-constraints__div.md -->
  Set constraints individually for each feature as a string (the number of features is n).

  Format

  ```
  "(<constraint_0>, <constraint_2>, .., <constraint_n-1>)"
  ```
  <!-- endsource: en/_includes/work_src/reusage/set-individual-constraints__div.md -->

  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.

- <!-- source: en/_includes/work_src/reusage/monotone-constraints__formats__individually-for-required-features.md -->
  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>"
  ```
  <!-- endsource: en/_includes/work_src/reusage/monotone-constraints__formats__individually-for-required-features.md -->

    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 <q>Feature2</q> and the name of the feature indexed 4 is <q>Feature4</q>.

- <!-- source: en/_includes/work_src/reusage/cli__monotone-constraints__arra-or-dict.md -->
  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>}
  ```
  <!-- endsource: en/_includes/work_src/reusage/cli__monotone-constraints__arra-or-dict.md -->

  {% cut "Array examples" %}

    ```
    monotone_constraints = [1, 0, -1]
    ```

  {% endcut %}

  {% cut "These dictionary examples" %}

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

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

  {% endcut %}

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

**Type**

- list of strings
- string
- dict
- list

**Default value**

{% cut "Python package, R package" %}

None

{% endcut %}

{% cut "Command-line" %}

Ommited

{% endcut %}

**Supported processing units**

 CPU

## feature_weights {#feature_weights}

Command-line: `--feature-weights`

#### Description


<!-- source: en/_includes/work_src/reusage/cli__feature-weight__desc__intro.md -->
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:
<!-- endsource: en/_includes/work_src/reusage/cli__feature-weight__desc__intro.md -->


- <!-- source: en/_includes/work_src/reusage/cli__feature-weight__desc__weight-for-each-feature.md -->
  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 info %}

  Spaces between values are not allowed.

  {% endnote %}



  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.
  <!-- endsource: en/_includes/work_src/reusage/cli__feature-weight__desc__weight-for-each-feature.md -->

  In this

  {% cut "example" %}

    ```
    feature_weights = "(0.1,1,3)"
    ```

  {% endcut %}

  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.

- <!-- source: en/_includes/work_src/reusage/cli__feature-weight__formats__individually-for-required-features.md -->
  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 info %}

  Spaces between values are not allowed.

  {% endnote %}
  <!-- endsource: en/_includes/work_src/reusage/cli__feature-weight__formats__individually-for-required-features.md -->

  {% cut "These examples" %}

    ```
    feature_weights = "2:1.1,4:0.1"
    ```

    ```
    feature_weights = "Feature2:1.1,Feature4:0.1"
    ```

  {% endcut %}

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

- <!-- source: en/_includes/work_src/reusage/cli__feature-weights__arra-or-dict.md -->
  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>}
  ```
  <!-- endsource: en/_includes/work_src/reusage/cli__feature-weights__arra-or-dict.md -->

  {% cut "Array examples" %}

    ```
    feature_weights = [0.1, 1, 3]
    ```

  {% endcut %}

  {% cut "These dictionary examples" %}

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

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

  {% endcut %}

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

**Type**

- list
- numpy.ndarray
- string
- dict

**Default value**

 1 for all features

**Supported processing units**

 CPU

## first_feature_use_penalties {#first_feature_use_penalties}

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

#### Description


<!-- source: en/_includes/work_src/reusage/cli__first-feature-use-penalties__intro.md -->
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](https://catboost.ai/docs/en/concepts/algorithm-score-functions.md) section for details on applying different score penalties.

Non-negative float values are supported for each penalty.
<!-- endsource: en/_includes/work_src/reusage/cli__first-feature-use-penalties__intro.md -->

<!-- source: en/_includes/work_src/reusage-python/penalties_format.md -->
- <!-- source: en/_includes/work_src/reusage-cli/cli__first-feature-use-penalties__desc__weight-for-each-feature.md -->
  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 info %}

  Spaces between values are not allowed.

  {% endnote %}



  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.
  <!-- endsource: en/_includes/work_src/reusage-cli/cli__first-feature-use-penalties__desc__weight-for-each-feature.md -->

    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 info %}

    Spaces between values are not allowed.

    {% endnote %}

    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.

- <!-- source: en/_includes/work_src/reusage-cli/cli__ffirst-feature-use-penalties__formats__individually-for-required-features.md -->
  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 info %}

  Spaces between values are not allowed.

  {% endnote %}
  <!-- endsource: en/_includes/work_src/reusage-cli/cli__ffirst-feature-use-penalties__formats__individually-for-required-features.md -->

    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 <q>Feature2</q> and the name of the feature indexed 4 is <q>Feature4</q>.

- <!-- source: en/_includes/work_src/reusage-cli/cli__first-feature-use-penalties__arra-or-dict.md -->
  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>}
  ```
  <!-- endsource: en/_includes/work_src/reusage-cli/cli__first-feature-use-penalties__arra-or-dict.md -->

    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:

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

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

    `per_object_feature_penalties` parameter:

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

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

    are identical, given that the name of the feature indexed 2 is <q>Feature2</q> and the name of the feature indexed 4 is <q>Feature4</q>.
<!-- endsource: en/_includes/work_src/reusage-python/penalties_format.md -->

**Type**

- list
- numpy.ndarray
- string
- dict

**Default value**

 0 for all features

**Supported processing units**

 CPU

## fixed_binary_splits {#fixed_binary_splits}

Command-line: `--fixed-binary-splits`

#### Description


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_coefficient {#penalties_coefficient}

Command-line: `--penalties-coefficient`

#### Description


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_penalties {#per_object_feature_penalties}

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

#### Description


<!-- source: en/_includes/work_src/reusage/per-object-feature-penalties__intro.md -->
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](https://catboost.ai/docs/en/concepts/algorithm-score-functions.md) section for details on applying different score penalties.

Non-negative float values are supported for each penalty.
<!-- endsource: en/_includes/work_src/reusage/per-object-feature-penalties__intro.md -->

{% cut "Python package" %}

<!-- source: en/_includes/work_src/reusage-python/penalties_format.md -->
- <!-- source: en/_includes/work_src/reusage-cli/cli__first-feature-use-penalties__desc__weight-for-each-feature.md -->
  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 info %}

  Spaces between values are not allowed.

  {% endnote %}



  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.
  <!-- endsource: en/_includes/work_src/reusage-cli/cli__first-feature-use-penalties__desc__weight-for-each-feature.md -->

    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 info %}

    Spaces between values are not allowed.

    {% endnote %}

    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.

- <!-- source: en/_includes/work_src/reusage-cli/cli__ffirst-feature-use-penalties__formats__individually-for-required-features.md -->
  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 info %}

  Spaces between values are not allowed.

  {% endnote %}
  <!-- endsource: en/_includes/work_src/reusage-cli/cli__ffirst-feature-use-penalties__formats__individually-for-required-features.md -->

    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 <q>Feature2</q> and the name of the feature indexed 4 is <q>Feature4</q>.

- <!-- source: en/_includes/work_src/reusage-cli/cli__first-feature-use-penalties__arra-or-dict.md -->
  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>}
  ```
  <!-- endsource: en/_includes/work_src/reusage-cli/cli__first-feature-use-penalties__arra-or-dict.md -->

    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:

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

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

    `per_object_feature_penalties` parameter:

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

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

    are identical, given that the name of the feature indexed 2 is <q>Feature2</q> and the name of the feature indexed 4 is <q>Feature4</q>.
<!-- endsource: en/_includes/work_src/reusage-python/penalties_format.md -->

{% endcut %}

{% cut "R package" %}

<!-- source: en/_includes/work_src/reusage-r/r__penalties.md -->
- <!-- source: en/_includes/work_src/reusage-cli/cli__first-feature-use-penalties__desc__weight-for-each-feature.md -->
  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 info %}

  Spaces between values are not allowed.

  {% endnote %}



  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.
  <!-- endsource: en/_includes/work_src/reusage-cli/cli__first-feature-use-penalties__desc__weight-for-each-feature.md -->

    Penalties equal to 0 at the end of the list may be dropped.

    In this

    {% cut "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 info %}

    Spaces between values are not allowed.

    {% endnote %}

    {% endcut %}

    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.

- <!-- source: en/_includes/work_src/reusage-cli/cli__ffirst-feature-use-penalties__formats__individually-for-required-features.md -->
  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 info %}

  Spaces between values are not allowed.

  {% endnote %}
  <!-- endsource: en/_includes/work_src/reusage-cli/cli__ffirst-feature-use-penalties__formats__individually-for-required-features.md -->

    {% cut "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:

    ```no-highlight
    per_object_feature_penalties = "2:1.1,4:0.1"
    ```

    ```
    per_object_feature_penalties = "Feature2:1.1,Feature4:0.1"
    ```

    {% endcut %}

    are identical, given that the name of the feature indexed 2 is <q>Feature2</q> and the name of the feature indexed 4 is <q>Feature4</q>.
<!-- endsource: en/_includes/work_src/reusage-r/r__penalties.md -->

{% endcut %}

**Type**

- list
- numpy.ndarray
- string
- dict

**Default value**

 0 for all objects

**Supported processing units**

 CPU

## model_shrink_rate {#model_shrink_rate}

Command-line: `--model-shrink-rate`

#### Description


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-mode`for 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_mode {#model_shrink_mode}

Command-line: `model_shrink_mode`

#### Description

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-rate`for the Command-line version parameter.
    - $learning\_rate$ is the value of the `--learning-rate`for the Command-line version parameter

- Decreasing:

  $1 - \frac{model\_shrink\_rate}{i} {,}$
    - $model\_shrink\_rate$ is the value of the `--model-shrink-rate`for the Command-line version parameter.
    - $i$ is the identifier of the iteration.

**Type**

string

**Default value**

 Constant

**Supported processing units**

 CPU