Skip to content
koesterlabPublic

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

67 Commits

Folders and files

Repository files navigation

GitHub Workflow Status Conda Version Conda - License Conda Downloads

varpubs

varpubs is a command-line tool that automates retrieval and summarization of variant-associated biomedical literature to support faster variant interpretation in oncology.

Identifying treatment-relevant evidence for rare or poorly characterized mutations often requires reviewing large volumes of PubMed articles. varpubs streamlines this process by querying literature for variant-linked publications and generating concise, role-specific three-sentence summaries using a large language model (LLM). Optional LLM-based “judges” can score articles based on user given terms (e.g., therapy relevance) to prioritize relevant articles.

Variant-level summaries per transcript are annotated to the given input VCF file as well as the PubMed IDs of the used literature sources and mean judge scores for every given entry via --judges. A caching system stores previously generated summaries to reduce runtime in subsequent analyses.

Installation

Pixi

pixi global install varpubs

Bioconda

conda install -c bioconda varpubs

Usage

1. Deploy the PubMed variant database

varpubs deploy-db \
  --db-path pubmed.duckdb \
  --vcf-paths variants.vcf.gz other.vcf.gz \

The database can also (or instead) be built from a gene + variant TSV/CSV via --csv-paths variants.tsv (see the table columns below).

2. Summarize variant-associated articles

varpubs summarize-variants \
  --db-path pubmed.duckdb \
  --vcf-path variants_annotated.vcf.gz \
  --llm-url https://your-llm-endpoint \
  --api-key $HF_TOKEN \
  --model medgemma-27b-it \
  --role physician \
  --judges "therapy relevance" \
  --cache cache.duckdb \
  --output summaries.vcf \
  --output-cache tmp_cache.duckdb

Each LLM call starts with a budget of --max-new-tokens (default 500) and doubles it on every --retries attempt (default 3) if the response was cut off. Responses still truncated after the last attempt are discarded. Model reasoning is disabled by default and can be enabled via --enable-thinking true.

Instead of --vcf-path, pass --csv-path a gene + variant TSV/CSV. The input table is written back unchanged with appended varpubs_summary, varpubs_pmids and varpubs_<judge>_score columns:

varpubs summarize-variants \
  --db-path pubmed.duckdb \
  --csv-path variants.tsv \
  --gene-column gene \
  --variant-column variant \
  --llm-url https://your-llm-endpoint \
  --judges "therapy relevance" \
  --cache cache.duckdb \
  --output summaries.tsv

The delimiter is inferred from the file extension (.csv → comma, otherwise tab) and can be overridden with --delimiter. The variant column accepts HGVS protein changes in one- or three-letter form, with or without the p. prefix (e.g. p.Arg1748Ter, p.R1748*, R1748*).

3. Merge or update caches

varpubs update-cache \
  --cache tmp_cache.duckdb \
  --output cache.duckdb

Authors

  • Felix Wiegand
  • Felix Mölder
  • Hendrik Damm
  • İlmay Taş
  • Johannes Köster

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages