# FitOptions reference

{py:class}`~pykinbiont.FitOptions` is a dataclass that controls everything: preprocessing,
clustering, and fitting. Every field has a sensible default — pass only what you need to change.

```python
from pykinbiont import FitOptions

opts = FitOptions(
    smooth=True,
    smooth_method="rolling_avg",
    multistart=True,
    n_restart=30,
)
```

## Smoothing

| Field | Type | Default | Description |
|---|---|---|---|
| `smooth` | `bool` | `False` | Enable smoothing before fitting |
| `smooth_method` | `str` | `"lowess"` | Method: `"lowess"`, `"rolling_avg"`, `"gaussian"`, `"boxcar"`, `"none"` |
| `smooth_pt_avg` | `int` | `7` | Window size for `rolling_avg` and `gaussian` |
| `boxcar_window` | `int` | `5` | Window size for `boxcar` |
| `lowess_frac` | `float` | `0.05` | Fraction of data used for each LOWESS fit |
| `gaussian_h_mult` | `float` | `2.0` | Bandwidth multiplier for Gaussian kernel |
| `gaussian_time_grid` | `ndarray \| None` | `None` | Custom time grid for Gaussian resampling |

## Blank subtraction and negative values

| Field | Type | Default | Description |
|---|---|---|---|
| `blank_subtraction` | `bool` | `False` | Subtract a blank OD from all curves |
| `blank_value` | `float` | `0.0` | OD value to subtract (used when `blank_subtraction=True`) |
| `blank_from_labels` | `bool` | `False` | Compute blank from curves labelled "blank" |
| `correct_negatives` | `bool` | `False` | Handle OD values that go negative after blank subtraction |
| `negative_method` | `str` | `"remove"` | `"remove"`, `"thr_correction"`, `"blank_correction"` |
| `negative_threshold` | `float` | `0.01` | Minimum OD floor for `thr_correction` |

## Scattering correction

| Field | Type | Default | Description |
|---|---|---|---|
| `scattering_correction` | `bool` | `False` | Enable scattering correction |
| `calibration_file` | `str` | `""` | Path to calibration CSV (required when `scattering_correction=True`) |
| `scattering_method` | `str` | `"interpolation"` | `"interpolation"` or `"exp_fit"` |

## Stationary phase trimming

| Field | Type | Default | Description |
|---|---|---|---|
| `cut_stationary_phase` | `bool` | `False` | Remove stationary-phase data before fitting |
| `stationary_percentile_thr` | `float` | `0.05` | Percentile of max OD used as stationarity threshold |
| `stationary_pt_smooth_derivative` | `int` | `10` | Smoothing window for derivative used to detect stationarity |
| `stationary_win_size` | `int` | `5` | Window to confirm stationarity |
| `stationary_thr_od` | `float` | `0.02` | Minimum OD for a point to be considered in stationary phase |

## Clustering

```{admonition} Clustering is preprocessing, not fitting
:class: important

Setting `cluster=True` runs k-means clustering on the curve shapes and populates
`GrowthData.clusters`, but **does not fit growth models**. Use `preprocess()` for
clustering, then `fit()` separately for model fitting.
```

| Field | Type | Default | Description |
|---|---|---|---|
| `cluster` | `bool` | `False` | Run k-means clustering |
| `n_clusters` | `int` | `3` | Number of clusters (≥ 2) |
| `cluster_trend_test` | `bool` | `True` | Filter constant curves before clustering |
| `cluster_prescreen_constant` | `bool` | `False` | Remove constant curves entirely |
| `cluster_tol_const` | `float` | `1.5` | IQR multiplier for constant-curve detection |
| `cluster_q_low` | `float` | `0.05` | Lower quantile for normalization |
| `cluster_q_high` | `float` | `0.95` | Upper quantile for normalization |
| `cluster_exp_prototype` | `bool` | `False` | Use exponential-phase prototypes for cluster shapes |
| `kmeans_n_init` | `int` | `10` | Number of k-means random restarts |
| `kmeans_max_iters` | `int` | `300` | Maximum k-means iterations |
| `kmeans_tol` | `float` | `1e-6` | Convergence tolerance |
| `kmeans_seed` | `int` | `0` | Random seed for reproducibility |

## Fitting

| Field | Type | Default | Description |
|---|---|---|---|
| `loss` | `str` | `"RE"` | Loss function: `"RE"` (relative error), `"L2"` |
| `multistart` | `bool` | `False` | Run optimizer from `n_restart` random starting points |
| `n_restart` | `int` | `50` | Number of random restarts when `multistart=True` |
| `aic_correction` | `bool` | `True` | Use AICc (corrected AIC) instead of AIC for model selection |
| `pt_smooth_derivative` | `int` | `7` | Window for growth rate derivative estimate |
| `opt_params` | `dict` | `{}` | Extra keyword arguments forwarded to the Julia optimizer |

### `opt_params`

Pass additional options to the underlying Optim.jl optimizer. Keys must be valid Julia
identifiers; values must be `int`, `float`, or `bool`:

```python
opts = FitOptions(
    opt_params={
        "maxiters": 5000,
        "abstol": 1e-8,
    }
)
```

## Example combinations

**Minimal — log-linear only, no preprocessing:**

```python
opts = FitOptions()
```

**Smooth + blank subtraction:**

```python
opts = FitOptions(
    smooth=True,
    smooth_method="rolling_avg",
    smooth_pt_avg=5,
    blank_subtraction=True,
    blank_value=0.015,
    correct_negatives=True,
    negative_method="thr_correction",
    negative_threshold=0.001,
)
```

**Robust multistart fitting:**

```python
opts = FitOptions(
    multistart=True,
    n_restart=50,
    loss="L2",
    aic_correction=True,
)
```