Free-Dose Check

A small, inspectable design aid for a specific question: under a finite-bath, single-site equilibrium model, can free ligand reasonably be approximated by added ligand across a planned titration? It computes depletion and exact one-variable cell-count or volume limits, rather than declaring an assay “valid.”

Version 0.1.0. Research use only. Biological validation is not yet established.

Public demo

Open Free-Dose Check on GitHub Pages. No installation or sign-in is required. Select “Load & run” to explore an explicitly synthetic example, or supply your own conditions and evidence notes.

The demo opens in dark mode, with a Light/Dark toggle available in the header. Theme choices apply to the current page session only; no browser storage is used.

The public demo is built from main by the public-demo GitHub Actions workflow. Tests must pass before the static site is uploaded and deployed. The Python runtime bundle and downloadable source snapshot are generated in that build, so the demo uses the same calculation source as the CLI. See docs/deployment.md for maintenance and verification.

Run

Requires Python 3.10 or later. The installed package has no third-party runtime dependencies.

python -m pip install .
free-dose-check analyze examples/constrained.json --json report.json --csv doses.csv

Or from Python:

import json
from free_dose_check import analyze
report = analyze(json.load(open("examples/constrained.json")))

The browser executes the same package in pinned Pyodide 0.27.7. It does not reimplement the solver in JavaScript. Experimental values are not transmitted, stored in browser storage, or sent to an analysis server. Loading the interface and runtime requires network access; hosting/CDN providers receive ordinary asset requests.

What this release does

• Computes free and bound ligand, occupancy, depletion, and the error in naive occupancy at each concentration.
• Propagates user-supplied affinity and accessible-site bounds without invented midpoint estimates or confidence intervals.
• Separates model applicability, depletion assessment, and operating-constraint feasibility.
• Forward-checks rounded cell-count and volume recommendations.
• Exports full-precision deterministic JSON and CSV with embedded context.
• Compares one alternative count/volume condition against the same model and assumptions.

Scientific boundary

Only equilibrium, effectively monovalent 1:1 binding with independent sites in a well-mixed, conserved system is represented. Internalization, avidity, multiple affinity classes, nonspecific sinks, wash-induced dissociation, functional potency, and assay qualification are outside scope. Functional EC50/IC50 is rejected as an affinity input.

The established finite-bath equations and the influence of depletion on binding interpretation are described by Hulme and Trevethick (2010). The cell-binding context is discussed by Hunter and Cochran (2016). Related depletion-aware kinetic work already exists; this project does not claim a new binding theory (Kamprath et al., 2023).

Reproduce verification and build

python -m pip install -e '.[test]'
python -m pytest
python tools/build_web.py
python -m build

Serve web/ with any static HTTP server. The browser downloads a Python package ZIP assembled from src/; run the build script after any core change. No application backend is required. A pinned runtime CDN is needed for the browser; the Python CLI works offline.

The included static server is python tools/serve.py --port 3000. In a separate terminal, optional browser verification uses npm ci, npx playwright install chromium, then npm run test:browser. Afterward, run python tools/check_browser_parity.py /tmp/free-dose-qa to compare exported reports with native Python. The Node dependency is test-only, not part of the application runtime.

See docs/model.md, docs/assumptions.md, docs/validation.md, and docs/quickstart.md. The release specification is in docs/specification.md. Synthetic examples are not experimental validation.

License

Original project code and documentation are released under the MIT License, copyright 2026 dataRichinsightPoor. No third-party scientific dataset is bundled. Runtime, fonts, and test/build dependencies retain their own licenses; the project license does not replace their terms.