ferricml 0.2.1

A lean, pure-Rust toolkit for classical machine learning
Documentation
use super::super::forest::{forest_classifier, forest_regressor};
use super::parameters::{ExtraTreesClassifierParams, ExtraTreesRegressorParams};
use crate::artifact::{EXTRA_TREES_CLASSIFIER_ARTIFACT_KIND, EXTRA_TREES_REGRESSOR_ARTIFACT_KIND};

forest_classifier!(
    ExtraTreesClassifier,
    ExtraTreesClassifierParams,
    EXTRA_TREES_CLASSIFIER_ARTIFACT_KIND,
    "An extremely randomized tree classifier.",
    "",
    "Each member tree draws **one uniform threshold per candidate column**,",
    "over that column's own range within the node, and keeps the best-scoring",
    "draw — rather than evaluating every boundary between adjacent distinct",
    "values. The candidate columns themselves are drawn exactly as a random",
    "forest draws them. Trees therefore decorrelate through their thresholds",
    "instead of through resampling, which is why `bootstrap` defaults to",
    "`false` here and to `true` on a random forest.",
    "",
    "One member is correspondingly **higher-variance** than a random-forest",
    "member, so more of the quality is waiting on the averaging — and the",
    "narrower [`MaxFeatures`](crate::tree::MaxFeatures) is, the more of it",
    "there is. At the `Sqrt` default and 50 members, the held-out accuracy of",
    "a measured lane still moved by 0.013 across `random_state` alone and sat",
    "0.007 below its own asymptote; `MaxFeatures::All` reached that asymptote",
    "at 50 members. Narrowing the candidate columns is a reason to raise",
    "`n_estimators`, and the guide carries the measurements.",
    "",
    "```",
    "use ferricml::api::{Classifier, HasParams};",
    "use ferricml::data::{BinaryTargets, DenseMatrix};",
    "use ferricml::ensemble::{ExtraTreesClassifier, ExtraTreesClassifierParams};",
    "",
    "let data = DenseMatrix::new(vec![0.0, 1.0, 2.0, 3.0, 4.0, 5.0], 6, 1)?;",
    "let labels = BinaryTargets::new(vec![0, 0, 0, 1, 1, 1])?;",
    "",
    "let params = ExtraTreesClassifierParams::default()",
    "    .with_n_estimators(32)",
    "    .with_random_state(5);",
    "",
    "// Bootstrapping is off by default here, unlike a random forest: these",
    "// trees decorrelate through their thresholds instead.",
    "assert!(!params.bootstrap());",
    "",
    "let model = ExtraTreesClassifier::fit(&data.as_view(), &labels, params)?;",
    "assert_eq!(model.predict(&data.as_view())?, vec![0, 0, 0, 1, 1, 1]);",
    "assert!(!model.get_params().bootstrap());",
    "# Ok::<(), Box<dyn std::error::Error>>(())",
    "```",
);

forest_regressor!(
    ExtraTreesRegressor,
    ExtraTreesRegressorParams,
    EXTRA_TREES_REGRESSOR_ARTIFACT_KIND,
    crate::tree::Regression,
    "An extremely randomized tree regressor. Predictions are averages of tree",
    "leaf means.",
    "",
    "Each member tree draws one uniform threshold per candidate column rather",
    "than optimizing within it; see [`ExtraTreesClassifier`] for what that",
    "changes and what it leaves alone.",
    "",
    "```",
    "use ferricml::data::{DenseMatrix, RegressionTargets};",
    "use ferricml::ensemble::{ExtraTreesRegressor, ExtraTreesRegressorParams};",
    "",
    "let data = DenseMatrix::new(vec![0.0, 1.0, 2.0, 3.0, 4.0, 5.0], 6, 1)?;",
    "let targets = RegressionTargets::new(vec![0.0, 1.0, 4.0, 9.0, 16.0, 25.0])?;",
    "",
    "let model = ExtraTreesRegressor::fit(",
    "    &data.as_view(),",
    "    &targets,",
    "    ExtraTreesRegressorParams::default()",
    "        .with_n_estimators(24)",
    "        .with_random_state(3),",
    ")?;",
    "",
    "let predictions = model.predict(&data.as_view())?;",
    "assert_eq!(predictions.len(), 6);",
    "// Leaf means are averaged, so no prediction leaves the target range.",
    "assert!(predictions.iter().all(|value| (0.0..=25.0).contains(value)));",
    "# Ok::<(), Box<dyn std::error::Error>>(())",
    "```",
);