A collection of scripts and utility tools for everyday processing of biological data.
For detailed tool documentation, see docs/README.md.
- Python 3.12 or later
- uv (recommended) or pip
Note: Running the demultiplexing test recipes additionally requires the Illumina BCL-convert executable, which is not bundled with this repository because its redistribution is prohibited. Download it from the Illumina website and place it in the
assets/directory. See docs/README.md for details.
To only use biomate (no development setup), install it as an isolated tool:
uv tool install git+https://github.com/fagostini/BioMate
# With InterOp support (nspector --run-folder)
uv tool install "biomate[interop] @ git+https://github.com/fagostini/BioMate"
biomate --help# Clone repository
git clone https://github.com/fagostini/BioMate.git
cd BioMate
# Install all dependencies + dev tools
uv sync --al
8000
l-extras --all-groups
# Run commands with isolated environment
uv run biomate --help
uv run pytest tests/# Generate requirements.txt from lock file
uv export --frozen --output-file=requirements.txt
# Install dependencies
pip install -r requirements.txt
# Install package in development mode
pip install -e .
# Run commands
biomate --help
pytest tests/nspector and index --engine rust can use biomate_kernels, a compiled Rust extension in rust/biomate_kernels/. It is not on PyPI and is not built by uv sync or pip install. The Docker and Singularity images build and include it. Without it, nspector --engine auto (the default) uses the Python engine, which gives identical results but is about 20× slower on large runs (one hour against three minutes for 277 M reads).
Requirements:
- a Rust toolchain (
cargo,rustc), e.g. from rustup - maturin
>=1.5,<2.0, installed in the same environment asbiomate - a clone of this repository (the kernel is built from source)
In a development setup (make sync done, cargo on PATH), build it into .venv and check it:
make kernelsTo build it into another environment that runs biomate by hand:
uv pip install "maturin>=1.5,<2.0"
cd rust/biomate_kernels
VIRTUAL_ENV=../../.venv maturin develop --release- Always pass
--release. A debug build is many times slower. - In a conda shell, maturin refuses to build when both
CONDA_PREFIXandVIRTUAL_ENVare set. Prefix the command withenv -u CONDA_PREFIX. uv syncremoves packages the lock file does not list, including this one. Useuv sync --inexactto keep it, or rebuild after each sync.- Rebuild after pulling changes to
rust/biomate_kernels/. When the installed kernel is from another BioMate version,nspector --engine autowarns and uses Python, and--engine ruststops with an error.
Check the install:
uv run python -c "import biomate_kernels; print(biomate_kernels.SCAN_FORMAT)"BioMate uses a single source of truth for dependency management:
-
pyproject.toml- Source of truth- Defines all dependencies with version constraints
- Developers edit this file to change dependencies
- What gets published to PyPI
-
uv.lock- Reproducible builds- Machine-readable lock file with exact resolved versions
- Committed to repository
- Ensures reproducible builds across machines
-
requirements.txt- Generated artifact- Auto-generated from
uv.lockfor pip-only environments - NOT committed (regenerated as needed)
- Contains all transitive dependencies with hashes
- Auto-generated from
To update dependencies:
- Edit
pyproject.tomlto change version constraints - Run
uv lockto update lock file - Regenerate
requirements.txtif needed:uv export --frozen --output-file=requirements.txt - Commit:
pyproject.tomlanduv.lock
Use uv in CI pipelines (recommended):
- run: uv sync --all-extras --all-groups
- run: uv run pytest tests/Or use pip with generated requirements:
- run: uv export --frozen --output-file=requirements.txt
- run: pip install -r requirements.txt
- run: pytest tests/uv run pytest tests/ -vuv run ruff check src/
uv run ruff format src/uv run mkdocs serve# Install everything
uv sync --all-extras --all-groups
# See available tools
uv run biomate --help
# Example: Generate random sequences
uv run biomate blabber --seq-number 100 --seq-length 50
# Run tests
uv run pytest tests/ -vBioMate/
├── src/biomate/ # Main package source code
│ ├── blabber/ # Sequence generator
│ ├── dirstruct/ # Directory structure tool
│ ├── fastrewind/ # FASTQ file conversion
│ ├── index/ # Indexing tool
│ ├── nspector/ # FASTQ inspector
│ ├── strainer/ # Index analysis
│ └── web_interface.py # Tornado web UI
├── tests/ # Test suite
├── docs/ # Documentation
├── pyproject.toml # Dependency definitions
├── uv.lock # Frozen dependencies (committed)
└── README.md # This file
See LICENSE file for details.
See existing documentation for code standards and testing requirements.
Note: This project requires Python 3.12+. For development, using uv is strongly recommended for faster, more reliable dependency management.