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 onIdand filters onName.StarAllele— the diplotype (*1/*2).Activity— the phenotype / metaboliser status (Normal Metabolizer), ornullwhen 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: nullplus a warning in the provenance file, rather than an unrecognised term that looks valid to the report. - Genotype-guided genes (IFNL3, VKORC1) take their
StarAllelefrom 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
nulltarget still need filling from the approved mapping sheet. Run the parser and readunmappedTermsin 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.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 22.1 MB
Release files / geneyxpgxparser-0.1.4-cp314-cp314-win_amd64.whl
| Download URL | geneyxpgxparser-0.1.4-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 437.3 kB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
d56dcc530f6c5e82fae726df4d8e186ad492dee99947da6995559e5b330bd261
|
|
BLAKE2b-256 checksum How to use checksums |
0a47cd9d1b535fd87600b2a61085fdd50a4d737416dd8eaddf573bfd454ea8e0
|
| 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.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.14 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
7c610337a797315d30f5f4e6751076305bcb29c6944648738faf751a2893df78
|
|
BLAKE2b-256 checksum How to use checksums |
cba1e28f5ef01233ba307085a72498ef684192850abff9429bde140f20123ee6
|
| 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.4-cp314-cp314-macosx_10_15_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-cp314-cp314-macosx_10_15_x86_64.whl |
|---|---|
| Size | 471.1 kB |
| Tags | CPython 3.14 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
2b4308c81c9233d5fd97597722e095d956d11d717ce8d1249c374e51bbb608a8
|
|
BLAKE2b-256 checksum How to use checksums |
5cc4890b083f3208dc61ba10ef1001216f0daf47b2fb75954c8facf372ed4730
|
| 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.4-cp313-cp313-win_amd64.whl
| Download URL | geneyxpgxparser-0.1.4-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 426.4 kB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
31a7e338a81d63287555116f1fd4e4177618337cc88f84320fed078416792a9d
|
|
BLAKE2b-256 checksum How to use checksums |
0d2d3b1b9f04cee17291d020bf06858345132567c3dbf8eaeb93547dc88f626a
|
| 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.4-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-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 |
0891fa2d88ef1178dd4527fc91e22a3e7548d1a311e23f0449ab75b824da9afb
|
|
BLAKE2b-256 checksum How to use checksums |
fdc09b91ae10fe691f73aef012e8d4289d720edc44c067aabe60602b72d80789
|
| 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.4-cp313-cp313-macosx_10_13_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-cp313-cp313-macosx_10_13_x86_64.whl |
|---|---|
| Size | 469.0 kB |
| Tags | CPython 3.13 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
58e28f2daf7a3060f575eee68c1b7ca2afea80b2ba41fb7c40f4414e7f2e5d3f
|
|
BLAKE2b-256 checksum How to use checksums |
e13b748f1f4cbdaea1f4733ca097c9ec7ebfdfaf60419cbf39332c8436f3a46f
|
| 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.4-cp312-cp312-win_amd64.whl
| Download URL | geneyxpgxparser-0.1.4-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 433.2 kB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
55ed2a451ec2e269be6697f0e71ea1f204200c81e2a4d6267b865db21fec91a7
|
|
BLAKE2b-256 checksum How to use checksums |
764457e976d488aea16b79a153e0f41630c606f759379a0f02f93addea1217f7
|
| 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.4-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-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 |
c997513ea0b362ed959485f37e0fc336a123f2b90476176421bb7523ed0386e9
|
|
BLAKE2b-256 checksum How to use checksums |
6edeae042779e5ab2b8b6a46523d5fb104149d131db5acba9a3b4413abb8eead
|
| 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.4-cp312-cp312-macosx_10_13_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-cp312-cp312-macosx_10_13_x86_64.whl |
|---|---|
| Size | 475.3 kB |
| Tags | CPython 3.12 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
3227bd7a71565efbd31fd6b7e24f98c0f5117be6e6830ca0dff5edb61d90c21a
|
|
BLAKE2b-256 checksum How to use checksums |
758123ce712ed8be0f51826bf6747c22021919ad687eb53a5b3cdabb81027d76
|
| 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.4-cp311-cp311-win_amd64.whl
| Download URL | geneyxpgxparser-0.1.4-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 434.4 kB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
97a5ab6c1ba1900b78ebeb7e503e3d63ad4b150957578f8e7eb2ed487a604927
|
|
BLAKE2b-256 checksum How to use checksums |
8336e866ed6638adc9c31a485da84a4873aa1c4cd5ac23471fb883e85c907833
|
| 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.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-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 |
7b4359eb583b6ba58fbd77fcdf3ff0136e13545328195e6c9a5871a186719b83
|
|
BLAKE2b-256 checksum How to use checksums |
496f7f6c558fdd6f39b66896e00ba4dfd9bfb91c832256efc97e2f5b1ddc5666
|
| 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.4-cp311-cp311-macosx_10_9_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-cp311-cp311-macosx_10_9_x86_64.whl |
|---|---|
| Size | 467.9 kB |
| Tags | CPython 3.11 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
a9230e95d6ad27c706b1f78282b7543d063e5fc90550c5a341f9d8c007ad52e0
|
|
BLAKE2b-256 checksum How to use checksums |
69294bac63c9cd9acc77590e4388a8802720038360cbed34bc3252d3560e8d4c
|
| 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.4-cp310-cp310-win_amd64.whl
| Download URL | geneyxpgxparser-0.1.4-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 438.2 kB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
18d5e437eb29c7c44769f158943d7dd3ff619fdfd5df6651c1efd9603d807b48
|
|
BLAKE2b-256 checksum How to use checksums |
1cf1cd4f9569f675aa5aae846f05460b6384d5e64c8749902f0611b31a94cea3
|
| 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.4-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-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 |
04a4084d3d6b928a97e6c84e4dd646d3db6c9bf5c80cf733bfd6befa842a5ee1
|
|
BLAKE2b-256 checksum How to use checksums |
e68383df032e22e9b1fd19acd99891ebb8e974d2e19ab15a35b638bbea9a8d5e
|
| 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.4-cp310-cp310-macosx_10_9_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-cp310-cp310-macosx_10_9_x86_64.whl |
|---|---|
| Size | 475.3 kB |
| Tags | CPython 3.10 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
a8104cffb5321ba0199586975f85428734d0c622812d0c448ffae32a6e4b4f44
|
|
BLAKE2b-256 checksum How to use checksums |
36c49713798155d5f0c71d851e3341df638d59f301d6841cdb1f111ca46eccd6
|
| 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.4-cp39-cp39-win_amd64.whl
| Download URL | geneyxpgxparser-0.1.4-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 439.7 kB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
a323d409db5875e873bacb1b13f9569a404588d92ebdea63de8c28d6bf8bee5e
|
|
BLAKE2b-256 checksum How to use checksums |
53821b2d74174cadb6623dee0f4f3b93a0df94ab9d2bf31bc2e998f5ecd1c7dd
|
| 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.4-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-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 |
fe994b1995f74a1a2395ba450e76164ea92ad80268142d4e0895ecb9075c1b44
|
|
BLAKE2b-256 checksum How to use checksums |
0914bd8c27f81b9463d5e753a00debd9ee78d1378a167608dca5085adacd2dff
|
| 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.4-cp39-cp39-macosx_10_9_x86_64.whl
| Download URL | geneyxpgxparser-0.1.4-cp39-cp39-macosx_10_9_x86_64.whl |
|---|---|
| Size | 478.8 kB |
| Tags | CPython 3.9 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
484f45ef8d833d1982dc2435678922e034b1792ed9b68adba6a1895526170e29
|
|
BLAKE2b-256 checksum How to use checksums |
b7230e3b11fb3319b576bf6a596fac6edaf8d35e2adccd0c702410483f5368ce
|
| 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.4
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.