### pfor_map usage example

Source: https://docs.rs/pkboost/latest/pkboost/fork_parallel/fn.pfor_map.html

A basic example demonstrating how to use pfor_map to double the items in a slice.

```rust
let results = pfor_map(&data, |item| item * 2);
```

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

### PartitionedClassifierBuilder::new

Source: https://docs.rs/pkboost/latest/pkboost/partitioned_classifier/struct.PartitionedClassifierBuilder.html

Creates a new PartitionedClassifierBuilder instance. This is the starting point for building a PartitionedClassifier.

```APIDOC
## PartitionedClassifierBuilder::new

### Description
Creates a new instance of PartitionedClassifierBuilder.

### Method
new

### Signature
pub fn new() -> Self

### Parameters
None

### Returns
- Self - A new PartitionedClassifierBuilder instance.
```

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

### PKBoostBuilder::new

Source: https://docs.rs/pkboost/latest/pkboost/model/struct.PKBoostBuilder.html

Creates a new PKBoostBuilder instance with default settings.

```APIDOC
## PKBoostBuilder::new

### Description
Creates a new PKBoostBuilder instance with default settings.

### Method
new

### Signature
pub fn new() -> Self

### Parameters
None

### Returns
Self - A new PKBoostBuilder instance.
```

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

### Get vulnerability score

Source: https://docs.rs/pkboost/latest/src/pkboost/living_booster.rs.html

Returns the vulnerability score from the adversary component.

```rust
    pub fn get_vulnerability_score(&self) -> f64 {
        self.adversary.get_vulnerability_score()
    }
```

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

### new

Source: https://docs.rs/pkboost/latest/pkboost/regression/struct.PKBoostRegressor.html

Creates a new PKBoostRegressor instance with default settings.

```APIDOC
## new

### Description
Creates a new PKBoostRegressor instance with default settings.

### Method
new

### Signature
pub fn new() -> Self

### Parameters
None

### Returns
- **Self** - A new PKBoostRegressor instance.
```

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

### PKBoostBuilder::build_with_data method

Source: https://docs.rs/pkboost/latest/src/pkboost/model.rs.html

Builds an OptimizedPKBoostShannon model from data. If auto-parameter selection is enabled, it computes data statistics and prints dataset information before constructing the model.

```rust
pub fn build_with_data(
    self,
    x: ArrayView2<'_, f64>,
    y: ArrayView1<'_, f64>,
) -> OptimizedPKBoostShannon {
    if self.use_auto_params {
        let stats = compute_data_stats(x, y.as_slice().unwrap());
        let imbalance = (1.0 - stats.pos_ratio) / stats.pos_ratio.max(1e-6); // class weight

        println!("\nAuto-Parameter Selection :");
        println!("  Dataset shape: {} × {}", stats.n_rows, stats.n_cols);
        println!("  Positive ratio: {:.3}", stats.pos_ratio);
        println!("  Missing rate: {:.3}", stats.missing_rate);

        let mut model = OptimizedPKBoostShannon {
            n_estimators: 0,
            learning_rate: 0.0,
            max_depth: 0,
            min_samples_split: 0,
            min_child_weight: 0.0,
            reg_lambda: 0.0,
            gamma: 0.0,
            subsample: 0.0,
            colsample_bytree: 0.0,
            early_stopping_rounds: 0,
```

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

### PKBoostBuilder methods for setting hyperparameters

Source: https://docs.rs/pkboost/latest/src/pkboost/model.rs.html

Provides builder methods to set each hyperparameter and enable auto-parameter selection. Each method consumes and returns self for chaining.

```rust
impl PKBoostBuilder {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn auto(mut self) -> Self {
        self.use_auto_params = true;
        self
    }

    pub fn n_estimators(mut self, n: usize) -> Self {
        self.n_estimators = Some(n);
        self
    }

    pub fn learning_rate(mut self, lr: f64) -> Self {
        self.learning_rate = Some(lr);
        self
    }

    pub fn max_depth(mut self, depth: usize) -> Self {
        self.max_depth = Some(depth);
        self
    }

    pub fn min_samples_split(mut self, n: usize) -> Self {
        self.min_samples_split = Some(n);
        self
    }

    pub fn min_child_weight(mut self, weight: f64) -> Self {
        self.min_child_weight = Some(weight);
        self
    }

    pub fn reg_lambda(mut self, lambda: f64) -> Self {
        self.reg_lambda = Some(lambda);
        self
    }

    pub fn gamma(mut self, g: f64) -> Self {
        self.gamma = Some(g);
        self
    }

    pub fn subsample(mut self, ratio: f64) -> Self {
        self.subsample = Some(ratio);
        self
    }

    pub fn colsample_bytree(mut self, ratio: f64) -> Self {
        self.colsample_bytree = Some(ratio);
        self
    }

    pub fn early_stopping_rounds(mut self, rounds: usize) -> Self {
        self.early_stopping_rounds = Some(rounds);
        self
    }

    pub fn histogram_bins(mut self, bins: usize) -> Self {
        self.histogram_bins = Some(bins);
        self
    }

    pub fn mi_weight(mut self, weight: f64) -> Self {
        self.mi_weight = Some(weight);
        self
    }

    pub fn scale_pos_weight(mut self, weight: f64) -> Self {
        self.scale_pos_weight = Some(weight);
        self
    }
}
```

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

### Get system state and metamorphosis count

Source: https://docs.rs/pkboost/latest/src/pkboost/living_booster.rs.html

Getter methods that return the current SystemState and the metamorphosis count.

```rust
    pub fn get_state(&self) -> SystemState {
        self.state
    }

    pub fn get_metamorphosis_count(&self) -> usize {
        self.metamorphosis_count
    }
```

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

### MultiClassPKBoost::new

Source: https://docs.rs/pkboost/latest/pkboost/multiclass/struct.MultiClassPKBoost.html

Creates a new MultiClassPKBoost instance with the specified number of classes.

```APIDOC
## MultiClassPKBoost::new

### Description
Creates a new MultiClassPKBoost instance with the specified number of classes.

### Method
new

### Signature
pub fn new(n_classes: usize) -> Self

### Parameters
- **n_classes** (usize) - Required - The number of classes for the multi-class classification task.

### Returns
Self - A new MultiClassPKBoost instance.
```

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

### Get is_fitted, n_trees, to_bytes, from_bytes, to_json

Source: https://docs.rs/pkboost/latest/src/pkboost/python_bindings.rs.html

These methods expose state and serialization. get_n_trees, to_bytes, and to_json raise PyRuntimeError when not fitted; from_bytes is a static method that deserializes with serde_json and sets fitted to true. to_bytes returns the JSON-serialized model as PyBytes; to_json returns a String.

```rust
#[getter]
fn is_fitted(&self) -> bool {
    self.fitted
}
```

```rust
fn get_n_trees(&self) -> PyResult<usize> {
    if !self.fitted {
        return Err(PyRuntimeError::new_err(
            "Model not fitted. Call fit() first.",
        ));
    }
    Ok(self.model.as_ref().map(|m| m.trees.len()).unwrap_or(0))
}
```

```rust
fn to_bytes<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
    if !self.fitted {
        return Err(PyRuntimeError::new_err(
            "Model not fitted. Call fit() first.",
        ));
    }
    let model = self
        .model
        .as_ref()
        .ok_or_else(|| PyRuntimeError::new_err("Model not initialized"))?;
    let json_bytes = serde_json::to_vec(model)
        .map_err(|e| PyValueError::new_err(format!("Serialization failed: {}", e)))?;
    Ok(PyBytes::new(py, &json_bytes))
}
```

```rust
fn from_bytes(_py: Python<'_>, data: &Bound<'_, PyBytes>) -> PyResult<Self> {
    let bytes = data.as_bytes();
    let model: OptimizedPKBoostShannon = serde_json::from_slice(bytes)
        .map_err(|e| PyValueError::new_err(format!("Deserialization failed: {}", e)))?;
    Ok(Self {
        model: Some(model),
        fitted: true,
    })
}
```

```rust
fn to_json(&self) -> PyResult<String> {
    if !self.fitted {
        return Err(PyRuntimeError::new_err(
            "Model not fitted. Call fit() first.",
        ));
    }
    let model = self
        .model
        .as_ref()
        .ok_or_else(|| PyRuntimeError::new_err("Model not initialized"))?;
    let json = serde_json::to_string(model)
        .map_err(|e| PyValueError::new_err(format!("Serialization failed: {}", e)))?;
    Ok(json)
}
```

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

### PKBoostAdaptive fit_initial method

Source: https://docs.rs/pkboost/latest/src/pkboost/python_bindings.rs.html

Rust implementation of the fit_initial method for PKBoostAdaptive. Accepts numpy arrays for x, y, and optional validation data, converts them to readonly arrays, and trains an AdversarialLivingBooster. The verbose parameter defaults to false. Raises PyValueError if training fails.

```rust
    #[pyo3(signature = (x, y, x_val=None, y_val=None, verbose=None))]
    fn fit_initial<'py>(
        &mut self,
        py: Python<'py>,
        x: &Bound<'py, PyAny>,
        y: &Bound<'py, PyAny>,
        x_val: Option<&Bound<'py, PyAny>>,
        y_val: Option<&Bound<'py, PyAny>>,
        verbose: Option<bool>,
    ) -> PyResult<()> {
        let x_arr = to_readonly_array2(py, x)?;
        let y_arr = to_readonly_array1(py, y)?;
        let x_val_arr = x_val.map(|xv| to_readonly_array2(py, xv)).transpose()?;
        let y_val_arr = y_val.map(|yv| to_readonly_array1(py, yv)).transpose()?;
        let verbose = verbose.unwrap_or(false);

        let x_view = x_arr.as_array();
        let y_view = y_arr.as_array();
        let eval_set = match (&x_val_arr, &y_val_arr) {
            (Some(xv), Some(yv)) => Some((xv.as_array(), yv.as_array())),
            _ => None,
        };

        let mut booster = AdversarialLivingBooster::new(x_view, y_view);
        booster
            .fit_initial(x_view, y_view, eval_set, verbose)
            .map_err(|e| PyValueError::new_err(format!("Training failed: {}", e)))?;
        self.booster = Some(booster);
        self.fitted = true;
        Ok(())
    }
```

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

### PKBoostBuilder::auto

Source: https://docs.rs/pkboost/latest/pkboost/model/struct.PKBoostBuilder.html

Enables automatic hyperparameter tuning or selection.

```APIDOC
## PKBoostBuilder::auto

### Description
Enables automatic hyperparameter tuning or selection.

### Method
auto

### Signature
pub fn auto(self) -> Self

### Parameters
None

### Returns
Self - The builder instance for chaining.
```

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

### Fit method: auto-initialize model and train

Source: https://docs.rs/pkboost/latest/src/pkboost/python_bindings.rs.html

If the model is not already initialized, create it automatically with OptimizedPKBoostShannon::auto. Then fit the model, using internal Rayon parallelism. Errors are mapped to PyValueError with 'Training failed' prefix; a missing model raises PyRuntimeError.

```rust
// Initialize model if using auto mode
if self.model.is_none() {
    self.model = Some(OptimizedPKBoostShannon::auto(x_view, y_view));
}

// Fit model - Rayon provides internal parallelism
if let Some(ref mut model) = self.model {
    model
        .fit(x_view, y_view, eval_set, verbose)
        .map_err(|e| PyValueError::new_err(format!("Training failed: {}", e)))?;
    self.fitted = true;
    Ok(())
} else {
    Err(PyRuntimeError::new_err("Model initialization failed"))
}
```

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

### Model Training and Adaptive Observation

Source: https://docs.rs/pkboost/latest/src/pkboost/lib.rs.html

Demonstrates fitting an initial model and observing new data batches to allow the model to adapt automatically.

```rust
    model.fit_initial(&x_train, &y_train, None, true)?;

    // As new data arrives, observe it (model adapts automatically)
    let x_new: Vec<Vec<f64>> = vec![/* new batch */];
    let y_new: Vec<f64> = vec![/* new labels */];
    model.observe_batch(&x_new, &y_new, true)?;

    // Check model state
    println!("Vulnerability score: {:.4}", model.get_vulnerability_score());
    println!("Metamorphosis count: {}", model.get_metamorphosis_count());

    Ok(())
```

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

### Initialize PKBoostRegressorPy

Source: https://docs.rs/pkboost/latest/src/pkboost/python_bindings.rs.html

Constructors for the PKBoostRegressorPy class.

```rust
#[new]
    fn new() -> Self {
        Self {
            model: None,
            fitted: false,
        }
    }

    #[staticmethod]
    fn auto() -> Self {
        Self {
            model: None,
            fitted: false,
        }
    }
```

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

### Initialize and Auto-tune OptimizedPKBoostShannon

Source: https://docs.rs/pkboost/latest/src/pkboost/model.rs.html

This snippet shows the internal model initialization logic where hyperparameters are auto-tuned based on data statistics before constructing the final model instance.

```rust
histogram_bins: 0,
                mi_weight: 0.0,
                scale_pos_weight: 0.0,
                trees: Vec::new(),
                base_score: 0.0,
                best_iteration: 0,
                best_score: f64::NEG_INFINITY,
                fitted: false,
                loss_fn: OptimizedShannonLoss::new(),
                histogram_builder: None,
                auto_tuned: true,
                metric_history: Vec::new(),
                patience_counter: 0,
                binned_data_cache: None,
            };

            // let the auto-tuner set all hyperparameters based on data characteristics
            auto_tune_principled(&mut model, stats.n_rows, stats.n_cols, stats.pos_ratio);
            model.scale_pos_weight = imbalance;

            OptimizedPKBoostShannon {
                n_estimators: self.n_estimators.unwrap_or(model.n_estimators),
                learning_rate: self.learning_rate.unwrap_or(model.learning_rate),
                max_depth: self.max_depth.unwrap_or(model.max_depth),
                min_samples_split: self.min_samples_split.unwrap_or(model.min_samples_split),
                min_child_weight: self.min_child_weight.unwrap_or(model.min_child_weight),
                reg_lambda: self.reg_lambda.unwrap_or(model.reg_lambda),
                gamma: self.gamma.unwrap_or(model.gamma),
                subsample: self.subsample.unwrap_or(model.subsample),
                colsample_bytree: self.colsample_bytree.unwrap_or(model.colsample_bytree),
                early_stopping_rounds: self
                    .early_stopping_rounds
                    .unwrap_or(model.early_stopping_rounds),
                histogram_bins: self.histogram_bins.unwrap_or(model.histogram_bins),
                mi_weight: self.mi_weight.unwrap_or(model.mi_weight),
                scale_pos_weight: self.scale_pos_weight.unwrap_or(model.scale_pos_weight),
                trees: model.trees,
                base_score: model.base_score,
                best_iteration: model.best_iteration,
                best_score: model.best_score,
                fitted: model.fitted,
                loss_fn: model.loss_fn,
                histogram_builder: model.histogram_builder,
                auto_tuned: model.auto_tuned,
                metric_history: model.metric_history,
                patience_counter: model.patience_counter,
                binned_data_cache: None,
            }
        } else {
            self.build()
        }
    }
```

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

### PKBoostBuilder::build

Source: https://docs.rs/pkboost/latest/pkboost/model/struct.PKBoostBuilder.html

Builds the model using previously set data.

```APIDOC
## PKBoostBuilder::build

### Description
Builds the model using previously set data.

### Method
build

### Signature
pub fn build(self) -> OptimizedPKBoostShannon


### Parameters
None

### Returns
OptimizedPKBoostShannon - The built model.
```

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

### Perform Initial Training

Source: https://docs.rs/pkboost/latest/src/pkboost/living_booster.rs.html

Trains the primary model and calibrates vulnerability thresholds using an optional evaluation set.

```rust
pub fn fit_initial(
        &mut self,
        x: ArrayView2<'_, f64>,
        y: ArrayView1<'_, f64>,
        eval_set: Option<(ArrayView2<'_, f64>, ArrayView1<'_, f64>)>,
        verbose: bool,
    ) -> Result<(), String> {
        if verbose {
            println!("\n=== INITIAL TRAINING (Adversarial Living Booster) ===");
        }
        self.primary.fit(x, y, eval_set, verbose)?;

        // Calibrate vulnerability thresholds on validation set
        if let Some((x_val, y_val)) = eval_set {
            let y_val_slice = y_val.as_slice().unwrap();
            let calibration = crate::auto_tuner::VulnerabilityCalibration::calibrate_view(
                &self.primary,
                x_val,
                y_val_slice,
            );
```

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

### quick_train

Source: https://docs.rs/pkboost/latest/pkboost/model/fn.quick_train.html

Trains a PKBoost model using the provided training data and optional validation data. Returns an OptimizedPKBoostShannon model on success or an error string on failure.

```APIDOC
## Function: quick_train

### Description
Trains a PKBoost model using the provided training data and optional validation data. Returns an OptimizedPKBoostShannon model on success or an error string on failure.

### Signature
```rust
pub fn quick_train(
    x_train: ArrayView2<'_, f64>,
    y_train: ArrayView1<'_, f64>,
    x_val: Option<(ArrayView2<'_, f64>, ArrayView1<'_, f64>)>,
    verbose: bool,
) -> Result<OptimizedPKBoostShannon, String>
```

### Parameters
- **x_train** (ArrayView2<f64>) - Required - Training feature matrix.
- **y_train** (ArrayView1<f64>) - Required - Training label vector.
- **x_val** (Option<(ArrayView2<f64>, ArrayView1<f64>)>) - Optional - Validation feature matrix and label vector.
- **verbose** (bool) - Required - Whether to print progress information.

### Returns
- **Ok(OptimizedPKBoostShannon)** - The trained model.
- **Err(String)** - An error message if training fails.
```

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

### PKBoostBuilder::gamma

Source: https://docs.rs/pkboost/latest/pkboost/model/struct.PKBoostBuilder.html

Sets the minimum loss reduction required to make a further partition.

```APIDOC
## PKBoostBuilder::gamma

### Description
Sets the minimum loss reduction required to make a further partition.

### Method
gamma

### Signature
pub fn gamma(self, g: f64) -> Self


### Parameters
- **g** (f64) - Required - The gamma value.

### Returns
Self - The builder instance for chaining.
```

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

### AdaptiveRegressor struct, new(), and fit_initial()

Source: https://docs.rs/pkboost/latest/src/pkboost/living_regressor.rs.html

Defines the AdaptiveRegressor struct, its state and diagnostics enums, and the constructor plus initial training method. The constructor sets alert/metamorphosis thresholds, buffer size, and cooldown based on sample count, then prints configuration. fit_initial trains the primary PKBoostRegressor and validates learning by computing training RMSE.

```rust
1// Adaptive regression with drift detection and metamorphosis
2// Regression equivalent of AdversarialLivingBooster
3
4use crate::constants::*;
5use crate::metabolism::FeatureMetabolism;
6use crate::optimized_data::TransposedData;
7use crate::regression::calculate_rmse;
8use crate::regression::PKBoostRegressor;
9use crate::tree::{OptimizedTreeShannon, TreeParams};
10use ndarray::{Array1, Array2, ArrayView1, ArrayView2};
11use rayon::prelude::*;
12use std::collections::VecDeque;
13
14#[derive(Debug, Clone, Copy, PartialEq)]
15pub enum SystemState {
16    Normal,
17    Alert { checks_in_alert: usize },
18    Metamorphosis,
19}
20
21pub struct RegressionVulnerability {
22    pub error: f64,
23    pub sample_idx: usize,
24}
25
26#[derive(Debug)]
27pub struct DriftDiagnostics {
28    pub error_entropy: f64,
29    pub feature_entropy: Vec<f64>,
30    pub drift_type: DriftType,
31    pub residual_autocorrelation: f64,
32    pub heteroscedasticity_score: f64,
33}
34
35#[derive(Debug, Clone, Copy)]
36pub enum DriftType {
37    Systemic,
38    Localized,
39    FeatureShift,
40}
41
42pub struct AdaptiveRegressor {
43    primary: PKBoostRegressor,
44    metabolism: FeatureMetabolism,
45    state: SystemState,
46    alert_trigger_threshold: usize,
47    metamorphosis_trigger_threshold: usize,
48    vulnerability_alert_threshold: f64,
49    baseline_rmse: f64,
50    consecutive_vulnerable_checks: usize,
51    observations_count: usize,
52    metamorphosis_count: usize,
53    recent_x: VecDeque<Vec<f64>>, // Keep as Vec for streaming buffer
54    recent_y: VecDeque<f64>,
55    buffer_size: usize,
56    metamorphosis_cooldown: usize,
57    iterations_since_metamorphosis: usize,
58    recent_rmse: VecDeque<f64>,
59    recent_vulnerabilities: VecDeque<RegressionVulnerability>,
60    vulnerability_ema: f64,
61    ema_alpha: f64,
62}
63
64impl AdaptiveRegressor {
65    /// Create new AdaptiveRegressor from ArrayView2 (zero-copy from Python)
66    pub fn new(x_train: ArrayView2<'_, f64>, y_train: ArrayView1<'_, f64>) -> Self {
67        let n_features = x_train.ncols();
68        let n_samples = x_train.nrows();
69
70        let (alert_thresh, meta_thresh) = if n_samples < 50_000 {
71            (1, 2)
72        } else if n_samples < 200_000 {
73            (2, 3)
74        } else {
75            (3, 5)
76        };
77
78        let buffer_sz = if n_samples < 50_000 { 10000 } else { 15000 };
79        let cooldown = if n_samples < 50_000 { 1000 } else { 5000 };
80
81        println!("\n=== Adaptive Regressor Configuration ===");
82        println!("Dataset: {} samples, {} features", n_samples, n_features);
83        println!("Alert trigger: {} checks", alert_thresh);
84        println!("Metamorphosis trigger: {} checks", meta_thresh);
85        println!("Buffer size: {} samples", buffer_sz);
86        println!("Cooldown: {} observations", cooldown);
87        println!("=========================================\n");
88
89        Self {
90            primary: PKBoostRegressor::auto(x_train, y_train),
91            metabolism: FeatureMetabolism::new(n_features),
92            state: SystemState::Normal,
93            alert_trigger_threshold: alert_thresh,
94            metamorphosis_trigger_threshold: meta_thresh,
95            vulnerability_alert_threshold: 0.5,
96            baseline_rmse: 0.0,
97            consecutive_vulnerable_checks: 0,
98            observations_count: 0,
99            metamorphosis_count: 0,
100            recent_x: VecDeque::with_capacity(buffer_sz),
101            recent_y: VecDeque::with_capacity(buffer_sz),
102            buffer_size: buffer_sz,
103            metamorphosis_cooldown: cooldown,
104            iterations_since_metamorphosis: 0,
105            recent_rmse: VecDeque::with_capacity(5),
106            recent_vulnerabilities: VecDeque::with_capacity(5000),
107            vulnerability_ema: 0.0,
108            ema_alpha: VULNERABILITY_EMA_ALPHA,
109        }
110    }
111
112    /// Initial training with ArrayView2 (zero-copy from Python)
113    pub fn fit_initial(
114        &mut self,
115        x: ArrayView2<'_, f64>,
116        y: ArrayView1<'_, f64>,
117        eval_set: Option<(ArrayView2<'_, f64>, ArrayView1<'_, f64>)>,
118        verbose: bool,
119    ) -> Result<(), String> {
120        if verbose {
121            println!("\n=== INITIAL TRAINING (Adaptive Regressor) ===");
122        }
123        self.primary.fit(x, y, eval_set, verbose)?;
124
125        // Validate model learned
126        let train_preds = self.primary.predict(x)?;
127        let train_preds_slice = train_preds.as_slice().unwrap();
128        let y_slice = y.as_slice().ok_or("y must be contiguous")?;
129        let train_rmse = calculate_rmse(y_slice, train_preds_slice);
130        let y_mean = y_slice.iter().sum::<f64>() / y_slice.len() as f64;

```

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

### PKBoostClassifier.new()

Source: https://docs.rs/pkboost/latest/src/pkboost/python_bindings.rs.html

Creates a new PKBoostClassifier instance with configurable hyperparameters. All parameters have default values.

```APIDOC
## PKBoostClassifier.new()

### Description
Creates a new PKBoostClassifier instance with configurable hyperparameters. All parameters have default values.

### Method
Constructor (Python class instantiation)

### Signature
`PKBoostClassifier(n_estimators=1000, learning_rate=0.05, max_depth=6, min_samples_split=20, min_child_weight=1.0, reg_lambda=1.0, gamma=0.0, subsample=0.8, colsample_bytree=0.8, scale_pos_weight=1.0)`

### Parameters
- **n_estimators** (int) - Optional - Number of boosting estimators. Default: 1000.
- **learning_rate** (float) - Optional - Learning rate. Default: 0.05.
- **max_depth** (int) - Optional - Maximum tree depth. Default: 6.
- **min_samples_split** (int) - Optional - Minimum samples required to split. Default: 20.
- **min_child_weight** (float) - Optional - Minimum child weight. Default: 1.0.
- **reg_lambda** (float) - Optional - L2 regularization term. Default: 1.0.
- **gamma** (float) - Optional - Minimum loss reduction required for split. Default: 0.0.
- **subsample** (float) - Optional - Subsample ratio of training instances. Default: 0.8.
- **colsample_bytree** (float) - Optional - Subsample ratio of columns when constructing trees. Default: 0.8.
- **scale_pos_weight** (float) - Optional - Controls balance of positive and negative weights. Default: 1.0.

### Returns
A new PKBoostClassifier instance.
```

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

### PKBoostRegressor::new constructor with default hyperparameters

Source: https://docs.rs/pkboost/latest/src/pkboost/regression.rs.html

Creates a PKBoostRegressor with default values: 1000 estimators, learning rate 0.05, max depth 6, and MSE loss. Sets best_score to infinity and fitted to false.

```rust
impl PKBoostRegressor {
    pub fn new() -> Self {
        Self {
            n_estimators: 1000,
            learning_rate: 0.05,
            max_depth: 6,
            min_samples_split: 100,
            min_child_weight: 1.0,
            reg_lambda: 1.0,
            gamma: 0.0,
            subsample: 0.8,
            colsample_bytree: 0.8,
            early_stopping_rounds: 50,
            histogram_bins: 32,
            trees: Vec::new(),
            base_score: 0.0,
            best_iteration: 0,
            best_score: f64::INFINITY,
            fitted: false,
            loss_type: RegressionLossType::MSE,
            loss_fn: MSELoss::new(),
            huber_loss: None,
            histogram_builder: None,
        }
    }
```

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

### AdversarialLivingBooster::fit_initial

Source: https://docs.rs/pkboost/latest/pkboost/living_booster/struct.AdversarialLivingBooster.html

Performs initial training of the booster using provided data, with optional evaluation set and verbose output.

```APIDOC
## AdversarialLivingBooster::fit_initial

### Description
Performs initial training with ArrayView2 and ArrayView1, supporting an optional evaluation set and verbose mode.

### Method
Method

### Signature
pub fn fit_initial(&mut self, x: ArrayView2<'_, f64>, y: ArrayView1<'_, f64>, eval_set: Option<(ArrayView2<'_, f64>, ArrayView1<'_, f64>)>, verbose: bool) -> Result<(), String>

### Parameters
- **x** (ArrayView2<f64>) - Required - Feature matrix for training.
- **y** (ArrayView1<f64>) - Required - Label vector for training.
- **eval_set** (Option<(ArrayView2<f64>, ArrayView1<f64>)>) - Optional - Evaluation dataset as a tuple of features and labels.
- **verbose** (bool) - Required - Whether to print verbose output.

### Returns
- **Result<(), String>** - Ok(()) on success, or Err with an error message.
```

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

### Build OptimizedPKBoostShannon Model

Source: https://docs.rs/pkboost/latest/src/pkboost/model.rs.html

The build method constructs an OptimizedPKBoostShannon instance with default hyperparameters if they are not provided by the user.

```rust
pub fn build(self) -> OptimizedPKBoostShannon {
        OptimizedPKBoostShannon {
            n_estimators: self.n_estimators.unwrap_or(1000),
            learning_rate: self.learning_rate.unwrap_or(0.05),
            max_depth: self.max_depth.unwrap_or(6),
            min_samples_split: self.min_samples_split.unwrap_or(100),
            min_child_weight: self.min_child_weight.unwrap_or(5.0),
            reg_lambda: self.reg_lambda.unwrap_or(2.0),
            gamma: self.gamma.unwrap_or(0.1),
            subsample: self.subsample.unwrap_or(0.8),
            colsample_bytree: self.colsample_bytree.unwrap_or(0.7),
            early_stopping_rounds: self.early_stopping_rounds.unwrap_or(75),
            histogram_bins: self.histogram_bins.unwrap_or(32),
            mi_weight: self.mi_weight.unwrap_or(0.3),
            scale_pos_weight: self.scale_pos_weight.unwrap_or(1.0),
            trees: Vec::new(),
            base_score: 0.0,
            best_iteration: 0,
            best_score: f64::NEG_INFINITY,
            fitted: false,
            loss_fn: OptimizedShannonLoss::new(),
            histogram_builder: None,
            auto_tuned: false,
            metric_history: Vec::new(),
            patience_counter: 0,
            binned_data_cache: None,
        }
    }
}
```

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

### new

Source: https://docs.rs/pkboost/latest/pkboost/partitioned_classifier/struct.PartitionedClassifier.html

Creates a new PartitionedClassifier instance with the given configuration.

```APIDOC
## new

### Description
Creates a new PartitionedClassifier instance with the given configuration.

### Method
Constructor

### Signature
pub fn new(config: PartitionConfig) -> Self

### Parameters
- **config** (PartitionConfig) - Required - The configuration for the partitioned classifier.

### Returns
- **Self** - A new PartitionedClassifier instance.
```

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

### OptimizedTreeShannon Initialization and Node Management

Source: https://docs.rs/pkboost/latest/src/pkboost/tree.rs.html

Methods for creating a new tree and setting leaf or split nodes within the structure.

```rust
impl OptimizedTreeShannon {
    pub fn new(max_depth: usize) -> Self {
        let max_nodes = 2_usize.pow(max_depth as u32 + 1);
        Self {
            max_depth,
            node_types: vec![0; max_nodes],
            leaf_values: vec![0.0; max_nodes],
            split_features: vec![0; max_nodes],
            split_thresholds: vec![0; max_nodes],
            left_children: vec![0; max_nodes],
            right_children: vec![0; max_nodes],
            feature_indices: Vec::new(),
        }
    }

    #[inline(always)]
    fn set_leaf(&mut self, node_idx: usize, value: f64) {
        self.node_types[node_idx] = 1;
        self.leaf_values[node_idx] = value;
    }

    #[inline(always)]
    fn set_split(
        &mut self,
        node_idx: usize,
        feature: usize,
        threshold: i16,
        left_child: usize,
        right_child: usize,
    ) {
        self.node_types[node_idx] = 2;
        self.split_features[node_idx] = feature;
        self.split_thresholds[node_idx] = threshold;
        self.left_children[node_idx] = left_child;
        self.right_children[node_idx] = right_child;
    }
```

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

### PKBoostBuilder::build_with_data

Source: https://docs.rs/pkboost/latest/pkboost/model/struct.PKBoostBuilder.html

Builds the model using the provided training data.

```APIDOC
## PKBoostBuilder::build_with_data

### Description
Builds the model using the provided training data.

### Method
build_with_data

### Signature
pub fn build_with_data(self, x: ArrayView2<'_, f64>, y: ArrayView1<'_, f64>) -> OptimizedPKBoostShannon

### Parameters
- **x** (ArrayView2<'_, f64>) - Required - The feature matrix.
- **y** (ArrayView1<'_, f64>) - Required - The target vector.

### Returns
OptimizedPKBoostShannon - The built model.
```

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

### Configure OptimizedPKBoostShannon with Builder Pattern

Source: https://docs.rs/pkboost

Use the builder pattern to set fine-grained hyperparameters for the OptimizedPKBoostShannon model, including regularization, sampling, and class weighting.

```rust
use pkboost::OptimizedPKBoostShannon;

let model = OptimizedPKBoostShannon::builder()
    .n_estimators(200)
    .learning_rate(0.05)
    .max_depth(6)
    .min_samples_split(10)
    .reg_lambda(1.0)
    .gamma(0.1)
    .subsample(0.8)
    .colsample_bytree(0.8)
    .early_stopping_rounds(20)
    .histogram_bins(32)
    .mi_weight(0.1)           // Mutual information weight for imbalance
    .scale_pos_weight(5.0)    // Weight for positive class
    .build();
```

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

### MSELoss::new

Source: https://docs.rs/pkboost/latest/pkboost/regression/struct.MSELoss.html

Creates a new instance of the MSELoss struct.

```APIDOC
## MSELoss::new

### Description
Creates a new instance of the MSELoss struct.

### Method
new

### Signature
pub fn new() -> Self

### Parameters
None

### Returns
- Self - A new MSELoss instance.
```

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

### Initialize Model Calibration

Source: https://docs.rs/pkboost/latest/src/pkboost/living_booster.rs.html

Configures baseline vulnerability and performance metrics during the initial training phase.

```rust
            self.baseline_vulnerability = calibration.baseline_vulnerability;
            self.vulnerability_alert_threshold = calibration.alert_threshold;
            self.vulnerability_metamorphosis_threshold = calibration.metamorphosis_threshold;

            // Set baseline PR-AUC for performance tracking
            let val_preds = self.primary.predict_proba(x_val)?;
            self.baseline_pr_auc = calculate_pr_auc(y_val_slice, val_preds.as_slice().unwrap());

            if verbose {
                println!("Baseline PR-AUC: {:.4}", self.baseline_pr_auc);
                println!("Vulnerability thresholds configured based on validation data");
            }
        }

        if verbose {
            println!("Initial training complete. Model ready for streaming.");
        }
        Ok(())
    }
```

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

### PKBoostBuilder::min_samples_split

Source: https://docs.rs/pkboost/latest/pkboost/model/struct.PKBoostBuilder.html

Sets the minimum number of samples required to split a node.

```APIDOC
## PKBoostBuilder::min_samples_split

### Description
Sets the minimum number of samples required to split a node.

### Method
min_samples_split

### Signature
pub fn min_samples_split(self, n: usize) -> Self

### Parameters
- **n** (usize) - Required - The minimum number of samples for a split.

### Returns
Self - The builder instance for chaining.
```

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

### Initialize AdversarialLivingBooster

Source: https://docs.rs/pkboost/latest/src/pkboost/living_booster.rs.html

Creates a new instance of AdversarialLivingBooster by analyzing dataset properties like imbalance and sample size to configure adaptive thresholds and buffers.

```rust
pub fn new(x_train: ArrayView2<'_, f64>, y_train: ArrayView1<'_, f64>) -> Self {
        let n_features = x_train.ncols();
        let n_samples = x_train.nrows();
        let y_slice = y_train.as_slice().unwrap();

        // figure out how imbalanced the data is - this affects everything
        let pos_ratio = y_slice.iter().sum::<f64>() / y_slice.len() as f64;
        let imbalance_level = if pos_ratio < 0.02 || pos_ratio > 0.98 {
            "extreme"
        } else if pos_ratio < 0.10 || pos_ratio > 0.90 {
            "high"
        } else if pos_ratio < 0.20 || pos_ratio > 0.80 {
            "moderate"
        } else {
            "balanced"
        };

        // Default thresholds (will be calibrated during fit_initial)
        let vuln_alert_threshold = 0.02;
        let vuln_meta_threshold = 0.03;

        // smaller datasets = be more agressive with adaptation
        let (alert_thresh, meta_thresh) = if n_samples < 50_000 {
            (1, 2) // More aggressive for testing
        } else if n_samples < 200_000 {
            (2, 3)
        } else {
            (3, 5) // larger datasets can afford to wait a bit
        };

        // keep a rolling window of recent data for retraining
        let buffer_sz = if n_samples < 50_000 {
            10000
        } else if n_samples < 200_000 {
            15000
        } else {
            20000
        };

        let cooldown = if n_samples < 50_000 {
            5000
        } else if n_samples < 200_000 {
            10000
        } else {
            15000
        };

        println!("\n=== Adaptive Metamorphosis Configuration ===");
        println!("Dataset: {} samples, {} features", n_samples, n_features);
        println!(
            "Positive ratio: {:.1}% ({})",
            pos_ratio * 100.0,
            imbalance_level
        );
        println!("Alert trigger: {} consecutive checks", alert_thresh);
        println!("Metamorphosis trigger: {} checks in alert", meta_thresh);
        println!("Buffer size: {} samples", buffer_sz);
        println!("Cooldown period: {} observations", cooldown);
        println!("Note: Vulnerability thresholds will be calibrated during fit_initial");
        println!("===========================================\n");

        Self {
            primary: OptimizedPKBoostShannon::auto(x_train, y_train),
            adversary: AdversarialEnsemble::new(pos_ratio),
            metabolism: FeatureMetabolism::new(n_features),
            state: SystemState::Normal,
            alert_trigger_threshold: alert_thresh,
            metamorphosis_trigger_threshold: meta_thresh,
            vulnerability_alert_threshold: vuln_alert_threshold,
            vulnerability_metamorphosis_threshold: vuln_meta_threshold,
            baseline_vulnerability: 0.0,
            consecutive_vulnerable_checks: 0,
            observations_count: 0,
            metamorphosis_count: 0,
            recent_x: VecDeque::with_capacity(buffer_sz),
            recent_y: VecDeque::with_capacity(buffer_sz),
            buffer_size: buffer_sz,
            metamorphosis_cooldown: cooldown,
            iterations_since_metamorphosis: 0,
            drift_analyzer: DriftAnalyzer::new(n_features),
            last_strategy: MetamorphosisStrategy::Conservative,
            recent_pr_aucs: VecDeque::with_capacity(5),
            baseline_pr_auc: 0.0,
        }
    }
```

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

### Model Serialization with Serde

Source: https://docs.rs/pkboost/latest/src/pkboost/lib.rs.html

Saves and loads an OptimizedPKBoostShannon model using JSON serialization.

```rust
use pkboost::OptimizedPKBoostShannon;

// Save model
let model = OptimizedPKBoostShannon::auto(&x_train, &y_train);
let json = serde_json::to_string(&model)?;
std::fs::write("model.json", json)?;

// Load model
let json = std::fs::read_to_string("model.json")?;
let model: OptimizedPKBoostShannon = serde_json::from_str(&json)?;
# Ok::<(), Box<dyn std::error::Error>>(())
```

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

### new

Source: https://docs.rs/pkboost/latest/pkboost/adversarial/struct.AdversarialEnsemble.html

Creates a new AdversarialEnsemble instance with a given position ratio for the model.

```APIDOC
## pub fn new(pos_ratio: f64) -> Self

### Description
Creates a new AdversarialEnsemble instance with a given positive ratio for the underlying model.

### Parameters
- `pos_ratio` (f64) - The positive ratio for the model.

### Returns
A new `AdversarialEnsemble` instance.
```

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

### fit_initial

Source: https://docs.rs/pkboost/latest/pkboost/living_regressor/struct.AdaptiveRegressor.html

Performs initial training of the AdaptiveRegressor with the provided data and optional evaluation set.

```APIDOC
## fit_initial

### Description
Performs initial training of the AdaptiveRegressor with the provided data and optional evaluation set.

### Method
fit_initial

### Signature
pub fn fit_initial(&mut self, x: ArrayView2<'_, f64>, y: ArrayView1<'_, f64>, eval_set: Option<(ArrayView2<'_, f64>, ArrayView1<'_, f64>)>, verbose: bool) -> Result<(), String>

### Parameters
- **x** (ArrayView2<f64>) - Required - Training features.
- **y** (ArrayView1<f64>) - Required - Training targets.
- **eval_set** (Option<(ArrayView2<f64>, ArrayView1<f64>)>) - Optional - Evaluation set for validation.
- **verbose** (bool) - Required - Whether to print progress.

### Returns
- **Result<(), String>** - Ok(()) on success, Err with error message on failure.
```

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

### OptimizedShannonLoss::new()

Source: https://docs.rs/pkboost/latest/pkboost/loss/struct.OptimizedShannonLoss.html

Creates a new instance of OptimizedShannonLoss.

```APIDOC
## new()

### Description
Creates a new instance of OptimizedShannonLoss.

### Method
new

### Signature
```rust
pub fn new() -> Self
```

### Parameters
None

### Returns
- **Self** - A new OptimizedShannonLoss instance.
```

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

### Fit method: training loop with early stopping and validation

Source: https://docs.rs/pkboost/latest/src/pkboost/regression.rs.html

Shows the core training loop of the fit method. It updates predictions with learning rate, computes validation RMSE every 10 iterations, prints progress every 50 iterations, and implements early stopping based on validation RMSE. After training, it truncates trees to the best iteration if an eval_set is provided and prints final metrics.

```rust
                    .zip(val_tree_preds.par_iter())
                    .for_each(|(p, &tp)| *p += self.learning_rate * tp);

                if (iter + 1) % 10 == 0 {
                    let mse: f64 = vp
                        .iter()
                        .zip(yv_slice.iter())
                        .map(|(p, y)| (p - y).powi(2))
                        .sum::<f64>()
                        / yv_slice.len() as f64;
                    let rmse = mse.sqrt();

                    if verbose && (iter + 1) % 50 == 0 {
                        println!("Iter {}: RMSE = {:.4}", iter + 1, rmse);
                    }

                    if rmse < self.best_score {
                        self.best_score = rmse;
                        self.best_iteration = iter;
                    }

                    if iter - self.best_iteration >= self.early_stopping_rounds {
                        if verbose {
                            println!("Early stopping at iter {}", iter + 1);
                        }
                        break;
                    }
                } else {
                    self.best_iteration = iter;
                }

                self.trees.push(tree);
            }

            self.fitted = true;

            if eval_set.is_some() {
                self.trees.truncate(self.best_iteration + 1);
            }

            let final_train_rmse = calculate_rmse(y_slice, &train_preds);

            if verbose {
                if eval_set.is_some() {
                    println!(
                        "Training complete. Trees: {}, Best Val RMSE: {:.4}, Train RMSE: {:.4}",
                        self.trees.len(),
                        self.best_score,
                        final_train_rmse
                    );
                } else {
                    println!(
                        "Training complete. Trees: {}, Train RMSE: {:.4}",
                        self.trees.len(),
                        final_train_rmse
                    );
                }
            }

            Ok(())
        }
```

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

### AUCCalculator::new

Source: https://docs.rs/pkboost/latest/pkboost/metrics/struct.AUCCalculator.html

Creates a new AUCCalculator instance.

```APIDOC
## AUCCalculator::new

### Description
Creates a new AUCCalculator instance.

### Method
new

### Signature
pub fn new() -> Self

### Parameters
None

### Returns
- **Self** - A new AUCCalculator instance.
```

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

### PKBoostClassifier.fit(x, y, x_val=None, y_val=None, verbose=None)

Source: https://docs.rs/pkboost/latest/src/pkboost/python_bindings.rs.html

Fits the model to the provided training data. This method uses true zero-copy by borrowing directly from NumPy arrays when possible.

```APIDOC
## PKBoostClassifier.fit(x, y, x_val=None, y_val=None, verbose=None)

### Description
Fits the model to the provided training data. This method uses true zero-copy by borrowing directly from NumPy arrays when possible.

### Method
Instance method

### Signature
`fit(x, y, x_val=None, y_val=None, verbose=None)`

### Parameters
- **x** (array-like, 2D) - Required - Training feature matrix.
- **y** (array-like, 1D) - Required - Training labels.
- **x_val** (array-like, 2D, optional) - Optional - Validation feature matrix.
- **y_val** (array-like, 1D, optional) - Optional - Validation labels.
- **verbose** (bool, optional) - Optional - Whether to print verbose output. Default: False.

### Returns
None on success.
```