xgboost.training Namespace Reference

Data Structures
class	_PackedBooster
class	CVPack

Functions
Optional[Metric]	_configure_custom_metric (Optional[Metric] feval, Optional[Metric] custom_metric)
Booster	train (Dict[str, Any] params, DMatrix dtrain, int num_boost_round=10, *Optional[Sequence[Tuple[DMatrix, str]]] evals=None, Optional[Objective] obj=None, Optional[Metric] feval=None, Optional[bool] maximize=None, Optional[int] early_stopping_rounds=None, Optional[TrainingCallback.EvalsLog] evals_result=None, Optional[Union[bool, int]] verbose_eval=True, Optional[Union[str, os.PathLike, Booster, bytearray]] xgb_model=None, Optional[Sequence[TrainingCallback]] callbacks=None, Optional[Metric] custom_metric=None)
np.ndarray	groups_to_rows (List[np.ndarray] groups, np.ndarray boundaries)
List[CVPack]	mkgroupfold (DMatrix dall, int nfold, BoosterParam param, Sequence[str] evals=(), Optional[FPreProcCallable] fpreproc=None, bool shuffle=True)
List[CVPack]	mknfold (DMatrix dall, int nfold, BoosterParam param, int seed, Sequence[str] evals=(), Optional[FPreProcCallable] fpreproc=None, Optional[bool] stratified=False, Optional[XGBStratifiedKFold] folds=None, bool shuffle=True)
Union[Dict[str, float], DataFrame]	cv (BoosterParam params, DMatrix dtrain, int num_boost_round=10, int nfold=3, bool stratified=False, XGBStratifiedKFold folds=None, Sequence[str] metrics=(), Optional[Objective] obj=None, Optional[Metric] feval=None, Optional[bool] maximize=None, Optional[int] early_stopping_rounds=None, Optional[FPreProcCallable] fpreproc=None, bool as_pandas=True, Optional[Union[int, bool]] verbose_eval=None, bool show_stdv=True, int seed=0, Optional[Sequence[TrainingCallback]] callbacks=None, bool shuffle=True, Optional[Metric] custom_metric=None)

Variables
	_CVFolds = Sequence["CVPack"]

Detailed Description

Training Library containing training routines.

Function Documentation

cv()

Union[Dict[str, float], DataFrame] xgboost.training.cv	(	BoosterParam	params,
		DMatrix	dtrain,
		int	num_boost_round = 10,
		int	nfold = 3,
		bool	stratified = False,
		XGBStratifiedKFold	folds = None,
		Sequence[str]	metrics = (),
		Optional[Objective]	obj = None,
		Optional[Metric]	feval = None,
		Optional[bool]	maximize = None,
		Optional[int]	early_stopping_rounds = None,
		Optional[FPreProcCallable]	fpreproc = None,
		bool	as_pandas = True,
		Optional[Union[int, bool]]	verbose_eval = None,
		bool	show_stdv = True,
		int	seed = 0,
		Optional[Sequence[TrainingCallback]]	callbacks = None,
		bool	shuffle = True,
		Optional[Metric]	custom_metric = None
	)

Cross-validation with given parameters.

Parameters
----------
params : dict
    Booster params.
dtrain : DMatrix
    Data to be trained.
num_boost_round : int
    Number of boosting iterations.
nfold : int
    Number of folds in CV.
stratified : bool
    Perform stratified sampling.
folds : a KFold or StratifiedKFold instance or list of fold indices
    Sklearn KFolds or StratifiedKFolds object.
    Alternatively may explicitly pass sample indices for each fold.
    For ``n`` folds, **folds** should be a length ``n`` list of tuples.
    Each tuple is ``(in,out)`` where ``in`` is a list of indices to be used
    as the training samples for the ``n`` th fold and ``out`` is a list of
    indices to be used as the testing samples for the ``n`` th fold.
metrics : string or list of strings
    Evaluation metrics to be watched in CV.
obj :

    Custom objective function.  See :doc:`Custom Objective
    </tutorials/custom_metric_obj>` for details.

feval : function
    .. deprecated:: 1.6.0
        Use `custom_metric` instead.
maximize : bool
    Whether to maximize feval.
early_stopping_rounds: int
    Activates early stopping. Cross-Validation metric (average of validation
    metric computed over CV folds) needs to improve at least once in
    every **early_stopping_rounds** round(s) to continue training.
    The last entry in the evaluation history will represent the best iteration.
    If there's more than one metric in the **eval_metric** parameter given in
    **params**, the last metric will be used for early stopping.
fpreproc : function
    Preprocessing function that takes (dtrain, dtest, param) and returns
    transformed versions of those.
as_pandas : bool, default True
    Return pd.DataFrame when pandas is installed.
    If False or pandas is not installed, return np.ndarray
verbose_eval : bool, int, or None, default None
    Whether to display the progress. If None, progress will be displayed
    when np.ndarray is returned. If True, progress will be displayed at
    boosting stage. If an integer is given, progress will be displayed
    at every given `verbose_eval` boosting stage.
show_stdv : bool, default True
    Whether to display the standard deviation in progress.
    Results are not affected, and always contains std.
seed : int
    Seed used to generate the folds (passed to numpy.random.seed).
callbacks :
    List of callback functions that are applied at end of each iteration.
    It is possible to use predefined callbacks by using
    :ref:`Callback API <callback_api>`.

    .. note::

       States in callback are not preserved during training, which means callback
       objects can not be reused for multiple training sessions without
       reinitialization or deepcopy.

    .. code-block:: python

        for params in parameters_grid:
            # be sure to (re)initialize the callbacks before each run
            callbacks = [xgb.callback.LearningRateScheduler(custom_rates)]
            xgboost.train(params, Xy, callbacks=callbacks)

shuffle : bool
    Shuffle data before creating folds.
custom_metric :

    .. versionadded 1.6.0

    Custom metric function.  See :doc:`Custom Metric </tutorials/custom_metric_obj>`
    for details.

Returns
-------
evaluation history : list(string)

groups_to_rows()

np.ndarray xgboost.training.groups_to_rows	(	List[np.ndarray]	groups,
		np.ndarray	boundaries
	)

Given group row boundaries, convert ground indexes to row indexes
:param groups: list of groups for testing
:param boundaries: rows index limits of each group
:return: row in group

mkgroupfold()

List[CVPack] xgboost.training.mkgroupfold	(	DMatrix	dall,
		int	nfold,
		BoosterParam	param,
		Sequence[str]	evals = (),
		Optional[FPreProcCallable]	fpreproc = None,
		bool	shuffle = True
	)

Make n folds for cross-validation maintaining groups
:return: cross-validation folds

mknfold()

List[CVPack] xgboost.training.mknfold	(	DMatrix	dall,
		int	nfold,
		BoosterParam	param,
		int	seed,
		Sequence[str]	evals = (),
		Optional[FPreProcCallable]	fpreproc = None,
		Optional[bool]	stratified = False,
		Optional[XGBStratifiedKFold]	folds = None,
		bool	shuffle = True
	)

Make an n-fold list of CVPack from random indices.

train()

Booster xgboost.training.train	(	Dict[str, Any]	params,
		DMatrix	dtrain,
		int	num_boost_round = 10,
		*Optional[Sequence[Tuple[DMatrix, str]]]	evals = None,
		Optional[Objective]	obj = None,
		Optional[Metric]	feval = None,
		Optional[bool]	maximize = None,
		Optional[int]	early_stopping_rounds = None,
		Optional[TrainingCallback.EvalsLog]	evals_result = None,
		Optional[Union[bool, int]]	verbose_eval = True,
		Optional[Union[str, os.PathLike, Booster, bytearray]]	xgb_model = None,
		Optional[Sequence[TrainingCallback]]	callbacks = None,
		Optional[Metric]	custom_metric = None
	)

Train a booster with given parameters.

Parameters
----------
params :
    Booster params.
dtrain :
    Data to be trained.
num_boost_round :
    Number of boosting iterations.
evals :
    List of validation sets for which metrics will evaluated during training.
    Validation metrics will help us track the performance of the model.
obj
    Custom objective function.  See :doc:`Custom Objective
    </tutorials/custom_metric_obj>` for details.
feval :
    .. deprecated:: 1.6.0
        Use `custom_metric` instead.
maximize :
    Whether to maximize feval.
early_stopping_rounds :
    Activates early stopping. Validation metric needs to improve at least once in
    every **early_stopping_rounds** round(s) to continue training.
    Requires at least one item in **evals**.
    The method returns the model from the last iteration (not the best one).  Use
    custom callback or model slicing if the best model is desired.
    If there's more than one item in **evals**, the last entry will be used for early
    stopping.
    If there's more than one metric in the **eval_metric** parameter given in
    **params**, the last metric will be used for early stopping.
    If early stopping occurs, the model will have two additional fields:
    ``bst.best_score``, ``bst.best_iteration``.
evals_result :
    This dictionary stores the evaluation results of all the items in watchlist.

    Example: with a watchlist containing
    ``[(dtest,'eval'), (dtrain,'train')]`` and
    a parameter containing ``('eval_metric': 'logloss')``,
    the **evals_result** returns

    .. code-block:: python

        {'train': {'logloss': ['0.48253', '0.35953']},
         'eval': {'logloss': ['0.480385', '0.357756']}}

verbose_eval :
    Requires at least one item in **evals**.
    If **verbose_eval** is True then the evaluation metric on the validation set is
    printed at each boosting stage.
    If **verbose_eval** is an integer then the evaluation metric on the validation set
    is printed at every given **verbose_eval** boosting stage. The last boosting stage
    / the boosting stage found by using **early_stopping_rounds** is also printed.
    Example: with ``verbose_eval=4`` and at least one item in **evals**, an evaluation metric
    is printed every 4 boosting stages, instead of every boosting stage.
xgb_model :
    Xgb model to be loaded before training (allows training continuation).
callbacks :
    List of callback functions that are applied at end of each iteration.
    It is possible to use predefined callbacks by using
    :ref:`Callback API <callback_api>`.

    .. note::

       States in callback are not preserved during training, which means callback
       objects can not be reused for multiple training sessions without
       reinitialization or deepcopy.

    .. code-block:: python

        for params in parameters_grid:
            # be sure to (re)initialize the callbacks before each run
            callbacks = [xgb.callback.LearningRateScheduler(custom_rates)]
            xgboost.train(params, Xy, callbacks=callbacks)

custom_metric:

    .. versionadded 1.6.0

    Custom metric function.  See :doc:`Custom Metric </tutorials/custom_metric_obj>`
    for details.

Returns
-------
Booster : a trained booster model