nanogbm 0.6.0

A small, pure-Rust gradient boosting library (GBDT, binary classification, CPU only).
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

use super::{Bin, BinData, BinMapper, BinWidth, Dataset};
use crate::error::{Error, Result};

/// Build a binned [`Dataset`] from column-major `f64` data.
///
/// `max_bin` is the bin cap applied to every column; each column gets its own
/// [`BinMapper`] fit to that cap. Storage width is `u8` when the cap fits in a
/// byte (`max_bin <= 256`), else `u16`.
pub(crate) fn build_dataset(
    columns: Vec<Vec<f64>>,
    max_bin: usize,
    categorical: &[bool],
    min_data_in_bin: usize,
    labels: &[f32],
) -> Result<Dataset> {
    let n_features = columns.len();
    let n_rows = check_columns(&columns, labels)?;
    debug_assert_eq!(categorical.len(), n_features);

    // u8 storage iff the bin domain fits in a byte.
    let width = if max_bin <= 256 {
        BinWidth::U8
    } else {
        BinWidth::U16
    };

    // Fit and bin-encode each column, freeing its f64 storage the moment it has
    // been binned, so the full f64 matrix and the full binned matrix never
    // coexist (the f64 staging is the memory peak).
    let mut bin_mappers: Vec<BinMapper> = Vec::with_capacity(n_features);
    let bin_data = match width {
        BinWidth::U8 => BinData::U8(bin_and_consume::<u8>(columns, categorical, max_bin, min_data_in_bin, &mut bin_mappers)),
        BinWidth::U16 => BinData::U16(bin_and_consume::<u16>(columns, categorical, max_bin, min_data_in_bin, &mut bin_mappers)),
    };

    Ok(Dataset {
        n_rows,
        n_features,
        bin_data,
        bin_mappers,
        labels: labels.to_vec(),
    })
}

/// Fit a [`BinMapper`] per column and bin-encode it, dropping each f64 column as
/// soon as it is encoded. `mappers` is filled in column order alongside the
/// returned binned columns. `BinMapper::value_to_bin` always returns u16, which
/// we narrow via [`Bin::from_u16`].
fn bin_and_consume<B: Bin>(columns: Vec<Vec<f64>>, categorical: &[bool], max_bin: usize, min_data_in_bin: usize, mappers: &mut Vec<BinMapper>) -> Vec<Vec<B>> {
    let mut out = Vec::with_capacity(columns.len());
    for (col, &cat) in columns.into_iter().zip(categorical) {
        let bm = if cat { BinMapper::fit_categorical(&col, max_bin) } else { BinMapper::fit(&col, max_bin, min_data_in_bin) };
        out.push(col.iter().map(|&v| B::from_u16(bm.value_to_bin(v))).collect());
        mappers.push(bm);
        // `col` is dropped here, freeing its f64 storage before the next column.
    }
    out
}

fn check_columns(columns: &[Vec<f64>], labels: &[f32]) -> Result<usize> {
    if columns.is_empty() {
        return Err(Error::Shape("no features".into()));
    }
    let n_rows = columns[0].len();
    if labels.len() != n_rows {
        return Err(Error::Shape(format!(
            "labels len {} != n_rows {}",
            labels.len(),
            n_rows
        )));
    }
    for (i, c) in columns.iter().enumerate() {
        if c.len() != n_rows {
            return Err(Error::Shape(format!(
                "column {} has len {}, expected {}",
                i,
                c.len(),
                n_rows
            )));
        }
    }
    Ok(n_rows)
}