Skip to main content

GeneyxPgxParser

Converts pharmacogenomics caller output — PharmCAT, pbStarPhase, PyPGx, 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 GeneyxPgxParser
geneyx-pgx-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
*.pbstarphase.tsv .tsv header diplotypes only (PacBio v4 summary)
<GENE>.tsv (PyPGx) .tsv header diplotype + phenotype, one gene per file
*.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:

geneyx-pgx-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.

PyPGx, and callers whose terms are already Geneyx terms

The Geneyx PyPgx pipeline has produced this JSON format since it shipped, by reading PyPGx's per-gene data.tsv and writing its Genotype and Phenotype columns straight through. Those values are the Geneyx vocabulary, so mapping them would change clinical output rather than normalise it — phenotype_terms.json maps none of PyPGx's G6PD, MT-RNR1 or CFTR terms, and genotype_terms.json knows only PharmCAT's allele names for the genotype-guided genes.

PyPGx is therefore listed in gene_rules.json under passthrough_sources: its calls skip term mapping, sub-allele stripping and HLA truncation entirely, and the sidecar records which callers were passed through:

{ "passthroughSources": ["pypgx"] }

Removing pypgx from that list is a clinical behaviour change gated on the GAN-8770 mapping sheet, not a refactor.

Each PyPGx file covers one gene, and the gene comes from the file name (CYP2C19.tsv), because PyPGx's own table has no gene column. A table still named data.tsv needs a Gene column, or parsing fails rather than reporting a gene called "data". Point the parser at the whole results folder:

geneyx-pgx-parser --input-dir /path/to/pgx/results --output-json sample.geneyx-pgx-results.json --gzip

Mapping tables

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

File Contains
gene_rules.json structural rules — source preference, passthrough callers, 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 GeneyxPgxParser/Test/Test_GeneyxPgxParser.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 GeneyxPgxParser 0.1.2

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

Built distributions (wheels)

Table of built distributions (wheels) for GeneyxPgxParser 0.1.2
File Actions
geneyxpgxparser-0.1.2-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for geneyxpgxparser-0.1.2-cp313-cp313-win_amd64.whl
geneyxpgxparser-0.1.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.28+ x86-64, Linux glibc 2.17+ x86-64 Details for geneyxpgxparser-0.1.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
geneyxpgxparser-0.1.2-cp313-cp313-macosx_10_13_x86_64.whl CPython 3.13 CPython 3.13 macOS 10.13+ x86-64 Details for geneyxpgxparser-0.1.2-cp313-cp313-macosx_10_13_x86_64.whl
geneyxpgxparser-0.1.2-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for geneyxpgxparser-0.1.2-cp312-cp312-win_amd64.whl
geneyxpgxparser-0.1.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64, Linux glibc 2.17+ x86-64 Details for geneyxpgxparser-0.1.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
geneyxpgxparser-0.1.2-cp312-cp312-macosx_10_13_x86_64.whl CPython 3.12 CPython 3.12 macOS 10.13+ x86-64 Details for geneyxpgxparser-0.1.2-cp312-cp312-macosx_10_13_x86_64.whl
geneyxpgxparser-0.1.2-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for geneyxpgxparser-0.1.2-cp311-cp311-win_amd64.whl
geneyxpgxparser-0.1.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64, Linux glibc 2.17+ x86-64 Details for geneyxpgxparser-0.1.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
geneyxpgxparser-0.1.2-cp311-cp311-macosx_10_9_x86_64.whl CPython 3.11 CPython 3.11 macOS 10.9+ x86-64 Details for geneyxpgxparser-0.1.2-cp311-cp311-macosx_10_9_x86_64.whl
geneyxpgxparser-0.1.2-cp310-cp310-win_amd64.whl CPython 3.10 CPython 3.10 Windows x86-64 Details for geneyxpgxparser-0.1.2-cp310-cp310-win_amd64.whl
geneyxpgxparser-0.1.2-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64, Linux glibc 2.17+ x86-64 Details for geneyxpgxparser-0.1.2-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
geneyxpgxparser-0.1.2-cp310-cp310-macosx_10_9_x86_64.whl CPython 3.10 CPython 3.10 macOS 10.9+ x86-64 Details for geneyxpgxparser-0.1.2-cp310-cp310-macosx_10_9_x86_64.whl
geneyxpgxparser-0.1.2-cp39-cp39-win_amd64.whl CPython 3.9 CPython 3.9 Windows x86-64 Details for geneyxpgxparser-0.1.2-cp39-cp39-win_amd64.whl
geneyxpgxparser-0.1.2-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl CPython 3.9 CPython 3.9 Linux glibc 2.28+ x86-64, Linux glibc 2.17+ x86-64 Details for geneyxpgxparser-0.1.2-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
geneyxpgxparser-0.1.2-cp39-cp39-macosx_10_9_x86_64.whl CPython 3.9 CPython 3.9 macOS 10.9+ x86-64 Details for geneyxpgxparser-0.1.2-cp39-cp39-macosx_10_9_x86_64.whl

Total release size: 18.4 MB

Release files / geneyxpgxparser-0.1.2-cp313-cp313-win_amd64.whl

Download URL geneyxpgxparser-0.1.2-cp313-cp313-win_amd64.whl
Size 425.6 kB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
8993cbc8ec5313ffbd9e3f2d1439634bedad69e2d5a8bf6d8c4601b4cacead9c
BLAKE2b-256 checksum
How to use checksums
c33ef9fd478c7f0e1ac591a33cb8d1d6fd92abb1d115c464ffba9a3a9bdddac8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Download URL geneyxpgxparser-0.1.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Size 2.8 MB
Tags CPython 3.13 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
e526f781bfd28170f18ddae52bccbcf41790bb5c1ca9cb5e4ad0a66a8e9b209e
BLAKE2b-256 checksum
How to use checksums
20f05391a7503b3c50518a49ca953034bac10e51cb49ea3009da4fa0cd7cec07
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp313-cp313-macosx_10_13_x86_64.whl

Download URL geneyxpgxparser-0.1.2-cp313-cp313-macosx_10_13_x86_64.whl
Size 468.2 kB
Tags CPython 3.13 macOS 10.13+ x86-64
SHA-256 checksum
How to use checksums
526a6d791a0132ce0bd80367579d61354560d70840166d58a9c1a31a89062715
BLAKE2b-256 checksum
How to use checksums
dc55f61b837a643e75158c825f9bf2cb755286141056611afb67912acc8f5ff3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp312-cp312-win_amd64.whl

Download URL geneyxpgxparser-0.1.2-cp312-cp312-win_amd64.whl
Size 432.3 kB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
36c591e78b507ab0283c55421325e967b60e79cd9ecdaf5347ae10f0da72e2eb
BLAKE2b-256 checksum
How to use checksums
de084b1075177f06e2f58810dd5db47657c42535d16978a3528e538f8670efeb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Download URL geneyxpgxparser-0.1.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Size 2.9 MB
Tags CPython 3.12 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
97986b79f0c963ae70bc7af4f977ac5a43c05dc556aaacb149c228a0710683f0
BLAKE2b-256 checksum
How to use checksums
a42ad4b94760e44ef6d7bbb17586cc1627dcb6c92a6154d7d2cfcf3746c95c50
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp312-cp312-macosx_10_13_x86_64.whl

Download URL geneyxpgxparser-0.1.2-cp312-cp312-macosx_10_13_x86_64.whl
Size 474.5 kB
Tags CPython 3.12 macOS 10.13+ x86-64
SHA-256 checksum
How to use checksums
a35cbb811248598e82e6d53e8dfd1eab6428bed25bb154f1949df701b693d674
BLAKE2b-256 checksum
How to use checksums
6dd46dec2ffb0a611804c865d9d92a4da6389ca3b5859c181a1b68a962dfc366
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp311-cp311-win_amd64.whl

Download URL geneyxpgxparser-0.1.2-cp311-cp311-win_amd64.whl
Size 433.5 kB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
41d391dc031182eebb5ef9caaa0e093a554ddf15c0f17637a387e6101b37382e
BLAKE2b-256 checksum
How to use checksums
e4ef81c2ef138e5deedbad3c663b1da46afc56a0b4efbd5fe055d1564dba0294
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Download URL geneyxpgxparser-0.1.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Size 2.8 MB
Tags CPython 3.11 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
eb2ca2a292148a4d4e2af8a584bd861c620fd5046c287d644526547fc00e14ee
BLAKE2b-256 checksum
How to use checksums
493e0b722fed4c0a94ee9d12573c1cfc9a34c649e77a6dd861c02946f8cc18c3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp311-cp311-macosx_10_9_x86_64.whl

Download URL geneyxpgxparser-0.1.2-cp311-cp311-macosx_10_9_x86_64.whl
Size 467.0 kB
Tags CPython 3.11 macOS 10.9+ x86-64
SHA-256 checksum
How to use checksums
6bf529534a49acce6c1eef8b22d7d1348a1ce84fef97b6f27fda9768789e14fb
BLAKE2b-256 checksum
How to use checksums
9cf6ba56a1a55007a057a0ded0f000d64af9eecf40d6d964346067e19f3ad400
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp310-cp310-win_amd64.whl

Download URL geneyxpgxparser-0.1.2-cp310-cp310-win_amd64.whl
Size 437.3 kB
Tags CPython 3.10 Windows x86-64
SHA-256 checksum
How to use checksums
ebbb92974616f81c00d233623eb64ef6adb7aa1e9a5a241c7b24a505cbf0cab4
BLAKE2b-256 checksum
How to use checksums
cc9828b821cbb2704500738145920ad40d5efbd54c3025da92a882aae80c9ea0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Download URL geneyxpgxparser-0.1.2-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Size 2.7 MB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
7f28d0a17280a89a317e04100a942295f218a131cf55a26b70546135369fe9c3
BLAKE2b-256 checksum
How to use checksums
a197cab8c6a94d0b649ae60c625681202b5dde1eef2339d6bfab30246371f042
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp310-cp310-macosx_10_9_x86_64.whl

Download URL geneyxpgxparser-0.1.2-cp310-cp310-macosx_10_9_x86_64.whl
Size 474.4 kB
Tags CPython 3.10 macOS 10.9+ x86-64
SHA-256 checksum
How to use checksums
4b5e923ee568ec550a4dd6177c80e7fcca4b5388e156ac836412865b5756f5f3
BLAKE2b-256 checksum
How to use checksums
639d1523e9f88e3866d88c6c21fca273fe7ec04e03f0d534c9603e38bdb0e1c0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp39-cp39-win_amd64.whl

Download URL geneyxpgxparser-0.1.2-cp39-cp39-win_amd64.whl
Size 438.9 kB
Tags CPython 3.9 Windows x86-64
SHA-256 checksum
How to use checksums
8e4a854958299c6f39460eab4db1ac68b5c348c843a5186b881df75b890fc039
BLAKE2b-256 checksum
How to use checksums
f126b831d934544961545f486ab605170755e8d459dfc2994953093210c0edab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Download URL geneyxpgxparser-0.1.2-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Size 2.7 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
d9dc9dae4cc31c2308ecd56dc444363f2705c03d462213113c6f93bf6cd53fac
BLAKE2b-256 checksum
How to use checksums
fb9d5d543a710388c92f96976b798d838c85a054206d5289ca14df589c9456d7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / geneyxpgxparser-0.1.2-cp39-cp39-macosx_10_9_x86_64.whl

Download URL geneyxpgxparser-0.1.2-cp39-cp39-macosx_10_9_x86_64.whl
Size 477.9 kB
Tags CPython 3.9 macOS 10.9+ x86-64
SHA-256 checksum
How to use checksums
17cc6cfe31e40dee1e9a4ef14f9d15c3649587bed231654989c4952b2def6f9b
BLAKE2b-256 checksum
How to use checksums
7b4d6a9e8e047911c1f51723848d0d73faa4225e443ff2f84027618c9051e9a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Security for GeneyxPgxParser 0.1.2

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.

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