# XGBoost Model

XGBoost model for time series regression/classification, with a built-in `TimeSeriesPreprocessor` for rolling features and scaling.

## Model Parameters (`Booster`)

These parameters are defined in the `model.yaml` under `opt_params_map` (which configure the XGBoost booster training) and are also represented in `schemas.yaml` under `components.schemas.opt_params` with concrete `example` values used during automated validation:

| Parameter               | Example  | Description                                                                 |
|-------------------------|----------|-----------------------------------------------------------------------------|
| `tree_method`           | `"hist"` | Tree construction algorithm. Options: `'hist'`, `'exact'`, `'approx'`, etc. |
| `device`                | `"cuda"` | Device for computation (`cuda` or `cpu`).                                   |
| `learning_rate`         | `0.3`    | Step size shrinkage to prevent overfitting.                                 |
| `n_estimators`          | `100`    | Number of boosting rounds.                                                  |
| `max_depth`             | `32`     | Maximum depth of a tree.                                                    |
| `subsample`             | `0.8`    | Subsample ratio of the training instances (0–1).                            |
| `colsample_bytree`      | `0.8`    | Subsample ratio of columns when constructing each tree (0–1).               |
| `min_child_weight`      | `5`      | Minimum sum of instance weight in a child node.                             |
| `random_state`          | `42`     | Seed for XGBoost random number generation. Set this to make training fully reproducible. |
| `early_stopping_rounds` | `None`   | If set, enables early stopping after N rounds with no improvement on validation. Requires an internal 15% validation split. |

## Data Model Parameters (`TimeSeriesPreprocessor`)

These parameters are defined in the `model.yaml` under `data_model.input_map` and are also represented in `schemas.yaml` under `components.schemas.data_model` with concrete `example` values used during automated validation:

| Parameter         | Example                                              | Description                                                                 |
|-------------------|------------------------------------------------------|-----------------------------------------------------------------------------|
| `scaler_method`   | `"MinMax"`                                           | Scaling strategy, either `'MinMax'`, `'Standard'` or None for no scaling.   |
| `window_size`     | `3`                                                  | Rolling window size used to generate lagged statistics for the target. Zero disables rolling features. |
| `use_filtering`   | `true`                                               | Whether to filter rows based on a CI column during `fit` when `arpr_config` is provided. |
| `transform_mode`  | `"all"`                                              | Prediction mode, `'all'` to keep all rows or `'latest'` to return only the last row. |
| `arpr_config`     | `{"ci_col": "ci", "ar_col": "ar", "pr_col": "pr"}`   | Optional configuration mapping `'ci_col'`, `'ar_col'` and `'pr_col'` names used for AR/PR substitution. |

### Rolling Features

When `window_size > 0`, the preprocessor generates rolling features for the target: `rolling_mean`, `rolling_max`, `rolling_min`, `rolling_std`.

### AR/PR Substitution

If `arpr_config` contains `ar_col`, `pr_col`, and `ci_col`, rows where `ci_col == 0` have `ar_col` replaced with `pr_col`.

## Lifecycle (train / retrain)

The wrapper follows the `SientiaModel` interface. Data is always passed as full DataFrames (features + target).

- **`train(train_data, val_data, target)`**  
  - `train_data`: full training DataFrame (features + target column).  
  - `val_data`: full validation DataFrame (features + target column).  
  - `target`: name of the target column (must exist in both).  
  The base class fits the transformer on the full datasets, then transforms and fits the model on transformed features and target.

- **`retrain(data)`**  
  - `data`: full dataset (features + target column).  
  Uses `self.target` set during `train()`. Call only after `train()` has been run. Retrain uses an internal 15% validation split when `early_stopping_rounds` is set.

Neither method mutates the passed DataFrames.

## Data Format

- Timestamp must be represented only on the DataFrame index (do not provide `timestamp` or `Timestamp` as regular columns).
- Input and output frames used in `transform()`/`predict()` must use `DatetimeIndex` with datetime64 dtype.
- Runtime validation checks that output max timestamp stays aligned with the corresponding input max timestamp for both `transform` and `predict` flows.
- Training uses an internal 15% validation split when `early_stopping_rounds` is set.
- **Data Alignment**: The wrapper automatically aligns the target variable with the features after transformation. This ensures that if the preprocessor drops rows (e.g., due to rolling windows or lags), the model training remains consistent.

All fields documented above should remain consistent across:

- This README
- `model.yaml` (`opt_params_map` and `data_model.input_map`)
- `schemas.yaml` (`components.schemas.opt_params` and `components.schemas.data_model`)

Examples defined in `schemas.yaml` are used directly during runtime validation to build `opt_params` and `transformer_kwargs`. Parameters without examples may not be fully exercised in the automated validation flow, so authors should always provide realistic and complete examples for all relevant fields.