BioMapper

biomapper

Python client for the BioMapper2 API — map biological entity names to standardized knowledge-graph identifiers (CHEBI, HMDB, PubChem, RefMet, and more).

from biomapper import map_entity

result = map_entity("L-Histidine") print(result.primary_curie) # RM:0129894 print(result.confidence_tier) # high print(result.ids_for("CHEBI")) # ['15971'] print(result.equivalent_ids_for("HMDB")) # ['HMDB0000177']

---

Installation

# Core (async HTTP client + Pydantic models)

pip install biomapper

With the external benchmark suite

pip install 'biomapper[benchmarks]'

The core install includes the MCP server for agents (Claude Code, Claude Desktop, other MCP clients); launch it with uvx biomapper (see Use from an agent (MCP)).

Use 1.6.2 or later for `uvx biomapper`. 1.6.0 and 1.6.1 shipped the server behind an mcp extra (uvx --from 'biomapper[mcp]' biomapper-mcp); that line still works on 1.6.2.

Use 1.5.6 or later for `harmonize_cohorts()` and ambiguous-link flags (see Harmonization).

Use 1.5.4 or later to call the hosted deployment without a key (see API keys).

Use 1.5.3 or later for the benchmark suite. Earlier published releases, up to and including 1.4.0, ship neither biomapper.benchmarks nor the benchmarks extra, so pip install 'biomapper[benchmarks]' against them warns that the extra is unknown and installs only the core client. 1.5.2 contains the suite but its extras were published empty, so the same command installs the core client without pandas, requests, rdkit, openpyxl or defusedxml and the suite fails on first import; install those by hand if you are pinned to 1.5.2. 1.5.3 is the first release whose benchmarks extra actually carries its dependencies. The changelog records which versions reached the index; 1.5.0 and 1.5.1 are tagged *(not published)*.

---

Notebooks

• notebooks/biomapper_tutorial.ipynb: the harmonization protocol end to end, keyless and build-pinned: resolve two cohort panels, link them by identifier-only CURIE sets, and read a certified and a refused structural certificate.
• notebooks/monti_overlap_benchmark.ipynb: BioMapper vs Monti et al. 2026 on the NECS cross-cohort overlap, as linked-count coverage for four cohorts plus a structural certification of the NECS to Arivale links, replayed from a pinned run with a small live check.
• notebooks/ukbb_arivale_harmonization_sop.ipynb: a standard operating procedure for harmonizing two cohorts with this package, worked on UK Biobank × Arivale (metabolites, proteins, clinical labs): inclusion rules, map, match, verify, and results asserted against the Activity 2 milestone, replayed offline from shipped panel metadata.

---

API keys (optional)

No API key is needed for the hosted deployment (https://biomapper.expertintheloop.io). From 1.5.4 the client is keyless by default: with no key configured it sends no X-API-Key header, and every entry point, including the synchronous wrappers, works as shown below.

A key is only for a self-hosted or authenticated deployment. Pass it as api_key=, or set it in your environment:

export BIOMAPPER_API_KEY=your-key-here

or in a .env file in your project root:

BIOMAPPER_API_KEY=your-key-here

A configured key is sent unless anonymous=True is passed. To force a keyless call while BIOMAPPER_API_KEY is set, use BioMapperClient(anonymous=True). If a deployment does require a key and none was sent, the first request raises BioMapperAuthError saying so.

Releases before 1.5.4 raise BioMapperConfigError when no key is configured, and their synchronous wrappers cannot reach a keyless deployment; upgrade, or use BioMapperClient(anonymous=True) directly.

---

Quick start

Single lookup (synchronous)

from biomapper import map_entity

result = map_entity("L-Histidine")

print(result.resolved) # True print(result.primary_curie) # RM:0129894 print(result.chosen_kg_id) # CHEBI:15971 print(result.chosen_kg_id_review) # None (or 'divergent_refmet' when a ChEBI conflict is flagged for review) print(result.confidence_score) # 2.489 print(result.confidence_tier) # high (≥2.0) print(result.ids_for("CHEBI")) # ['15971'] print(result.ids_for("refmet_id")) # ['RM0129894']

KG equivalent IDs — all identifiers from the resolved knowledge graph node

print(result.kg_equivalent_ids) # {'CHEBI': ['15971', '44637'], 'HMDB': ['HMDB0000177'], ...} print(result.equivalent_ids_for("HMDB")) # ['HMDB0000177']

Batch mapping (synchronous)

from biomapper import map_entities, summarize

records = [ {"name": "L-Histidine"}, {"name": "Glucose", "identifiers": {"HMDB": "HMDB00122"}}, {"name": "Sphinganine"}, ]

results = map_entities(records, progress=True) # tqdm bar with [notebook] summary = summarize(results)

print(f"{summary.resolved}/{summary.total_queried} resolved") print(f"Resolution rate: {summary.resolution_rate:.1%}") print(summary.vocabulary_coverage)

Inputs are auto-chunked at 1000 entities per request against the native POST /map/batch endpoint, so 10,000 records cost 10 round-trips.

Dataset upload (synchronous)

For larger inputs, hand the server a TSV/CSV file directly and stream results back. The server processes the file row-by-row over the POST /map/dataset/stream endpoint:

from pathlib import Path

from biomapper import map_dataset_file_sync

result = map_dataset_file_sync( Path("compounds.tsv"), name_column="name", provided_id_columns=["hmdb_id"], progress=True, # tqdm bar total_hint=1000, # optional; enables % progress ) result.raise_for_error() # opt-in: raise BioMapperError if the stream truncated print(f"resolved {sum(1 for r in result.results if r.resolved)} of {len(result.results)}")

name_column and provided_id_columns are required — the server uses them to map your file's columns to entity names and identifier hints. For per-result streaming into a UI or custom processing, use the async BioMapperClient.map_dataset_file_iter method (see the tutorial notebook in notebooks/).

Discovering what the API supports

from biomapper import list_annotators, list_vocabularies, list_entity_types

for a in list_annotators(): print(f"{a.slug:30s} {a.name}")

300+ supported vocabularies (CHEBI, HMDB, PubChem, …)

vocabs = list_vocabularies() print(f"{len(vocabs)} vocabularies supported")

Biolink entity types with aliases and default vocabulary prefixes

for et in list_entity_types(): print(f"{et.type}: {', '.join(et.aliases)}") if et.default_prefixes: print(f" prefixes: {', '.join(et.default_prefixes)}")

Tuning resolution

The mapping calls accept the API's resolution options as keyword arguments. An option you do not pass is omitted from the request, so the server's own default applies and the payload is unchanged for callers who ignore them.

Coverage is uneven, so check this before reaching for one. Passing an option to a call that does not accept it raises TypeError locally, before any request:

array_delimiters is absent from the dataset routes because the API does not accept it there. The four missing from map_dataset_file_sync are a gap in that wrapper rather than an API limitation: the async map_dataset_file_iter underneath it does accept them, so use that directly if you need them on a file-based run.

from biomapper import map_entity  # map_entity / map_entities accept all six

result = map_entity( "PC 34:1", vocab="refmet", # restrict to one vocabulary (or a list) prefer_human=False, # gene/protein: allow a non-human ortholog to win prefer_canonical=False, # non-gene: allow a non-canonical-namespace node to win candidate_limit=20, # candidates each Kestrel search annotator retrieves (1..100) array_delimiters=["|"], # how delimited ID strings are split kestrel_top_n=5, # opt in to raw Kestrel passthrough rows (1..100) )

kestrel_top_n populates result.kestrel_results with the raw rows Kestrel returned, exactly as returned, for each search endpoint the pipeline used. Those rows are untrusted external data: treat every field as unescaped and unverified.

Resolution certificates and refusal

A mapping result carries the structural certificate the API computed for chosen_kg_id, which is how you tell "we could not check this" apart from "we checked and disagree".

result = map_entity("cortisone")

cert = result.certificate if cert is not None: print(cert.state) # corroborated | uncorroborated | contradicted |

unavailable | not_applicable

print(cert.independent_source) # registry consulted, e.g. "pubchem" print(cert.independent_of_selection) # False => corroboration would be circular print(cert.refmet_availability) # voted | no_match | unavailable | not_queried

Why the resolver declined, when it did. Distinct from error:

an error means the call failed; a refusal means the pipeline ran and declined to assert.

print(result.refusal_reason)

state="contradicted" means a human should look, not that the resolver is wrong: a name lookup at an external registry can itself return a related-but-different compound. state="unavailable" means there was nothing to check against, which is unverifiable rather than wrong.

Async usage

import asyncio

from biomapper import BioMapperClient

async def main() -> None: async with BioMapperClient() as client:

Verify connectivity

health = await client.health_check() print(health) # {'status': 'healthy', ...}

Single

result = await client.map_entity( "L-Histidine", identifiers={"HMDB": "HMDB00177"}, )

Batch — auto-chunked at 1000 entities per request

results = await client.map_entities( [{"name": "L-Histidine"}, {"name": "Glucose"}], progress=True, )

Stream from a file — per-result as they arrive

from pathlib import Path async for r in client.map_dataset_file_iter( Path("compounds.tsv"), name_column="name", provided_id_columns=["hmdb_id"], ): print(r.query_name, r.primary_curie)

asyncio.run(main())

map_dataset_file_iter is the primitive for UIs and custom processing that want per-result reactivity. Callers needing a