### Configure Dataset with Fields

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Full example showing how to set feature names and label fields for a dataset created from a matrix.

```java
        String[] columns = new String[] {
            "Age","BMI","Glucose","Insulin","HOMA","Leptin","Adiponectin","Resistin","MCP.1"
        };
        double[] values = new double[] {
            71,30.3,102,8.34,2.098344,56.502,8.13,4.2989,200.976,
            66,27.7,90,6.042,1.341324,24.846,7.652055,6.7052,225.88,
            75,25.7,94,8.079,1.8732508,65.926,3.74122,4.49685,206.802,
            78,25.3,60,3.508,0.519184,6.633,10.567295,4.6638,209.749,
            69,29.4,89,10.704,2.3498848,45.272,8.2863,4.53,215.769,
            85,26.6,96,4.462,1.0566016,7.85,7.9317,9.6135,232.006,
            76,27.1,110,26.211,7.111918,21.778,4.935635,8.49395,45.843,
            77,25.9,85,4.58,0.960273333,13.74,9.75326,11.774,488.829,
            45,21.30394858,102,13.852,3.4851632,7.6476,21.056625,23.03408,552.444,
            45,20.82999519,74,4.56,0.832352,7.7529,8.237405,28.0323,382.955,
            49,20.9566075,94,12.305,2.853119333,11.2406,8.412175,23.1177,573.63,
            34,24.24242424,92,21.699,4.9242264,16.7353,21.823745,12.06534,481.949,
            42,21.35991456,93,2.999,0.6879706,19.0826,8.462915,17.37615,321.919,
            68,21.08281329,102,6.2,1.55992,9.6994,8.574655,13.74244,448.799,
            51,19.13265306,93,4.364,1.0011016,11.0816,5.80762,5.57055,90.6,
            62,22.65625,92,3.482,0.790181867,9.8648,11.236235,10.69548,703.973
        };
        
        float[] labels = new float[] {
            0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1
        };
        LGBMDataset dataset = LGBMDataset.createFromMat(values, 16, columns.length, true, "", null);
        dataset.setFeatureNames(columns);
        dataset.setField("label", labels);
        return dataset;
```

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

### Low-level SWIG JNI interface example

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Demonstrates the manual memory management and buffer handling required when using the raw SWIG-generated JNI interface.

```java
        SWIGTYPE_p_float dataBuffer = new_floatArray(input.length);
        for (int i = 0; i < input.length; i++) {
            floatArray_setitem(dataBuffer, i, input[i]);
        }
        int result = <...>
        if (result < 0) {
            delete_floatArray(dataBuffer);
            throw new Exception(LGBM_GetLastError());
        } else {
            delete_floatArray(dataBuffer);
            <...>
        }
```

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

### Install native library dependencies

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Commands to install required OpenMP libraries on MacOS and Debian Linux.

```bash
brew install libomp
```

```bash
apt install libgomp1
```

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

### Train Model with File-based Datasets

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Full training loop example using datasets loaded from CSV files.

```java
// cancer dataset from https://archive.ics.uci.edu/ml/datasets/Breast+Cancer+Coimbra
// with labels altered to fit the [0,1] range
LGBMDataset train = LGBMDataset.createFromFile("cancer.csv", "header=true label=name:Classification", null);
LGBMDataset test = LGBMDataset.createFromFile("cancer-test.csv", "header=true label=name:Classification", train);
LGBMBooster booster = LGBMBooster.create(train, "objective=binary label=name:Classification");
booster.addValidData(test);

for (int i=0; i<10; i++) {
     booster.updateOneIter();
     double[] evalTrain = booster.getEval(0);
     double[] evalTest = booster.getEval(1);
     System.out.println("train: " + eval[0] + " test: " + );
}
booster.close();
train.close();
test.close();
```

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

### Native library override logs

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Example log output indicating that the library successfully loaded custom native binaries from the path specified by the LIGHTGBM_NATIVE_LIB_PATH environment variable.

```text
LIGHTGBM_NATIVE_LIB_PATH is set: loading /home/user/code/LightGBM/lib_lightgbm.so
LIGHTGBM_NATIVE_LIB_PATH is set: loading /home/user/code/LightGBM/lib_lightgbm_swig.so
```

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

### Custom Objective Function (MSE)

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Implement a custom objective function for LightGBM4j by providing gradients and hessians. Use 'objective=none' and specify an evaluation metric. This example demonstrates Mean Squared Error (MSE).

```java
LGBMDataset dataset = LGBMDataset.createFromFile("cancer.csv", "header=true label=name:Classification", null);
LGBMBooster booster = LGBMBooster.create(dataset, "objective=none metric=rmse label=name:Classification");
// actual ground truth label values
float y[] = dataset.getFieldFloat("label");

for (int it=0; it<10; it++) {
    // predictions for current iteration
    double[] yhat = booster.getPredict(0); // 0 - training dataset
    float[] grad = new float[y.length];
    float[] hess = new float[y.length];
    for (int i=0; i<y.length; i++) {
        // 1-st derivative of squared error
        grad[i] = (float)(2 * (yhat[i]-y[i]));
        // 2-nd derivative of squared error
        hess[i] = (float)(0 * (yhat[i]-y[i]) + 2);
    }
    booster.updateOneIterCustom(grad, hess);
    // print the computed average error
    double[] err = booster.getEval(0);
    System.out.println("it " + it + " err=" + err[0]);
}
booster.close();
dataset.close();
```

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

### Configure and Train with Categorical Features

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Demonstrates how to load data with categorical features, set feature names, specify categorical features in parameters, and train a booster. Ensure data is index-encoded for categorical features.

```java
// LibSVM format data with categorical features (index-encoded)
// 1 0:7 1:2 2:3 3:20 4:15 5:38 6:29 7:201
// 0 0:5 1:15 2:2 3:1859 4:1 5:156 6:164 7:2475

LGBMDataset dataset = LGBMDataset.createFromFile(
    "./src/test/resources/categorical.data",
    "",
    null
);

// Set feature names so they can be referenced in parameters
dataset.setFeatureNames(new String[] {
    "f0", "f1", "f2", "f3", "f4", "f5", "f6", "f7"
});

// Specify which features are categorical
String params = "objective=binary " +
    "label=name:Classification " +
    "categorical_feature=f0,f1,f2,f3,f4,f5,f6,f7";

LGBMBooster booster = LGBMBooster.create(dataset, params);

for (int i = 0; i < 10; i++) {
    booster.updateOneIter();
    double[] eval = booster.getEval(0);
    System.out.println("Iteration " + i + " - Train metric: " + eval[0]);
}

dataset.close();
booster.close();
```

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

### Create LGBMBooster from Dataset

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Create a new boosting learner from a dataset with specified training parameters. Parameters are passed as a space-separated key=value string.

```java
LGBMDataset dataset = LGBMDataset.createFromFile(
    "src/test/resources/cancer.csv",
    "header=true label=name:Classification",
    null
);

LGBMBooster booster = LGBMBooster.create(
    dataset,
    "objective=binary label=name:Classification"
);

// Ranking task with LambdaMART
LGBMBooster rankingBooster = LGBMBooster.create(
    rankingDataset,
    "objective=lambdarank metric=ndcg lambdarank_truncation_level=10 " +
    "max_depth=5 learning_rate=0.1 num_leaves=8"
);

// Custom objective (no built-in loss function)
LGBMBooster customBooster = LGBMBooster.create(
    dataset,
    "objective=none metric=rmse label=name:Classification"
);

dataset.close();
booster.close();
```

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

### LGBMBooster.create

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Creates a new boosting learner from a dataset with specified training parameters.

```APIDOC
## LGBMBooster.create

### Description
Creates a new boosting learner from a dataset with specified training parameters. Parameters are passed as a space-separated key=value string.

### Parameters
#### Request Body
- **dataset** (LGBMDataset) - Required - The dataset used for training.
- **parameters** (String) - Required - Space-separated key=value string for configuration (e.g., "objective=binary label=name:Classification").

### Request Example
LGBMBooster.create(dataset, "objective=binary label=name:Classification");
```

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

### Load Dataset from File with LGBMDataset.createFromFile

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Load a dataset directly from a CSV or LibSVM file. Specify parameters like header presence and the label column. A reference dataset can be provided for consistent binning, especially for test sets.

```java
// Load dataset from CSV file with header and label column specification
LGBMDataset trainDataset = LGBMDataset.createFromFile(
    "cancer.csv",                           // file path
    "header=true label=name:Classification", // parameters
    null                                     // reference dataset (null for training set)
);

// Load test dataset with reference to align bin mappers
LGBMDataset testDataset = LGBMDataset.createFromFile(
    "cancer-test.csv",
    "header=true label=name:Classification",
    trainDataset  // reference to training dataset for consistent binning
);

// Get dataset info
int numRows = trainDataset.getNumData();      // Returns: 116
int numFeatures = trainDataset.getNumFeatures(); // Returns: 9

// Always close datasets when done
testDataset.close();
trainDataset.close();
```

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

### Load and Predict with LGBMBooster

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Demonstrates loading a model from a string and performing predictions on a float array.

```java
LGBMBooster loaded = LGBMBooster.loadModelFromString(model);
float[] input = new float[] {1.0f, 1.0f, 1.0f, 1.0f};
double[] pred = booster.predictForMat(input, 2, 2, true);
```

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

### Load and Use Categorical Features

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Load a dataset with categorical features from a file and configure the booster to recognize them. Ensure features are index-encoded in the dataset and specified in booster parameters.

```java
LGBMDataset ds = LGBMDataset.createFromFile("./src/test/resources/categorical.data", "", null);
ds.setFeatureNames(new String[]{"f0", "f1", "f2", "f3", "f4", "f5", "f6", "f7"});
String params = "objective=binary label=name:Classification categorical_feature=f0,f1,f2,f3,f4,f5,f6,f7";
LGBMBooster booster = LGBMBooster.create(ds, params);
for (int i=0; i<10; i++) {
    booster.updateOneIter();
    double[] eval1 = booster.getEval(0);
    System.out.println("train " + eval1[0]);
}
```

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

### Train LambdaMART Ranking Model

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Shows how to create a ranking dataset with group information, set labels and groups, and train a LambdaMART booster with NDCG metric optimization. Includes prediction for ranking scores.

```java
// Create ranking dataset with group information
float[] features = new float[] {
    // Query group 1 (2 documents)
    1.0f, 2.0f, 3.0f, 4.0f,  // doc1 features
    5.0f, 6.0f, 7.0f, 8.0f,  // doc2 features
    // Query group 2 (2 documents)
    2.0f, 3.0f, 4.0f, 5.0f,  // doc1 features
    6.0f, 7.0f, 8.0f, 9.0f   // doc2 features
};

LGBMDataset train = LGBMDataset.createFromMat(features, 4, 4, true, "", null);
train.setFeatureNames(new String[] { "f1", "f2", "f3", "f4" });
train.setField("label", new float[] { 2.0f, 1.0f, 3.0f, 0.0f });  // relevance labels
train.setField("group", new int[] { 2, 2 });  // 2 docs per query group

// Create ranking booster with LambdaMART
LGBMBooster booster = LGBMBooster.create(
    train,
    "objective=lambdarank " +
    "metric=ndcg " +
    "lambdarank_truncation_level=10 " +
    "max_depth=5 " +
    "learning_rate=0.1 " +
    "num_leaves=8"
);

// Train
for (int i = 0; i < 100; i++) {
    booster.updateOneIter();
    double[] ndcg = booster.getEval(0);
    if (i % 10 == 0) {
        System.out.println("Iteration " + i + " - NDCG: " + ndcg[0]);
    }
}

// Predict relevance scores for ranking
double[] scores = booster.predictForMat(
    features, 4, 4, true,
    PredictionType.C_API_PREDICT_NORMAL
);
System.out.println("Ranking scores: " + java.util.Arrays.toString(scores));

train.close();
booster.close();
```

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

### LightGBM C-API Functions

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

A collection of C-API functions for interacting with LightGBM models and datasets.

```APIDOC
## LightGBM C-API Functions

### Description
The LightGBM C-API provides low-level functions for managing boosters and datasets. These include methods for prediction, model refitting, and dataset construction from various formats like CSC and CSR.

### Available Functions
- **LGBM_BoosterPredictForCSC**: Predict using CSC matrix input.
- **LGBM_BoosterPredictForCSR**: Predict using CSR matrix input.
- **LGBM_BoosterPredictForCSRSingleRow**: Predict for a single row in CSR format.
- **LGBM_BoosterPredictForCSRSingleRowFast**: Fast prediction for a single row in CSR format.
- **LGBM_BoosterPredictForCSRSingleRowFastInit**: Initialize fast prediction for a single row.
- **LGBM_BoosterPredictForFile**: Predict using data from a file.
- **LGBM_BoosterPredictForMats**: Predict using matrix input.
- **LGBM_BoosterPredictSparseOutput**: Predict with sparse output.
- **LGBM_BoosterRefit**: Refit the booster model.
- **LGBM_BoosterResetParameter**: Reset booster parameters.
- **LGBM_BoosterResetTrainingData**: Reset training data for the booster.
- **LGBM_BoosterRollbackOneIter**: Roll back the booster by one iteration.
- **LGBM_BoosterSetLeafValue**: Set specific leaf values in the booster.
- **LGBM_BoosterShuffleModels**: Shuffle the models within the booster.
- **LGBM_DatasetAddFeaturesFrom**: Add features to a dataset from another source.
- **LGBM_DatasetCreateByReference**: Create a dataset by referencing an existing one.
- **LGBM_DatasetCreateFromCSC**: Create a dataset from a CSC matrix.
- **LGBM_DatasetCreateFromCSR**: Create a dataset from a CSR matrix.
- **LGBM_DatasetCreateFromCSRFunc**: Create a dataset using a CSR callback function.
- **LGBM_DatasetCreateFromMats**: Create a dataset from a matrix.
- **LGBM_DatasetCreateFromSampledColumn**: Create a dataset from sampled columns.
- **LGBM_DatasetGetField**: Retrieve a field from the dataset.
- **LGBM_DatasetGetSubset**: Get a subset of the dataset.
- **LGBM_DatasetPushRows**: Push rows into the dataset.
- **LGBM_DatasetPushRowsByCSR**: Push rows into the dataset using CSR format.
- **LGBM_DatasetSaveBinary**: Save the dataset in binary format.
- **LGBM_DatasetUpdateParamChecking**: Update parameter checking for the dataset.
- **LGBM_FastConfigFree**: Free memory associated with fast configuration.
```

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

### Train LGBMBooster with One Iteration

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Perform one iteration of gradient boosting training. Returns true when no more splits are possible. Call repeatedly to train the model. Includes adding validation data and retrieving evaluation metrics.

```java
LGBMDataset train = LGBMDataset.createFromFile(
    "src/test/resources/cancer.csv",
    "header=true label=name:Classification",
    null
);
LGBMDataset test = LGBMDataset.createFromFile(
    "src/test/resources/cancer.csv",
    "header=true label=name:Classification",
    train
);

LGBMBooster booster = LGBMBooster.create(train, "objective=binary label=name:Classification");
booster.addValidData(test);

// Training loop
for (int i = 0; i < 100; i++) {
    boolean finished = booster.updateOneIter();

    // Get evaluation metrics (0 = training, 1 = first validation set)
    double[] trainEval = booster.getEval(0);
    double[] testEval = booster.getEval(1);

    System.out.println("Iteration " + i +
        " - Train: " + trainEval[0] +
        " Test: " + testEval[0]);

    if (finished) {
        System.out.println("Training finished early - no more splits possible");
        break;
    }
}

test.close();
train.close();
booster.close();
```

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

### LGBMBooster.updateOneIter

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Performs one iteration of gradient boosting training.

```APIDOC
## LGBMBooster.updateOneIter

### Description
Perform one iteration of gradient boosting training. Returns true when no more splits are possible. Call repeatedly to train the model.

### Response
#### Success Response (200)
- **finished** (boolean) - Returns true if no more splits are possible.
```

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

### Perform fast single-row prediction with LightGBM4J

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Optimizes prediction performance by initializing a FastConfig object before inference. Ensure the configuration is closed after use to prevent memory leaks.

```java
LGBMDataset dataset = LGBMDataset.createFromFile("src/test/resources/cancer.csv", "header=true label=name:Classification", null);
LGBMBooster booster = LGBMBooster.create(dataset, "objective=binary label=name:Classification");
booster.updateOneIter();
booster.updateOneIter();
booster.updateOneIter();
LGBMBooster.FastConfig config = booster.predictForMatSingleRowFastInit(PredictionType.C_API_PREDICT_NORMAL, C_API_DTYPE_FLOAT32,9, "");
double pred = booster.predictForMatSingleRowFast(config, new float[]{1, 2, 3, 4, 5, 6, 7, 8, 9}, PredictionType.C_API_PREDICT_NORMAL);
assertTrue(Double.isFinite(pred));
config.close();
dataset.close();
booster.close();
```

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

### LGBMBooster.saveModelToString / loadModelFromString

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Methods for serializing and deserializing LightGBM models to and from string formats for persistence.

```APIDOC
## Java Methods: saveModelToString / loadModelFromString

### Description
Allows saving a trained model to a string representation and loading it back into a new booster instance.

### Parameters (saveModelToString)
- **startIteration** (int) - Required - The starting iteration index.
- **numIterations** (int) - Required - Number of iterations to save.
- **importanceType** (FeatureImportanceType) - Required - The importance type to include.

### Parameters (loadModelFromString)
- **modelString** (String) - Required - The serialized model string.
```

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

### Perform Ultra-Low-Latency Predictions

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Use FastConfig to pre-allocate structures for high-frequency prediction. FastConfig implements AutoCloseable and must be closed to prevent memory leaks.

```java
import com.microsoft.ml.lightgbm.PredictionType;
import static com.microsoft.ml.lightgbm.lightgbmlibConstants.C_API_DTYPE_FLOAT32;
import static com.microsoft.ml.lightgbm.lightgbmlibConstants.C_API_DTYPE_FLOAT64;

// Train model
LGBMDataset dataset = LGBMDataset.createFromFile(
    "src/test/resources/cancer.csv",
    "header=true label=name:Classification",
    null
);
LGBMBooster booster = LGBMBooster.create(dataset, "objective=binary label=name:Classification");
for (int i = 0; i < 10; i++) booster.updateOneIter();

// Initialize fast prediction config (do once, reuse many times)
LGBMBooster.FastConfig configFloat = booster.predictForMatSingleRowFastInit(
    PredictionType.C_API_PREDICT_NORMAL,
    C_API_DTYPE_FLOAT32,  // input data type
    9,                     // number of features
    ""                     // additional parameters (e.g., "num_threads=1")
);

// Fast predictions (very low latency)
float[] features = new float[] { 71, 30.3f, 102, 8.34f, 2.098f, 56.5f, 8.13f, 4.29f, 200.9f };
for (int i = 0; i < 1000; i++) {
    double pred = booster.predictForMatSingleRowFast(
        configFloat,
        features,
        PredictionType.C_API_PREDICT_NORMAL
    );
}

// Double precision version
LGBMBooster.FastConfig configDouble = booster.predictForMatSingleRowFastInit(
    PredictionType.C_API_PREDICT_NORMAL,
    C_API_DTYPE_FLOAT64,
    9,
    "num_threads=1"  // use single thread for minimal latency
);

double[] featuresDouble = new double[] { 71, 30.3, 102, 8.34, 2.098, 56.5, 8.13, 4.29, 200.9 };
double pred = booster.predictForMatSingleRowFast(
    configDouble,
    featuresDouble,
    PredictionType.C_API_PREDICT_NORMAL
);

// Clean up (FastConfig is AutoCloseable)
configFloat.close();
configDouble.close();
dataset.close();
booster.close();
```

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

### Create Dataset from Matrix with LGBMDataset.createFromMat

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Create a dataset from in-memory `float[]` or `double[]` arrays. Supports row-major or column-major encoding. Feature names and labels can be set subsequently.

```java
// Feature columns for cancer dataset
String[] columns = new String[] {
    "Age", "BMI", "Glucose", "Insulin", "HOMA", "Leptin", "Adiponectin", "Resistin", "MCP.1"
};

// Flattened feature matrix (16 rows x 9 columns = 144 values)
double[] values = new double[] {
    71, 30.3, 102, 8.34, 2.098344, 56.502, 8.13, 4.2989, 200.976,
    66, 27.7, 90, 6.042, 1.341324, 24.846, 7.652055, 6.7052, 225.88,
    75, 25.7, 94, 8.079, 1.8732508, 65.926, 3.74122, 4.49685, 206.802,
    // ... more rows
};

// Labels for binary classification (must be float[])
float[] labels = new float[] { 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1 };

// Create dataset from matrix
LGBMDataset dataset = LGBMDataset.createFromMat(
    values,  // data matrix
    16,      // number of rows
    9,       // number of columns
    true,    // is row-major encoding
    "",      // extra parameters
    null     // reference dataset
);

// Set feature names for interpretability
dataset.setFeatureNames(columns);

// Set label field (must use float[] for labels)
dataset.setField("label", labels);

dataset.close();
```

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

### Update LGBMBooster with Custom Gradients and Hessians

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Update the model using custom gradients and hessians for implementing custom loss functions. Requires `objective=none` parameter. This method is used when you need to define your own loss function and provide its derivatives.

```java
LGBMDataset dataset = LGBMDataset.createFromFile(
    "src/test/resources/cancer.csv",
    "header=true label=name:Classification",
    null
);

// Create booster with no built-in objective
LGBMBooster booster = LGBMBooster.create(
    dataset,
    "objective=none metric=rmse label=name:Classification"
);

// Get ground truth labels
float[] y = dataset.getFieldFloat("label");

for (int iteration = 0; iteration < 10; iteration++) {
    // Get current predictions for training data
    double[] yhat = booster.getPredict(0);  // 0 = training dataset

    // Compute gradients and hessians for MSE loss
    float[] grad = new float[y.length];
    float[] hess = new float[y.length];

    for (int i = 0; i < y.length; i++) {
        // First derivative of squared error: 2 * (pred - actual)
        grad[i] = (float)(2 * (yhat[i] - y[i]));
        // Second derivative of squared error: 2
        hess[i] = 2.0f;
    }

    // Update model with custom derivatives
    boolean finished = booster.updateOneIterCustom(grad, hess);

    // Check training progress
    double[] rmse = booster.getEval(0);
    System.out.println("Iteration " + iteration + " RMSE: " + rmse[0]);
}

booster.close();
dataset.close();
```

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

### LGBMBooster.predictForMatSingleRowFast

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Provides an ultra-low-latency prediction method by pre-allocating internal structures, suitable for real-time serving.

```APIDOC
## Java Method: predictForMatSingleRowFast

### Description
Performs high-speed predictions on single rows of data by utilizing a pre-initialized FastConfig object.

### Parameters
- **config** (FastConfig) - Required - The pre-initialized configuration object.
- **features** (float[] or double[]) - Required - The input feature array.
- **predictionType** (PredictionType) - Required - The type of prediction to perform (e.g., C_API_PREDICT_NORMAL).

### Response
- **prediction** (double) - The predicted value.
```

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

### Create LGBMDataset from Matrix

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Initializes a dataset from a flat float array representing a matrix.

```java
float[] matrix = new float[] {1.0f, 1.0f, 1.0f, 1.0f};
LGBMDataset ds = LGBMDataset.createFromMat(matrix, 2, 2, true, "", null);
```

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

### LGBMBooster.updateOneIterCustom

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Updates the model using custom gradients and hessians for implementing custom loss functions.

```APIDOC
## LGBMBooster.updateOneIterCustom

### Description
Update the model using custom gradients and hessians for implementing custom loss functions. Requires `objective=none` parameter to be set during booster creation.

### Parameters
#### Request Body
- **grad** (float[]) - Required - Array of gradients.
- **hess** (float[]) - Required - Array of hessians.

### Response
#### Success Response (200)
- **finished** (boolean) - Returns true if no more splits are possible.
```

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

### Position Bias Removal Training

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Configure and train a LightGBM booster for position-bias aware Learning to Rank (LTR) using the LambdaMART objective. Requires setting 'group' and 'position' fields.

```java
float[] matrix = new float[] {
        // query group 1
        1.0f, 2.0f, // doc1
        3.0f, 4.0f, // doc2
        // query group 2
        1.0f, 2.0f, // doc1
        3.0f, 4.0f}; // doc2
LGBMDataset ds = LGBMDataset.createFromMat(matrix, 4, 2, true, "", null);
ds.setField("label", new float[] {1.0, 0.0, 1.0, 0.0}); // set relevance labels
ds.setField("group", new int[] {2, 2}); // set document-to-group mapping
ds.setField("position", new int[] {0, 1, 2, 3, 0, 1, 2, 3}); // bias classes
LGBMBooster booster = LGBMBooster.create(ds, "objective=lambdarank");
```

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

### Batch Predictions with LGBMBooster.predictForMat

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Use predictForMat for making predictions on multiple samples at once. Supports various prediction types. Ensure the input matrix is correctly formatted and sized.

```java
import com.microsoft.ml.lightgbm.PredictionType;

// Train a model first
LGBMDataset dataset = LGBMDataset.createFromFile(
    "src/test/resources/cancer.csv",
    "header=true label=name:Classification",
    null
);
LGBMBooster booster = LGBMBooster.create(dataset, "objective=binary label=name:Classification");
for (int i = 0; i < 10; i++) booster.updateOneIter();

// Prepare input matrix (2 samples, 9 features each)
float[] input = new float[] {
    71, 30.3f, 102, 8.34f, 2.098f, 56.5f, 8.13f, 4.29f, 200.9f,  // sample 1
    45, 21.3f, 102, 13.8f, 3.48f, 7.64f, 21.0f, 23.0f, 552.4f    // sample 2
};

// Normal prediction (probability for binary classification)
double[] probabilities = booster.predictForMat(
    input,
    2,      // rows
    9,      // columns
    true,   // row-major
    PredictionType.C_API_PREDICT_NORMAL
);
System.out.println("Probabilities: " + probabilities[0] + ", " + probabilities[1]);

// Raw score prediction (logits before sigmoid)
double[] rawScores = booster.predictForMat(
    input, 2, 9, true,
    PredictionType.C_API_PREDICT_RAW_SCORE
);

// Leaf index prediction (which leaf each sample lands in per tree)
double[] leafIndices = booster.predictForMat(
    input, 2, 9, true,
    PredictionType.C_API_PREDICT_LEAF_INDEX
);

// SHAP values (feature contributions)
double[] shapValues = booster.predictForMat(
    input, 2, 9, true,
    PredictionType.C_API_PREDICT_CONTRIB
);

dataset.close();
booster.close();
```

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

### Perform single-row prediction with LightGBM4J

Source: https://github.com/metarank/lightgbm4j/blob/main/README.md

Executes standard single-row predictions using double or float arrays. Requires an initialized LGBMBooster and dataset.

```java
LGBMDataset dataset = LGBMDataset.createFromFile("src/test/resources/cancer.csv", "header=true label=name:Classification", null);
LGBMBooster booster = LGBMBooster.create(dataset, "objective=binary label=name:Classification");
booster.updateOneIter();
booster.updateOneIter();
booster.updateOneIter();
for (int i = 0; i < 10; i++) {
    double pred1 = booster.predictForMatSingleRow(new double[]{1, 2, 3, 4, 5, 6, 7, 8, 9}, PredictionType.C_API_PREDICT_NORMAL);
    assertTrue(pred1 > 0);
    double pred2 = booster.predictForMatSingleRow(new float[]{1, 2, 3, 4, 5, 6, 7, 8, 9}, PredictionType.C_API_PREDICT_NORMAL);
    assertTrue(pred2 > 0);
}
dataset.close();
booster.close();
```

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

### Add Maven Dependency for LightGBM4j

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Include this Maven dependency to add LightGBM4j to your project. It includes pre-built native libraries for all supported platforms.

```xml
<dependency>
  <groupId>io.github.metarank</groupId>
  <artifactId>lightgbm4j</artifactId>
  <version>4.6.0-2</version>
</dependency>
```

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

### LGBMBooster.predictForMatSingleRow

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Optimized prediction method for single samples. Re-uses internal predictor structures for better performance in serving scenarios.

```APIDOC
## POST /predictForMatSingleRow

### Description
Optimized prediction method for single samples. Re-uses internal predictor structures for better performance in serving scenarios.

### Method
POST

### Endpoint
/predictForMatSingleRow

### Parameters
#### Request Body
- **features** (double[] or float[]) - Required - Array of features for a single sample.
- **prediction_type** (PredictionType) - Required - The type of prediction to perform (e.g., NORMAL, RAW_SCORE).

### Request Example
```json
{
  "features": [71.0, 30.3, 102.0, 8.34, 2.098, 56.5, 8.13, 4.29, 200.9],
  "prediction_type": "C_API_PREDICT_NORMAL"
}
```

### Response
#### Success Response (200)
- **prediction** (double) - The prediction value for the single sample.

#### Response Example
```json
{
  "prediction": 0.12345
}
```
```

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

### Serialize and Deserialize Models

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Convert models to strings for storage or network transmission and reload them for inference.

```java
// Train a model
LGBMDataset dataset = LGBMDataset.createFromFile(
    "src/test/resources/cancer.csv",
    "header=true label=name:Classification",
    null
);
LGBMBooster booster = LGBMBooster.create(dataset, "objective=binary label=name:Classification");
for (int i = 0; i < 10; i++) booster.updateOneIter();

// Save model to string
String modelString = booster.saveModelToString(
    0,  // start iteration (0 = from beginning)
    0,  // num iterations (0 = all iterations)
    LGBMBooster.FeatureImportanceType.GAIN  // importance type for saved model
);

// Save to file if needed
// Files.writeString(Path.of("model.txt"), modelString);

booster.close();
dataset.close();

// Later: Load model from string
LGBMBooster loadedBooster = LGBMBooster.loadModelFromString(modelString);

// Or load from file
// LGBMBooster fileBooster = LGBMBooster.createFromModelfile("model.txt");

// Use loaded model for predictions
float[] input = new float[] { 71, 30.3f, 102, 8.34f, 2.098f, 56.5f, 8.13f, 4.29f, 200.9f };
double prediction = loadedBooster.predictForMatSingleRow(
    input,
    PredictionType.C_API_PREDICT_NORMAL
);
System.out.println("Loaded model prediction: " + prediction);

loadedBooster.close();
```

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

### LGBMBooster.predictForMat

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Make predictions on a batch of samples provided as a matrix array. Supports multiple prediction types including probabilities, raw scores, leaf indices, and SHAP values.

```APIDOC
## POST /predictForMat

### Description
Make predictions on a batch of samples provided as a matrix array. Supports multiple prediction types including probabilities, raw scores, leaf indices, and SHAP values.

### Method
POST

### Endpoint
/predictForMat

### Parameters
#### Request Body
- **input** (float[]) - Required - Array of input features in row-major order.
- **rows** (int) - Required - Number of samples (rows) in the input matrix.
- **columns** (int) - Required - Number of features (columns) in the input matrix.
- **row_major** (boolean) - Required - Specifies if the input matrix is in row-major format.
- **prediction_type** (PredictionType) - Required - The type of prediction to perform (e.g., NORMAL, RAW_SCORE, LEAF_INDEX, CONTRIB).

### Request Example
```json
{
  "input": [71.0, 30.3, 102.0, 8.34, 2.098, 56.5, 8.13, 4.29, 200.9, 45.0, 21.3, 102.0, 13.8, 3.48, 7.64, 21.0, 23.0, 552.4],
  "rows": 2,
  "columns": 9,
  "row_major": true,
  "prediction_type": "C_API_PREDICT_NORMAL"
}
```

### Response
#### Success Response (200)
- **predictions** (double[]) - An array of prediction values.

#### Response Example
```json
{
  "predictions": [0.12345, 0.67890]
}
```
```

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

### Single-Row Predictions with LGBMBooster.predictForMatSingleRow

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Use predictForMatSingleRow for optimized single-sample predictions, ideal for serving scenarios. It accepts both double[] and float[] input types and allows specifying prediction types.

```java
import com.microsoft.ml.lightgbm.PredictionType;

// Load trained model
LGBMDataset dataset = LGBMDataset.createFromFile(
    "src/test/resources/cancer.csv",
    "header=true label=name:Classification",
    null
);
LGBMBooster booster = LGBMBooster.create(dataset, "objective=binary label=name:Classification");
for (int i = 0; i < 10; i++) booster.updateOneIter();

// Single row prediction with double[] input
double[] featuresDouble = new double[] { 71, 30.3, 102, 8.34, 2.098, 56.5, 8.13, 4.29, 200.9 };
double predDouble = booster.predictForMatSingleRow(
    featuresDouble,
    PredictionType.C_API_PREDICT_NORMAL
);
System.out.println("Prediction (double): " + predDouble);

// Single row prediction with float[] input
float[] featuresFloat = new float[] { 71, 30.3f, 102, 8.34f, 2.098f, 56.5f, 8.13f, 4.29f, 200.9f };
double predFloat = booster.predictForMatSingleRow(
    featuresFloat,
    PredictionType.C_API_PREDICT_NORMAL
);
System.out.println("Prediction (float): " + predFloat);

// Get raw score instead of probability
double rawScore = booster.predictForMatSingleRow(
    featuresDouble,
    PredictionType.C_API_PREDICT_RAW_SCORE
);
System.out.println("Raw score: " + rawScore);

dataset.close();
booster.close();
```

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

### Set Special Fields on Dataset with LGBMDataset.setField

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Set special fields like labels, weights, groups (for ranking), and position (for position bias) on a dataset. Labels and weights require `float[]`, while group and position require `int[]`.

```java
// Create dataset for ranking task
float[] matrix = new float[] {
    // query group 1
    1.0f, 2.0f,  // doc1 features
    3.0f, 4.0f,  // doc2 features
    // query group 2
    1.0f, 2.0f,  // doc1 features
    3.0f, 4.0f   // doc2 features
};

LGBMDataset dataset = LGBMDataset.createFromMat(matrix, 4, 2, true, "", null);

// Set relevance labels (float[])
dataset.setField("label", new float[] { 1.0f, 0.0f, 1.0f, 0.0f });

// Set query groups - each value indicates docs per group (int[])
dataset.setField("group", new int[] { 2, 2 });

// Set position bias classes for position-aware LTR training (int[])
dataset.setField("position", new int[] { 0, 1, 0, 1 });

// Optional: set sample weights (float[])
dataset.setField("weight", new float[] { 1.0f, 1.0f, 0.5f, 0.5f });

dataset.close();
```

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

### Analyze Feature Importance

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Retrieve gain or split-count importance metrics to evaluate feature contribution to the model.

```java
// Train model
LGBMDataset dataset = LGBMDataset.createFromFile(
    "src/test/resources/cancer.csv",
    "header=true label=name:Classification",
    null
);
LGBMBooster booster = LGBMBooster.create(dataset, "objective=binary label=name:Classification");
for (int i = 0; i < 10; i++) booster.updateOneIter();

// Get feature names
String[] featureNames = booster.getFeatureNames();

// Get importance by gain (total gain from splits using each feature)
double[] gainImportance = booster.featureImportance(
    0,  // num iterations (0 = all)
    LGBMBooster.FeatureImportanceType.GAIN
);

// Get importance by split count (number of times each feature is used)
double[] splitImportance = booster.featureImportance(
    0,
    LGBMBooster.FeatureImportanceType.SPLIT
);

// Print feature importances
System.out.println("Feature Importance (Gain):");
for (int i = 0; i < featureNames.length; i++) {
    System.out.printf("  %s: %.4f (gain), %.0f (splits)%n",
        featureNames[i], gainImportance[i], splitImportance[i]);
}

// Get number of features and classes
int numFeatures = booster.getNumFeature();
int numClasses = booster.getNumClasses();
System.out.println("Features: " + numFeatures + ", Classes: " + numClasses);

dataset.close();
booster.close();
```

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

### LGBMBooster.featureImportance

Source: https://context7.com/metarank/lightgbm4j/llms.txt

Retrieves feature importance scores to evaluate the contribution of each feature to the model's predictions.

```APIDOC
## Java Method: featureImportance

### Description
Calculates and returns the importance scores for features based on gain or split count.

### Parameters
- **numIterations** (int) - Required - Number of iterations to consider.
- **importanceType** (FeatureImportanceType) - Required - The metric to use (GAIN or SPLIT).

### Response
- **importanceScores** (double[]) - An array of importance scores corresponding to the model features.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.