Expose objective functions to the Python interface.

demo/guide-python/multioutput_reduced_gradient.py

@@ -18,33 +18,18 @@
 from typing import Tuple
 
 import numpy as np
+import xgboost as xgb
 from sklearn.base import BaseEstimator
 from sklearn.datasets import make_regression
-
-import xgboost as xgb
-from xgboost.objective import TreeObjective
+from xgboost.objective import RegSquaredError
 
 
-class LsObjMean(TreeObjective):
-    """Least squared error. Reduce the size of the gradient using mean value."""
+class LsObjMean(RegSquaredError):
+    """Built-in squared error with reduced gradient using mean value."""
 
     def __init__(self, device: str) -> None:
         self.device = device
-
-    def __call__(
-        self, iteration: int, y_pred: np.ndarray, dtrain: xgb.DMatrix
-    ) -> Tuple[np.ndarray, np.ndarray]:
-        y_true = dtrain.get_label()
-        grad = y_pred - y_true
-        if self.device == "cpu":
-            hess = np.ones(grad.shape)
-            return grad, hess
-        else:
-            import cupy as cp
-
-            hess = cp.ones(grad.shape)
-
-            return cp.array(grad), cp.array(hess)
+        super().__init__()
 
     def split_grad(
         self, iteration: int, grad: np.ndarray, hess: np.ndarray
@@ -59,7 +44,7 @@ def split_grad(
         return sgrad, shess
 
 
-def svd_class(device: str) -> BaseEstimator:
+def svd_class() -> BaseEstimator:
     """One of the methods in the sketch boost paper."""
     from sklearn.decomposition import TruncatedSVD
 
@@ -77,10 +62,10 @@ def __init__(self, device: str) -> None:
     def split_grad(
         self, iteration: int, grad: np.ndarray, hess: np.ndarray
     ) -> Tuple[np.ndarray, np.ndarray]:
-        svd = svd_class(self.device)
+        svd = svd_class()
         if self.device == "cuda":
-            grad = grad.get()   # type: ignore
-            hess = hess.get()   # type: ignore
+            grad = grad.get()  # type: ignore
+            hess = hess.get()  # type: ignore
 
         svd.fit(grad)
         grad = svd.transform(grad)
@@ -95,6 +80,7 @@ def split_grad(
 
 
 def main() -> None:
+    """Entry point for the multi-output reduced gradient demo."""
     parser = argparse.ArgumentParser()
     parser.add_argument("--device", choices=["cpu", "cuda"], default="cpu")
     args = parser.parse_args()

doc/python/python_api.rst

@@ -45,6 +45,11 @@ Core Data Structure
 
 .. autoclass:: xgboost.core.Categories
 
+Objective API
+-------------
+.. automodule:: xgboost.objective
+    :members:
+
 Learning API
 ------------
 .. automodule:: xgboost.training
@@ -216,4 +221,4 @@ Collective
 
 .. automodule:: xgboost.tracker
 
-.. autoclass:: xgboost.tracker.RabitTracker
+.. autoclass:: xgboost.tracker.RabitTracker

doc/tutorials/multioutput.rst

@@ -106,17 +106,17 @@ function for leaf values. The `Sketch Boost` paper proposes using dimensionality
 on the gradient matrix. In practice, one can also define a different but related loss with
 a small gradient matrix for finding the tree structure.
 
-To access this feature, create a custom objective that inherits from ``TreeObjective`` and
-implement the ``split_grad`` method.
+To access this feature, create a custom objective that inherits from ``Objective`` or one
+of the built-in objectives, and implement the ``split_grad`` method.
 
 .. code-block:: python
 
-    from xgboost.objective import TreeObjective
+    from xgboost.objective import Objective
     from cuml.decomposition import TruncatedSVD
 
     import cupy as cp
 
-    class LsObj(TreeObjective):
+    class LsObj(Objective):
         def __call__(self, iteration: int, y_pred, dtrain):
             """Least squared error."""
             y_true = dtrain.get_label()

python-package/xgboost/core.py

@@ -87,7 +87,7 @@
     is_pyarrow_available,
     py_str,
 )
-from .objective import Objective, TreeObjective, _grad_arrinf
+from .objective import Objective, _grad_arrinf, _stringify
 
 if TYPE_CHECKING:
     from pandas import DataFrame as PdDataFrame
@@ -2162,13 +2162,11 @@ def set_param(
         elif isinstance(params, str) and value is not None:
             params = [(params, value)]
         for key, val in cast(Iterable[Tuple[str, str]], params):
-            if isinstance(val, np.ndarray):
-                val = val.tolist()
-            elif hasattr(val, "__cuda_array_interface__") and hasattr(val, "tolist"):
-                val = val.tolist()
             if val is not None:
                 _check_call(
-                    _LIB.XGBoosterSetParam(self.handle, c_str(key), c_str(str(val)))
+                    _LIB.XGBoosterSetParam(
+                        self.handle, c_str(key), c_str(_stringify(val))
+                    )
                 )
 
     def update(
@@ -2280,21 +2278,14 @@ def train_one_iter(grad: NumpyOrCupy, hess: NumpyOrCupy) -> None:
         vgrad: Optional[ArrayLike]
         vhess: Optional[ArrayLike]
 
-        if isinstance(fobj, TreeObjective):
-            # full gradient for leaf values
+        if isinstance(fobj, Objective):
             vgrad, vhess = fobj(iteration, y_pred, dtrain)
-            # Reduced gradient for split nodes
             split_grad = fobj.split_grad(iteration, vgrad, vhess)
-            # Switch the role of gradient if there's no split gradient but the tree
-            # objective is used.
             if split_grad is not None:
                 sgrad, shess = split_grad
             else:
                 sgrad, shess = vgrad, vhess
                 vgrad, vhess = None, None
-        elif isinstance(fobj, Objective):
-            sgrad, shess = fobj(iteration, y_pred, dtrain)
-            vgrad, vhess = None, None
         else:
             # Plain callable
             sgrad, shess = fobj(y_pred, dtrain)

python-package/xgboost/objective.py

@@ -1,6 +1,13 @@
+# pylint: disable=missing-class-docstring
 """Experimental support for a new objective interface with target dimension
 reduction.
 
+
+This module exposes built-in objectives like ``reg:squarederror`` into the Python
+interface, and enables users to specify parameters for some objectives like
+``reg:quantileerror``. In addition, one can define a custom ``split_grad`` for training
+vector-leaf models.
+
 .. warning::
 
   Do not use this module unless you want to participate in development.
@@ -11,7 +18,7 @@
 
 import warnings
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Tuple
+from typing import TYPE_CHECKING, Any, Dict, Tuple
 
 import numpy as np
 
@@ -44,18 +51,6 @@ def __call__(
         self, iteration: int, y_pred: ArrayLike, dtrain: "DMatrix"
     ) -> Tuple[ArrayLike, ArrayLike]: ...
 
-
-class TreeObjective(Objective):
-    """Base class for tree-specific custom objective functions.
-
-    .. warning::
-
-        Do not use this class unless you want to participate in development.
-
-    .. versionadded:: 3.2.0
-
-    """
-
     # pylint: disable=unused-argument
     def split_grad(
         self, iteration: int, grad: ArrayLike, hess: ArrayLike
@@ -64,8 +59,179 @@ def split_grad(
         return None
 
 
+class _BuiltInObjective(Objective):
+    """Base class for Python wrappers of built-in C++ objective functions."""
+
+    _name: str = ""
+    _KNOWN_PARAMS: Dict[str, str] = {}
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._params: Dict[str, Any] = {}
+        for py_name in self._KNOWN_PARAMS:
+            self._params[py_name] = kwargs.pop(py_name, None)
+        if kwargs:
+            raise TypeError(f"Unknown parameters for {self._name}: {list(kwargs)}")
+
+    @property
+    def name(self) -> str:
+        """The objective name string."""
+        return self._name
+
+    # pylint: disable=missing-function-docstring
+    def flat_params(self) -> Dict[str, str]:
+        result: Dict[str, str] = {"objective": self._name}
+        for py_name, cpp_name in self._KNOWN_PARAMS.items():
+            value = self._params[py_name]
+            if value is not None:
+                result[cpp_name] = _stringify(value)
+        return result
+
+    def __call__(
+        self, iteration: int, y_pred: ArrayLike, dtrain: "DMatrix"
+    ) -> Tuple[ArrayLike, ArrayLike]:
+        raise RuntimeError(
+            "This method should not be called directly for the built-in objective."
+        )
+
+
+def _stringify(value: Any) -> str:
+    if isinstance(value, bool):
+        return str(int(value))
+    if isinstance(value, np.ndarray):
+        value = value.tolist()
+    elif _is_cupy_alike(value) and hasattr(value, "get"):
+        value = value.get().tolist()
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(str(v) for v in value) + "]"
+    return str(value)
+
+
+# Regression objectives
+
+
+class RegSquaredError(_BuiltInObjective):
+    _name = "reg:squarederror"
+    _KNOWN_PARAMS = {"scale_pos_weight": "scale_pos_weight"}
+
+
+class RegSquaredLogError(_BuiltInObjective):
+    _name = "reg:squaredlogerror"
+
+
+class RegAbsoluteError(_BuiltInObjective):
+    _name = "reg:absoluteerror"
+
+
+class RegPseudoHuberError(_BuiltInObjective):
+    _name = "reg:pseudohubererror"
+    _KNOWN_PARAMS = {"delta": "huber_slope"}
+
+
+class RegQuantileError(_BuiltInObjective):
+    _name = "reg:quantileerror"
+    _KNOWN_PARAMS = {"alpha": "quantile_alpha"}
+
+
+class RegExpectileError(_BuiltInObjective):
+    _name = "reg:expectileerror"
+    _KNOWN_PARAMS = {"alpha": "expectile_alpha"}
+
+
+class RegTweedie(_BuiltInObjective):
+    _name = "reg:tweedie"
+    _KNOWN_PARAMS = {"variance_power": "tweedie_variance_power"}
+
+
+class CountPoisson(_BuiltInObjective):
+    _name = "count:poisson"
+    _KNOWN_PARAMS = {"max_delta_step": "max_delta_step"}
+
+
+# Logistic / classification objectives
+
+
+class RegLogistic(_BuiltInObjective):
+    _name = "reg:logistic"
+    _KNOWN_PARAMS = {"scale_pos_weight": "scale_pos_weight"}
+
+
+class BinaryLogistic(_BuiltInObjective):
+    _name = "binary:logistic"
+    _KNOWN_PARAMS = {"scale_pos_weight": "scale_pos_weight"}
+
+
+class RegGamma(_BuiltInObjective):
+    _name = "reg:gamma"
+    _KNOWN_PARAMS = {"scale_pos_weight": "scale_pos_weight"}
+
+
+class BinaryLogitRaw(_BuiltInObjective):
+    _name = "binary:logitraw"
+    _KNOWN_PARAMS = {"scale_pos_weight": "scale_pos_weight"}
+
+
+class BinaryHinge(_BuiltInObjective):
+    _name = "binary:hinge"
+
+
+# Multiclass objectives
+
+
+class MultiSoftmax(_BuiltInObjective):
+    _name = "multi:softmax"
+    _KNOWN_PARAMS = {"num_class": "num_class"}
+
+
+class MultiSoftprob(_BuiltInObjective):
+    _name = "multi:softprob"
+    _KNOWN_PARAMS = {"num_class": "num_class"}
+
+
+# Survival objectives
+
+
+class SurvivalAFT(_BuiltInObjective):
+    _name = "survival:aft"
+    _KNOWN_PARAMS = {
+        "distribution": "aft_loss_distribution",
+        "distribution_scale": "aft_loss_distribution_scale",
+    }
+
+
+class SurvivalCox(_BuiltInObjective):
+    _name = "survival:cox"
+
+
+# Ranking objectives
+
+
+class RankNDCG(_BuiltInObjective):
+    _name = "rank:ndcg"
+    _KNOWN_PARAMS = {
+        "pair_method": "lambdarank_pair_method",
+        "num_pair_per_sample": "lambdarank_num_pair_per_sample",
+        "unbiased": "lambdarank_unbiased",
+        "exp_gain": "ndcg_exp_gain",
+    }
+
+
+class RankPairwise(_BuiltInObjective):
+    _name = "rank:pairwise"
+    _KNOWN_PARAMS = {
+        "pair_method": "lambdarank_pair_method",
+        "num_pair_per_sample": "lambdarank_num_pair_per_sample",
+    }
+
+
+class RankMAP(_BuiltInObjective):
+    _name = "rank:map"
+    _KNOWN_PARAMS = {
+        "pair_method": "lambdarank_pair_method",
+        "num_pair_per_sample": "lambdarank_num_pair_per_sample",
+    }
+
+
 def _grad_arrinf(array: NumpyOrCupy, n_samples: int) -> bytes:
-    # Can we check for __array_interface__ instead of a specific type instead?
     msg = (
         "Expecting `np.ndarray` or `cupy.ndarray` for gradient and hessian."
         f" Got: {type(array)}"