# Configuration

Every stage of `mobts` is controlled by small configuration dataclasses with sensible defaults. This page lists what each one controls and how to override it.

## Shared configuration

Used by both preprocessing and imputation.

### ColumnsConfig

The canonical internal names `mobts` renames your columns to during processing. Input and output column names are always your own (see [Data format](data_format.md)). This only matters if you are working with the package's internals directly.

| Field | Default |
|---|---|
| `counter` | `'counter'` |
| `timestamp` | `'timestamp'` |
| `count` | `'count'` |
| `weekday` | `'weekday'` |
| `week_num` | `'week_num'` |
| `hour` | `'hour'` |
| `how` (hour of week) | `'how'` |
| `date` | `'date'` |

### SparsityConfig

Controls when a counter is dropped for having too few valid observations.

| Field | Default |
|---|---|
| `sparse_threshold` | `0.5` |

A counter is dropped if the fraction of missing counts exceeds this threshold. Setting it to `1.0` effectively disables sparse-counter dropping, since no counter's missing rate can exceed 100%.

## Preprocessing configuration

### PreprocessConfig

Controls the always-on measurement-error rules described in [Preprocessing](preprocessing.md).

| Field | Default | Meaning |
|---|---|---|
| `low_abs_daily` | `5` | Absolute low-count threshold (daily) |
| `low_rel_daily` | `0.01` | Low-count threshold as a fraction of the counter's median |
| `low_run_min_daily` | `2` | Minimum consecutive low-count days before they're nulled |
| `zero_rate_max` | `0.05` | Max allowed rate of zero observations for an hour to be considered a real zero (hourly) |
| `zero_run_min` | `6` | Minimum consecutive zero hours before they're nulled |
| `island_max_len` | `6` | Max length of a real-looking "island" surrounded by gaps to still be nulled |
| `surround_min_len` | `12` | Minimum surrounding gap length for the island rule above to apply |

*Fixed, not currently overridable:* `night_hours` (`[1, 2, 3, 4, 5, 6]`). The hours excluded from the hourly zero-rate check.

### STLConfig (preprocessing)

Parameters for the STL decomposition used to compute each observation's outlier score. Only applies to daily data .Hourly outlier scoring uses a different, lighter-weight method.

| Field | Default |
|---|---|
| `period` | `28` |
| `robust` | `False` |

### OutlierConfig

The threshold an outlier score has to cross to be flagged and replaced with `NaN`.

| Field | Default |
|---|---|
| `threshold_daily` | `20` |
| `threshold_hourly` | `45` |

### PlotConfig

Cosmetic and sampling settings for `plot_outliers()`.

| Field | Default |
|---|---|
| `ncols` | `3` |
| `figsize_width` | `15` |
| `min_fig_height` | `10` |
| `height_per_row` | `3` |
| `linewidth_d` | `0.5` |
| `linewidth_h` | `0.3` |
| `x_label_rotation` | `45` |
| `default_max_counters` | `30` |

`default_max_counters` is only used when `plot_outliers()` is called without an explicit `counters` list or `max_counters` value .It caps how many counters get randomly sampled for the plot in that case.

### PipelineConfig

Aggregates all of the above into one object, passed to `preprocess()` as a whole:

```python
from mobts import preprocess
from mobts.configs.config_preprocessing import PipelineConfig, PreprocessConfig, OutlierConfig

custom_cfg = PipelineConfig(
    preprocess=PreprocessConfig(low_abs_daily=10),
    outliers=OutlierConfig(threshold_daily=15),
)

pp = preprocess(cfg=custom_cfg)
```

You only need to override the sub-config(s) you actually want to change. Anything you do not set keeps its default.

## Imputation configuration

Imputation doesn't have a single aggregating config object. Each config is passed to `impute()` individually.

### STLConfig (imputation)

A different class from the preprocessing `STLConfig` above, despite the same name .This one controls the STL-based gap-filling used as imputation's univariate fallback.

| Field | Default |
|---|---|
| `rolling_median_window` | `2` |
| `rolling_median_min_valid` | `1` |

*Fixed, not currently overridable:* `clip_lower` (`0`), `stl_robust` (`False`), `stl_season_daily` (`7`), `stl_season_hourly` (`168`).

### DonorsConfig

Thresholds governing donor eligibility and selection for the regression and scaled-median methods.

| Field | Default | Meaning |
|---|---|---|
| `max_donor_rate` | `0.5` | Fraction of correlated counters considered as candidate donors |
| `top_k_donor` | `21` | Maximum number of donors used per target counter |
| `min_mutual_days` / `min_mutual_hours` | `60` / `1440` | Minimum overlapping history required between target and donors |
| `min_pred_days` / `min_pred_hours` | `30` / `720` | Minimum length of the missing period for coverage checks to apply |
| `min_pred_coverage` | `1` | Minimum donor coverage required over the missing period |
| `sm_min_overlap_day` / `sm_min_overlap_hour` | `60` / `1440` | Minimum overlap required specifically for scaled-median imputation |

### OutputConfig

Names of the output columns imputation produces, and the labels written into `imputation_method`.

| Field | Default |
|---|---|
| `col_reg_imputed` | `'multi-variate(regression)'` |
| `col_sm_imputed` | `'multi-variate(scaled-medians)'` |
| `col_stl_imputed` | `'uni-variate(STL)'` |
| `col_final` | `'count_imputed/clean'` |
| `col_method_used` | `'imputation_method'` |

*Fixed, not currently overridable:* `col_intp` (`'count_intp'`), an internal interpolation column not present in final output.

```{note}
Column names containing `/` or `()` (the current `col_reg_imputed`/`col_sm_imputed`/`col_stl_imputed`/`col_final` defaults) work fine with normal pandas indexing (`df['multi-variate(regression)']`), but will break `df.query()`/`df.eval()` unless backtick-escaped, and can't be accessed as attributes (`df.count_imputed/clean` is not valid Python).
```

### Putting it together

```python
from mobts import impute
from mobts.configs.config_imputation import STLConfig, OutputConfig

imp = impute(
    stl_cfg=STLConfig(rolling_median_window=3),
    out_cfg=OutputConfig(col_final='final_count'),
)
```