Skip to main content

PharmcatParser

Converts long-read pharmacogenomics output — PharmCAT, pbStarPhase, or a plain Gene/Diplotype table — into the JSON format Geneyx Analysis consumes for PGx reporting.

Install it next to your own PacBio or ONT pipeline, run it on the output, and upload the result to Geneyx.

pip install PharmcatParser
pharmcat-parser HG002.pharmcat.report.json HG002.pbstarphase.json --output-json HG002.geneyx-pgx-results.json

Output format

A JSON array, one entry per gene, with exactly four fields:

[
  { "Id": "CYP2C19", "Name": "CYP2C19", "StarAllele": "*1/*1", "Activity": "Normal Metabolizer" }
]
  • Id / Name — the gene symbol. Both are required; the Geneyx report keys its result set on Id and filters on Name.
  • StarAllele — the diplotype (*1/*2).
  • Activity — the phenotype / metaboliser status (Normal Metabolizer), or null when it is not known.

These names are matched case-sensitively on the Geneyx side. Do not rename them.

A second file, <output>.provenance.json, is written alongside the result. It records the caller versions, the mapping-table versions used, per-gene warnings, and any term that had no Geneyx mapping. It is not part of the upload contract — it exists so a report can be traced back to what produced it.

Supported inputs

Input Detected by Provides
*.pharmcat.report.json name or pharmcatVersion diplotypes, phenotypes, tool + data versions
*.pharmcat.phenotype.json name or geneReports diplotypes, phenotypes
*.pbstarphase.json name or gene_details diplotypes only, for more genes than PharmCAT reports
*.csv / *.json table fallback Gene + Diplotype (+ optional Phenotype)

The minimal table is the upload format: a header with Gene and Diplotype is enough. Column names are matched loosely (gene, geneSymbol, symbol; diplotype, genotype, starAllele).

Why two files are better than one

PharmCAT only reports genes that have a CPIC or DPWG guideline. In a PacBio HG002 run, pbStarPhase called 35 genes and PharmCAT reported 22. Four of the dropped genes — NAT2, CYP1A2, CYP2A13, CYP2C8 — are covered by the Geneyx PGx report. Passing the pbStarPhase summary alongside the PharmCAT output recovers them; they arrive with a diplotype and no phenotype.

Where both files describe the same gene, PharmCAT wins: it normalises PharmVar sub-alleles (*4.015) to the core alleles (*4) that Geneyx uses.

Merging rules

  • One entry per gene. PharmCAT emits a gene report per phenotype source, so the same 22 genes appear under both CPIC and DPWG. One source is preferred and the other is consulted only as a fallback — see below.
  • Unmapped terms are dropped, not passed through. A PharmCAT phenotype with no Geneyx equivalent yields Activity: null plus a warning in the provenance file, rather than an unrecognised term that looks valid to the report.
  • Genotype-guided genes (IFNL3, VKORC1) take their StarAllele from the rewritten allele names rather than from the phenotype.
  • HLA alleles are truncated to two fields (*01:01:01:01 → *01:01).
  • Single-allele genes (MT-RNR1) are not written as a diplotype.

Choosing a phenotype source

PharmCAT phenotypes come from two guideline bodies, CPIC and DPWG, and they do not always agree. Pick one:

pharmcat-parser HG002.pharmcat.report.json --phenotype-source DPWG

The default is CPIC (the first entry of phenotype_source_preference in gene_rules.json). The choice only reorders the sources — it never narrows the output. When the chosen source has no usable phenotype for a gene, the next source in the default order is used instead, and the substitution is recorded:

{ "Id": "CYP2B6", "phenotypeSource": "CPIC",
  "warnings": ["no usable phenotype from DPWG; taken from CPIC"] }

"No usable phenotype" covers three cases: the source reported none at all (HG002 CPIC: CYP3A4, CYP4F2, VKORC1), it reported a no-call token such as n/a (HG002 DPWG: CYP2B6), or its term has no Geneyx mapping yet (HG002 DPWG: DPYD 2.0 (Normal Metabolizer)).

The source selection affects Activity only — StarAllele is identical either way, since both sources describe the same call. The preference actually used is written to the provenance file as phenotypeSourcePreference.

Mapping tables

The clinical vocabulary lives in PharmcatParser/Mappings/ as versioned JSON:

File Contains
gene_rules.json structural rules — source preference, HLA/sub-allele handling
phenotype_terms.json PharmCAT phenotype term → Geneyx Activity term
genotype_terms.json allele/diplotype rewrites for genotype-guided genes

The term tables are incomplete. Entries with a null target still need filling from the approved mapping sheet. Run the parser and read unmappedTerms in the provenance file to see exactly which terms are missing for your data.

Development

pip install -e .
pytest PharmcatParser/Test/Test_PharmcatParser.py -v

Test fixtures are real PacBio output for HG002, a public GIAB reference sample. No patient data belongs in this repository.

Metadata

Release files for PharmcatParser 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for PharmcatParser 0.1.0
File Size Uploaded Provenance Actions
pharmcatparser-0.1.0.tar.gz 22.5 kB Without provenance Details for pharmcatparser-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for PharmcatParser 0.1.0
File Interpreter ABI Platform Actions
pharmcatparser-0.1.0-py3-none-any.whl Python 3 none any Details for pharmcatparser-0.1.0-py3-none-any.whl

Total release size: 49.9 kB

Release files / pharmcatparser-0.1.0.tar.gz

Download URL pharmcatparser-0.1.0.tar.gz
Size 22.5 kB
Tags Source
SHA-256 checksum
How to use checksums
f6c8a959fc66d8447bab59a16f86fa9e6dcc69644052ac0f46ff9fb1da197d93
BLAKE2b-256 checksum
How to use checksums
c585d6fc087aea0f9dd25075ec6cdbec6551f11de57ea78463e964c2778f07ff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Release files / pharmcatparser-0.1.0-py3-none-any.whl

Download URL pharmcatparser-0.1.0-py3-none-any.whl
Size 27.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
02854421a3b9cd659bca4fcf96727a79925235339b0062771e1b4a0815e2eed6
BLAKE2b-256 checksum
How to use checksums
87162165afd9c2c3bd0d25206e34bf2ab8cd949829a2c8c0ecdfe149d452009b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Security for PharmcatParser 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page