---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.3
alternate:
  - https://catboost.ai/docs/en/concepts/python-reference_catboostranker.md
---
> **Documentation Index:** Fetch the complete configuration index at https://catboost.ai/docs/en/llms.txt

# CatBoostRanker

```python
class CatBoostRanker(iterations=None,
                     learning_rate=None,
                     depth=None,
                     l2_leaf_reg=None,
                     model_size_reg=None,
                     rsm=None,
                     loss_function='YetiRank',
                     border_count=None,
                     feature_border_type=None,
                     per_float_feature_quantization=None,
                     input_borders=None,
                     output_borders=None,
                     fold_permutation_block=None,
                     od_pval=None,
                     od_wait=None,
                     od_type=None,
                     nan_mode=None,
                     counter_calc_method=None,
                     leaf_estimation_iterations=None,
                     leaf_estimation_method=None,
                     thread_count=None,
                     random_seed=None,
                     use_best_model=None,
                     best_model_min_trees=None,
                     verbose=None,
                     silent=None,
                     logging_level=None,
                     metric_period=None,
                     ctr_leaf_count_limit=None,
                     store_all_simple_ctr=None,
                     max_ctr_complexity=None,
                     has_time=None,
                     allow_const_label=None,
                     target_border=None,
                     one_hot_max_size=None,
                     random_strength=None,
                     name=None,
                     ignored_features=None,
                     train_dir=None,
                     custom_metric=None,
                     eval_metric=None,
                     bagging_temperature=None,
                     save_snapshot=None,
                     snapshot_file=None,
                     snapshot_interval=None,
                     fold_len_multiplier=None,
                     used_ram_limit=None,
                     gpu_ram_part=None,
                     pinned_memory_size=None,
                     allow_writing_files=None,
                     final_ctr_computation_mode=None,
                     approx_on_full_history=None,
                     boosting_type=None,
                     simple_ctr=None,
                     combinations_ctr=None,
                     per_feature_ctr=None,
                     ctr_description=None,
                     ctr_target_border_count=None,
                     task_type=None,
                     device_config=None,
                     devices=None,
                     bootstrap_type=None,
                     subsample=None,
                     mvs_reg=None,
                     sampling_frequency=None,
                     sampling_unit=None,
                     dev_score_calc_obj_block_size=None,
                     dev_efb_max_buckets=None,
                     sparse_features_conflict_fraction=None,
                     max_depth=None,
                     n_estimators=None,
                     num_boost_round=None,
                     num_trees=None,
                     colsample_bylevel=None,
                     random_state=None,
                     reg_lambda=None,
                     objective=None,
                     eta=None,
                     max_bin=None,
                     gpu_cat_features_storage=None,
                     data_partition=None,
                     metadata=None,
                     early_stopping_rounds=None,
                     cat_features=None,
                     grow_policy=None,
                     min_data_in_leaf=None,
                     min_child_samples=None,
                     max_leaves=None,
                     num_leaves=None,
                     score_function=None,
                     leaf_estimation_backtracking=None,
                     ctr_history_unit=None,
                     monotone_constraints=None,
                     feature_weights=None,
                     penalties_coefficient=None,
                     first_feature_use_penalties=None,
                     per_object_feature_penalties=None,
                     model_shrink_rate=None,
                     model_shrink_mode=None,
                     langevin=None,
                     diffusion_temperature=None,
                     posterior_sampling=None,
                     boost_from_average=None,
                     text_features=None,
                     tokenizers=None,
                     dictionaries=None,
                     feature_calcers=None,
                     text_processing=None,
                     embedding_features=None,
                     fixed_binary_splits=None)
```

## Purpose {#purpose}

Implementation of [the scikit-learn estimator API](https://scikit-learn.org/stable/developers/develop.html) for CatBoost ranking.

Supports model training, inference and auxiliary calculations like feature importance.

## Parameters {#parameters}

<!-- source: en/_includes/work_src/reusage-python/python__parameters_metadata.md -->
### metadata

#### Description

The key-value string pairs to store in the model's metadata storage after the training.

**Default value**

None
<!-- endsource: en/_includes/work_src/reusage-python/python__parameters_metadata.md -->

<!-- source: en/_includes/work_src/reusage-python/python__parameters_cat_features.md -->
### cat_features

#### Description

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

This array can contain both indices and names for different elements.

If any features in the `cat_features` parameter are specified as names instead of indices, feature names must be provided for the training dataset. Therefore, the type of the `X` parameter in the future calls of the `fit` function must be either [catboost.Pool](https://catboost.ai/docs/en/concepts/python-reference_pool.md) with defined feature names data or pandas.DataFrame or [polars.DataFrame](https://docs.pola.rs/api/python/stable/reference/dataframe/index.html).

{% note info %}

- If this parameter is not None and the training dataset passed as the value of the X parameter to the fit function of this class has the [catboost.Pool](https://catboost.ai/docs/en/concepts/python-reference_pool.md) type, CatBoost checks the equivalence of the categorical features indices specification in this object and the one in the [catboost.Pool](https://catboost.ai/docs/en/concepts/python-reference_pool.md) object.

- If this parameter is not None, passing objects of the [catboost.FeaturesData](https://catboost.ai/docs/en/concepts/python-features-data__desc.md) type as the X parameter to the fit function of this class is prohibited.

{% endnote %}

<!-- source: en/_includes/concepts/default-value-none.md -->
**Default value**

None (all features are either considered numerical or of other types if specified precisely)
<!-- endsource: en/_includes/concepts/default-value-none.md -->
<!-- endsource: en/_includes/work_src/reusage-python/python__parameters_cat_features.md -->

<!-- source: en/_includes/work_src/reusage/see-training-params.md -->
See [Python package training parameters](https://catboost.ai/docs/en/references/training-parameters/index.md) for the full list of parameters.
<!-- endsource: en/_includes/work_src/reusage/see-training-params.md -->


<!-- source: en/_includes/work_src/reusage/python--ranker--precedence-note.md -->
{% note info %}

Some parameters duplicate the ones specified for the [fit](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_fit.md) method. In these cases the values specified for the [fit](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_fit.md) method take precedence.

{% endnote %}
<!-- endsource: en/_includes/work_src/reusage/python--ranker--precedence-note.md -->

## Attributes {#attributes}

### tree_count_

<!-- source: en/_includes/work_src/reusage-attributes/tree_count__desc.md -->
Return the number of trees in the model.

This number can differ from the value specified in the `--iterations` training parameter in the following cases:
- The training is stopped by the [overfitting detector](https://catboost.ai/docs/en/concepts/overfitting-detector.md).
- The `--use-best-model` training parameter is set to <q>True</q>.
<!-- endsource: en/_includes/work_src/reusage-attributes/tree_count__desc.md -->

### feature_importances_

<!-- source: en/_includes/work_src/reusage-attributes/feature_importances__desc.md -->
Return the calculated [feature importances](https://catboost.ai/docs/en/concepts/fstr.md). The output data depends on the type of the model's loss function:
- Non-ranking loss functions — [PredictionValuesChange](https://catboost.ai/docs/en/concepts/fstr.md#regular-feature-importance)
- Ranking loss functions — [LossFunctionChange](https://catboost.ai/docs/en/concepts/fstr.md#regular-feature-importances__lossfunctionchange)
<!-- endsource: en/_includes/work_src/reusage-attributes/feature_importances__desc.md -->


### random_seed_

<!-- source: en/_includes/work_src/reusage-attributes/random_seed__desc.md -->
The random seed used for training.
<!-- endsource: en/_includes/work_src/reusage-attributes/random_seed__desc.md -->


### learning_rate_

<!-- source: en/_includes/work_src/reusage-attributes/learning_rate__desc.md -->
The learning rate used for training.
<!-- endsource: en/_includes/work_src/reusage-attributes/learning_rate__desc.md -->

### feature_names_

<!-- source: en/_includes/work_src/reusage-attributes/feature_names__desc.md -->
The names of features in the dataset.
<!-- endsource: en/_includes/work_src/reusage-attributes/feature_names__desc.md -->

### evals_result_

<!-- source: en/_includes/work_src/reusage/python__get-evals-result__desc.md -->
Return the values of metrics calculated during the training.
<!-- endsource: en/_includes/work_src/reusage/python__get-evals-result__desc.md -->

### best_score_

<!-- source: en/_includes/work_src/reusage/python__method__get_best_score__desc.md -->
Return the best result for each metric calculated on each validation dataset.
<!-- endsource: en/_includes/work_src/reusage/python__method__get_best_score__desc.md -->

### best_iteration_

<!-- source: en/_includes/work_src/reusage/python__method__get_best_iteration__desc.md -->
Return the identifier of the iteration with the best result of the evaluation metric or loss function on the last validation set.
<!-- endsource: en/_includes/work_src/reusage/python__method__get_best_iteration__desc.md -->

## Methods {#methods}

### [fit](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_fit.md)

Train a model.

### [predict](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_predict.md)

Apply the model to the given dataset.

### [calc_leaf_indexes](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_calc_leaf_indexes.md)

<!-- source: en/_includes/concepts/python-reference_catboost_calc_leaf_indexes/calc_leaf_indexes__desc.md -->
Returns indexes of leafs to which objects from pool are mapped by model trees.
<!-- endsource: en/_includes/concepts/python-reference_catboost_calc_leaf_indexes/calc_leaf_indexes__desc.md -->

### [calc_feature_statistics](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_calc_feature_statistics.md)

<!-- source: en/_includes/work_src/reusage-python/get_feature_statistics__desc__div.md -->
Calculate and plot a set of statistics for the chosen feature.
<!-- endsource: en/_includes/work_src/reusage-python/get_feature_statistics__desc__div.md -->

### [copy](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_copy.md)

<!-- source: en/_includes/work_src/reusage/copy--purpose.md -->
Copy the CatBoost object.
<!-- endsource: en/_includes/work_src/reusage/copy--purpose.md -->

### [compare](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_modelcompare.md)

<!-- source: en/_includes/work_src/reusage-python/compare__purpose.md -->
Draw train and evaluation metrics in [Jupyter Notebook](https://catboost.ai/docs/en/features/visualization_jupyter-notebook.md) for two trained models.
<!-- endsource: en/_includes/work_src/reusage-python/compare__purpose.md -->

### [eval_metrics](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_eval-metrics.md)

<!-- source: en/_includes/work_src/reusage/python__eval-metrics__purpose.md -->
Calculate the specified metrics for the specified dataset.
<!-- endsource: en/_includes/work_src/reusage/python__eval-metrics__purpose.md -->

### [get_all_params](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_get_all_params.md)

<!-- source: en/_includes/work_src/reusage-python/python__get_all_params__desc__p.md -->
Return the values of all training parameters (including the ones that are not explicitly specified by users).
<!-- endsource: en/_includes/work_src/reusage-python/python__get_all_params__desc__p.md -->

### [get_best_iteration](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_get_best_iteration.md)

<!-- source: en/_includes/work_src/reusage/python__method__get_best_iteration__desc.md -->
Return the identifier of the iteration with the best result of the evaluation metric or loss function on the last validation set.
<!-- endsource: en/_includes/work_src/reusage/python__method__get_best_iteration__desc.md -->

### [get_best_score](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_get_best_score.md)

<!-- source: en/_includes/work_src/reusage/python__method__get_best_score__desc.md -->
Return the best result for each metric calculated on each validation dataset.
<!-- endsource: en/_includes/work_src/reusage/python__method__get_best_score__desc.md -->

### [get_borders](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_get_borders.md)

<!-- source: en/_includes/work_src/reusage-python/get_borders__desc__div.md -->
Return the list of borders for numerical features.
<!-- endsource: en/_includes/work_src/reusage-python/get_borders__desc__div.md -->

### [get_evals_result](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_get_evals_result.md)

<!-- source: en/_includes/work_src/reusage/python__get-evals-result__desc.md -->
Return the values of metrics calculated during the training.
<!-- endsource: en/_includes/work_src/reusage/python__get-evals-result__desc.md -->

### [get_feature_importance](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_get_feature_importance.md)

<!-- source: en/_includes/work_src/reusage/feature_importances--purpose.md -->
Calculate and return the [feature importances](https://catboost.ai/docs/en/concepts/fstr.md).
<!-- endsource: en/_includes/work_src/reusage/feature_importances--purpose.md -->

### [get_metadata](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_metadata.md)

Return a proxy object with metadata from the model's internal key-value string storage.

### [get_object_importance](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_get_object_importance.md)

<!-- source: en/_includes/work_src/reusage/python__get_object_importance__desc.md -->
Calculate the effect of objects from the train dataset on the optimized metric values for the objects from the input dataset:
- Positive values reflect that the optimized metric increases.
- Negative values reflect that the optimized metric decreases.
<!-- endsource: en/_includes/work_src/reusage/python__get_object_importance__desc.md -->

### [get_param](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_get_param.md)

<!-- source: en/_includes/work_src/reusage/get_param--purpose.md -->
Return the value of the given  parameter if it is explicitly by the user before starting the training. If this parameter is used with the default value, this function returns None.
<!-- endsource: en/_includes/work_src/reusage/get_param--purpose.md -->

### [get_params](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_get_params.md)

<!-- source: en/_includes/work_src/reusage/get_params--purpose.md -->
Return the values of training parameters that are explicitly specified by the user. If all parameters are used with their default values, this function returns an empty dict.
<!-- endsource: en/_includes/work_src/reusage/get_params--purpose.md -->

### [get_scale_and_bias](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_get_scale_and_bias.md)

<!-- source: en/_includes/work_src/reusage-python/get_scale_and_bias__desc.md -->
Return the scale and bias of the model.

These values affect the results of applying the model, since the model prediction results are calculated as follows:
$\sum leaf\_values \cdot scale + bias$
<!-- endsource: en/_includes/work_src/reusage-python/get_scale_and_bias__desc.md -->

### [get_test_eval](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_get_test_eval.md)

<!-- source: en/_includes/work_src/reusage/get_test_val--desc.md -->
Return the formula values that were calculated for the objects from the validation dataset provided for training.
<!-- endsource: en/_includes/work_src/reusage/get_test_val--desc.md -->

### [grid_search](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_grid_search.md)

<!-- source: en/_includes/work_src/reusage-python/python__grid_search--desc.md -->
A simple grid search over specified parameter values for a model.
<!-- endsource: en/_includes/work_src/reusage-python/python__grid_search--desc.md -->

### [is_fitted](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_is_fitted.md)

<!-- source: en/_includes/work_src/reusage/is_fitted--purpose.md -->
Check whether the model is trained.
<!-- endsource: en/_includes/work_src/reusage/is_fitted--purpose.md -->

### [load_model](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_load_model.md)

<!-- source: en/_includes/work_src/reusage/load_model--purpose.md -->
Load the model from a file.
<!-- endsource: en/_includes/work_src/reusage/load_model--purpose.md -->

### [plot_predictions](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_plot_predictions.md)

<!-- source: en/_includes/work_src/reusage-python/plot_predictions__desc__short.md -->
Sequentially vary the value of the specified features to put them into all buckets and calculate predictions for the input objects accordingly.
<!-- endsource: en/_includes/work_src/reusage-python/plot_predictions__desc__short.md -->

### [plot_tree](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_plot_tree.md)

<!-- source: en/_includes/work_src/reusage-python/python__plot-tree_desc__div.md -->
Visualize the CatBoost decision trees.
<!-- endsource: en/_includes/work_src/reusage-python/python__plot-tree_desc__div.md -->

### [randomized_search](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_randomized_search.md)

<!-- source: en/_includes/work_src/reusage-python/python__randomized_search--desc.md -->
A simple randomized search on hyperparameters.
<!-- endsource: en/_includes/work_src/reusage-python/python__randomized_search--desc.md -->

### [save_borders](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_save_borders.md)

<!-- source: en/_includes/work_src/reusage-python/save_model__div_desc.md -->
Save the model borders to a file.
<!-- endsource: en/_includes/work_src/reusage-python/save_model__div_desc.md -->

### [save_model](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_save_model.md)

<!-- source: en/_includes/work_src/reusage/save_model--purpose.md -->
Save the model to a file.
<!-- endsource: en/_includes/work_src/reusage/save_model--purpose.md -->

### [score](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_score.md)

<!-- source: en/_includes/work_src/reusage-python/scor__purpose.md -->
Calculate the R2 [metric](https://catboost.ai/docs/en/concepts/loss-functions.md) for the objects in the given dataset.
<!-- endsource: en/_includes/work_src/reusage-python/scor__purpose.md -->

### [select_features](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_select_features.md)

Select the best features from the dataset using the [Recursive Feature Elimination](https://scikit-learn.org/stable/modules/generated/sklearn.feature_selection.RFE.html) algorithm.

### [set_feature_names](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_set_feature_names.md)

<!-- source: en/_includes/work_src/reusage-python/non_pool__set_feature_names__div.md -->
Set names for all features in the model.
<!-- endsource: en/_includes/work_src/reusage-python/non_pool__set_feature_names__div.md -->

### [set_params](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_set_params.md)

<!-- source: en/_includes/work_src/reusage/set_params--purpose.md -->
Set the training parameters.
<!-- endsource: en/_includes/work_src/reusage/set_params--purpose.md -->

### [set_scale_and_bias](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_set_scale_and_bias.md)

<!-- source: en/_includes/work_src/reusage-python/set_scale_and_bias__desc.md -->
Set the scale and bias.
<!-- endsource: en/_includes/work_src/reusage-python/set_scale_and_bias__desc.md -->

### [shrink](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_shrink.md)

<!-- source: en/_includes/work_src/reusage/shrink__purpose.md -->
Shrink the model. Only trees with indices from the range `[ntree_start, ntree_end)` are kept.
<!-- endsource: en/_includes/work_src/reusage/shrink__purpose.md -->

### [staged_predict](https://catboost.ai/docs/en/concepts/python-reference_catboostranker_staged_predict.md)

<!-- source: en/_includes/work_src/reusage/staged_predict--purpose.md -->
Apply the model to the given dataset and calculate the results taking into consideration only the trees in the range [0; i).
<!-- endsource: en/_includes/work_src/reusage/staged_predict--purpose.md -->