From 6c1e5d993d6952e2433269d7937ebdc9b0762e3c Mon Sep 17 00:00:00 2001 From: fis Date: Sun, 19 Dec 2021 14:46:55 +0800 Subject: [PATCH 1/7] [doc] Use cross references in sphinx doc. * Use cross references instead of URL. * Fix auto doc for callback. --- doc/python/callbacks.rst | 2 +- doc/python/python_api.rst | 23 ++++++++++++++++++----- python-package/xgboost/core.py | 29 +++++++++++++---------------- python-package/xgboost/dask.py | 5 ++--- python-package/xgboost/sklearn.py | 18 ++++++++---------- python-package/xgboost/training.py | 20 ++++++++------------ 6 files changed, 50 insertions(+), 47 deletions(-) diff --git a/doc/python/callbacks.rst b/doc/python/callbacks.rst index b3302d7f7304..a372cc968b76 100644 --- a/doc/python/callbacks.rst +++ b/doc/python/callbacks.rst @@ -54,6 +54,6 @@ this callback function directly into XGBoost: Defining your own callback -------------------------- -XGBoost provides an callback interface class: ``xgboost.callback.TrainingCallback``, user +XGBoost provides an callback interface class: :py:class:`xgboost.callback.TrainingCallback`, user defined callbacks should inherit this class and override corresponding methods. There's a working example in `demo/guide-python/callbacks.py `_ diff --git a/doc/python/python_api.rst b/doc/python/python_api.rst index 2d0b1ed9f960..81b220239fd2 100644 --- a/doc/python/python_api.rst +++ b/doc/python/python_api.rst @@ -77,15 +77,28 @@ Plotting API Callback API ------------ -.. autofunction:: xgboost.callback.TrainingCallback +.. autoclass:: xgboost.callback.TrainingCallback + :members: -.. autofunction:: xgboost.callback.EvaluationMonitor +.. autoclass:: xgboost.callback.EvaluationMonitor + :members: + :inherited-members: + :show-inheritance: -.. autofunction:: xgboost.callback.EarlyStopping +.. autoclass:: xgboost.callback.EarlyStopping + :members: + :inherited-members: + :show-inheritance: -.. autofunction:: xgboost.callback.LearningRateScheduler +.. autoclass:: xgboost.callback.LearningRateScheduler + :members: + :inherited-members: + :show-inheritance: -.. autofunction:: xgboost.callback.TrainingCheckPoint +.. autoclass:: xgboost.callback.TrainingCheckPoint + :members: + :inherited-members: + :show-inheritance: .. _dask_api: diff --git a/python-package/xgboost/core.py b/python-package/xgboost/core.py index e4187a7108ec..24ded0c614f2 100644 --- a/python-package/xgboost/core.py +++ b/python-package/xgboost/core.py @@ -1817,9 +1817,8 @@ def predict( .. note:: - See `Prediction - `_ - for issues like thread safety and a summary of outputs from this function. + See :doc:`Prediction ` for issues like thread safety and a + summary of outputs from this function. Parameters ---------- @@ -1945,8 +1944,8 @@ def inplace_predict( base_margin: Any = None, strict_shape: bool = False ): - """Run prediction in-place, Unlike ``predict`` method, inplace prediction does - not cache the prediction result. + """Run prediction in-place, Unlike :py:meth:`predict` method, inplace prediction does not + cache the prediction result. Calling only ``inplace_predict`` in multiple threads is safe and lock free. But the safety does not hold when used in conjunction with other @@ -1971,7 +1970,7 @@ def inplace_predict( ``predictor`` to ``gpu_predictor`` for running prediction on CuPy array or CuDF DataFrame. iteration_range : - See :py:meth:`xgboost.Booster.predict` for details. + See :py:meth:`predict` for details. predict_type : * `value` Output model prediction values. * `margin` Output the raw untransformed margin value. @@ -2127,9 +2126,8 @@ def save_model(self, fname: Union[str, os.PathLike]) -> None: The model is saved in an XGBoost internal format which is universal among the various XGBoost interfaces. Auxiliary attributes of the Python Booster object (such as feature_names) will not be saved when using binary format. To save those - attributes, use JSON instead. See: `Model IO - `_ for more - info. + attributes, use JSON instead. See :doc:`Model IO ` for + more info. Parameters ---------- @@ -2165,9 +2163,8 @@ def load_model(self, fname: Union[str, bytearray, os.PathLike]) -> None: The model is loaded from XGBoost format which is universal among the various XGBoost interfaces. Auxiliary attributes of the Python Booster object (such as feature_names) will not be loaded when using binary format. To save those - attributes, use JSON instead. See: `Model IO - `_ for more - info. + attributes, use JSON instead. See :doc:`Model IO ` for + more info. Parameters ---------- @@ -2215,7 +2212,7 @@ def num_features(self) -> int: return features.value def dump_model(self, fout, fmap='', with_stats=False, dump_format="text"): - """Dump model into a text or JSON file. Unlike `save_model`, the + """Dump model into a text or JSON file. Unlike :py:meth:`save_model`, the output format is primarily used for visualization or interpretation, hence it's more human readable but cannot be loaded back to XGBoost. @@ -2258,9 +2255,9 @@ def get_dump( with_stats: bool = False, dump_format: str = "text" ) -> List[str]: - """Returns the model dump as a list of strings. Unlike `save_model`, the - output format is primarily used for visualization or interpretation, - hence it's more human readable but cannot be loaded back to XGBoost. + """Returns the model dump as a list of strings. Unlike :py:meth:`save_model`, the output + format is primarily used for visualization or interpretation, hence it's more + human readable but cannot be loaded back to XGBoost. Parameters ---------- diff --git a/python-package/xgboost/dask.py b/python-package/xgboost/dask.py index cb972afa3e8c..4b70a4fbee09 100644 --- a/python-package/xgboost/dask.py +++ b/python-package/xgboost/dask.py @@ -3,9 +3,8 @@ # pylint: disable=too-many-lines, fixme # pylint: disable=too-few-public-methods # pylint: disable=import-error -"""Dask extensions for distributed training. See -https://xgboost.readthedocs.io/en/latest/tutorials/dask.html for simple -tutorial. Also xgboost/demo/dask for some examples. +"""Dask extensions for distributed training. See :doc:`Distributed XGBoost with Dask +` for simple tutorial. Also xgboost/demo/dask for some examples. There are two sets of APIs in this module, one is the functional API including ``train`` and ``predict`` methods. Another is stateful Scikit-Learner wrapper diff --git a/python-package/xgboost/sklearn.py b/python-package/xgboost/sklearn.py index 949dae7b46c7..e3d2ae8d53f8 100644 --- a/python-package/xgboost/sklearn.py +++ b/python-package/xgboost/sklearn.py @@ -122,10 +122,10 @@ def inner(y_score: np.ndarray, dmatrix: DMatrix) -> Tuple[str, float]: booster: Optional[str] Specify which booster to use: gbtree, gblinear or dart. tree_method: Optional[str] - Specify which tree method to use. Default to auto. If this parameter - is set to default, XGBoost will choose the most conservative option - available. It's recommended to study this option from the parameters - document: https://xgboost.readthedocs.io/en/latest/treemethod.html. + Specify which tree method to use. Default to auto. If this parameter is set to + default, XGBoost will choose the most conservative option available. It's + recommended to study this option from the parameters document :doc:`tree method + ` n_jobs : Optional[int] Number of parallel threads used to run xgboost. When used with other Scikit-Learn algorithms like grid search, you may choose which algorithm to parallelize and @@ -216,9 +216,8 @@ def inner(y_score: np.ndarray, dmatrix: DMatrix) -> Tuple[str, float]: For advanced usage on Early stopping like directly choosing to maximize instead of minimize, see :py:obj:`xgboost.callback.EarlyStopping`. - See `Custom Objective and Evaluation Metric - `_ for - more. + See :doc:`Custom Objective and Evaluation Metric ` + for more. .. note:: @@ -268,9 +267,8 @@ def inner(y_score: np.ndarray, dmatrix: DMatrix) -> Tuple[str, float]: save_best=True)] kwargs : dict, optional - Keyword arguments for XGBoost Booster object. Full documentation of - parameters can be found here: - https://github.com/dmlc/xgboost/blob/master/doc/parameter.rst. + Keyword arguments for XGBoost Booster object. Full documentation of parameters + can be found :doc:`here `. Attempting to set a parameter via the constructor args and \\*\\*kwargs dict simultaneously will result in a TypeError. diff --git a/python-package/xgboost/training.py b/python-package/xgboost/training.py index 3cb6b2936c54..9066124a4cd6 100644 --- a/python-package/xgboost/training.py +++ b/python-package/xgboost/training.py @@ -76,9 +76,8 @@ def train( 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 `Custom Objective - `_ for - details. + Custom objective function. See :doc:`Custom Objective + ` for details. feval : .. deprecated:: 1.6.0 Use `custom_metric` instead. @@ -134,9 +133,8 @@ def train( .. versionadded 1.6.0 - Custom metric function. See `Custom Metric - `_ for - details. + Custom metric function. See :doc:`Custom Metric ` + for details. Returns ------- @@ -387,9 +385,8 @@ def cv(params, dtrain, num_boost_round=10, nfold=3, stratified=False, folds=None Evaluation metrics to be watched in CV. obj : - Custom objective function. See `Custom Objective - `_ for - details. + Custom objective function. See :doc:`Custom Objective + ` for details. feval : function .. deprecated:: 1.6.0 @@ -434,9 +431,8 @@ def cv(params, dtrain, num_boost_round=10, nfold=3, stratified=False, folds=None .. versionadded 1.6.0 - Custom metric function. See `Custom Metric - `_ for - details. + Custom metric function. See :doc:`Custom Metric ` + for details. Returns ------- From 2812fceb4c293f71e2bffd930301c90b76dc3112 Mon Sep 17 00:00:00 2001 From: fis Date: Sun, 19 Dec 2021 14:51:46 +0800 Subject: [PATCH 2/7] Remove prefix. --- doc/treemethod.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/treemethod.rst b/doc/treemethod.rst index f47b8c027322..e22a8c7095bf 100644 --- a/doc/treemethod.rst +++ b/doc/treemethod.rst @@ -1,6 +1,6 @@ -#################### -XGBoost Tree Methods -#################### +############ +Tree Methods +############ For training boosted tree models, there are 2 parameters used for choosing algorithms, namely ``updater`` and ``tree_method``. XGBoost has 4 builtin tree methods, namely From b88debdf8012d3cc41575ef6d7b68e5d1bfae196 Mon Sep 17 00:00:00 2001 From: fis Date: Mon, 20 Dec 2021 23:12:29 +0800 Subject: [PATCH 3/7] Remove 2 more. --- doc/parameter.rst | 5 ++++- python-package/xgboost/config.py | 4 ++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/parameter.rst b/doc/parameter.rst index 97f6232d8397..bb2666737c5b 100644 --- a/doc/parameter.rst +++ b/doc/parameter.rst @@ -16,10 +16,13 @@ Before running XGBoost, we must set three types of parameters: general parameter :backlinks: none :local: + +.. _global_config: + ******************** Global Configuration ******************** -The following parameters can be set in the global scope, using ``xgb.config_context()`` (Python) or ``xgb.set.config()`` (R). +The following parameters can be set in the global scope, using :py:func:`xgboost.config_context()` (Python) or ``xgb.set.config()`` (R). * ``verbosity``: Verbosity of printing messages. Valid values of 0 (silent), 1 (warning), 2 (info), and 3 (debug). * ``use_rmm``: Whether to use RAPIDS Memory Manager (RMM) to allocate GPU memory. This option is only applicable when XGBoost is built (compiled) with the RMM plugin enabled. Valid values are ``true`` and ``false``. diff --git a/python-package/xgboost/config.py b/python-package/xgboost/config.py index 3ff9f97942a9..427ea4ea3915 100644 --- a/python-package/xgboost/config.py +++ b/python-package/xgboost/config.py @@ -30,8 +30,8 @@ def config_doc(*, header=None, extra_note=None, parameters=None, returns=None, {header} Global configuration consists of a collection of parameters that can be applied in the - global scope. See https://xgboost.readthedocs.io/en/stable/parameter.html for the full - list of parameters supported in the global configuration. + global scope. See :ref:`global_config` for the full list of parameters supported in + the global configuration. {extra_note} From 6a448c9ea055cb6a4982d7e9e2ac8ae88e20de57 Mon Sep 17 00:00:00 2001 From: fis Date: Mon, 20 Dec 2021 23:27:22 +0800 Subject: [PATCH 4/7] Remove 2 more. --- doc/tutorials/custom_metric_obj.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/tutorials/custom_metric_obj.rst b/doc/tutorials/custom_metric_obj.rst index b84229599364..c5bdb2d6f3c6 100644 --- a/doc/tutorials/custom_metric_obj.rst +++ b/doc/tutorials/custom_metric_obj.rst @@ -146,7 +146,8 @@ We will be able to see XGBoost printing something like: Notice that the parameter ``disable_default_eval_metric`` is used to suppress the default metric in XGBoost. -For fully reproducible source code and comparison plots, see `custom_rmsle.py `_. +For fully reproducible source code and comparison plots, see +:ref:`sphx_glr_python_examples_custom_rmsle.py`. ********************* Reverse Link Function @@ -261,8 +262,7 @@ available in XGBoost: We use ``multi:softmax`` to illustrate the differences of transformed prediction. With ``softprob`` the output prediction array has shape ``(n_samples, n_classes)`` while for ``softmax`` it's ``(n_samples, )``. A demo for multi-class objective function is also -available at `demo/guide-python/custom_softmax.py -`_ +available at :ref:`sphx_glr_python_examples_custom_softmax.py`. ********************** From 2c86da427228b8faa67722ffd6d7450147e1dc32 Mon Sep 17 00:00:00 2001 From: fis Date: Tue, 21 Dec 2021 10:34:18 +0800 Subject: [PATCH 5/7] Add more references. --- doc/python/callbacks.rst | 20 +++++++++++--------- doc/python/python_api.rst | 1 + python-package/xgboost/callback.py | 6 +++++- 3 files changed, 17 insertions(+), 10 deletions(-) diff --git a/doc/python/callbacks.rst b/doc/python/callbacks.rst index a372cc968b76..7cb257a819ed 100644 --- a/doc/python/callbacks.rst +++ b/doc/python/callbacks.rst @@ -2,10 +2,11 @@ Callback Functions ################## -This document gives a basic walkthrough of callback function used in XGBoost Python -package. In XGBoost 1.3, a new callback interface is designed for Python package, which -provides the flexibility of designing various extension for training. Also, XGBoost has a -number of pre-defined callbacks for supporting early stopping, checkpoints etc. +This document gives a basic walkthrough of :ref:`callback API ` used in +XGBoost Python package. In XGBoost 1.3, a new callback interface is designed for Python +package, which provides the flexibility of designing various extension for training. +Also, XGBoost has a number of pre-defined callbacks for supporting early stopping, +checkpoints etc. Using builtin callbacks @@ -14,8 +15,8 @@ Using builtin callbacks By default, training methods in XGBoost have parameters like ``early_stopping_rounds`` and ``verbose``/``verbose_eval``, when specified the training procedure will define the corresponding callbacks internally. For example, when ``early_stopping_rounds`` is -specified, ``EarlyStopping`` callback is invoked inside iteration loop. You can also pass -this callback function directly into XGBoost: +specified, :py:class:`EarlyStopping ` callback is invoked +inside iteration loop. You can also pass this callback function directly into XGBoost: .. code-block:: python @@ -54,6 +55,7 @@ this callback function directly into XGBoost: Defining your own callback -------------------------- -XGBoost provides an callback interface class: :py:class:`xgboost.callback.TrainingCallback`, user -defined callbacks should inherit this class and override corresponding methods. There's a -working example in `demo/guide-python/callbacks.py `_ +XGBoost provides an callback interface class: :py:class:`TrainingCallback +`, user defined callbacks should inherit this class and +override corresponding methods. There's a working example in +:ref:`sphx_glr_python_examples_callbacks.py`. diff --git a/doc/python/python_api.rst b/doc/python/python_api.rst index 81b220239fd2..9f077edbc0df 100644 --- a/doc/python/python_api.rst +++ b/doc/python/python_api.rst @@ -77,6 +77,7 @@ Plotting API Callback API ------------ +.. automodule:: xgboost.callback .. autoclass:: xgboost.callback.TrainingCallback :members: diff --git a/python-package/xgboost/callback.py b/python-package/xgboost/callback.py index c94f0930474a..901724a67d00 100644 --- a/python-package/xgboost/callback.py +++ b/python-package/xgboost/callback.py @@ -1,7 +1,11 @@ # coding: utf-8 # pylint: disable=invalid-name, too-many-statements, no-self-use # pylint: disable=too-many-arguments -"""Training Library containing training routines.""" +"""Callback library containing training routines. See :doc:`Callback Functions +` for a quick introduction. + +""" + from abc import ABC import collections import os From 7044c6b3706858fec19b78a5c12177c0c8cbc4ae Mon Sep 17 00:00:00 2001 From: fis Date: Tue, 21 Dec 2021 11:14:58 +0800 Subject: [PATCH 6/7] Add more references. --- python-package/xgboost/sklearn.py | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/python-package/xgboost/sklearn.py b/python-package/xgboost/sklearn.py index e3d2ae8d53f8..937d8b4de880 100644 --- a/python-package/xgboost/sklearn.py +++ b/python-package/xgboost/sklearn.py @@ -167,14 +167,14 @@ def inner(y_score: np.ndarray, dmatrix: DMatrix) -> Tuple[str, float]: num_parallel_tree: Optional[int] Used for boosting random forest. monotone_constraints : Optional[Union[Dict[str, int], str]] - Constraint of variable monotonicity. See tutorial for more - information. + Constraint of variable monotonicity. See :doc:`tutorial ` + for more information. interaction_constraints : Optional[Union[str, List[Tuple[str]]]] Constraints for interaction representing permitted interactions. The - constraints must be specified in the form of a nest list, e.g. [[0, 1], - [2, 3, 4]], where each inner list is a group of indices of features - that are allowed to interact with each other. See tutorial for more - information + constraints must be specified in the form of a nested list, e.g. ``[[0, 1], [2, + 3, 4]]``, where each inner list is a group of indices of features that are + allowed to interact with each other. See :doc:`tutorial + ` for more information importance_type: Optional[str] The feature importance type for the feature_importances\\_ property: @@ -242,7 +242,7 @@ def inner(y_score: np.ndarray, dmatrix: DMatrix) -> Tuple[str, float]: 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 **eval_set** in :py:meth:`xgboost.sklearn.XGBModel.fit`. + one item in **eval_set** in :py:meth:`fit`. The method returns the model from the last iteration (not the best one). If there's more than one item in **eval_set**, the last entry will be used for early @@ -250,7 +250,8 @@ def inner(y_score: np.ndarray, dmatrix: DMatrix) -> Tuple[str, float]: will be used for early stopping. If early stopping occurs, the model will have three additional fields: - ``clf.best_score``, ``clf.best_iteration`` and ``clf.best_ntree_limit``. + :py:attr:`best_score`, :py:attr:`best_iteration` and + :py:attr:`best_ntree_limit`. .. note:: @@ -1114,10 +1115,15 @@ def _early_stopping_attr(self, attr: str) -> Union[float, int]: @property def best_score(self) -> float: + """The best score obtained by early stopping.""" return float(self._early_stopping_attr('best_score')) @property def best_iteration(self) -> int: + """The best iteration obtained by early stopping. This attribute is 0-based, + for instance if the best iteration is the first round, then best_iteration is 0. + + """ return int(self._early_stopping_attr('best_iteration')) @property From 4181454bffa5101e90eff3f9406edb9edfd62e7c Mon Sep 17 00:00:00 2001 From: fis Date: Tue, 21 Dec 2021 11:21:55 +0800 Subject: [PATCH 7/7] doc. --- python-package/xgboost/sklearn.py | 1 + 1 file changed, 1 insertion(+) diff --git a/python-package/xgboost/sklearn.py b/python-package/xgboost/sklearn.py index 937d8b4de880..a0f6b3f7340e 100644 --- a/python-package/xgboost/sklearn.py +++ b/python-package/xgboost/sklearn.py @@ -1101,6 +1101,7 @@ def evals_result(self) -> Dict[str, Dict[str, List[float]]]: @property def n_features_in_(self) -> int: + """Number of features seen during :py:meth:`fit`.""" booster = self.get_booster() return booster.num_features()