XGBoost

https://xgboost.readthedocs.io/en/latest/
Admin
XGBoost is an optimized distributed gradient boosting library designed for efficient, flexible, and...
Tokens:1,308,131
Snippets:10,341
Trust Score:9.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example: Binary classification setup

Source: https://xgboost.readthedocs.io/en/latest/r_docs/R-package/docs/reference/xgb.cb.gblinear.history.html

This example sets the number of threads to 1 for reproducibility. It is the beginning of a binary classification example that uses the callback.

```r
#### Binary classification:

## Keep the number of threads to 1 for examples
nthread <- 1
data.table::setDTthreads(nthread)
```

--------------------------------

### Method: start()

Source: https://xgboost.readthedocs.io/en/latest/jvm_docs/javadocs/ml/dmlc/xgboost4j/java/RabitTracker.html

Starts the Rabit tracker.

```APIDOC
## start()

### Description
Starts the Rabit tracker to coordinate distributed workers.

### Method Signature
`public boolean start() throws XGBoostError`

### Returns
- **boolean** - Indicates whether the tracker started successfully.

### Throws
- `XGBoostError` - If an error occurs while starting the tracker.
```

--------------------------------

### start() - Method in class ml.dmlc.xgboost4j.java.RabitTracker

Source: https://xgboost.readthedocs.io/en/latest/jvm_docs/javadocs/index-all.html

Starts the Rabit tracker.

```APIDOC
## start()

### Description
Starts the Rabit tracker.

### Method
start

```

--------------------------------

### start()

Source: https://xgboost.readthedocs.io/en/latest/jvm_docs/javadocs/ml/dmlc/xgboost4j/java/ITracker.html

Starts the tracker, awaiting worker connections.

```APIDOC
## start()

### Description
Starts the tracker, awaiting worker connections.

### Method
`boolean start()`

### Throws
- `XGBoostError`

### Return Value
- `boolean` - Indicates whether the tracker started successfully.
```

--------------------------------

### Example: Set and get verbosity level

Source: https://xgboost.readthedocs.io/en/latest/r_docs/R-package/docs/reference/xgbConfig.html

Demonstrates setting the global verbosity level to 0 (silent) and then to 1 (warning) using xgb.set.config(), and retrieving the current value with xgb.get.config(). The example prints the verbosity after each set.

```r
# Set verbosity level to silent (0)
xgb.set.config(verbosity = 0)
# Now global verbosity level is 0
config <- xgb.get.config()
print(config$verbosity)
# Set verbosity level to warning (1)
xgb.set.config(verbosity = 1)
# Now global verbosity level is 1
config <- xgb.get.config()
print(config$verbosity)
```

--------------------------------

### start() - Method in interface ml.dmlc.xgboost4j.java.ITracker

Source: https://xgboost.readthedocs.io/en/latest/jvm_docs/javadocs/index-all.html

Starts the tracker.

```APIDOC
## start()

### Description
Starts the tracker.

### Method
start

```

--------------------------------

### Set and get DMatrix labels

Source: https://xgboost.readthedocs.io/en/latest/_sources/tutorials/c_api_tutorial.rst.txt

Demonstrates setting labels on a DMatrix using XGDMatrixSetFloatInfo and retrieving them with XGDMatrixGetFloatInfo. The example creates a DMatrix from a matrix, sets labels as float values, and prints them.

```c
  const int ROWS=5, COLS=3;
  const int data[ROWS][COLS] = { {1, 2, 3}, {2, 4, 6}, {3, -1, 9}, {4, 8, -1}, {2, 5, 1}, {0, 1, 5} };
  DMatrixHandle dmatrix;

  safe_xgboost(XGDMatrixCreateFromMat(data, ROWS, COLS, -1, &dmatrix));

  // variable to store labels for the dataset created from above matrix
  float labels[ROWS];

  for (int i = 0; i < ROWS; i++) {
    labels[i] = i;
  }

  // Loading the labels
  safe_xgboost(XGDMatrixSetFloatInfo(dmatrix, "label", labels, ROWS));

  // reading the labels and store the length of the result
  bst_ulong result_len;

  // labels result
  const float *result;

  safe_xgboost(XGDMatrixGetFloatInfo(dmatrix, "label", &result_len, &result));

  for(unsigned int i = 0; i < result_len; i++) {
    printf("label[%i] = %f\n", i, result[i]);
  }
```

--------------------------------

### Main entry point: run both continuation demos with pickle and JSON

Source: https://xgboost.readthedocs.io/en/latest/_downloads/c5c09a1e215d95eadfd0916e0d732644/continuation.ipynb

Executes training_continuation_early_stop and training_continuation with both use_pickle=False and use_pickle=True inside a temporary directory.

```python
if __name__ == "__main__":
    with tempfile.TemporaryDirectory() as tmpdir:
        training_continuation_early_stop(tmpdir, False)
        training_continuation_early_stop(tmpdir, True)

        training_continuation(tmpdir, True)
        training_continuation(tmpdir, False)
```

--------------------------------

### RabitTracker usage example

Source: https://xgboost.readthedocs.io/en/latest/python/python_api.html

Creates a RabitTracker with two workers on localhost, starts it, and uses a CommunicatorContext to broadcast a message. The example asserts that the broadcast returns the original message.

```python
from xgboost.tracker import RabitTracker
from xgboost import collective as coll

tracker = RabitTracker(host_ip="127.0.0.1", n_workers=2)
tracker.start()

with coll.CommunicatorContext(**tracker.worker_args()):
    ret = coll.broadcast("msg", 0)
    assert str(ret) == "msg"
```

--------------------------------

### get_metadata_routing()

Source: https://xgboost.readthedocs.io/en/latest/python/python_api.html

Get metadata routing of this object. See scikit-learn User Guide for details on the routing mechanism.

```APIDOC
## get_metadata_routing()

### Description
Get metadata routing of this object. Please check User Guide on how the routing mechanism works.

### Method
get_metadata_routing

### Returns
- **routing** - A MetadataRequest encapsulating routing information.

### Return Type
MetadataRequest
```

--------------------------------

### Command-line entry point with device selection and async pool

Source: https://xgboost.readthedocs.io/en/latest/_sources/python/examples/external_memory.rst.txt

Parses command-line arguments for device (cpu or cuda). For cuda, sets up the async pool and uses `xgboost.config_context(use_cuda_async_pool=True)`; otherwise runs training directly. Both paths use a temporary directory.

```python
if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--device", choices=["cpu", "cuda"], default="cpu")
    args = parser.parse_args()
    if args.device == "cuda":
        setup_async_pool()
        # Make sure XGBoost is using the CUDA async pool for all allocations.
        with xgboost.config_context(use_cuda_async_pool=True):
            with tempfile.TemporaryDirectory() as tmpdir:
                main(tmpdir, args)
    else:
        with tempfile.TemporaryDirectory() as tmpdir:
            main(tmpdir, args)
```

--------------------------------

### XGBRanker.get_metadata_routing

Source: https://xgboost.readthedocs.io/en/latest/python/python_api.html

Get metadata routing of this object. Please check User Guide on how the routing mechanism works.

```APIDOC
## XGBRanker.get_metadata_routing

### Description
Get metadata routing of this object. Please check User Guide on how the routing mechanism works.

### Method
get_metadata_routing

### Response
#### Success Response
- **routing** (MetadataRequest) - A MetadataRequest encapsulating routing information.

```

--------------------------------

### get_metadata_routing()

Source: https://xgboost.readthedocs.io/en/latest/python/python_api.html

Get metadata routing of this object. Please check User Guide on how the routing mechanism works.

```APIDOC
## get_metadata_routing()

### Description
Get metadata routing of this object. Please check User Guide on how the routing mechanism works.

### Returns
- **routing** - A MetadataRequest encapsulating routing information.
- **Return type** - MetadataRequest
```

--------------------------------

### Nested xgb.config_context example

Source: https://xgboost.readthedocs.io/en/latest/python/python_api.html

Demonstrates nested usage of the xgb.config_context context manager, showing that inner contexts override outer settings and restore previous values upon exit. Also shows setting configuration with xgb.set_config and verifying with assertions.

```python
with xgb.config_context(verbosity=3):
    assert xgb.get_config()["verbosity"] == 3
    with xgb.config_context(verbosity=2):
        assert xgb.get_config()["verbosity"] == 2

xgb.set_config(verbosity=2)
assert xgb.get_config()["verbosity"] == 2
with xgb.config_context(verbosity=3):
    assert xgb.get_config()["verbosity"] == 3
```

--------------------------------

### ITracker trait

Source: https://xgboost.readthedocs.io/en/latest/jvm_docs/scaladocs/xgboost4j/ml/dmlc/xgboost4j/java/ITracker.html

Interface for tracker implementations with methods to start, get worker args, wait for tasks, and stop.

```APIDOC
## ITracker

### Description
Interface for a tracker implementations with three public methods:
- start(timeout): Start the tracker awaiting for worker connections, with a given timeout value (in seconds).
- getWorkerArgs(): Return the arguments needed to initialize Rabit clients.
- waitFor(timeout): Wait for the task execution by the worker nodes for at most `timeout` milliseconds.

Each implementation is expected to implement a callback function `uncaughtException(Thread t, Throwable e)` to interrupt waitFor() in order to prevent the tracker from hanging indefinitely.

The Rabit tracker handles connections from distributed workers, assigns ranks to workers, and brokers connections between workers.

### Methods

#### start(): Boolean
- **Description**: Start the tracker awaiting for worker connections.
- **Returns**: Boolean indicating success.

#### getWorkerArgs(): Map[String, AnyRef]
- **Description**: Return the arguments needed to initialize Rabit clients.
- **Returns**: Map of worker arguments.

#### waitFor(taskExecutionTimeout: Long): Unit
- **Description**: Wait for the task execution by the worker nodes for at most `taskExecutionTimeout` milliseconds.
- **Parameters**:
  - `taskExecutionTimeout` (Long) - Timeout in milliseconds.

#### stop(): Unit
- **Description**: Stop the tracker.

#### uncaughtException(arg0: Thread, arg1: Throwable): Unit
- **Description**: Callback to handle uncaught exceptions, used to interrupt waitFor().
- **Parameters**:
  - `arg0` (Thread) - The thread where the exception occurred.
  - `arg1` (Throwable) - The throwable exception.

```

--------------------------------

### Typical usage of xgboost::Learner

Source: https://xgboost.readthedocs.io/en/latest/dev/classxgboost_1_1Learner.html

Shows the typical workflow of creating a Learner, configuring it, and running training iterations with evaluation. The example uses std::unique_ptr and calls Create, Configure, UpdateOneIter, and EvalOneIter.

```cpp
std::unique_ptr<Learner> learner{Learner::Create(cache_mats)};
learner->Configure(configs);
for (int iter = 0; iter < max_iter; ++iter) {
  learner->UpdateOneIter(iter, train_mat);
  LOG(INFO) << learner->EvalOneIter(iter, data_sets, data_names);
}
```

--------------------------------

### Predict with a trained XGBoost model

Source: https://xgboost.readthedocs.io/en/latest/python/python_intro.html

Create a DMatrix from random data and call `bst.predict(dtest)` to get predictions. The example uses 7 entities with 10 features each.

```python
# 7 entities, each contains 10 features
data = np.random.rand(7, 10)
dtest = xgb.DMatrix(data)
ypred = bst.predict(dtest)
```

--------------------------------

### SocketStartup()

Source: https://xgboost.readthedocs.io/en/latest/dev/namespacexgboost_1_1system.html

Initializes the socket subsystem.

```APIDOC
## Function: SocketStartup()

### Description
Initializes the socket subsystem.

### Signature
```cpp
void xgboost::system::SocketStartup();
```

### Returns
- **void** - This function does not return a value.
```

--------------------------------

### Specify RMM location with CMAKE_PREFIX_PATH

Source: https://xgboost.readthedocs.io/en/latest/_sources/python/rmm-examples/index.rst.txt

If CMake cannot find RMM, specify its location using -DCMAKE_PREFIX_PATH. Two examples are given: one for Conda installations and one for custom locations.

```sh
# If using Conda:
cmake -B build -S . -DUSE_CUDA=ON -DUSE_NCCL=ON -DPLUGIN_RMM=ON -DCMAKE_PREFIX_PATH=$CONDA_PREFIX
```

```sh
# If using RMM installed with a custom location
cmake -B build -S . -DUSE_CUDA=ON -DUSE_NCCL=ON -DPLUGIN_RMM=ON -DCMAKE_PREFIX_PATH=/path/to/rmm
```

--------------------------------

### Init(Args const &kwargs)

Source: https://xgboost.readthedocs.io/en/latest/dev/structxgboost_1_1Context-members.html

Initialises the Context with the given keyword arguments.

```APIDOC
## Init(Args const &kwargs)

### Description
Initialises the Context with the given keyword arguments.

### Method
Member function

### Signature
`Init(Args const &kwargs)`
```

--------------------------------

### ITracker.start()

Source: https://xgboost.readthedocs.io/en/latest/jvm_docs/javadocs/ml/dmlc/xgboost4j/java/class-use/XGBoostError.html

Starts the tracker.

```APIDOC
## ITracker.start()

### Description
Starts the tracker.

### Method
start

### Parameters
None.

### Returns
boolean - Whether the tracker started successfully.
```

--------------------------------

### Install Python package with custom CMake options

Source: https://xgboost.readthedocs.io/en/latest/_sources/build.rst.txt

Use --config-settings cmake.define.[CMAKE_OPTION]=[OPTION_VALUE] to customize CMake options. Example enables CUDA and NCCL. Requires pip 22.1+.

```console
$ pip install -v . \
    --config-settings cmake.define.USE_CUDA=ON \
    --config-settings cmake.define.USE_NCCL=ON
```

--------------------------------

### Example: Get quantile cuts after training hist model

Source: https://xgboost.readthedocs.io/en/latest/r_docs/R-package/docs/reference/xgb.get.DMatrix.qcut.html

Shows how to create an xgb.DMatrix, train a histogram model with max_bin=8, and then retrieve the quantile cuts with xgb.get.DMatrix.qcut. The DMatrix is not quantized until a hist model is generated.

```r
data(mtcars)

y <- mtcars$mpg
x <- as.matrix(mtcars[, -1])
dm <- xgb.DMatrix(x, label = y, nthread = 1)

# DMatrix is not quantized right away, but will be once a hist model is generated
model <- xgb.train(
  data = dm,
  params = xgb.params(tree_method = "hist", max_bin = 8, nthread = 1),
  nrounds = 3
)

# Now can get the quantile cuts
xgb.get.DMatrix.qcut(dm)
```

--------------------------------

### xgboost::system::SocketStartup

Source: https://xgboost.readthedocs.io/en/latest/dev/socket_8h.html

Initializes the socket subsystem.

```APIDOC
## SocketStartup

### Description
Initializes the socket subsystem.

### Function Signature
`void xgboost::system::SocketStartup()`

### Parameters
None.

### Return Value
None.
```

--------------------------------

### Example: Retrieve configuration with xgb.config

Source: https://xgboost.readthedocs.io/en/latest/r_docs/R-package/docs/reference/xgb.config.html

Trains a binary logistic model on the agaricus dataset and retrieves its configuration as a list. Sets the number of threads to 1 for the example.

```r
data(agaricus.train, package = "xgboost")

## Keep the number of threads to 1 for examples
nthread <- 1
data.table::setDTthreads(nthread)
train <- agaricus.train

bst <- xgb.train(
  data = xgb.DMatrix(train$data, label = train$label, nthread = 1),
  nrounds = 2,
  params = xgb.params(
    max_depth = 2,
    nthread = nthread,
    objective = "binary:logistic"
  )
)

config <- xgb.config(bst)
```

--------------------------------

### Example: Basic use of xgb.model.dt.tree

Source: https://xgboost.readthedocs.io/en/latest/r_docs/R-package/docs/reference/xgb.model.dt.tree.html

Trains a simple binary classification model on the agaricus dataset and then parses the model's tree dump into a data.table. Shows how to merge the result to get feature names for 'Yes' branches.

```r
# Basic use:

data(agaricus.train, package = "xgboost")
## Keep the number of threads to 1 for examples
nthread <- 1
data.table::setDTthreads(nthread)

bst <- xgb.train(
  data = xgb.DMatrix(agaricus.train$data, label = agaricus.train$label, nthread = 1),
  nrounds = 2,
  params = xgb.params(
    max_depth = 2,
    nthread = nthread,
    objective = "binary:logistic"
  )
)

# This bst model already has feature_names stored with it, so those would be used when
# feature_names is not set:
dt <- xgb.model.dt.tree(bst)

# How to match feature names of splits that are following a current 'Yes' branch:
merge(
  dt,
  dt[, .(ID, Y.Feature = Feature)], by.x = "Yes", by.y = "ID", all.x = TRUE
)[
  order(Tree, Node)
]
```

--------------------------------

### Install Python package with automatic CMake build

Source: https://xgboost.readthedocs.io/en/latest/_sources/build.rst.txt

If the shared object is not present, the setup script runs CMake automatically. Use -v for verbose output to monitor progress. Requires pip 22.1+ for --config-settings.

```console
$ cd python-package/
$ pip install -v .
```

--------------------------------

### initializeLogIfNecessary(isInterpreter: Boolean)

Source: https://xgboost.readthedocs.io/en/latest/jvm_docs/scaladocs/xgboost4j-spark/ml/dmlc/xgboost4j/scala/spark/XGBoostClassificationModel.html

Initializes the logging system if needed.

```APIDOC
## initializeLogIfNecessary(isInterpreter: Boolean)

### Description
Initializes logging if necessary.

### Method
GET

### Endpoint
XGBoostClassificationModel.initializeLogIfNecessary(isInterpreter: Boolean)

### Parameters
#### Path Parameters
- **isInterpreter** (Boolean) - Required - Whether the context is an interpreter.
```

--------------------------------

### Get and free categories from DMatrix with XGBoosterGetCategories

Source: https://xgboost.readthedocs.io/en/latest/dev/group__DMatrix.html

Shows how to retrieve the categories container from a DMatrix using XGBoosterGetCategories and free it with XGBCategoriesFree. The example omits error handling for the DMatrix creation and assumes fmat is valid. The API is experimental and subject to change.

```c
DMatrixHandle fmat;
// Create a DMatrix from categorical data
// ...
CategoriesHandle cats;
int err = XGBoosterGetCategories(fmat, NULL, &cats)
if (err != 0) {
exit(-1);
}
err = XGBCategoriesFree(cats);
if (err != 0) {
exit(-1);
}
```

--------------------------------

### Dense matrix example

Source: https://xgboost.readthedocs.io/en/latest/_sources/jvm/java_intro.rst.txt

Shows a sample dense matrix in plain text format.

```none
1    2
3    4
5    6
```

--------------------------------

### Usage of xgb.set.config() and xgb.get.config()

Source: https://xgboost.readthedocs.io/en/latest/r_docs/R-package/docs/reference/xgbConfig.html

Shows the function signatures for setting and getting global configuration parameters. xgb.set.config() takes keyword arguments for parameters, and xgb.get.config() returns a list of all global-scope parameters.

```r
xgb.set.config(...)

xgb.get.config()
```

--------------------------------

### Get and reuse categories with QuantileDMatrix

Source: https://xgboost.readthedocs.io/en/latest/python/python_api.html

Shows how to retrieve categories from a trained booster and use them as feature_types when creating a new QuantileDMatrix for re-coding. The categories are saved with the model, so they do not need to be preserved separately. The example also saves the model to model.json, which includes the categories.

```python
Xy = xgboost.QuantileDMatrix(X, y, enable_categorical=True)
booster = xgboost.train({}, Xy)

categories = booster.get_categories() # Get categories

# Use categories as a reference for re-coding
Xy_new = xgboost.QuantileDMatrix(
    X_new, y_new, feature_types=categories, enable_categorical=True, ref=Xy
)

# Categories will be part of the `model.json`.
booster.save_model("model.json")
```

--------------------------------

### Example feature_segments array for categorical features

Source: https://xgboost.readthedocs.io/en/latest/_sources/tutorials/saving_model.rst.txt

Shows the CSR-like pointer format for category counts. The list starts with zero and ends with the total number of categories. Here, it represents two categorical features (3 and 2 categories) and one numerical feature (0 categories).

```python
feature_segments = [0, 3, 3, 5]
```

--------------------------------

### begin()

Source: https://xgboost.readthedocs.io/en/latest/dev/classxgboost_1_1BatchSet-members.html

Returns an iterator to the beginning of the batch set.

```APIDOC
## begin()

### Description
Returns an iterator to the beginning of the batch set.

### Signature
`begin()`

### Returns
- Iterator to the first batch in the set.

```

--------------------------------

### Configure()

Source: https://xgboost.readthedocs.io/en/latest/dev/classxgboost_1_1Learner.html

Pure virtual method to configure the Learner with a parameter batch.

```APIDOC
## Configure()

### Description
Configure Learner with a parameter batch.

### Method
virtual void xgboost::Learner::Configure(Args const& _args_ = {})

### Parameters
- **args** (Args const&) - Optional - Ordered parameter batch. Repeated parameters are preserved. Default is empty.

### Returns
void
```

--------------------------------

### Install a binary wheel with pip install xgboost-2.0.0-py3-none-linux_x86_64.whl

Source: https://xgboost.readthedocs.io/en/latest/_sources/contrib/python_packaging.rst.txt

Installs a pre-built XGBoost binary wheel. Since the wheel already contains libxgboost.so, no compilation is needed at install time, so installation completes quickly.

```console
$ pip install xgboost-2.0.0-py3-none-linux_x86_64.whl  # Completes quickly
```

--------------------------------

### Install XGBoost with conda

Source: https://xgboost.readthedocs.io/en/latest/_sources/install.rst.txt

Installs py-xgboost from conda-forge. Conda detects GPU and installs the appropriate variant.

```bash
conda install -c conda-forge py-xgboost
```

--------------------------------

### ConfigContext()

Source: https://xgboost.readthedocs.io/en/latest/jvm_docs/javadocs/ml/dmlc/xgboost4j/java/ConfigContext.html

Creates a new ConfigContext instance with default configuration.

```APIDOC
## ConfigContext()

### Description
Creates a new ConfigContext instance with default configuration.

### Method
Constructor

### Signature
public ConfigContext() throws XGBoostError

### Throws
- **XGBoostError** - if an error occurs during initialization

```

--------------------------------

### initializeLogIfNecessary(isInterpreter: Boolean, silent: Boolean)

Source: https://xgboost.readthedocs.io/en/latest/jvm_docs/scaladocs/xgboost4j-spark/ml/dmlc/xgboost4j/scala/spark/XGBoostClassificationModel.html

Initializes the logging system if needed, based on interpreter and silent flags.

```APIDOC
## initializeLogIfNecessary(isInterpreter: Boolean, silent: Boolean)

### Description
Initializes logging if necessary.

### Method
GET

### Endpoint
XGBoostClassificationModel.initializeLogIfNecessary(isInterpreter: Boolean, silent: Boolean)

### Parameters
#### Path Parameters
- **isInterpreter** (Boolean) - Required - Whether the context is an interpreter.
- **silent** (Boolean) - Required - Whether to suppress logging.
```

--------------------------------

### Load data for base_margin example (Python)

Source: https://xgboost.readthedocs.io/en/latest/tutorials/intercept.html

Imports necessary libraries and creates a synthetic binary classification dataset using scikit-learn's make_classification with a fixed random state.

```python
import numpy as np
from scipy.special import logit
from sklearn.datasets import make_classification

import xgboost as xgb

X, y = make_classification(random_state=2025)
```

--------------------------------

### XGTrackerRun

Source: https://xgboost.readthedocs.io/en/latest/dev/c__api_8h.html

Starts the tracker in the background and returns once started.

```APIDOC
## XGTrackerRun

### Description
Start the tracker. The tracker runs in the background and this function returns once the tracker is started.

### Function Signature
int XGTrackerRun (TrackerHandle handle, char const *config)

### Parameters
- **handle** (TrackerHandle) - Required - Tracker handle.
- **config** (char const*) - Required - Configuration string for the tracker run.

### Returns
- **int** - 0 on success, non-zero on error.

```

--------------------------------

### Example ci_container.yml entry for xgb-ci.gpu

Source: https://xgboost.readthedocs.io/en/latest/_sources/contrib/ci.rst.txt

Shows the YAML configuration for the xgb-ci.gpu container, including container_def and build_args such as CUDA_VERSION, NCCL_VERSION, RAPIDS_VERSION, and ARCH.

```yaml
xgb-ci.gpu:
  container_def: gpu
  build_args:
    CUDA_VERSION: "13.3.0"
    NCCL_VERSION: "2.30.7-1"
    RAPIDS_VERSION: "26.04"
    ARCH: x86_64
```

--------------------------------

### Install Python dependencies with pip

Source: https://xgboost.readthedocs.io/en/latest/_sources/contrib/docs.rst.txt

Install required packages from requirements.txt using pip. Installing via conda is not possible because xgboost_ray is unavailable in conda channels.

```bash
pip install -r requirements.txt
```

--------------------------------

### Example: Create and print an xgb.DMatrix

Source: https://xgboost.readthedocs.io/en/latest/r_docs/R-package/docs/reference/print.xgb.DMatrix.html

Creates an xgb.DMatrix from the agaricus.train dataset and prints it, first with default settings and then with verbose=TRUE to show colnames.

```r
data(agaricus.train, package = "xgboost")

dtrain <- with(agaricus.train, xgb.DMatrix(data, label = label, nthread = 2))
dtrain

print(dtrain, verbose = TRUE)
```

--------------------------------

### XGBoost C API: Training, Evaluation, and Prediction with Dense, CSR, and CSC Matrices

Source: https://xgboost.readthedocs.io/en/latest/dev/c-api-demo_8c-example.html

This C example demonstrates the full XGBoost C API workflow: creating DMatrix objects from dense, CSR, and CSC data, training a booster with XGBoosterUpdateOneIter, evaluating with XGBoosterEvalOneIter, and predicting with XGBoosterPredictFromDMatrix. It includes helper functions MakeArrayInterface and MakeConfig for constructing array interface strings and configuration strings. The example prints evaluation results and predictions, and asserts output shapes for the dense, CSR, and CSC prediction examples. It ends by freeing all resources.

```c
safe_xgboost(XGBoosterUpdateOneIter(booster, i, dtrain));
safe_xgboost(XGBoosterEvalOneIter(booster, i, eval_dmats, eval_names, 2, &eval_result));
printf("%s\n", eval_result);
}
bst_ulong num_feature = 0;
safe_xgboost(XGBoosterGetNumFeature(booster, &num_feature));
printf("num_feature: %lu\n", (unsigned long)(num_feature));
// predict
bst_ulong out_len = 0;
int n_print = 10;
/* Run prediction with DMatrix object. */
char const config[] =
"{\"training\": false, \"type\": 0, "
"\"iteration_begin\": 0, \"iteration_end\": 0, \"strict_shape\": false}";
/* Shape of output prediction */
uint64_t const* out_shape;
/* Dimension of output prediction */
uint64_t out_dim;
/* Pointer to a thread local contigious array, assigned in prediction function. */
float const* out_result = NULL;
safe_xgboost(
XGBoosterPredictFromDMatrix(booster, dtest, config, &out_shape, &out_dim, &out_result));
printf("y_pred: ");
for (int i = 0; i < n_print; ++i) {
printf("%1.4f ", out_result[i]);
}
printf("\n");
// print true labels
safe_xgboost(XGDMatrixGetFloatInfo(dtest, "label", &out_len, &out_result));
printf("y_test: ");
for (int i = 0; i < n_print; ++i) {
printf("%1.4f ", out_result[i]);
}
printf("\n");
{
printf("Dense Matrix Example (XGDMatrixCreateFromMat): ");
const float values[] = {0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1,
0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 0, 1, 0, 0, 1, 0,
0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1,
0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,
1, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0};
DMatrixHandle dmat;
safe_xgboost(XGDMatrixCreateFromMat(values, 1, 127, 0.0, &dmat));
const float* out_result = NULL;
safe_xgboost(
XGBoosterPredictFromDMatrix(booster, dmat, config, &out_shape, &out_dim, &out_result));
assert(out_dim == 1);
assert(out_shape[0] == 1);
printf("%1.4f \n", out_result[0]);
safe_xgboost(XGDMatrixFree(dmat));
}
{
printf("Sparse Matrix Example (XGDMatrixCreateFromCSR): ");
const uint64_t indptr[] = {0, 22};
const uint32_t indices[] = {1, 9, 19, 21, 24, 34, 36, 39, 42, 53, 56,
65, 69, 77, 86, 88, 92, 95, 102, 106, 117, 122};
const float data[] = {1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0};
DMatrixHandle dmat;
char j_indptr[128];
MakeArrayInterface((size_t)indptr, 2ul, "<u8", sizeof(j_indptr), j_indptr);
char j_indices[128];
MakeArrayInterface((size_t)indices, sizeof(indices) / sizeof(uint32_t), "<u4",
sizeof(j_indices), j_indices);
char j_data[128];
MakeArrayInterface((size_t)data, sizeof(data) / sizeof(float), "<f4", sizeof(j_data), j_data);
char j_config[64];
MakeConfig(0, sizeof(j_config), j_config);
safe_xgboost(XGDMatrixCreateFromCSR(j_indptr, j_indices, j_data, 127, j_config, &dmat));
const float* out_result = NULL;
safe_xgboost(
XGBoosterPredictFromDMatrix(booster, dmat, config, &out_shape, &out_dim, &out_result));
assert(out_dim == 1);
assert(out_shape[0] == 1);
printf("%1.4f \n", out_result[0]);
safe_xgboost(XGDMatrixFree(dmat));
}
{
printf("Sparse Matrix Example (XGDMatrixCreateFromCSC): ");
const uint64_t indptr[] = {
0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3,
4, 4, 4, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 6, 6, 7, 7, 7, 8, 8, 8, 9,
9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 10, 10, 10, 11, 11, 11, 11, 11, 11, 11, 11, 11,
12, 12, 12, 12, 13, 13, 13, 13, 13, 13, 13, 13, 14, 14, 14, 14, 14, 14, 14, 14, 14, 15,
15, 16, 16, 16, 16, 17, 17, 17, 18, 18, 18, 18, 18, 18, 18, 19, 19, 19, 19, 20, 20, 20,
20, 20, 20, 20, 20, 20, 20, 20, 21, 21, 21, 21, 21, 22, 22, 22, 22, 22};
const uint32_t indices[] = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0};
const float data[] = {1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0};
char j_indptr[128];
MakeArrayInterface((size_t)indptr, 128ul, "<u8", sizeof(j_indptr), j_indptr);
char j_indices[128];
MakeArrayInterface((size_t)indices, sizeof(indices) / sizeof(unsigned), "<u4",
sizeof(j_indices), j_indices);
char j_data[128];
MakeArrayInterface((size_t)data, sizeof(data) / sizeof(float), "<f4", sizeof(j_data), j_data);
char j_config[64];
MakeConfig(0, sizeof(j_config), j_config);
DMatrixHandle dmat;
safe_xgboost(XGDMatrixCreateFromCSC(j_indptr, j_indices, j_data, 1, j_config, &dmat));
const float* out_result = NULL;
safe_xgboost(
XGBoosterPredictFromDMatrix(booster, dmat, config, &out_shape, &out_dim, &out_result));
assert(out_dim == 1);
assert(out_shape[0] == 1);
printf("%1.4f \n", out_result[0]);
safe_xgboost(XGDMatrixFree(dmat));
}
// free everything
safe_xgboost(XGBoosterFree(booster));
safe_xgboost(XGDMatrixFree(dtrain));
safe_xgboost(XGDMatrixFree(dtest));
return 0;
}
```

--------------------------------

### Create QuantileDMatrix for training and test with reference

Source: https://xgboost.readthedocs.io/en/latest/python/python_api.html

Shows how to create a QuantileDMatrix for training data and a validation/test QuantileDMatrix using the training DMatrix as a reference (ref) to ensure consistent quantisation. The training DMatrix must be supplied as a reference for valid quantiles.

```python
from sklearn.datasets import make_regression
from sklearn.model_selection import train_test_split

X, y = make_regression()
X_train, X_test, y_train, y_test = train_test_split(X, y)
Xy_train = xgb.QuantileDMatrix(X_train, y_train)
# It's necessary to have the training DMatrix as a reference for valid
# quantiles.
Xy_test = xgb.QuantileDMatrix(X_test, y_test, ref=Xy_train)
```
Tokens:
Raw