fit¶

Train a model.

The number of distinct classes in y decides the model: two classes train a logistic model, and three or more train a softmax model with one set of rating tables per class.

Method call format¶

fit(X,
    y,
    sample_weight=None,
    exposure=None,
    groups=None,
    *,
    offset=None,
    eval_set=None,
    eval_sample_weight=None,
    eval_exposure=None,
    eval_offset=None,
    callbacks=None)

Parameters¶

The training parameters are set in the constructor of the TBoostClassifier class.

X¶

Description¶

The input training dataset in the form of a two-dimensional feature matrix.

The description is different for each group of possible types.

Possible types

polars.DataFrame, polars.LazyFrame

The column names become the feature names (feature_names_in_). String, Categorical and Enum columns are treated as categorical features, and numeric columns are converted to float32, with nulls treated as missing values. A LazyFrame is collected at the start of the fit.

The columns named by the y, sample_weight, exposure, groups and offset parameters are not used as features.

numpy.ndarray, other array-like data

Every feature is numerical unless it is listed in the categorical_features parameter. For a pandas DataFrame the column names become the feature names, but at prediction time the features are matched by position. A Fortran-ordered (column-major) float32 array is the cheapest input: its columns are copied without a transpose.

Default value

Required parameter

y¶

Description¶

The class labels of the training objects: at least two distinct values, not a continuous target. The labels can be of any type; they are sorted into classes_. A string names a column of a polars X, which is then not used as a feature.

Possible types

numpy.ndarray of shape (object_count,)
polars.Series
list
string

Default value

Required parameter

sample_weight¶

Description¶

The weight of each object in the input data in the form of a one-dimensional array-like data. A string names a column of a polars X.

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

Possible types

numpy.ndarray of shape (object_count,)
polars.Series
list
string

Default value

None

exposure¶

Description¶

The exposure of each object. \(\log(exposure)\) is added to the raw score (the logit) as an offset. A string names a column of a polars X.

Supported for binary classification only: passing it with three or more classes raises an error.

Possible types

numpy.ndarray of shape (object_count,)
polars.Series
list
string

Default value

None

groups¶

Description¶

The entity each object belongs to, for panel data where the same entity (for example, a policy renewed each year) contributes several similar objects. A string names a column of a polars X.

When it is given, whole groups are assigned to one side of every internal split instead of single objects: the validation objects of early stopping, the bag samples and the pruning folds. Otherwise near-duplicate objects of the same entity leak across these splits, early stopping does not trigger, and pruning is biased. A grouping in which every group has one object is the same as no grouping.

Possible types

numpy.ndarray of shape (object_count,)
polars.Series
list
string

Default value

None (every object is its own group)

offset¶

Description¶

A link-scale offset added to the raw score of each object and never learned (the equivalent of XGBoost's base_margin and LightGBM's init_score). A string names a column of a polars X.

For the squared_error objective, the fit is exactly the fit of y - offset. For the log and logit links it is added to the exposure offset, \(\log(exposure) + offset\).

Prediction methods add it only when it is passed to them again (their offset parameter); otherwise objects are scored with a zero offset.

Possible types

numpy.ndarray of shape (object_count,)
polars.Series
list
string

Default value

None

eval_set¶

Description¶

The validation dataset used by early stopping, as a tuple (X_val, y_val). Every bag stops at its own best iteration on it, and no validation objects are set aside from X (validation_fraction is ignored).

The evaluation objects are used only by early stopping: they never reach the training, the intercept, the cell refit, the tables or pruning. X_val is matched to the features as in predict, and y_val may name a column of a polars X_val. Setting reanchor_slope=True with an eval_set raises an error.

Possible types

tuple (X_val, y_val)

Default value

None

eval_sample_weight, eval_exposure, eval_offset¶

Description¶

The weight, the exposure and the offset of the evaluation objects. A string names a column of X_val. eval_exposure is required when exposure is given, and eval_offset when offset is given.

Possible types

numpy.ndarray of shape (object_count,)
polars.Series
list
string

Default value

None

callbacks¶

Description¶

Functions called after every iteration of the training of the deployed model, each with a dictionary:

phase — "fit".
bag, n_bags — The bag and the number of bags.
round — The iteration, starting at 1.
n_trees — The maximum number of trees (the n_trees parameter).
train_deviance, eval_deviance — The mean deviance on the bag's training objects and on its validation objects (None without validation objects).

The bags are trained in parallel, so calls for different bags interleave. Each bag's iterations arrive in order, all on the calling thread. A true return value stops every bag after its current iteration (stopping_reason_ is then "callback"); an exception stops the training and is raised from fit. The deviances of every iteration are kept in evals_result_.

Possible types

callable
list of callables

Default value

None

Return value¶

The estimator itself, trained, with classes_ set to the sorted distinct labels found in y.

For binary classification, the attributes n_trees_per_bag_, stopping_reason_per_bag_, n_trees_, stopping_reason_ and evals_result_ describe the boosting (see Attributes).

Usage examples¶

from t_boost import TBoostClassifier

model = TBoostClassifier()
model.fit(train_data, "Lapsed")
print(model.classes_)