pedigree-ga4gh
Write, read, check and upgrade the GA4GH files that describe a family: the GA4GH Pedigree and the Phenopackets v2 Family, Phenopacket and Cohort.
It is the one GA4GH implementation behind the Hearn lab's pedigree tools. studio2ga4gh, ga4gh2studio, abusua2ga4gh, ga4gh2abusua, the phenopacket toolkit (phenotk) and the Pedigree workbench all read and write GA4GH files through it, so they agree on a single form. It needs nothing beyond the Python standard library (Python 3.9 or later).
pip install pedigree-ga4gh
What it writes
The GA4GH Pedigree Standard is still in development. Its published documentation describes a conceptual model, carried either by Phenopackets or by HL7 FHIR, and neither form has been approved. pedigree-ga4gh writes:
- a GA4GH Pedigree in the Phenopackets form, the form of the standard's
published examples: every individual is a complete Phenopacket v2, and each
relationship is
{individualId, relation, relativeId}with a current term of KIN, the Kinship Ontology. Relationships follow the standard's reduced form: parents to their children, partners only when their children don't already say so, twins all relative to one twin, and no siblings, since shared parents imply them. - a Phenopackets Family exactly to the Phenopackets v2 schema, with the
whole family's pedigree in PED form and
consanguinousParentsworked out from the relationships: true when the proband's parents are recorded as consanguineous partners, or are related as second cousins or closer, as KIN defines it.
Every file it writes passes phenopacket-tools' JSON schemas. A condition
without an ontology term is left out with a warning rather than written with
an empty id, and so is a term from an ontology whose details it cannot write
in metaData: it knows the HPO, Mondo, OMIM, Orphanet, the Disease Ontology,
SNOMED CT, ICD-10-CM and the ontologies phenopacket-tools declares, and keeps
any other ontology a file it reads declares in full. Anything the standard
has no field for – a carrier, a pregnancy – goes into the pedigree's
narrative so that it isn't lost.
docs/ga4gh.md sets out the decision, the sources behind it, and the draft of version 1 of the standard that is now under review.
On the command line
pedigree-ga4gh validate family.json # check a file against the standard
pedigree-ga4gh validate family.json --json # the findings as JSON
pedigree-ga4gh upgrade old.json -o new.json # rewrite a file from an older tool
pedigree-ga4gh convert pedigree.json --to family -o family.json
pedigree-ga4gh convert family.json --to pedigree -o pedigree.json
pedigree-ga4gh kin # list the KIN relations
validate exits with status 1 when a file has errors, so it can be used in
scripts and checks.
In Python
from pedigree_ga4gh import (Kindred, Member, Relation, Term,
to_ga4gh_pedigree, to_phenopackets_family, validate, errors, dump)
trio = Kindred("FAM1", members=[
Member("MOTHER", sex="FEMALE"),
Member("FATHER", sex="MALE"),
Member("CHILD", index=True, terms=[Term("cystic fibrosis", "MONDO:0009061")]),
], relations=[
Relation("MOTHER", "KIN:027", "CHILD"),
Relation("FATHER", "KIN:028", "CHILD"),
], versions={"MONDO": "2026-10-06"})
pedigree, warnings = to_ga4gh_pedigree(trio, created_by="my-tool 1.0")
family, warnings = to_phenopackets_family(trio, created_by="my-tool 1.0")
assert not errors(validate(pedigree)) and not errors(validate(family))
dump(pedigree, "FAM1_ga4gh-pedigree.json")
from_document(doc) reads any of the four kinds of file back into a
Kindred, validate(doc) returns the findings (errors, warnings and notes,
each with where in the file and how to fix it), and upgrade(doc) returns the
rewritten document with the list of changes and what is left for a person to
do.
The checks
validate applies:
- the Phenopackets v2 JSON schemas of phenopacket-tools: required fields,
types, enumerations,
oneofgroups, lengths and counts; - phenopacket-tools' check that every ontology prefix used is declared in
metaData.resources; - the pedigree's own rules: everyone named in a relationship or as an index patient is in the file, relations are current KIN terms with KIN's labels, no one is related to themselves, a biological mother is female and a father male, no one has more than two genetic parents, and nobody is their own ancestor.
Older files
studio2ga4gh up to 0.3 and abusua2ga4gh up to 0.2 wrote GA4GH files that the
standard does not accept, and earlier drafts of KIN used codes that have since
been retired. Those files are recognised (identify_legacy): the commands,
and the converters built on this package, refuse them with a message, and
pedigree-ga4gh upgrade rewrites them once, listing every change and what
still needs a person (usually conditions without an ontology term).
from_document itself reads whatever it is given, so check with
identify_legacy first if you call it directly.
A file in the form of the draft of version 1 is recognised too, and refused
with a message saying what it is: the draft isn't approved, and it can't be
converted yet.
Licence
MIT (see LICENSE). The KIN terms in pedigree_ga4gh/kin.py come
from the GA4GH Pedigree Standard's kin.owl
(ga4gh/pedigree_family_history_terminology,
commit 71616ea) and are used under the Apache License 2.0
(pedigree_ga4gh/LICENSE-KIN.txt).
Metadata
Release files for pedigree-ga4gh 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pedigree_ga4gh-1.0.0.tar.gz | 68.2 kB | With provenance | Details for pedigree_ga4gh-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pedigree_ga4gh-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for pedigree_ga4gh-1.0.0-py3-none-any.whl |
Total release size: 127.6 kB
Release files / pedigree_ga4gh-1.0.0.tar.gz
| Download URL | pedigree_ga4gh-1.0.0.tar.gz |
|---|---|
| Size | 68.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d76a580493f6d758373cf36221bdd2a4665f2b4b3d640f54381c95b63e674548
|
|
BLAKE2b-256 checksum How to use checksums |
af772a52a612d305b7526042aa1bb078a1cc0e28118d31f548138b509fad9018
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logRelease files / pedigree_ga4gh-1.0.0-py3-none-any.whl
| Download URL | pedigree_ga4gh-1.0.0-py3-none-any.whl |
|---|---|
| Size | 59.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9b7c489c3d13aa68f89e1e5bde4827ab30c0db2da8c7665d6bb1ac65f052748e
|
|
BLAKE2b-256 checksum How to use checksums |
9ff1c8eb62019ed5547c028acdecd7b2ce8183e85fcc7e4e4228f34016e54439
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logSecurity for pedigree-ga4gh 1.0.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pedigree_ga4gh-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logA 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.