# pykinbiont

**Python interface for [KinBiont.jl](https://github.com/pinheiroGroup/KinBiont.jl)**

pykinbiont lets you run the full KinBiont microbial kinetics analysis pipeline from Python — loading
plate-reader data, fitting growth models, clustering curves, and exporting results — while keeping
all numerical computation inside Julia via
[juliacall](https://juliapy.github.io/PythonCall.jl/stable/juliacall/).

```{admonition} Julia required
:class: note

pykinbiont calls Julia under the hood. You need Julia ≥ 1.10 installed separately.
On first run Julia downloads and installs KinBiont and its dependencies automatically (~5 min).
```

## Highlights

- **One-call fitting** — pass a `GrowthData`, a `ModelSpec`, and `FitOptions`; get back
  a `GrowthFitResults` with the best model per curve selected by AICc.
- **All KinBiont models** — log-linear, logistic, Gompertz, Richards, ODEs, and more, accessible
  via `MODEL_REGISTRY`.
- **Custom models in Python** — wrap any `f(p, t)` function as an `NLModel` or write an
  in-place ODE as an `ODEModel`; the Julia bridge handles the callback.
- **Pure-Python preprocessing** — smoothing, blank subtraction, negative-value correction,
  stationary-phase trimming, and k-means clustering via `preprocess()`.
- **Tidy output** — `to_dataframe()` and `save_results()` give you pandas/CSV-ready results.

## Quick example

```python
import pykinbiont
from pykinbiont import GrowthData, FitOptions, ModelSpec, MODEL_REGISTRY, fit, save_results

# Point at a local KinBiont.jl clone (run once; persists to disk)
pykinbiont.configure("/path/to/KinBiont.jl")   # omit to use registry version

# Load a plate-reader CSV
data = GrowthData.from_csv("experiment.csv")   # time column first, then wells

# Choose a model from the registry
logistic = MODEL_REGISTRY["NL_logistic"]
spec = ModelSpec(
    models=[logistic],
    params=[[1.2, 0.01, 0.5]],    # [N_max, N0, mu]
    lower=[[0.3, 1e-3, 0.05]],
    upper=[[3.0, 0.05, 3.0]],
)

# Fit with smoothing
opts = FitOptions(smooth=True, smooth_method="rolling_avg", multistart=True, n_restart=20)
results = fit(data, spec, opts)

# Inspect
print(results.to_dataframe()[["label", "best_model", "aic"]])

# Save to CSV files
save_results(results, "output/", prefix="my_experiment")
```

---

```{toctree}
:maxdepth: 1
:caption: Getting started

installation
quickstart
kinbiont-jl
```

```{toctree}
:maxdepth: 2
:caption: User guide

user-guide/index
```

```{toctree}
:maxdepth: 1
:caption: Examples

examples/index
```

```{toctree}
:maxdepth: 2
:caption: API reference

api/index
```