|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## About This Project |
| 6 | + |
| 7 | +**libpetab-python** is the Python reference implementation of [PEtab](https://petab.readthedocs.io/), a standardized format for specifying parameter estimation problems in systems biology. It provides reading, writing, and validation of PEtab files. |
| 8 | + |
| 9 | +## Specs |
| 10 | + |
| 11 | +The PEtab specs can be found at: |
| 12 | + |
| 13 | +v1: https://github.com/PEtab-dev/PEtab/blob/main/doc/v1/documentation_data_format.rst |
| 14 | + |
| 15 | +v2: https://github.com/PEtab-dev/PEtab/blob/main/doc/v2/documentation_data_format.rst |
| 16 | + |
| 17 | + |
| 18 | +## Commands |
| 19 | + |
| 20 | +### Install for development |
| 21 | +```bash |
| 22 | +uv sync --extra tests --extra quality --extra vis --extra combine |
| 23 | +uv run pre-commit install |
| 24 | +``` |
| 25 | + |
| 26 | +### Run tests |
| 27 | +```bash |
| 28 | +# All unit tests |
| 29 | +uv run pytest tests/ |
| 30 | + |
| 31 | +# Single test file |
| 32 | +uv run pytest tests/v1/test_parameters.py |
| 33 | + |
| 34 | +# Single test |
| 35 | +uv run pytest tests/v1/test_parameters.py::test_get_optimization_parameter_scaling |
| 36 | +``` |
| 37 | + |
| 38 | +### Linting and formatting |
| 39 | +```bash |
| 40 | +uv run pre-commit run --all-files |
| 41 | +``` |
| 42 | + |
| 43 | +Uses **ruff** (linter + formatter), configured in `pyproject.toml` with 79-char line length. |
| 44 | + |
| 45 | +### Build docs |
| 46 | +```bash |
| 47 | +uv sync --extra doc --extra vis |
| 48 | +cd doc && make html |
| 49 | +``` |
| 50 | + |
| 51 | +## Architecture |
| 52 | + |
| 53 | +### V1 vs V2 API |
| 54 | + |
| 55 | +The package has two versioned APIs: |
| 56 | + |
| 57 | +- **`petab.v1`** — stable, pandas-DataFrame-based API (PEtab 1.x spec). This is what most existing code uses. |
| 58 | +- **`petab.v2`** — newer Pydantic-based API with stricter typing (PEtab 2.x spec). Still evolving. |
| 59 | + |
| 60 | +Top-level `petab.*` imports are legacy shims that forward to `petab.v1`; new code should use the versioned subpackage explicitly. |
| 61 | + |
| 62 | +### Core Data Model |
| 63 | + |
| 64 | +A PEtab problem is a collection of tables (stored as pandas DataFrames in v1, Pydantic models in v2): |
| 65 | + |
| 66 | +| Table | Content | |
| 67 | +|-------|---------| |
| 68 | +| **parameter** | Parameters to estimate (id, scale, bounds, priors) | |
| 69 | +| **condition** | Experimental conditions (parameter overrides per experiment) | |
| 70 | +| **measurement** | Experimental data (observable, time, value, condition reference) | |
| 71 | +| **observable** | Observable definitions (formula, noise formula) | |
| 72 | +| **mapping** | Maps PEtab observables to model entities (optional) | |
| 73 | +| **visualization** | Plot specifications (optional) | |
| 74 | + |
| 75 | +The **`Problem`** class (`v1/problem.py`, `v2/core.py`) is the central container that loads all tables and the dynamical model. |
| 76 | + |
| 77 | +### Constants (`C.py`) |
| 78 | + |
| 79 | +All column names and allowed values are defined as constants in `petab/v1/C.py` (and `petab/v2/C.py`). Always use these instead of string literals (e.g., `C.PARAMETER_ID`, `C.ESTIMATE`, `C.LOG10`). |
| 80 | + |
| 81 | +### Model Abstraction |
| 82 | + |
| 83 | +The `models/` subpackage provides an abstract `Model` base class with concrete implementations for SBML (`sbml_model.py`) and PySB (`pysb_model.py`). Use `model_from_file()` to load a model without knowing the type. |
| 84 | + |
| 85 | +### Mathematical Expressions |
| 86 | + |
| 87 | +Observable and noise formulas are symbolic expressions parsed via a generated ANTLR grammar in `v1/math/_generated/` (auto-generated — do not edit directly). Use `sympify_petab()` to parse them. The `_generated/` directory is excluded from ruff linting. |
| 88 | + |
| 89 | +### Validation |
| 90 | + |
| 91 | +`lint.py` contains the validation logic. The `petablint` CLI entry point calls `lint_problem()`. Linting checks cross-table consistency, required columns, type correctness, and formula validity. |
| 92 | + |
| 93 | +### Parameter Mapping |
| 94 | + |
| 95 | +`parameter_mapping.py` handles the non-trivial logic of resolving which parameter value applies for a given observable/condition combination, including condition-specific overrides and placeholder substitution in formulas. |
| 96 | + |
| 97 | +## Key Conventions |
| 98 | + |
| 99 | +- **Deprecation policy:** features deprecated in a minor release are kept for ≥ 6 months before removal. Use `warnings.warn(..., DeprecationWarning, stacklevel=2)`. See `doc/development.rst` for the full release process. |
| 100 | +- **Docstrings:** Sphinx/reStructuredText style with `:param name:` and `:return:` tags. |
| 101 | +- **Test layout:** `tests/v1/` for v1 API tests, `tests/v2/` for v2. Test fixtures live in `tests/v1/test_petab.py`. |
| 102 | +- **Auto-generated files:** `petab/*/math/_generated/` — never edit manually. |
0 commit comments