checkbio

A static analysis linter that catches bioinformatics-specific mistakes in Python code — especially the kind AI coding assistants (Claude, Codex, ChatGPT, Copilot, etc.) tend to silently introduce.

It does not try to be a general-purpose linter. Use flake8/pylint/ ruff for that. checkbio only checks for domain-specific correctness issues that a general linter has no way of knowing about: genomic coordinate bugs, hallucinated or deprecated Biopython/pysam API usage, and file format mismatches.

Why

AI coding assistants are very good at producing plausible-looking bioinformatics code, and just as good at confidently getting domain-specific details wrong: mixing 0-based and 1-based coordinate systems, calling a Biopython API that was removed years ago, passing an invalid mode string to pysam.AlignmentFile. These bugs are usually silent — the code runs, sometimes even produces output, and just happens to be wrong. checkbio exists to catch the specific patterns that keep showing up.

Install

pip install checkbio

From source

git clone https://github.com/Affogat0/checkbio.git
cd checkbio
pip install -e .

Usage

checkbio script.py
checkbio pipeline/*.py

Example output:

examples/bad_example.py
  12:0  [BIO001] 'Bio.Alphabet' was removed in Biopython 1.78 (2020)...
  15:11 [REF001] Found an hg19/GRCh37 reference and an hg38/GRCh38 reference in the same file...
  19:13 [LOC003] Found chromosome name 'chr1' and 'MT' in the same file...
  25:14 [BIO002] 'fastq-generic' is not a recognized Bio.SeqIO format string...
  31:11 [PYS001] 'read' is not a valid pysam.AlignmentFile mode string...
  37:11 [PYS002] '.fetch()' requires an index file (.bai/.csi/.crai)...
  43:11 [PYS003] '.fetch()' called with argument(s) ['vcf_pos'] that look 1-based...
  49:7  [LOC001] Comparing a 0-based coordinate directly against a 1-based coordinate...
  57:11 [LOC002] Slicing with genomic-position-like variable(s) ['start', 'end']...
  62:11 [TAB001] Merge key(s) ['position'] include a genomic position column but no chromosome column...
  68:4  [CLI001] Call to 'samtools' via subprocess does not verify the command succeeded...

checkbio: 3 error(s), 9 warning(s)

As a pre-commit hook

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Affogat0/checkbio
    rev: v0.1.0
    hooks:
      - id: checkbio

Rule families

Rules are grouped into families by ID prefix, following the same pattern as tools like ESLint/Ruff. This will grow well past v0.1 — the prefix tells you at a glance what domain a warning belongs to without needing to memorize individual rule numbers.

Rules (v0.1)

Known limitations (v0.1):

• PYS002 flags every .fetch()/.pileup() call, even ones already correctly guarded by an index check. Real guard-detection needs data-flow analysis (on the roadmap) — for now it's a reminder, not a definitive error.
• LOC003 and REF001 are file-level heuristics based on string literals — they won't catch mismatches that only appear via runtime values (e.g. a chromosome name read from a config file at runtime), and a deliberate liftover step will trigger a (correct, but not-actually-a-bug) flag.
• TAB001 only inspects string literal merge keys — it won't catch keys built dynamically (e.g. a list constructed in a variable before being passed to on=).

Roadmap

• Data-flow-aware PYS002 (stop flagging already-guarded .fetch() calls)
• VCF family: multi-allelic assumptions, genotype/INFO field presence, variant normalization before comparison
• SEQ family: translation frame mistakes, ambiguous base (IUPAC) assumptions, sequence-type confusion (protein vs. nucleotide)
• ID family: Ensembl ID version suffix mismatches, gene symbol vs. stable ID joins, species mismatches
• NET family: NCBI/Entrez rate limiting, missing email/API key, retry/backoff on remote calls
• File-extension vs. parser-library mismatch detection (e.g. calling a FASTA parser on a .vcf path)
• GitHub Action for CI-time checking on pull requests
• VS Code extension for real-time inline flagging

Contributing

This project exists to catch real, recurring mistakes — if you've hit a bioinformatics-specific bug that an AI coding assistant introduced (or that you've seen a colleague hit), please open an issue describing it. Concrete before/after code examples are the most useful thing you can contribute.

License

MIT