Tablassert

PyPI Downloads Python CI License Docs GitHub stars

Extract knowledge assertions from tabular data into NCATS Translator-compliant KGX NDJSON, declaratively, with entity resolution built in and optional quality control.

Tablassert turns biomedical spreadsheets (Excel, CSV, TSV) into knowledge graphs ready for NCATS Translator. Declare how your columns map to subject-predicate-object statements in YAML; Tablassert resolves free text to standard CURIEs, attaches provenance and statistical annotations, and emits KGX-compliant nodes and edges.

Full Documentation : installation guides, tutorial, configuration reference, and API docs.

pip install tablassert

Given a CSV of gene-disease associations with p-values and sample sizes, declare the mapping in a table config (table.yaml):

template:
 source:
 kind: text
 local: ./gene-disease.csv
 url: https://example.com/data.csv
 row_slice: [1, auto]
 delimiter: ","
 statement:
 subject: { method: column, encoding: A, prioritize: [Gene] }
 predicate: associated_with
 object: { method: column, encoding: B, prioritize: [Disease] }
 provenance: { repo: PMID, publication: "12345678" }
 annotations:
 - { annotation: p_value, method: column, encoding: C }
 - { annotation: study_size, method: column, encoding: D }

Wrap it in a graph config (graph.yaml) pointing at your fullmap entity-resolution database and carrying the required rig: metadata for the generated Resource Ingest Guide:

name: MY_KG
version: 1.0.0
tables:
 - ./table.yaml
fullmap: /path/to/fullmap
rig:
 source_info:
 infores_id: infores:my-kg
 terms_of_use_info:
 terms_of_use_url: https://example.org/terms
 data_access_locations:
 - My source downloads - https://example.org/downloads
 source_status: maintained_regular_updates
 ingest_info:
 utility: Gene-disease associations support Translator disease-mechanism queries.
 scope: Gene-disease associations extracted from tabular sources.
 provenance_info:
 contributions:
 - "Author Name - code author, data modeling"
 artifact_base_url: https://example.org/my-kg
 artifact_base_path: ./published/my-kg

Build the knowledge graph:

tablassert build-kg graph.yaml

Output is one JSON object per line: nodes with Biolink categories, edges with annotations.

{"id":"HGNC:11998","name":"TP53","category":["biolink:Gene"],"taxon":"NCBITaxon:9606"}
{"id":"MONDO:0008903","name":"lung cancer","category":["biolink:Disease"]}

{"subject":"HGNC:11998","predicate":"biolink:associated_with","object":"MONDO:0008903","p_value":"1.0000e-03","has_supporting_studies":{"PMID:12345678":{"id":"PMID:12345678","name":"gene-disease.csv","study_size":450,"has_study_results":[{"id":"row:2"}]}}}

See the Tutorial for the full walkthrough.

• Declarative YAML configuration: define data transformations without writing code
• Built-in entity resolution: map free text to genes, diseases, and chemicals with standard CURIEs, taxonomic filtering, and provenance, backed by an embedded redb database
• Optional quality control: a four-stage audit (exact → fuzzy → abbreviation → SapBERT embeddings) flags low-confidence mappings
• KGX compliance: emits NCATS Translator-compatible node/edge NDJSON with Biolink categories and predicates
• Autonomous agent: tablassert agent derives, builds, and refines configs for whole papers
• Performance & reproducibility: lazy Polars pipelines and a deterministic UV-based development environment

pip install tablassert

Or with uv: uv tool install tablassert. The base install builds knowledge graphs from CSV/TSV/Excel sources; optional extras add runtime and pipeline capabilities:

QC is opt-in at build time (build-kg --qc). Reaching a feature whose extra is not installed never produces a bare ModuleNotFoundError: the failure names the missing package and the exact install command, and for build-kg --qc and tablassert agent it arrives before the run starts rather than partway through. Logging is the exception: without the log extra it degrades to a stdlib fallback instead of failing. See the Installation guide for the full matrix and the CLI Reference for every flag.

from pathlib import Path
from tablassert.lib import resolve_many
results = resolve_many(
 col="gene",
 entities=["TP53", "BRCA1"],
 fullmap=Path("/path/to/fullmap"),
 taxon="9606",
)
# [{"original_gene": "TP53", "gene": "HGNC:11998", "gene_name": "TP53", ...}, ...]

Point resolve_many() at a fullmap database to resolve any iterable of entity strings to CURIEs, no LazyFrame setup or NLP preprocessing required. See the Batch Resolution API for the full reference.

• Installation : install methods, extras, and development setup
• Tutorial : step-by-step example with synthetic data
• CLI Reference : complete command-line flag reference
• Use Case Gallery : real-world configuration patterns
• Configuration : graph and table configuration reference
• Agent : the autonomous agent pipeline
• API Reference : core functions documentation

uv sync --group dev --extra qc --extra log
uv run maturin develop --manifest-path rust/Cargo.toml
make check

See CONTRIBUTING.md for the full development loop, quality gates, and pull request guidelines.

If you use Tablassert, please cite it as described in CITATION.cff. The approach is described in:

Skye Lane Goetz, Alex K. Glen, and Gwênlyn Glusman. "MicrobiomeKG: bridging microbiome research and host health through knowledge graphs." Frontiers in Systems Biology 5 (2025). doi:10.3389/fsysb.2025.1544432

Apache License 2.0

• Skye Lane Goetz, Institute for Systems Biology
• Gwênlyn Glusman, Institute for Systems Biology
• Jared C. Roach, Institute for Systems Biology