Resistance, and why the rules are hashed

Vendored algorithms, and content hashing over version labels. This page is rendered from a real run on every docs build — every value below was computed by the engine, not typed out. The notebook itself is ordinary Python you can download and run.


marimo edit examples/notebooks/04_resistance_and_its_rules.py   # as a notebook
python examples/notebooks/04_resistance_and_its_rules.py        # or as a plain script

Read the source on GitHub


from pathlib import Path
import marimo as mo
import ligase as lg
from ligase import hivdb
root = Path(__file__).resolve().parents[2]

4 — Resistance, and why the rules are hashed

Interpreting a mutation means asking a published algorithm what it means. Ligase ships Stanford’s HIVdb definitions in the package, pinned by checksum, and never calls a web service to find out.

The reason is not convenience. An interpretation that reaches the network for its meaning is not reproducible: the answer depends on the day you ran it, and no cache key can see that.


shipped = (hivdb.ALGORITHMS, hivdb.DEFAULT)
shipped


(('HIVDB_10.2', 'HIVDB_9.8'), 'HIVDB_9.8')

What goes into the cache key


HIVdb rules as shipped: 9.8 2025-01-05 blake3:a1139c719bfb76b221303ea9884ef093e1d0e4026a9028f2583e7b62ad42ce6b; 10.2 2026-04-26 blake3:3268c99f3d91dd7657a6c3ddda7281a2c1d246b7fad7a639670db66e96e98df1; read by ligase 0.4.0+14.g6c6a8b4

That is a BLAKE3 hash of each ruleset’s contents, not the string "9.8". The distinction is the whole discipline of this project applied to one field: a version label is metadata you can derive from content, and metadata lies. Edit a rule without touching the version and the hash moves, so every result that depended on it is recomputed. Switch 9.8 to 10.2 and only the steps that read the rules rerun.

The human-readable version still exists — it goes into the methods paragraph, where a reader needs “HIVdb 9.8” and a citation rather than a hash.


lg.remotes.configure(cache=root / '.ligase', offline=True)
try:
    hxb2 = lg.remote('ncbi:K03455.1', kind=lg.types.Reference, organism='HIV-1', build='HXB2')
except lg.RemoteError:
    hxb2 = None
have_demo_data = hxb2 is not None

Running it for real

The HIV-1 demo data is not in the store, so this cell is showing the rule metadata only. To run the interpretation for real:


python scripts/fetch_demo_data.py --project PRJNA1218827
ligase run examples/hiv-resistance/pipeline.py

!!! warning “Research use”

These calls are not for clinical use. Ligase’s validation checks its calls against published results, which is evidence the implementation is faithful to the algorithm — not evidence that it is fit for patient care.