Pool

class Pool(data, 
           label=None,
           cat_features=None,
           column_description=None,
           pairs=None,
           delimiter='\t',
           has_header=False,
           weight=None, 
           group_id=None,
           group_weight=None,
           subgroup_id=None,
           pairs_weight=None
           baseline=None,
           feature_names=None,
           thread_count=-1)

Purpose

Dataset processing.

The fastest way to pass the features data to the Pool constructor (and other CatBoost, CatBoostClassifier, CatBoostRegressor methods that accept it) if most (or all) of your features are numerical is to pass it using FeaturesData class. Another way to get similar performance with datasets that contain numerical features only is to pass features data as numpy.ndarray with numpy.float32 dtype.

Parameters

Parameter Possible types Description Default value
data
  • list
  • numpy.array
  • pandas.DataFrame
  • pandas.Series

Dataset in the form of a two-dimensional feature matrix.

Required parameter
catboost.FeaturesData Dataset in the form of catboost.FeaturesData. The fastest way to create a Pool from Python objects.
string

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

label
  • list
  • numpy.array
  • pandas.Series
  • pandas.DataFrame

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

Must be in the form of a one-dimensional array. The type of data in the array depends on the machine learning task being solved:
  • Regression and ranking  — Numeric values.
  • Binary classification — Numeric values.

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

    • Logloss — The value is considered a positive class if it is strictly grater than the value of the border parameter of the loss function. Otherwise, it is considered a negative class.
    • CrossEntropy — The value is interpreted as the probability that the dataset object belongs to the positive class. Possible values are in the range [0; 1].
  • Multiclassification — Integers or strings that represents the labels of the classes.
None
cat_features
  • list
  • numpy.array

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

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

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

None (it is assumed that all columns are the values of numerical features)
column_description string

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

None
pairs
  • list
  • numpy.array
  • pandas.DataFrame

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

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

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

None

string

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

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

delimiter string

The delimiter character used to separate the data in the dataset description input file.

Only single char delimiters are supported. If the specified value contains more than one character, only the first one is used.

"\t"
has_header bool

Read the column names from the first line if this parameter is set to True.

False
weight
  • list
  • numpy.array

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

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

Restriction.

Only one of the following parameters can be used at a time:

  • weight
  • group_weight
None
group_weight
  • list
  • numpy.array

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

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

Restriction.

Only one of the following parameters can be used at a time:

  • weight
  • group_weight
None
group_id
  • list
  • numpy.array
Group identifiers for all input objects. Supported identifier types are:
  • int
  • string types (string or unicode for Python 2 and bytes or string for Python 3).
Attention.

All objects in the dataset must be grouped by group identifiers if they are present. I.e., the objects with the same group identifier should follow each other in the dataset.

Example

For example, let's assume that the dataset consists of documents . The corresponding groups are , respectively. The feature vectors for the given documents are respectively. Then the dataset can take the following form:

The grouped blocks of lines can be input in any order. For example, the following order is equivalent to the previous one:

None
subgroup_id
  • list
  • numpy.array
Subgroup identifiers for all input objects. Supported identifier types are:
  • int
  • string types (string or unicode for Python 2 and bytes or string for Python 3).
None
pairs_weight
  • list
  • numpy.array

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

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

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

None
baseline
  • list
  • numpy.array

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

None
feature_names list

A list of names for each feature in the dataset.

None
thread_count int

The number of threads to use when reading data from file.

Use only when the dataset is read from an input file.

-1 (the number of threads is equal to the number of processor cores)
Parameter Possible types Description Default value
data
  • list
  • numpy.array
  • pandas.DataFrame
  • pandas.Series

Dataset in the form of a two-dimensional feature matrix.

Required parameter
catboost.FeaturesData Dataset in the form of catboost.FeaturesData. The fastest way to create a Pool from Python objects.
string

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

label
  • list
  • numpy.array
  • pandas.Series
  • pandas.DataFrame

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

Must be in the form of a one-dimensional array. The type of data in the array depends on the machine learning task being solved:
  • Regression and ranking  — Numeric values.
  • Binary classification — Numeric values.

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

    • Logloss — The value is considered a positive class if it is strictly grater than the value of the border parameter of the loss function. Otherwise, it is considered a negative class.
    • CrossEntropy — The value is interpreted as the probability that the dataset object belongs to the positive class. Possible values are in the range [0; 1].
  • Multiclassification — Integers or strings that represents the labels of the classes.
None
cat_features
  • list
  • numpy.array

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

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

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

None (it is assumed that all columns are the values of numerical features)
column_description string

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

None
pairs
  • list
  • numpy.array
  • pandas.DataFrame

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

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

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

None

string

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

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

delimiter string

The delimiter character used to separate the data in the dataset description input file.

Only single char delimiters are supported. If the specified value contains more than one character, only the first one is used.

"\t"
has_header bool

Read the column names from the first line if this parameter is set to True.

False
weight
  • list
  • numpy.array

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

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

Restriction.

Only one of the following parameters can be used at a time:

  • weight
  • group_weight
None
group_weight
  • list
  • numpy.array

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

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

Restriction.

Only one of the following parameters can be used at a time:

  • weight
  • group_weight
None
group_id
  • list
  • numpy.array
Group identifiers for all input objects. Supported identifier types are:
  • int
  • string types (string or unicode for Python 2 and bytes or string for Python 3).
Attention.

All objects in the dataset must be grouped by group identifiers if they are present. I.e., the objects with the same group identifier should follow each other in the dataset.

Example

For example, let's assume that the dataset consists of documents . The corresponding groups are , respectively. The feature vectors for the given documents are respectively. Then the dataset can take the following form:

The grouped blocks of lines can be input in any order. For example, the following order is equivalent to the previous one:

None
subgroup_id
  • list
  • numpy.array
Subgroup identifiers for all input objects. Supported identifier types are:
  • int
  • string types (string or unicode for Python 2 and bytes or string for Python 3).
None
pairs_weight
  • list
  • numpy.array

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

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

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

None
baseline
  • list
  • numpy.array

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

None
feature_names list

A list of names for each feature in the dataset.

None
thread_count int

The number of threads to use when reading data from file.

Use only when the dataset is read from an input file.

-1 (the number of threads is equal to the number of processor cores)

Attributes

Attribute Description
shape

Return the shape of the dataset.

is_empty_

Indicates that an empty array was input.