FitOptions reference

FitOptions is a dataclass that controls everything: preprocessing, clustering, and fitting. Every field has a sensible default — pass only what you need to change.

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

Clustering is preprocessing, not fitting

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:

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

Example combinations

Minimal — log-linear only, no preprocessing:

opts = FitOptions()

Smooth + blank subtraction:

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:

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