Package 'catboostr'

Description

Get statistics for a feature using the model, dataset and target (see https://catboost.ai/docs/concepts/python-reference_catboost_calc_feature_statistics.html). The catboost model has borders for the float features used in it. The borders divide feature values into bins, and the model's prediction depends on the number of the bin where the feature value falls in.

For float features this function takes the model's borders and computes 1) Mean target value for every bin; 2) Mean model prediction for every bin; 3) The number of objects in the dataset which fall into each bin; 4) Predictions on varying feature: for every object, varies the feature value so that it falls into bin #0, bin #1, ... and counts model predictions, then averages that over each bin.

For categorical features (one-hot encoded only – pass one_hot_max_size at training time to keep a feature one-hot) does the same, but with the feature's unique values (from pool, or cat_feature_values) taking the role of bins.

Usage

catboost.calc_feature_statistics(
  model,
  pool,
  feature = NULL,
  prediction_type = NULL,
  cat_feature_values = NULL,
  thread_count = -1
)

Arguments

Value

A list (single feature) or a named list of lists (multiple features). For a float feature, the list has borders, binarized_feature, mean_target, mean_weighted_target, mean_prediction, objects_per_bin, predictions_on_varying_feature. A one-hot categorical feature has the same, but cat_values instead of borders.

See Also

https://catboost.ai/docs/concepts/python-reference_catboost_calc_feature_statistics.html

Description

R equivalent of Python's model.calc_leaf_indexes(data, ntree_start, ntree_end, thread_count, verbose) (core.py:3157-3195).

Usage

catboost.calc_leaf_indexes(
  model,
  pool,
  ntree_start = 0,
  ntree_end = 0,
  thread_count = -1,
  verbose = FALSE
)

Arguments

Value

An integer matrix of shape (number of objects in pool) x (ntree_end - ntree_start); row i is the array of leaf indexes for the i-th object.

Description

Support caret interface

Usage

catboost.caret

Description

Evaluate metrics for model and other on the same pool and return both models' per-iteration metric values for comparison.

Python's CatBoost.compare(model, data, metrics, ...) only draws an interactive Jupyter widget from this data (it returns None); there is no headless R equivalent of that widget, so catboost.compare exposes the widget's underlying metrics-diff data structure instead – what compare() computes internally via self._eval_metrics(...) and model._eval_metrics(...) on the same pool/metrics (both funnel into the same TMetricsPlotCalcer vendor entry point as catboost.eval_metrics, which this function calls once per model).

Named catboost.compare (not model.compare, and not an S3 method) because a dotted name would collide with R's existing S3 dispatch on catboost.Model (see predict.catboost.Model).

Usage

catboost.compare(
  model,
  other,
  pool,
  metrics,
  ntree_start = 0L,
  ntree_end = 0L,
  eval_period = 1,
  thread_count = -1,
  tmp_dir = NULL
)

Arguments

Value

An object of class catboost.compare (a list): model and other, each the same named-list-of-numeric-vectors (metric name -> per-iteration values) that catboost.eval_metrics returns for that model on pool.

See Also

https://catboost.ai/docs/concepts/python-reference_catboost_compare.html

Description

R equivalent of Python's catboost.utils.compute_training_options(): resolves a plain params list (the same shape catboost.train accepts) to its final, fully-resolved training options, without fitting a model. Some defaults (e.g. depth, border_count) depend on the shape of the training data, so a minimal description of that shape must be supplied via train_meta_info instead of an actual pool.

Usage

catboost.compute_training_options(
  params,
  train_meta_info,
  test_meta_info = NULL
)

Arguments

Value

A list object with the fully-resolved training options.

Description

R equivalent of Python's CatBoost.create_metric_calcer() (core.py:3354-3374): incrementally aggregate metrics across several pool chunks (e.g. a dataset too large to hold as a single Pool at once). Python's BatchMetricCalcer streams sufficient statistics natively; this R implementation instead buffers each $add()-ed catboost.Pool and, on $eval_metrics(), concatenates the raw feature/label/weight data of all buffered pools into one fresh Pool and delegates to catboost.eval_metrics – numerically identical to streaming aggregation for standard per-object metrics (they are sums/ means over all objects regardless of how those objects were chunked), but does not preserve group_id/pairs across chunks: passing several chunks of a grouped/ranking pool will not reproduce Python's per-group behavior. Add the whole pool in one $add() call for grouped/ranking metrics.

Usage

catboost.create_metric_calcer(
  model,
  metrics,
  ntree_start = 0,
  ntree_end = 0,
  eval_period = 1,
  thread_count = -1,
  tmp_dir = NULL
)

Arguments

Value

A catboost.BatchMetricCalcer object with $add(pool) and $eval_metrics() methods.

Description

Estimate model performance using cross-validation.

Usage

catboost.cv(
  pool,
  params = list(),
  fold_count = 3,
  type = "Classical",
  partition_random_seed = 0,
  shuffle = TRUE,
  stratified = FALSE,
  early_stopping_rounds = NULL,
  custom_objective = NULL,
  custom_eval_metric_object = NULL
)

Arguments

Value

A data.frame of evaluation results from cross-validation.

Description

R equivalent of CatBoost CLI's dataset-statistics mode: computes per-feature statistics (and, unless only_light_statistics is set, per-float-feature histograms) for a dataset read from disk. Calls the same core library entry point the CLI mode itself calls (catboost/private/libs/app_helpers/mode_dataset_statistics_helpers.h's NCB::CalculateDatasetStatisticsSingleHost) directly, in-process – no CLI binary shell-out.

Usage

catboost.dataset_statistics(
  pool_path,
  cd_path = "",
  pairs_path = "",
  delimiter = "\t",
  has_header = FALSE,
  thread_count = -1,
  border_count = 254,
  only_group_statistics = FALSE,
  only_light_statistics = FALSE,
  not_convert_string_targets = TRUE,
  custom_feature_limits = "",
  spot_size = 0,
  spot_count = 0
)

Arguments

Value

A named list with elements statistics and histograms (each the parsed contents of the corresponding CLI JSON output file; histograms is NULL if only_light_statistics was set).

Description

Builds a token/id vocabulary from text data. Native bridge to Python's catboost.text_processing.Dictionary, backed directly by vendor's NTextProcessing::NDictionary::TDictionary/ TDictionaryBuilder/TBpeDictionary/TBpeDictionaryBuilder. Use catboost.dictionary.fit to train it and catboost.dictionary.apply to convert text to token ids.

Usage

catboost.Dictionary(
  token_level_type = NULL,
  gram_order = NULL,
  start_token_id = NULL,
  end_of_word_policy = NULL,
  end_of_sentence_policy = NULL,
  occurence_lower_bound = NULL,
  max_dictionary_size = NULL,
  dictionary_type = NULL,
  num_bpe_units = NULL,
  skip_unknown = NULL,
  skip_step = NULL
)

Arguments

Value

A mutable catboost.Dictionary object (fit/load update it in place).

Description

Converts data into token ids.

Usage

catboost.dictionary.apply(
  dictionary,
  data,
  tokenizer = NULL,
  unknown_token_policy = NULL
)

Arguments

Value

An integer vector of token ids if data is a single string, otherwise a list of integer vectors (one per document).

Description

Identifier of the end-of-sentence token

Usage

catboost.dictionary.end_of_sentence_token_id(dictionary)

Arguments

Value

An integer id.

Description

Builds the token/id vocabulary from data.

Usage

catboost.dictionary.fit(dictionary, data, tokenizer = NULL, verbose = FALSE)

Arguments

Value

The (mutated) catboost.Dictionary, invisibly.

Description

Get a single token by id

Usage

catboost.dictionary.get_token(dictionary, token_id)

Arguments

Value

A character string.

Description

Get tokens by id

Usage

catboost.dictionary.get_tokens(dictionary, token_ids)

Arguments

Value

A character vector of tokens.

Description

Most frequent tokens

Usage

catboost.dictionary.get_top_tokens(dictionary, top_size = NULL)

Arguments

Value

A character vector of the most frequent tokens, most frequent first.

Description

Reads a dictionary file written by catboost.dictionary.save or Python's Dictionary.save.

Usage

catboost.dictionary.load(dictionary, frequency_dict_path, bpe_path = NULL)

Arguments

Value

The (mutated) catboost.Dictionary, invisibly.

Description

Smallest unused token identifier

Usage

catboost.dictionary.min_unused_token_id(dictionary)

Arguments

Value

An integer id.

Description

Writes the vendor "id_count_token" text format (a JSON options header line, a token-count line, then one "id\tcount\ttoken" line per token) for "FrequencyBased" dictionaries – byte-identical to the pinned Python oracle's Dictionary.save because both call the same vendor TDictionary::Save. "Bpe" dictionaries additionally require bpe_path and are written via vendor's TBpeDictionary::Save.

Usage

catboost.dictionary.save(dictionary, frequency_dict_path, bpe_path = NULL)

Arguments

Value

The catboost.Dictionary, invisibly.

Description

Dictionary size

Usage

catboost.dictionary.size(dictionary)

Arguments

Value

An integer.

Description

Identifier of the unknown-token placeholder

Usage

catboost.dictionary.unknown_token_id(dictionary)

Arguments

Value

An integer id.

Description

Drop unused features information from model

Usage

catboost.drop_unused_features(model)

Arguments

Value

Status, the result of dropping feature. TRUE if this succeeded, FALSE otherwise.

Description

R equivalent of the CatBoost CLI's eval-feature mode: repeated cross-validated training that measures how much each tested set of features changes the loss, and reports a Wilcoxon test p-value per set.

This calls the same core entry point the CLI mode calls (EvaluateFeatures, catboost/libs/train_lib/eval_feature.h), in process – no CLI binary is required. There is no Python-side counterpart of this mode; CatBoost.select_features is a different algorithm.

Usage

catboost.eval_feature(
  pool,
  features_to_evaluate = list(),
  params = list(),
  eval_mode = "OneVsNone",
  offset = 0,
  fold_count = 3,
  fold_size_unit = "Object",
  fold_size = 0,
  relative_fold_size = 0,
  timesplit_quantile = 0.5,
  custom_objective = NULL,
  custom_eval_metric_object = NULL
)

Arguments

Value

A list with one entry per tested feature set, mirroring the columns of the CLI's --feature-eval-output-file TSV but at full double precision:

• p_value – numeric, Wilcoxon test p-value per feature set.

• best_iterations – list of integer vectors, best baseline iteration per fold.

• metric_names – character vector of evaluated metric names.

• metric_delta – numeric matrix, feature sets by metrics; average metric change, signed so that positive always means improvement.

• feature_sets – list of integer vectors, the evaluated sets echoed back.

Description

R equivalent of Python's catboost.utils.eval_metric() (utils.py:271): evaluates a single named metric directly on raw label and approx (prediction) arrays, needing neither a fitted model nor a catboost.Pool – unlike catboost.eval_metrics, which requires both.

Usage

catboost.eval_metric(
  label,
  approx,
  metric,
  weight = NULL,
  group_id = NULL,
  group_weight = NULL,
  subgroup_id = NULL,
  pairs = NULL,
  thread_count = -1
)

Arguments

Value

A numeric vector with the metric's value(s).

Description

Calculate the specified metrics for the specified dataset.

Usage

catboost.eval_metrics(
  model,
  pool,
  metrics,
  ntree_start = 0L,
  ntree_end = 0L,
  eval_period = 1,
  thread_count = -1,
  tmp_dir = NULL
)

Arguments

Value

dict: metric -> array of shape [(ntree_end - ntree_start) / eval_period].

See Also

https://catboost.ai/docs/concepts/python-reference_catboost_eval-metrics.html

Description

Get the number of categorical features in a catboost.FeaturesData.

Usage

catboost.features_data.get_cat_feature_count(features_data)

Arguments

Value

The number of categorical features.

Description

Get the total number of features (numerical + categorical) in a catboost.FeaturesData.

Usage

catboost.features_data.get_feature_count(features_data)

Arguments

Value

The total number of features.

Description

Get the names of the features of a catboost.FeaturesData: numerical feature names followed by categorical feature names. Unnamed features are empty strings.

Usage

catboost.features_data.get_feature_names(features_data)

Arguments

Value

A character vector of feature names, length equal to catboost.features_data.get_feature_count(features_data).

Description

Get the number of numerical features in a catboost.FeaturesData.

Usage

catboost.features_data.get_num_feature_count(features_data)

Arguments

Value

The number of numerical features.

Description

Get the number of objects (rows) in a catboost.FeaturesData.

Usage

catboost.features_data.get_object_count(features_data)

Arguments

Value

The number of objects.

Description

Store features data in a form that can be passed directly to catboost.load_pool/catboost.from_matrix as the data/ float_and_cat_features_data argument, as an alternative to a plain matrix or data.frame. Numerical features are given as a numeric matrix, categorical features are given separately as a character matrix, each with optional column names.

Usage

catboost.FeaturesData(
  num_feature_data = NULL,
  cat_feature_data = NULL,
  num_feature_names = NULL,
  cat_feature_names = NULL
)

Arguments

Value

catboost.FeaturesData

Description

Return the 0-based iteration index of the best model seen during training, as determined by early stopping / use_best_model against the (last) eval set, or NULL if the model was fitted without an eval set (or has no recorded training history). R equivalent of Python's model.get_best_iteration()/model.best_iteration_.

Usage

catboost.get_best_iteration(model)

Arguments

Value

A single integer, or NULL.

Description

Return the best metric value(s) seen during training for the learn set and each eval set. R equivalent of Python's model.get_best_score()/model.best_score_.

Usage

catboost.get_best_score(model)

Arguments

Value

A named list, one element per dataset (learn, plus validation if there is exactly one eval set, or validation_0, validation_1, ... if there are several), each itself a named list of metric name to best value. Empty list if the model has no recorded training history.

Description

R equivalent of Python's model.get_borders() (core.py:3822-3827, defined once on the CatBoost base class and inherited unchanged by CatBoostClassifier/CatBoostRegressor/ CatBoostRanker): returns the quantization borders the model's float features were split on during training.

Usage

catboost.get_borders(model)

Arguments

Value

A named list keyed by flat feature index (as a string); each element is the numeric vector of that feature's borders (empty for a feature the model does not use as a float feature).

Description

Return the full per-iteration metric history recorded during training for the learn set and each eval set. R equivalent of Python's model.get_evals_result()/model.evals_result_.

Usage

catboost.get_evals_result(model)

Arguments

Value

A named list, one element per dataset (learn, plus validation if there is exactly one eval set, or validation_0, validation_1, ... if there are several), each itself a named list of metric name to a numeric vector (one value per iteration where the metric was recorded – shorter than the total iteration count when metric_period > 1). Empty list if the model has no recorded training history.

Description

Calculate the feature importances (see https://catboost.ai/docs/concepts/fstr.html#fstr) (Regular feature importance, ShapValues, and Feature interaction strength).

Usage

catboost.get_feature_importance(
  model,
  pool = NULL,
  type = "FeatureImportance",
  thread_count = -1,
  fstr_type = NULL
)

Arguments

Value

Feature importances

See Also

https://catboost.ai/docs/features/feature-importances-calculation.html

Description

R equivalent of Python's model.get_leaf_values() (core.py:2121-2129, defined once on _CatBoostBase and inherited unchanged by CatBoost/CatBoostClassifier/ CatBoostRegressor/CatBoostRanker).

Usage

catboost.get_leaf_values(model)

Arguments

Value

A numeric vector of leaf values for all trees, of length sum(catboost.get_tree_leaf_counts(model)) * ApproxDimension (ApproxDimension is 1 except for multiclass/multi-dimensional losses, e.g. MultiClass). Each leaf occupies ApproxDimension consecutive entries: the value for dimension k (0-based) of the j-th leaf (0-based) of the i-th tree (0-based) is at position (sum(catboost.get_tree_leaf_counts(model)[seq_len(i)]) + j) * ApproxDimension + k + 1 (1-based R indexing).

Description

R equivalent of Python's model.get_leaf_weights() (core.py:2131-2139, defined once on _CatBoostBase and inherited unchanged by CatBoost/CatBoostClassifier/ CatBoostRegressor/CatBoostRanker).

Usage

catboost.get_leaf_weights(model)

Arguments

Value

A numeric vector of leaf weights for all trees, of length sum(catboost.get_tree_leaf_counts(model)) – one weight per leaf (unlike catboost.get_leaf_values, this is never multiplied by ApproxDimension: a leaf has one weight regardless of how many value dimensions it stores).

Description

Return all key/value string metadata pairs stored in the model (training params, custom user data, etc). R equivalent of Python's model.get_metadata() (returned as a plain named character vector rather than a dict-like proxy) and of the CLI's metadata dump mode. To read a single key, index the result: catboost.get_metadata(model)[["my_key"]] errors on a missing key (matching Python's KeyError for metadata["my_key"]), while catboost.get_metadata(model)["my_key"] returns NA (matching metadata.get("my_key")).

Usage

catboost.get_metadata(model)

Arguments

Value

A named character vector of all metadata key/value pairs.

Description

Return the names of the features used by the model (falling back to their string indices for features that have no name). R equivalent of Python's model.feature_names_ property and of the CLI's metadata dump-feature-names mode.

Usage

catboost.get_model_feature_names(model)

Arguments

Value

A character vector of feature names, ordered as in the model.

Description

Return the model parameters.

Usage

catboost.get_model_params(model)

Arguments

Value

A list object with model parameters.

See Also

https://catboost.ai/docs/concepts/r-reference_catboost-get_model_params.html

Description

Calculate the object importances (see https://catboost.ai/docs/concepts/ostr.html). This is the implementation of the LeafInfluence algorithm from the following paper: https://arxiv.org/pdf/1802.06640.pdf

Usage

catboost.get_object_importance(
  model,
  pool,
  train_pool,
  top_size = -1,
  type = "Average",
  update_method = "SinglePoint",
  thread_count = -1,
  ostr_type = NULL
)

Arguments

Value

List with elements "indices" and "scores".

See Also

https://catboost.ai/docs/concepts/r-reference_catboost-get_object_importance.html

Description

Return the plain model parameters.

Usage

catboost.get_plain_params(model)

Arguments

Value

A list object with model parameters.

Description

Get the threshold used for class separation in a binary classification model, R equivalent of Python's CatBoostClassifier.get_probability_threshold() (core.py:5909-5914). Backed by the same model metadata key (binclass_probability_threshold) catboost.get_metadata/ catboost.set_metadata expose; defaults to 0.5 (DEFAULT_BINCLASS_PROBABILITY_THRESHOLD, model.h:74) when the key has never been set.

Usage

catboost.get_probability_threshold(model)

Arguments

Value

A single numeric value in [0, 1].

Description

Build the points of the ROC curve for a binary classification model, matching Python's catboost.utils.get_roc_curve and the CLI's roc mode. Ports the same engine both wrap (catboost/private/libs/algo/roc_curve.cpp TRocCurve): raw model predictions are converted to probabilities, sorted in descending order, and swept once to accumulate false positive / false negative rates, inserting a synthetic point wherever the FPR and FNR curves cross.

Usage

catboost.get_roc_curve(model, pool, label_border = 0.5)

Arguments

Value

A list with three numeric vectors of equal length, sorted by decreasing threshold: fpr (false positive rate), tpr (true positive rate), and threshold (probability decision boundary, in [0, 1]).

See Also

https://catboost.ai/docs/concepts/python-reference_utils_get_roc_curve.html

Description

Return the model's scale and bias, used to compute the final formula as Scale * sumTrees + Bias. R equivalent of Python's model.get_scale_and_bias() and of the CLI's normalize-model --print-scale-and-bias mode.

Usage

catboost.get_scale_and_bias(model)

Arguments

Value

A list with scale (a single number) and bias (a numeric vector, one value per model output dimension; empty for the zero-bias default).

Description

R equivalent of Python's CatBoost.get_test_eval() (core.py:1830-1840): returns the trained model's raw (RawFormulaVal) predictions on an evaluation set. Python caches these values in-process at training time (self._object.__test_evals, populated by TrainModel()'s TEvalResult output argument); R's catboost.Model object does not retain a reference to the test_pool a model was trained with, so this function takes the eval pool explicitly and recomputes the identical values via catboost.predict(model, eval_pool, prediction_type = "RawFormulaVal") – mathematically the same quantity Python's cached TEvalResult holds, since both are the deterministic output of applying the same fully-trained trees to the same eval set.

Usage

catboost.get_test_eval(model, eval_pool)

Arguments

Value

A vector (single-dimension models) or matrix (multiclass models) of raw predictions, one row per object in eval_pool.

Description

R equivalent of Python's CatBoost.get_test_evals() (core.py:1842-1850). Python supports fitting against a list of several eval sets, so get_test_evals() returns one entry per set; catboost.train only accepts a single test_pool, so this always returns a length-1 list wrapping catboost.get_test_eval's result.

Usage

catboost.get_test_evals(model, eval_pool)

Arguments

Value

A length-1 list containing the same result catboost.get_test_eval would return.

Description

R equivalent of Python's model.get_tree_leaf_counts() (core.py:2112-2119, defined once on _CatBoostBase and inherited unchanged by CatBoost/CatBoostClassifier/ CatBoostRegressor/CatBoostRanker).

Usage

catboost.get_tree_leaf_counts(model)

Arguments

Value

An integer vector of size catboost.ntrees(model); element i is the number of leaves in the i-th tree (1-based R indexing).

Description

R equivalent of Python's CatBoost.grid_search: calls the same native search entry point (NCB::GridSearch, vendored at catboost/private/libs/hyperparameter_tuning/hyperparameter_tuning.h) that Python's CatBoost._tune_hyperparams calls via its Cython wrapper, rather than approximating the search with an R-side loop over catboost.cv – the grid/quantization-parameter enumeration order and train/test-split reuse live entirely in that native code, so calling it directly is what makes best-params/best-score match the Python oracle.

Usage

catboost.grid_search(
  param_grid,
  pool,
  params = list(),
  cv = 3,
  partition_random_seed = 0,
  calc_cv_statistics = TRUE,
  search_by_train_test_split = TRUE,
  refit = TRUE,
  shuffle = TRUE,
  stratified = FALSE,
  train_size = 0.8,
  verbose = TRUE,
  custom_objective = NULL,
  custom_eval_metric_object = NULL
)

Arguments

Value

A list with $params (best found parameters, as a named list), $cv_results (a data.frame of cross-validation results with the same columns catboost.cv returns), and, if refit = TRUE, $model (a catboost.Model fit with the best parameters).

Examples

# (c) refit = TRUE correctly reuses the supplied custom_objective for the
# final refit, not just for the search itself.
## Not run: 
n <- 50
features <- data.frame(x1 = rnorm(n), x2 = rnorm(n))
label <- with(features, x1 - x2 + rnorm(n, sd = 0.3))
pool <- catboost.load_pool(features, label = label)
rmse_custom_objective <- list(
    calc_ders_range = function(approx, target, weight) {
        w <- if (is.null(weight)) 1 else weight
        cbind(w * (target - approx), w * (-1))
    })
result <- catboost.grid_search(
    list(depth = c(3, 4)), pool,
    params = list(iterations = 10, logging_level = "Silent",
                  eval_metric = "RMSE", boost_from_average = FALSE),
    cv = 3, refit = TRUE, verbose = FALSE,
    custom_objective = rmse_custom_objective)
# result$model was refit with rmse_custom_objective, not a built-in loss.

## End(Not run)

Description

R equivalent of Python's model.iterate_leaf_indexes(data, ntree_start, ntree_end) (core.py:3132-3155). Python streams results one object at a time via _leaf_indexes_iterator purely to bound memory for very large pools; the underlying leaf-index computation is identical to catboost.calc_leaf_indexes (same CalcLeafIndexesMulti native call). R has no lazy generator protocol in the base language, so this is a thin wrapper that computes the full result via catboost.calc_leaf_indexes and splits it into one list element per object – identical numeric output, not an approximation.

Usage

catboost.iterate_leaf_indexes(model, pool, ntree_start = 0, ntree_end = 0)

Arguments

Value

A list with one element per object in pool; each element is an integer vector of leaf indexes for that object.

Description

Load the model from a file.

Note: Feature importance (see https://catboost.ai/docs/concepts/fstr.html#fstr) is not saved when using this function.

Usage

catboost.load_model(model_path, file_format = "cbm")

Arguments

Value

A model object.

See Also

https://catboost.ai/docs/concepts/r-reference_catboost-load_model.html

Description

Create a dataset from the given file, matrix or data.frame.

Usage

catboost.load_pool(
  data,
  label = NULL,
  cat_features = NULL,
  column_description = NULL,
  pairs = NULL,
  delimiter = "\t",
  has_header = FALSE,
  weight = NULL,
  group_id = NULL,
  group_weight = NULL,
  subgroup_id = NULL,
  pairs_weight = NULL,
  baseline = NULL,
  feature_names = NULL,
  thread_count = -1,
  graph = NULL,
  embedding_features = NULL,
  timestamp = NULL,
  feature_tags = NULL
)

Arguments

Value

catboost.Pool

Examples

## Not run: 
# From file
pool_path <- system.file("extdata", "adult_train.1000", package = "catboostr")
cd_path <- system.file("extdata", "adult.cd", package = "catboostr")
pool <- catboost.load_pool(pool_path, column_description = cd_path)
print(pool)

# From matrix
target <- 1
data_matrix <-matrix(runif(18), 6, 3)
pool <- catboost.load_pool(data_matrix[, -target], label = data_matrix[, target])
print(pool)

# From data.frame
nonsense <- factor(c('A', 'B', 'C'))
data_frame <- data.frame(value = runif(10), category = nonsense[(1:10) %% 3 + 1])
label = (1:10) %% 2
pool <- catboost.load_pool(data_frame, label = label)
print(pool)

## End(Not run)

Description

R equivalent of the CatBoost CLI's model-based-eval mode: continue a pre-trained baseline model's training in repeated short experiments, with and without the tested feature sets, and write the resulting per-experiment error logs into train_dir.

This calls the same core entry point the CLI mode calls (ModelBasedEval, catboost/libs/train_lib/train_model.h), in process – no CLI binary is required. There is no Python-side counterpart of this mode.

This mode is GPU-only. CatBoost's CPU trainer refuses it outright ("Model based eval is not implemented for CPU"), and the mode's options are only recognised when task_type = "GPU". On a build or machine without a working CUDA device the call fails with a specific error rather than falling back to CPU.

Unlike catboost.eval_feature this function takes dataset file paths rather than a catboost.Pool: the only public core entry point for this mode is file-driven, it reads the baseline model's training snapshot from disk, and it writes its results to disk.

Usage

catboost.model_based_eval(
  learn_set,
  test_set,
  features_to_evaluate,
  baseline_model_snapshot = "baseline_model_snapshot",
  column_description = NULL,
  params = list(task_type = "GPU"),
  offset = 1000,
  experiment_count = 200,
  experiment_size = 5,
  use_evaluated_features_in_baseline_model = FALSE,
  delimiter = "\t",
  has_header = FALSE
)

Arguments

Value

The train_dir the per-experiment error logs were written to, invisibly.

See Also

catboost.eval_feature for the CPU-capable eval-feature mode.

Description

CLI-only capability: R equivalent of the CLI's normalize-model --input-path/-i mode (mode_normalize_model.cpp), which has no Python get_scale_and_bias/set_scale_and_bias counterpart. Resets the model to identity scale/bias, computes the min and max of its raw (RawFormulaVal) predictions over pool, then sets scale = 1 / (max - min), bias = -scale * min so the rescaled raw predictions span exactly [0, 1] – mirroring mode_normalize_model.cpp's CalcMinMaxOnAllPools + model.SetScaleAndBias({scale, {bias}}) in-place.

Usage

catboost.normalize_model_from_pool(model, pool)

Arguments

Value

No return value, called for side effects.

Description

R equivalent of Python's CatBoost.plot_partial_dependence() (core.py:3947-4020), minus the optional plotly figure. Computes, per bucket of the given float feature(s), the model's mean prediction over pool when that feature is perturbed to a representative value of the bucket – the standard partial-dependence definition, and mathematically identical to CatBoost's native tree-traversal implementation (GetPartialDependence(), catboost/libs/fstr/partial_dependence.cpp) for CPU (oblivious-tree) models: since every float-feature split is at one of that feature's borders, the prediction is constant within a bucket, so averaging predictions at any one representative point per bucket equals the true expectation the native algorithm computes via leaf-weight redistribution.

Usage

catboost.plot_partial_dependence(
  model,
  pool,
  features,
  prediction_type = "RawFormulaVal",
  ntree_start = 0,
  ntree_end = 0,
  thread_count = -1
)

Arguments

Value

If one feature was given: a numeric vector, one value per bucket. If two features were given: a numeric matrix, rows indexed by the first feature's buckets and columns by the second's.

Description

R equivalent of Python's CatBoost.plot_predictions() (core.py:3847-3945), minus the optional plotly figure: for each object in pool and each feature in features_to_change, the feature's value is perturbed across every bucket of the model's float- feature borders (catboost.predict is then called on the perturbed data) and the resulting predictions are returned as the primary, required contract of this function – core.py:3847-4020's own evidence (see this ticket) established these are real numeric prediction arrays, not plotting-only output.

Usage

catboost.plot_predictions(
  model,
  pool,
  features_to_change,
  prediction_type = "RawFormulaVal",
  ntree_start = 0,
  ntree_end = 0,
  thread_count = -1
)

Arguments

Value

A list with one entry per object in pool; each entry is a named list keyed by the (string) 0-based feature index, holding the vector (or matrix, for multi-dimensional prediction_types) of predictions across that feature's buckets.

Description

Return the node/edge structure of one tree in model (see https://catboost.ai/docs/concepts/python-reference_catboost_plot_tree.html).

Python's plot_tree returns a graphviz.Digraph built from the model's internal per-tree splits and leaf values (_get_tree_splits/_get_tree_leaf_values in catboost/python-package/catboost/core.py, reading the same vendor TFullModel tree layout that catboost.save_model's "json" export format serializes). catboost.plot_tree reuses that existing JSON export (no new native entry point) to read the same split/leaf data and reconstructs the DOT-text graph with base R string building – no DiagrammeR/graphviz R package dependency is added, since none is required for either the structural differential test (spec Sec 4.3's "Structural" row targets canonical node/edge JSON, not a rendered image) or the "object of the expected class" smoke test.

Only oblivious (symmetric) trees with FloatFeature/OneHotFeature splits are supported; other tree/split kinds stop with an explicit error rather than silently mis-rendering.

Usage

catboost.plot_tree(model, tree_idx, pool = NULL)

Arguments

Value

An object of class catboost.plot_tree: a list with dot (character scalar, DOT-language source text), nodes (data.frame: id, label, color, shape) and edges (data.frame: from, to, label).

See Also

https://catboost.ai/docs/concepts/python-reference_catboost_plot_tree.html

Description

Get the baseline data of a Pool.

Usage

catboost.pool.get_baseline(pool)

Arguments

Value

A (rows x baseline_count) numeric matrix. baseline_count is 0 if the Pool has no baseline data.

Description

Get the (0-based) column indices of the categorical features of a Pool.

Usage

catboost.pool.get_cat_feature_indices(pool)

Arguments

Value

An integer vector of 0-based categorical feature indices.

Description

Get the (0-based) column indices of the embedding features of a Pool. Always integer(0): this package does not support building Pools with embedding features.

Usage

catboost.pool.get_embedding_feature_indices(pool)

Arguments

Value

An integer vector of 0-based embedding feature indices.

Description

Get the names of the features (columns) of a Pool.

Usage

catboost.pool.get_feature_names(pool)

Arguments

Value

A character vector of feature names, length equal to catboost.pool.num_col(pool). Unnamed features are empty strings.

Description

Get the raw numeric feature matrix of a Pool. Only supported for Pools whose features are all numeric (no categorical or text features).

Usage

catboost.pool.get_features(pool)

Arguments

Value

A (rows x columns) numeric matrix of feature values.

Description

Get the hashes generated from a Pool's group ids.

Usage

catboost.pool.get_group_id_hash(pool)

Arguments

Value

A character vector of decimal-formatted 64-bit hash values (one per object), or NULL if the Pool has no group ids. Returned as character rather than numeric because R's double cannot represent the full 64-bit hash range exactly.

Description

Get the label (target) data of a Pool.

Usage

catboost.pool.get_label(pool)

Arguments

Value

A vector of labels if the target is one-dimensional, a (rows x targets) matrix otherwise. numeric(0) if the Pool has no label data.

Description

Get the (0-based) column indices of the text features of a Pool.

Usage

catboost.pool.get_text_feature_indices(pool)

Arguments

Value

An integer vector of 0-based text feature indices.

Description

Get the per-object weight of a Pool. Objects with no weight set default to weight 1.

Usage

catboost.pool.get_weight(pool)

Arguments

Value

A numeric vector of per-object weights.

Description

Check whether the Pool has label (target) data.

Usage

catboost.pool.has_label(pool)

Arguments

Value

TRUE if the Pool has label data, FALSE otherwise.

Description

Check whether the Pool has no objects.

Usage

catboost.pool.is_empty(pool)

Arguments

Value

TRUE if the Pool has zero rows, FALSE otherwise.

Description

Check whether the Pool's feature data has already been quantized (either by catboost.pool.quantize or as a side effect of catboost.train).

Usage

catboost.pool.is_quantized(pool)

Arguments

Value

TRUE if the Pool is quantized, FALSE otherwise.

Description

Get the number of features (columns) in a Pool.

Usage

catboost.pool.num_col(pool)

Arguments

Value

The number of feature columns.

Description

Get the number of pairs in a Pool.

Usage

catboost.pool.num_pairs(pool)

Arguments

Value

An integer, the number of pairs.

Description

Get the number of objects (rows) in a Pool.

Usage

catboost.pool.num_row(pool)

Arguments

Value

The number of rows.

Description

Quantize this Pool in place: build the binarized (quantized) feature data used by training, same as Python's Pool.quantize() (catboost/libs/data/quantization.h's ConstructQuantizedPoolFromRawPool, the same core entry point catboost.train itself uses).

Usage

catboost.pool.quantize(pool, params = list())

Arguments

Value

Nothing. The Pool is quantized in place.

Description

R equivalent of Python's Pool.save(): saves an already-quantized Pool to CatBoost's own binary quantized-pool format (catboost/private/libs/quantized_pool/serialization.h's SaveQuantizedPool, the same core entry point Python's Pool.save()/_save() calls). This is a different, binary format from catboost.save_pool (R/catboost.R), which writes CD/TSV files read back by catboost.load_pool's column_description path – catboost.save_pool does NOT already satisfy Python's Pool.save().

Usage

catboost.pool.save(pool, fname)

Arguments

Value

Nothing. Writes fname as a side effect.

Description

Save the borders used in numeric feature quantization to a file, so they can be reused to quantize another Pool identically (via upstream's input_borders mechanism). File format is described at https://catboost.ai/docs/concepts/input-data_custom-borders.html.

Usage

catboost.pool.save_quantization_borders(pool, output_file)

Arguments

Value

Nothing. Writes output_file as a side effect.

Description

Set the baseline data of a Pool.

Usage

catboost.pool.set_baseline(pool, baseline)

Arguments

Value

Nothing. Mutates pool in place.

Description

Set the names of the features (columns) of a Pool.

Usage

catboost.pool.set_feature_names(pool, feature_names)

Arguments

Value

Nothing. Mutates pool in place.

Description

Set the group ids of a Pool. Each id is hashed the same way Python's Pool.set_group_id hashes it, so the resulting group id hashes (see catboost.pool.get_group_id_hash) match the Python oracle for the same input values.

Usage

catboost.pool.set_group_id(pool, group_id)

Arguments

Value

Nothing. Mutates pool in place.

Description

Set the per-object group weight of a Pool (weights must be equal within each group).

Usage

catboost.pool.set_group_weight(pool, group_weight)

Arguments

Value

Nothing. Mutates pool in place.

Description

Set the pairwise comparison data of a Pool.

Usage

catboost.pool.set_pairs(pool, pairs)

Arguments

Value

Nothing. Mutates pool in place.

Description

Set the per-pair weight of a Pool's existing pairs, keeping the (winner_id, loser_id) ids unchanged.

Usage

catboost.pool.set_pairs_weight(pool, pairs_weight)

Arguments

Value

Nothing. Mutates pool in place.

Description

Set the subgroup ids of a Pool. Each id is hashed the same way Python's Pool.set_subgroup_id hashes it.

Usage

catboost.pool.set_subgroup_id(pool, subgroup_id)

Arguments

Value

Nothing. Mutates pool in place.

Description

Set the per-object timestamp of a Pool.

Usage

catboost.pool.set_timestamp(pool, timestamp)

Arguments

Value

Nothing. Mutates pool in place.

Description

Set the per-object weight of a Pool.

Usage

catboost.pool.set_weight(pool, weight)

Arguments

Value

Nothing. Mutates pool in place.

Description

Get the (rows, columns) shape of a Pool.

Usage

catboost.pool.shape(pool)

Arguments

Value

An integer vector of length 2: c(num_row, num_col).

Description

Return a new Pool containing a contiguous range of rows from pool: R equivalent of Python's Pool.slice(). Like Python's Pool.slice() (which calls _take_slice() in catboost/python-package/catboost/_catboost.pyx), this builds the new Pool with the core TDataProvider::GetSubset machinery via CatBoostPoolSliceSubset_R (src/catboostr.cpp), so all column kinds – numeric, categorical, text and embedding features, every target column, weights, group ids, subgroup ids, baseline, pairs and feature names – are preserved in the sliced Pool.

The only difference from Python is the row selector: Python accepts an arbitrary row-index array (rindex), whereas this exposes a contiguous [offset, offset + size) range.

Usage

catboost.pool.slice(pool, offset, size)

Arguments

Value

A new catboost.Pool object containing the sliced rows.

Description

R equivalent of Python's Pool.train_eval_split(): splits pool into a train and (optionally) an eval Pool, with the same shuffle-then-split(-then-stratify) semantics as the Python method. Python's own implementation (TrainEvalSplit() in catboost/python-package/catboost/helpers.cpp) lives in the python-package tree (not a core lib) and includes Python.h, so it is not directly callable from R; CatBoostPoolTrainEvalSplit_R (src/catboostr.cpp) reimplements its body against the same core entry points it itself calls.

Usage

catboost.pool.train_eval_split(
  pool,
  has_time = FALSE,
  is_classification = FALSE,
  eval_fraction = 0.2,
  save_eval_pool = TRUE
)

Arguments

Value

A named list with elements train and eval (each a catboost.Pool, or NULL for eval if save_eval_pool is FALSE).

Description

Get predictions from a CatBoost model on new data.

In case of multiclassification the prediction is returned in the form of a matrix. Each row of this matrix contains the predictions for one row of the input dataset.

Usage

## S3 method for class 'catboost.Model'
predict(
  object,
  newdata,
  verbose = FALSE,
  prediction_type = "RawFormulaVal",
  ntree_start = 0,
  ntree_end = 0,
  thread_count = -1
)

catboost.predict(
  model,
  pool,
  verbose = FALSE,
  prediction_type = "RawFormulaVal",
  ntree_start = 0,
  ntree_end = 0,
  thread_count = -1
)

Arguments

Details

The function 'catboost.predict' is a synonym for 'predict.catboost.Model', which is an S3 method (i.e. called like 'predict(model, newdata)').

Value

Vector of predictions (matrix for multi-class classification).

See Also

https://catboost.ai/docs/concepts/r-reference_catboost-predict.html

Description

Predict class log-probabilities, R equivalent of Python's CatBoostClassifier.predict_log_proba() (core.py:5655-5697). A thin wrapper over catboost.predict with prediction_type = "Probability" followed by log() – exactly Python's own implementation (self._predict(data, 'LogProbability', ...) resolves, for a binary classifier, to log() of the same two-column [P(class 0), P(class 1)] representation predict_proba() returns), not a separately re-derived computation.

R's catboost.predict(..., prediction_type = "Probability") collapses the binary case to a single P(class 1) column (see catboost.predict), so for a binary model this function reconstructs the two-column [log(1 - p), log(p)] matrix Python always returns; for a multiclass model catboost.predict() already returns the full probability matrix and log() is applied directly.

Usage

catboost.predict_log_proba(
  model,
  pool,
  ntree_start = 0,
  ntree_end = 0,
  thread_count = -1
)

Arguments

Value

Matrix of per-class log-probabilities (rows = objects, columns = classes).

Description

R equivalent of Python's CatBoost.randomized_search: calls the same native search entry point (NCB::RandomizedSearch, vendored at catboost/private/libs/hyperparameter_tuning/hyperparameter_tuning.h) that Python's CatBoost._tune_hyperparams calls via its Cython wrapper. In contrast to catboost.grid_search, not all parameter values are tried: a fixed number (n_iter) of settings is sampled uniformly from param_distributions (the native sampler seeds its shuffle from a fixed constant, so the sampled combinations – not just the winner – are reproducible across calls with the same grid and n_iter).

Sampling from continuous distributions (Python's scipy.stats-style rvs() objects) is not supported: param_distributions entries must be plain value vectors, sampled uniformly by the native code.

Usage

catboost.randomized_search(
  param_distributions,
  pool,
  params = list(),
  cv = 3,
  n_iter = 10,
  partition_random_seed = 0,
  calc_cv_statistics = TRUE,
  search_by_train_test_split = TRUE,
  refit = TRUE,
  shuffle = TRUE,
  stratified = FALSE,
  train_size = 0.8,
  verbose = TRUE,
  custom_objective = NULL,
  custom_eval_metric_object = NULL
)

Arguments

Value

A list with $params (best found parameters, as a named list), $cv_results (a data.frame of cross-validation results with the same columns catboost.cv returns), and, if refit = TRUE, $model (a catboost.Model fit with the best parameters).

Description

After de-serializing a model object through R base's functions ('readRDS', 'load'), its underlying object will not exist in the computer's memory anymore, and needs to be restored from the raw bytes that the model stores.

This is automatically done internally when calling functions such as catboost.predict, but the process is repeated at each call, which makes them slower than if using a fresh model object and increases memory usage inbetween calls to the garbage collector. This function allows restoring the internal object beforehand so as to avoid restoring the object multiple times.

Note that the model object needs to be re-assigned as the output of this function, as the modifications are not done in-place.

Usage

catboost.restore_handle(model)

Arguments

Value

The model object with its handle pointing to a valid object in memory.

Description

R equivalent of the CatBoost CLI's run-worker mode: blocks the calling process, acting as a distributed-training worker awaiting commands from a master node over the network, until stopped. There is no R-level stop mechanism beyond what the CLI mode itself provides – killing the process, or the master sending a stop-slave command through the par protocol.

Call this from a separate R process (or session) on each worker machine, before starting the master-side training call. On the master side, pass params = list(node_type = "Master", file_with_hosts = <path>, node_port = <port>) to catboost.train (see its Distributed training section) or to catboost.select_features. file_with_hosts is a plain text file with one host:port line per worker, where each port matches that worker's own node_port below.

Usage

catboost.run_worker(node_port, thread_count = parallel::detectCores())

Arguments

Value

No value is returned; this call blocks until the worker stops.

See Also

https://catboost.ai/docs/features/distributed-training.html

Examples

## Not run: 
# Run on each worker machine; blocks until killed or stopped by the master.
catboost.run_worker(node_port = 12345)

## End(Not run)

Description

R port of Python's module-level catboost.sample_gaussian_process. Implements Gaussian Process posterior sampling (Kernel Gradient Boosting / Algorithm 4) from "Gradient Boosting Performs Gaussian Process Inference" (https://arxiv.org/abs/2206.05608). Produces samples from the GP posterior under the prior assumption f ~ GP(0, sigma^2 K + delta^2 I).

Takes a catboost.Pool rather than the separate X/y/ cat_features/text_features/embedding_features arguments Python's version takes – every other R training entry point (catboost.train, catboost.cv, ...) is Pool-based, and the Pool already carries that information.

Reproduces the Python algorithm's two-stage fit – a near-zero-signal "prior" model whose leaf values are then randomized by direct JSON model surgery, then a "posterior" model fit to the residual – with the same fitting hyperparameters. Both stages need to fit learn_pool's features against a boosting label other than its own (pure noise for the prior, a residual for the posterior); this package's Pool object has no set_label entry point (unlike Python's X/y arrays, which Python simply resubmits with a different y each stage), so each stage instead builds a throwaway catboost.Pool from learn_pool's features (catboost.pool.get_features) plus the desired label, carrying over learn_pool's weight (catboost.pool.get_weight) and group id (catboost.pool.get_group_id_hash/ catboost.pool.set_group_id) if either is set – the same "extract features, rebuild pool with something else changed" idiom already used by catboost.plot_predictions/catboost.plot_partial_dependence. As with those, this restricts learn_pool to all-numeric features (get_features's own restriction); an earlier revision instead kept one shared pool and retargeted its label via a temporary catboost.pool.set_baseline (which supports categorical/text/ embedding features), but CatBoost's native trainer silently zeroes out model_shrink_rate whenever a baseline column is present ("Model shrinkage in combination with baseline column is not implemented yet"), which would silently drop a term the paper's Algorithm 4 requires – not an acceptable substitution. learn_pool's own baseline and pairs (if either is set) are NOT propagated onto the rebuilt Pools and trigger a warning, not a silent drop; group weight/subgroup id have no accessor anywhere in this package to even detect, so they can't be checked either.

RNG note: draws a seeded, deterministic sequence from random_seed (default 0), scoped to this call only – the caller's global RNG stream is saved before and restored after, so this function has no observable RNG side effect (unlike Python's local np.random.default_rng, R has no non-global RNG object, so this is done by save/restore of .Random.seed instead). Reproducible within this package, but not byte-identical to the Python implementation – R has no generator matching numpy's PCG64 default_rng bit-for-bit (same caveat as this package's embedding_processing LDA calcer; see catboost.train).

Usage

catboost.sample_gaussian_process(
  learn_pool,
  test_pool = NULL,
  random_seed = NULL,
  samples = 10,
  posterior_iterations = 900,
  prior_iterations = 100,
  learning_rate = 0.1,
  depth = 6,
  sigma = 0.1,
  delta = 0,
  random_strength = 0.1,
  random_score_type = "Gumbel",
  eps = 0.0001,
  verbose = FALSE
)

Arguments

Value

A list of samples trained catboost.Model objects, each the sum (via catboost.sum_models) of that sample's prior and posterior model.

See Also

https://arxiv.org/abs/2206.05608

Description

R equivalent of Python's model.save_borders(fname) (core.py:3809-3820, _save_borders()): writes the model's float feature quantization borders to a file in the format described at https://catboost.ai/docs/concepts/input-data_custom-borders.html, so they can be reused to quantize another Pool identically (upstream's input_borders mechanism). Unlike catboost.pool.save_quantization_borders (which requires an already-quantized Pool), this reads borders directly off a trained model.

Usage

catboost.save_borders(model, output_file)

Arguments

Value

No return value, called for side effects.

Description

Save the model to a file.

Note: Feature importance (see https://catboost.ai/docs/concepts/fstr.html#fstr) is not saved when using this function.

Usage

catboost.save_model(
  model,
  model_path,
  file_format = "cbm",
  export_parameters = NULL,
  pool = NULL
)

Arguments

Value

Status, the result of model shrinking. TRUE if shrinking succeeded, FALSE otherwise.

See Also

https://catboost.ai/docs/features/export-model-to-core-ml.html

Description

Save the dataset to the CatBoost format. Files with the following data are created:

• Dataset description

• Column descriptions

Use the catboost.load_pool function to read the resulting files. These files can also be used in the Command-line version and the Python library.

Usage

catboost.save_pool(
  data,
  label = NULL,
  weight = NULL,
  baseline = NULL,
  pool_path = "data.pool",
  cd_path = "cd.pool"
)

Arguments

Value

Nothing. This method writes a dataset to disk.

Description

R equivalent of Python's CatBoost.select_features: trains repeatedly while eliminating the weakest features, and reports which features survived.

This calls the same native entry point Python's select_features calls (NCB::SelectFeatures, vendored at catboost/libs/features_selection/select_features.h), so the elimination loop, its per-step retraining, the SHAP-based feature strengths and the final model all come from vendor code rather than an R-side reimplementation.

This is a different algorithm from catboost.eval_feature, which scores caller-supplied feature sets by cross-validation instead of eliminating features.

Feature selection by feature tags (Python's grouping = "ByTags") is supported via grouping/features_tags_for_select/ num_features_tags_to_select: attach tags to learn_pool with catboost.load_pool's feature_tags argument, then select among them here.

Usage

catboost.select_features(
  learn_pool,
  features_for_select = NULL,
  num_features_to_select = NULL,
  test_pool = NULL,
  params = list(),
  algorithm = NULL,
  steps = NULL,
  shap_calc_type = NULL,
  train_final_model = TRUE,
  custom_eval_metric_object = NULL,
  grouping = NULL,
  features_tags_for_select = NULL,
  num_features_tags_to_select = NULL
)

Arguments

Value

A list with the fields of the vendor's selection summary:

• selected_features – 0-based indices of the kept features.

• selected_features_names – their names.

• eliminated_features – 0-based indices of the dropped features.

• eliminated_features_names – their names.

• selected_features_tags/eliminated_features_tags – present only when grouping = "ByTags": the kept/dropped tag names.

• loss_graph – list with removed_features_count, loss_values and main_indices (the graph points whose loss was measured by fitting a model rather than estimated from fstr).

• model – the fitted catboost.Model, present only when train_final_model = TRUE.

Description

R equivalent of Python's model.set_leaf_values(new_leaf_values) (core.py:2141-2152, defined once on _CatBoostBase and inherited unchanged by CatBoost/CatBoostClassifier/CatBoostRegressor/ CatBoostRanker). The change is held in memory only; call catboost.save_model to persist it, same calling convention as catboost.set_scale_and_bias.

Usage

catboost.set_leaf_values(model, new_leaf_values)

Arguments

Value

No return value, called for side effects.

Description

Set a single string metadata key/value pair on the model, in place. R equivalent of Python's model.get_metadata()[key] = value and of the CLI's metadata set --key --value mode. The change is held in memory only; call catboost.save_model to persist it, matching Python's calling convention.

Usage

catboost.set_metadata(model, key, value)

Arguments

Value

No return value, called for side effects.

Description

Set (or discard) the threshold used for class separation in a binary classification model, R equivalent of Python's CatBoostClassifier.set_probability_threshold() (core.py:5891-5906). Held in the same model metadata key (binclass_probability_threshold) catboost.get_metadata/ catboost.set_metadata expose; the change is in-memory only, same calling convention as catboost.set_metadata.

Usage

catboost.set_probability_threshold(
  model,
  binclass_probability_threshold = NULL
)

Arguments

Value

No return value, called for side effects.

Description

Set the model's scale and bias, in place. R equivalent of Python's model.set_scale_and_bias(scale, bias) and of the CLI's normalize-model --set-scale --set-bias mode. The change is held in memory only; call catboost.save_model to persist it, matching Python's calling convention.

Usage

catboost.set_scale_and_bias(model, scale, bias)

Arguments

Value

No return value, called for side effects.

Description

Shrink the model

Usage

catboost.shrink(model, ntree_end, ntree_start = 0)

Arguments

Value

Status, the result of model shrinking. TRUE if shrinking succeeded, FALSE otherwise.

See Also

https://catboost.ai/docs/concepts/r-reference_catboost-shrink.html

Description

Apply the model to the given dataset and calculate the results for each i-th tree of the model taking into consideration only the trees in the range [1;i].

Peculiarities: In case of multiclassification the prediction is returned in the form of a matrix. Each line of this matrix contains the predictions for one object of the input dataset.

Usage

catboost.staged_predict(
  model,
  pool,
  verbose = FALSE,
  prediction_type = "RawFormulaVal",
  ntree_start = 0L,
  ntree_end = 0L,
  eval_period = 1,
  thread_count = -1
)

Arguments

Value

List object with predictions from one iteration.

See Also

https://catboost.ai/docs/concepts/r-reference_catboost-staged_predict.html

Description

Predict class log-probabilities at each iteration, R equivalent of Python's CatBoostClassifier.staged_predict_log_proba() (core.py:5796-5835). A thin wrapper over catboost.staged_predict with prediction_type = "Probability": each iteration's result is log()-transformed the same way catboost.predict_log_proba transforms a single catboost.predict() call.

Usage

catboost.staged_predict_log_proba(
  model,
  pool,
  ntree_start = 0L,
  ntree_end = 0L,
  eval_period = 1,
  thread_count = -1
)

Arguments

Value

Iterator object; each nextElem() call returns the matrix of per-class log-probabilities for the corresponding iteration.

Description

Blend trees and counters of two or more trained CatBoost models into a new model. Leaf values can be individually weighted for each input model. For example, it may be useful to blend models trained on different validation datasets.

Usage

catboost.sum_models(
  models,
  weights = NULL,
  ctr_merge_policy = "IntersectingCountersAverage"
)

Arguments

Value

Model object.

Description

Splits a string into tokens ahead of catboost.Dictionary fitting/application. Native bridge to Python's catboost.text_processing.Tokenizer, backed directly by vendor's NTextProcessing::NTokenizer::TTokenizer.

Usage

catboost.Tokenizer(
  lowercasing = NULL,
  number_process_policy = NULL,
  number_token = NULL,
  separator_type = NULL,
  delimiter = NULL,
  split_by_set = NULL,
  skip_empty = NULL,
  token_types = NULL,
  sub_tokens_policy = NULL,
  languages = NULL,
  lemmatizing = NULL
)

Arguments

Value

catboost.Tokenizer

Description

Split string into tokens using a catboost.Tokenizer.

Usage

catboost.tokenizer.tokenize(tokenizer, string, types = FALSE)

Arguments

Value

A character vector of tokens, or (if types = TRUE) a data.frame with token and type columns.

Description

Train the model using a CatBoost dataset.

The list of parameters

• Common parameters

  • fold_permutation_block

    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.

    Default value:

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

  • ignored_features

    Identifiers of features to exclude from training. The 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 "42", 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 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: "categorical feature<⁠\t⁠>label<⁠\t⁠>numerical feature". So for the row "rock<⁠\t⁠>0<⁠\t⁠>42", the identifier for the "rock" feature is 0, and for the "42" feature it is 1.

    The identifiers of features to exclude should be enumerated at vector.

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

    Default value:

    None (use all features)

  • use_best_model

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

    Build the number of trees defined by the training parameters.

    • Identify the iteration with the optimal loss function value.

    • No trees are saved after this iteration.

    This option requires a test dataset to be provided.

    Default value:

    FALSE (not used)

  • loss_function

    The loss function (see https://catboost.ai/docs/concepts/loss-functions.html#loss-functions) to use in training. The specified value also determines the machine learning problem to solve.

    Format:

    <Loss function 1>[:<parameter 1>=<value>:..<parameter N>=<value>:]

    Supported loss functions:

    • 'Logloss'

    • 'CrossEntropy'

    • 'MultiClass'

    • 'MultiClassOneVsAll'

    • 'RMSE'

    • 'MAE'

    • 'Quantile'

    • 'LogLinQuantile'

    • 'MAPE'

    • 'Poisson'

    • 'Lq'

    • 'PairLogit'

    • 'PairLogitPairwise'

    • 'YetiRank'

    • 'YetiRankPairwise'

    • 'QueryCrossEntropy'

    • 'QueryRMSE'

    • 'QuerySoftMax'

    Supported parameters:

    • alpha - The coefficient used in quantile-based losses ('Quantile' and 'LogLinQuantile'). The default value is 0.5.

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

      'Quantile:alpha=0.1'

    Default value:

    'RMSE'

  • custom_loss

    Loss function (see https://catboost.ai/docs/concepts/loss-functions.html#loss-functions) values to output during training. These functions are not used for optimization and are displayed for informational purposes only.

    Format:

    c(<Loss function 1>[:<parameter>=<value>],<Loss function 2>[:<parameter>=<value>],...,<Loss function N>[:<parameter>=<value>])

    Supported loss functions:

    • 'Logloss'

    • 'CrossEntropy'

    • 'Precision'

    • 'Recall'

    • 'F1'

    • 'F'

    • 'BalancedAccuracy'

    • 'BalancedErrorRate'

    • 'MCC'

    • 'Accuracy'

    • 'CtrFactor'

    • 'AUC'

    • 'BrierScore'

    • 'HingeLoss'

    • 'HammingLoss'

    • 'ZeroOneLoss'

    • 'Kappa'

    • 'WKappa'

    • 'LogLikelihoodOfPrediction'

    • 'MultiClass'

    • 'MultiClassOneVsAll'

    • 'TotalF1'

    • 'MAE'

    • 'MAPE'

    • 'Poisson'

    • 'Quantile'

    • 'RMSE'

    • 'LogLinQuantile'

    • 'Lq'

    • 'NumErrors'

    • 'SMAPE'

    • 'R2'

    • 'MSLE'

    • 'MedianAbsoluteError'

    • 'PairLogit'

    • 'PairLogitPairwise'

    • 'PairAccuracy'

    • 'QueryCrossEntropy'

    • 'QueryRMSE'

    • 'QuerySoftMax'

    • 'PFound'

    • 'NDCG'

    • 'AverageGain'

    • 'PrecisionAt'

    • 'RecallAt'

    • 'MAP'

    • 'MRR'

    • 'ERR'

    Supported parameters:

    • alpha - The coefficient used in quantile-based losses ('Quantile' and 'LogLinQuantile'). The default value is 0.5.

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

    c('CrossEntropy') or simply 'CrossEntropy'.

    Values of all custom loss functions for learning and test datasets are saved to the Loss function (see https://catboost.ai/docs/concepts/output-data_loss-function.html#output-data_loss-function) output files (learn_error.tsv and test_error.tsv respectively). The catalog for these files is specified in the train-dir (train_dir) parameter.

    Default value:

    None (use one of the loss functions supported by the library)

  • eval_metric

    The loss function used for overfitting detection (if enabled) and best model selection (if enabled).

    Supported loss functions:

    • 'Logloss'

    • 'CrossEntropy'

    • 'Precision'

    • 'Recall'

    • 'F1'

    • 'F'

    • 'BalancedAccuracy'

    • 'BalancedErrorRate'

    • 'MCC'

    • 'Accuracy'

    • 'CtrFactor'

    • 'AUC'

    • 'BrierScore'

    • 'HingeLoss'

    • 'HammingLoss'

    • 'ZeroOneLoss'

    • 'Kappa'

    • 'WKappa'

    • 'LogLikelihoodOfPrediction'

    • 'MultiClass'

    • 'MultiClassOneVsAll'

    • 'TotalF1'

    • 'MAE'

    • 'MAPE'

    • 'Poisson'

    • 'Quantile'

    • 'RMSE'

    • 'LogLinQuantile'

    • 'Lq'

    • 'NumErrors'

    • 'SMAPE'

    • 'R2'

    • 'MSLE'

    • 'MedianAbsoluteError'

    • 'PairLogit'

    • 'PairLogitPairwise'

    • 'PairAccuracy'

    • 'QueryCrossEntropy'

    • 'QueryRMSE'

    • 'QuerySoftMax'

    • 'PFound'

    • 'NDCG'

    • 'AverageGain'

    • 'PrecisionAt'

    • 'RecallAt'

    • 'MAP'

    • 'MRR'

    • 'ERR'

    Format:

    metric_name:param=Value

    Examples:

    'R2'

    'Quantile:alpha=0.3'

    Default value:

    Optimized objective is used

  • iterations

    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.

    Default value:

    1000

  • border

    The target border. If the value is strictly greater than this threshold, it is considered a positive class. Otherwise it is considered a negative class.

    The parameter is obligatory if the Logloss function is used, since it uses borders to transform any given target to a binary target.

    Used in binary classification.

    Default value:

    0.5

  • leaf_estimation_iterations

    The number of gradient steps when calculating the values in leaves.

    Default value:

    1

  • depth

    Depth of the trees.

    The value can be any integer up to 16. It is recommended to use values in the range [1; 10].

    Default value:

    6

  • learning_rate

    The learning rate.

    Used for reducing the gradient step.

    Default value:

    0.03

  • rsm

    Random subspace method. The percentage of features to use at each iteration of building trees. At each iteration, features are selected over again at random.

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

    Default value:

    1

  • random_seed

    The random seed used for training.

    Default value:

    0

  • nan_mode

    Way to process missing values.

    Possible values:

    • 'Min'

    • 'Max'

    • 'Forbidden'

    Default value:

    'Min'

  • od_pval

    Use the Overfitting detector (see https://catboost.ai/docs/concepts/overfitting-detector.html#overfitting-detector) to stop training when the threshold is reached. Requires that a test dataset was input.

    For best results, it is recommended to set a value in the range [10^-10; 10^-2].

    The larger the value, the earlier overfitting is detected.

    Default value:

    The overfitting detection is turned off

  • od_type

    The method used to calculate the values in leaves.

    Possible values:

    • IncToDec

    • Iter

    Restriction. Do not specify the overfitting detector threshold when using the Iter type.

    Default value:

    'IncToDec'

  • od_wait

    The number of iterations to continue the training after the iteration with the optimal loss function value. The purpose of this parameter differs depending on the selected overfitting detector type:

    • IncToDec - Ignore the overfitting detector when the threshold is reached and continue learning for the specified number of iterations after the iteration with the optimal loss function value.

    • Iter - Consider the model overfitted and stop training after the specified number of iterations since the iteration with the optimal loss function value.

    Default value:

    20

  • leaf_estimation_method

    The method used to calculate the values in leaves.

    Possible values:

    • Newton

    • Gradient

    Default value:

    Default value depends on the selected loss function

  • grow_policy

    GPU only. The tree growing policy. It describes how to perform greedy tree construction.

    Possible values:

    • SymmetricTree

    • Lossguide

    • Depthwise

    Default value:

    SymmetricTree

  • min_data_in_leaf

    GPU only. The minimum training samples count in leaf. CatBoost will not search for new splits in leaves with samples count less than min_data_in_leaf. This parameter is used only for Depthwise and Lossguide growing policies.

    Default value:

    1

  • max_leaves

    GPU only. The maximum leaf count in resulting tree. Used only for Lossguide growing policy. This parameter is used only for Lossguide growing policy.

    Default value:

    31

  • score_function GPU only. Score that is used during tree construction to select the next tree split.

    Possible values:

    • L2

    • Cosine

    • NewtonL2

    • NewtonCosine

    Default value:

    Cosine

    For growing policy Lossguide default is NewtonL2.

  • l2_leaf_reg

    L2 regularization coefficient. Used for leaf value calculation.

    Any positive values are allowed.

    Default value:

    3

  • model_size_reg

    Model size regularization coefficient. The influence coefficient of the model size for choosing tree structure. To get a smaller model size - increase this coefficient.

    Any positive values are allowed.

    Default value:

    0.5

  • has_time

    Use the order of objects in the input data (do not perform a random permutation of the dataset at the preprocessing stage)

    Default value:

    FALSE (not used; permute input dataset)

  • allow_const_label

    To allow the constant label value in the dataset.

    Default value:

    FALSE

  • name

    The experiment name to display in visualization tools (see https://catboost.ai/docs/features/visualization.html#visualization).

    Default value:

    experiment

  • prediction_type

    The format for displaying approximated values in output data.

    Possible values:

    • 'Probability'

    • 'Class'

    • 'RawFormulaVal'

    Default value:

    'RawFormulaVal'

  • fold_len_multiplier

    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.

    Default value:

    2

  • class_weights

    Classes weights. The values are used as multipliers for the object weights.

    For example, for 3 class classification you could use:

    c(0.85, 1.2, 1)

    Default value:

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

  • classes_count

    The upper limit for the numeric class label. Defines the number of classes for multiclassification.

    Only non-negative integers can be specified. The given integer should be greater than any of the target values.

    If this parameter is specified the labels for all classes in the input dataset should be smaller than the given value.

    Default value:

    maximum class label + 1

  • one_hot_max_size

    Convert the feature to float if the number of different values that it takes exceeds the specified value. Ctrs are not calculated for such features.

    The one-vs.-all delimiter is used for the resulting float features.

    Default value:

    FALSE

    Do not convert features to float based on the number of different values

  • random_strength

    Score standard deviation multiplier.

    Default value:

    1

  • bootstrap_type

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

    Possible values:

    • 'Bayesian'

    • 'Bernoulli'

    • 'Poisson'

    • 'MVS'

    • 'No'

    Poisson bootstrap is supported only on GPU.

    Default value:

    'Bayesian'

  • bagging_temperature

    Controls intensity of Bayesian bagging. The higher the temperature the more aggressive bagging is.

    Typical values are in the range $[0, 1]$ (0 is for no bagging).

    Possible values are in the range $[0, +\infty)$.

    Default value:

    1

  • subsample

    Sample rate for bagging. This parameter can be used if one of the following bootstrap types is defined:

    • 'Bernoulli'

    Default value:

    0.66

  • sampling_unit

    The parameter allows to specify the sampling scheme: sample weights for each object individually or for an entire group of objects together.

    Possible values:

    • 'Object'

    • 'Group'

    Default value:

    'Object'

  • sampling_frequency

    Frequency to sample weights and objects when building trees.

    Possible values:

    • 'PerTree'

    • 'PerTreeLevel'

    Default value:

    'PerTreeLevel'

  • model_shrink_rate

    For i > 0 at the start of i-th iteration multiplies model by (1 - model_shrink_rate / i).

    Possible values: [0, 1).

    Default value: 0

• CTR settings

  • simple_ctr

    Binarization settings for categorical features (see https://catboost.ai/docs/concepts/algorithm-main-stages_cat-to-numberic.html).

    Format:

    c(CtrType[:TargetBorderCount=BorderCount][:TargetBorderType=BorderType][:CtrBorderCount=Count][:CtrBorderType=Type][:Prior=num_1/denum_1]..[:Prior=num_N/denum_N])

    Components:

    • CTR types for training on CPU:

      • 'Borders'

      • 'Buckets'

      • 'BinarizedTargetMeanValue'

      • 'Counter'

    • CTR types for training on GPU:

      • 'Borders'

      • 'Buckets'

      • 'FeatureFreq'

      • 'FloatTargetMeanValue'

    • The number of borders for label value binarization. (see https://catboost.ai/docs/concepts/quantization.html) Only used for regression problems. Allowed values are integers from 1 to 255 inclusively. The default value is 1. This option is available for training on CPU only.

    • The binarization (see https://catboost.ai/docs/concepts/quantization.html) type for the label value. Only used for regression problems.

      Possible values:

      • 'Median'

      • 'Uniform'

      • 'UniformAndQuantiles'

      • 'MaxLogSum'

      • 'MinEntropy'

      • 'GreedyLogSum'

      By default, 'MinEntropy' This option is available for training on CPU only.

    • The number of splits for categorical features. Allowed values are integers from 1 to 255 inclusively.

    • The binarization type for categorical features. Supported values for training on CPU:

      • 'Uniform'

      Supported values for training on GPU:

      • 'Median'

      • 'Uniform'

      • 'UniformAndQuantiles'

      • 'MaxLogSum'

      • 'MinEntropy'

      • 'GreedyLogSum'

    • Priors to use during training (several values can be specified) Possible formats:

      • 'One number - Adds the value to the numerator.'

      • 'Two slash-delimited numbers (for GPU only) - Use this format to set a fraction. The number is added to the numerator and the second is added to the denominator.'

  • combinations_ctr

    Binarization settings for combinations of categorical features (see https://catboost.ai/docs/concepts/algorithm-main-stages_cat-to-numberic.html).

    Format:

    c(CtrType[:TargetBorderCount=BorderCount][:TargetBorderType=BorderType][:CtrBorderCount=Count][:CtrBorderType=Type][:Prior=num_1/denum_1]..[:Prior=num_N/denum_N])

    Components:

    • CTR types for training on CPU:

      • 'Borders'

      • 'Buckets'

      • 'BinarizedTargetMeanValue'

      • 'Counter'

    • CTR types for training on GPU:

      • 'Borders'

      • 'Buckets'

      • 'FeatureFreq'

      • 'FloatTargetMeanValue'

    • The number of borders for target binarization. (see https://catboost.ai/docs/concepts/quantization.html) Only used for regression problems. Allowed values are integers from 1 to 255 inclusively. The default value is 1. This option is available for training on CPU only.

    • The binarization (see https://catboost.ai/docs/concepts/quantization.html) type for the target. Only used for regression problems.

      Possible values:

      • 'Median'

      • 'Uniform'

      • 'UniformAndQuantiles'

      • 'MaxLogSum'

      • 'MinEntropy'

      • 'GreedyLogSum'

      By default, 'MinEntropy' This option is available for training on CPU only.

    • The number of splits for categorical features. Allowed values are integers from 1 to 255 inclusively.

    • The binarization type for categorical features. Supported values for training on CPU:

      • 'Uniform'

      Supported values for training on GPU:

      • 'Median'

      • 'Uniform'

      • 'UniformAndQuantiles'

      • 'MaxLogSum'

      • 'MinEntropy'

      • 'GreedyLogSum'

    • Priors to use during training (several values can be specified) Possible formats:

      • 'One number - Adds the value to the numerator.'

      • 'Two slash-delimited numbers (for GPU only) - Use this format to set a fraction. The number is added to the numerator and the second is added to the denominator.'

  • ctr_target_border_count

    Maximum number of borders used in target binarization for categorical features that need it. If TargetBorderCount is specified in 'simple_ctr', 'combinations_ctr' or 'per_feature_ctr' option it overrides this value.

    Default value:

    1

  • counter_calc_method

    The method for calculating the Counter CTR type for the test dataset.

    Possible values:

    • 'Full'

    • 'FullTest'

    • 'PrefixTest'

    • 'SkipTest'

    Default value: 'PrefixTest'

  • max_ctr_complexity

    The maximum number of categorical features that can be combined.

    Default value:

    4

  • ctr_leaf_count_limit

    The maximum number of leaves with categorical features. If the number of leaves exceeds the specified limit, some leaves are discarded. The value must be positive (for zero limit use ignored_features parameter).

    The leaves to be discarded are selected as follows:

    1. The leaves are sorted by the frequency of the values.

    2. The top N leaves are selected, where N is the value specified in the parameter.

    3. All leaves starting from N+1 are discarded.

    This option reduces the resulting model size and the amount of memory required for training. Note that the resulting quality of the model can be affected.

    Default value:

    None (The number of leaves with categorical features is not limited)

  • store_all_simple_ctr

    Ignore categorical features, which are not used in feature combinations, when choosing candidates for exclusion.

    Use this parameter with ctr-leaf-count-limit only.

    Default value:

    FALSE (Both simple features and feature combinations are taken in account when limiting the number of leaves with categorical features)

• Binarization settings

  • border_count

    The number of splits for numerical features. Allowed values are integers from 1 to 255 inclusively.

    Default value:

    254 for training on CPU or 128 for training on GPU

  • feature_border_type

    The binarization mode (see https://catboost.ai/docs/concepts/quantization.html) for numerical features.

    Possible values:

    • 'Median'

    • 'Uniform'

    • 'UniformAndQuantiles'

    • 'MaxLogSum'

    • 'MinEntropy'

    • 'GreedyLogSum'

    Default value:

    'MinEntropy'

• Performance settings

  • thread_count

    The number of threads to use when applying the model.

    Allows you to optimize the speed of execution. This parameter doesn't affect results.

    Default value:

    The number of CPU cores.

• Output settings

  • logging_level

    Possible values:

    • 'Silent'

    • 'Verbose'

    • 'Info'

    • 'Debug'

    Default value:

    'Silent'

  • metric_period

    The frequency of iterations to print the information to stdout. The value should be a positive integer.

    Default value:

    1

  • train_dir

    The directory for storing the files generated during training.

    Default value:

    None (current catalog)

  • save_snapshot

    Enable snapshotting for restoring the training progress after an interruption.

    Default value:

    None

  • snapshot_file

    Settings for recovering training after an interruption (see https://catboost.ai/docs/features/snapshots.html).

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

    • Missing - write information about training progress to the specified file.

    • Exists - load data from the specified file and continue training from where it left off.

    Default value:

    File can't be generated or read. If the value is omitted, the file name is experiment.cbsnapshot.

  • snapshot_interval

    Interval between saving snapshots (seconds)

    Default value:

    600

  • allow_writing_files

    If this flag is set to FALSE, no files with different diagnostic info will be created during training. With this flag set to FALSE no snapshotting can be done. Plus visualisation will not work, because visualisation uses files that are created and updated during training.

    Default value:

    TRUE

  • approx_on_full_history

    If this flag is set to TRUE, each approximated value is calculated using all the preceding rows in the fold (slower, more accurate). If this flag is set to FALSE, each approximated value is calculated using only the beginning 1/fold_len_multiplier fraction of the fold (faster, slightly less accurate).

    Default value:

    FALSE

  • boosting_type

    Boosting scheme. Possible values: - 'Ordered' - Gives better quality, but may slow down the training. - 'Plain' - The classic gradient boosting scheme. May result in quality degradation, but does not slow down the training.

    Default value:

    Depends on object count and feature count in train dataset and on learning mode.

  • dev_score_calc_obj_block_size

    CPU only. Size of block of samples in score calculation. Should be > 0 Used only for learning speed tuning. Changing this parameter can affect results in pairwise scoring mode due to numerical accuracy differences

    Default value:

    5000000

  • dev_efb_max_buckets

    CPU only. Maximum bucket count in exclusive features bundle. Should be in an integer between 0 and 65536. Used only for learning speed tuning.

    Default value:

    1024

  • sparse_features_conflict_fraction

    CPU only. Maximum allowed fraction of conflicting non-default values for features in exclusive features bundle. Should be a real value in [0, 1) interval.

    Default value:

    0.0

  • leaf_estimation_backtracking

    Type of backtracking during gradient descent. Possible values: - 'No' - never backtrack; supported on CPU and GPU - 'AnyImprovement' - reduce the descent step until the value of loss function is less than before the step; supported on CPU and GPU - 'Armijo' - reduce the descent step until Armijo condition is satisfied; supported on GPU only

    Default value:

    'AnyImprovement'

Usage

catboost.train(
  learn_pool,
  test_pool = NULL,
  params = list(),
  init_model = NULL,
  custom_objective = NULL,
  custom_eval_metric_object = NULL
)

Arguments

Details

Custom objective / custom eval metric support matrix. Every entry point below shares the same custom_objective/custom_eval_metric_object argument contract documented under catboost.train's own custom_objective and custom_eval_metric_object params:

• catboost.train Both custom_objective and custom_eval_metric_object.

• catboost.cv Both.

• catboost.grid_search Both – forwarded to the search itself and, when refit = TRUE, to the refit.

• catboost.randomized_search Both – same forwarding as catboost.grid_search.

• catboost.eval_feature Both.

• catboost.select_features custom_eval_metric_object only. There is no custom_objective argument: the native entry point it calls, NCB::SelectFeatures (vendored at catboost/libs/features_selection/select_features.h), takes no TCustomObjectiveDescriptor parameter anywhere in its signature or in recursive_features_elimination.* – there is no C++-side slot to wire a custom objective into, so the omission is structural, not a missing feature.