# KinBiont.jl

pykinbiont is a thin Python bridge over [KinBiont.jl](https://github.com/pinheiroGroup/KinBiont.jl),
a Julia package for model-based analysis of microbial kinetics data developed by the Pinheiro Group.

## What KinBiont provides

KinBiont implements the full analysis pipeline in Julia:

- **Preprocessing** — smoothing (LOWESS, rolling average, Gaussian), blank subtraction,
  scattering correction, negative-value handling, stationary-phase trimming
- **Nonlinear fitting** — closed-form growth models (logistic, Gompertz, Richards, Baranyi, …)
  via `Optim.jl`
- **ODE fitting** — SciML-powered fitting for custom differential equation models
- **Data-Driven Differential Equations (DDDE)** — sparse regression to discover ODEs from data
- **Model selection** — AICc-based automatic selection across multiple candidate models
- **Clustering** — k-means clustering of curve shapes with centroid extraction

## Julia resources

| Resource | Link |
|---|---|
| KinBiont.jl source | <https://github.com/pinheiroGroup/KinBiont.jl> |
| Julia downloads | <https://julialang.org/downloads/> |
| PythonCall / juliacall | <https://juliapy.github.io/PythonCall.jl/stable/> |
| juliapkg | <https://github.com/JuliaPy/juliapkg.py> |

## How pykinbiont calls Julia

pykinbiont uses [juliacall](https://juliapy.github.io/PythonCall.jl/stable/juliacall/) to start
a Julia process in the same Python session. The bridge is transparent:

1. Python `GrowthData` / `FitOptions` / `ModelSpec` objects are converted to their Julia
   counterparts in `pykinbiont._convert`.
2. `Kinbiont.kinbiont_fit()` or `Kinbiont.preprocess()` is called from Python.
3. The Julia result structs are converted back to Python dataclasses.

For custom Python models (NLModel / ODEModel with a `func` argument), pykinbiont creates a
Julia closure that calls back into Python via PythonCall's `pyconvert`:

```julia
# Generated at runtime for each custom NLModel
(p, t) -> PythonCall.pyconvert(Vector{Float64}, pyfunc(p, t))
```

This means custom model functions are executed in Python on every optimizer call.
For performance-critical work, define the model in Julia directly.

## Accessing Julia directly

If you need to call KinBiont.jl functions not yet exposed by pykinbiont, you can
access the Julia module directly:

```python
import pykinbiont
pykinbiont.init()          # ensure Julia is started

jl = pykinbiont.get_jl()   # returns the juliacall Main module
print(list(jl.Kinbiont.MODEL_REGISTRY.keys()))
```

All juliacall features (type conversions, `seval`, etc.) are available through `get_jl()`.

## Version compatibility

| pykinbiont | KinBiont.jl |
|---|---|
| 0.2.x | ≥ 1.2.0 |

KinBiont.jl 1.2 introduced the unified `FitOptions` struct and `ModelSpec` API that
pykinbiont 0.2 relies on. Earlier KinBiont versions are not supported.