hessboost 0.1.0

A faithful, fast, pure-Rust reimplementation of XGBoost gradient boosting
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

//! # hessboost
//!
//! A faithful, fast, pure-Rust reimplementation of
//! [XGBoost](https://github.com/dmlc/xgboost) gradient boosting with no C/C++
//! dependency and no FFI.
//!
//! ## Quick start
//!
//! Build a [`DMatrix`], configure [`TrainingParams`] with a builder, call
//! [`train`], then [`predict`](BoostedModel::predict):
//!
//! ```
//! use hessboost::prelude::*;
//!
//! # fn main() -> Result<()> {
//! // 6 rows × 2 features, row-major, plus a label per row.
//! let x = [0.0, 0.0,  1.0, 0.0,  0.0, 1.0,  1.0, 1.0,  0.5, 0.5,  0.2, 0.9];
//! let y = [0.0,       1.0,       1.0,       0.0,       0.5,       0.7];
//! let dtrain = DMatrix::from_dense(&x, 6, 2)?.with_labels(&y)?;
//!
//! let params = TrainingParams::builder()
//!     .objective("reg:squarederror") // XGBoost-compatible names
//!     .tree_method(TreeMethod::Hist)
//!     .max_depth(3)
//!     .eta(0.1)
//!     .build()?;
//!
//! let model = train(&params, &dtrain, 50)?;
//! let preds = model.predict(&dtrain)?;
//! assert_eq!(preds.len(), 6);
//!
//! model.save_binary("model.bin")?;      // native format
//! # std::fs::remove_file("model.bin").ok();
//! # Ok(())
//! # }
//! ```
//!
//! ## What's here
//!
//! - **Boosters:** `gbtree`, `dart`, `gblinear`.
//! - **Tree methods:** `exact`, `hist`, and `approx`, with `depthwise` or
//!   `lossguide` growth.
//! - **Objectives:** regression, binary/multiclass classification, count
//!   (poisson/gamma/tweedie), learning-to-rank (LambdaMART), and a custom hook
//!   ([`train_with_objective`]).
//! - **Metrics:** rmse, mae, logloss, error, auc, aucpr, mlogloss, merror,
//!   ndcg/map, nloglik, and a custom hook ([`train_with_custom_metric`]).
//! - **Modeling:** monotone & interaction constraints, native categorical
//!   splits, early stopping, feature importance, TreeSHAP contributions and
//!   interaction values ([`BoostedModel::predict_contribs`] /
//!   [`predict_interactions`](BoostedModel::predict_interactions)).
//! - **I/O:** libsvm/CSV loaders, native binary + JSON model I/O, and
//!   XGBoost-format JSON model import/export ([`crate::model`]).
//! - **Validation:** cross-validation ([`cv`]).
//!
//! ## Where to look
//!
//! - Entry points: [`train`], [`train_with_eval`], [`train_with_objective`],
//!   [`train_with_custom_metric`], [`cv`].
//! - Core types: [`DMatrix`] (data), [`TrainingParams`] (config, mirrors
//!   XGBoost parameter names), [`BoostedModel`] (trained model).
//! - Runnable examples in the crate's `examples/` directory (e.g.
//!   `binary_classification`, `multiclass`, `ranking`, `shap`, `model_io`,
//!   `custom_objective`, `constraints`). Run one with
//!   `cargo run --release --example binary_classification`.
//!
//! ## Compatibility notes
//!
//! Objective, metric, and parameter names mirror XGBoost, so configurations
//! transfer directly. Predictions match XGBoost's *model quality* (parity is
//! CI-tested) but are not bit-identical. The two histogram implementations pick
//! slightly different split points.
#![forbid(unsafe_op_in_unsafe_fn)]
#![warn(missing_docs)]

pub mod booster;
pub mod config;
pub mod data;
pub mod error;
pub mod learner;
pub mod metric;
pub mod model;
pub mod objective;
mod simd;
pub mod tree;

pub use config::{
    BoosterKind, GrowPolicy, Monotone, TrainingParams, TrainingParamsBuilder, TreeMethod,
};
pub use data::{DMatrix, FeatureType};
pub use error::{HessboostError, Result};
pub use learner::{
    BoostedModel, CvResult, ImportanceType, TrainResult, cv, train, train_with_custom_metric,
    train_with_eval, train_with_objective,
};
pub use metric::{CustomMetric, Metric};
pub use objective::{CustomObjective, GradPair, Objective};
pub use tree::{Node, RegTree};

/// Commonly used imports include `use hessboost::prelude::*;`.
///
/// Pulls in the data container, configuration, training entry points, the model
/// type, and the objective/metric hooks. This provides everything needed for the
/// typical train to predict workflow.
pub mod prelude {
    pub use crate::data::CsvOptions;
    pub use crate::{
        BoostedModel, BoosterKind, CustomMetric, CustomObjective, CvResult, DMatrix, FeatureType,
        GradPair, GrowPolicy, HessboostError, ImportanceType, Metric, Monotone, Objective, Result,
        TrainResult, TrainingParams, TreeMethod, cv, train, train_with_custom_metric,
        train_with_eval, train_with_objective,
    };
}