ga4gh2abusua
Rebuild an Abusua Pedigree Studio session (.json) from a GA4GH
Pedigree or a Phenopackets v2 Family. It is the reverse of
abusua2ga4gh: a session
converted to GA4GH and back keeps its family, its biological and social
parentage, and its conditions with their ontology terms.
Files are read through pedigree-ga4gh,
the one GA4GH implementation that the lab's pedigree tools share, so
ga4gh2abusua reads exactly the standard form that abusua2ga4gh, studio2ga4gh
and the phenopacket toolkit write, in either JSON spelling (indexPatients or
index_patients).
Installation
pip install ga4gh2abusua
It needs Python 3.9 or later and installs pedigree-ga4gh with it.
Usage
ga4gh2abusua asante.ga4gh-pedigree.json # writes asante.json
ga4gh2abusua asante.family.json -o asante.json
ga4gh2abusua --pedigree asante.ga4gh-pedigree.json --family asante.family.json -o asante.json
ga4gh2abusua asante.ga4gh-pedigree.json --stdout
Give either file. The GA4GH Pedigree holds more than the Family (social and
foster parents, couples without children, carriers and the like, in its
narrative), so if you have only one, give the Pedigree. Given both, as with
version 0.3's --pedigree and --family, the Pedigree is read first and the
Family fills in anything it lacks.
The session is written to the current folder under the input's name, without
.ga4gh-pedigree.json or .family.json: asante.json, which may well be the
session the files were made from. So it never replaces a file that is already
there unless you name the file yourself with -o or give --force, and it
never replaces the file it is reading. Open the session in Abusua Pedigree
Studio with Open / Load.
What the files become
| In the GA4GH files | In the Abusua session |
|---|---|
KIN:027 isBiologicalMotherOf (or an ovum donor) |
bioMotherId |
KIN:028 isBiologicalFatherOf (or a sperm donor) |
bioFatherId, paternity confirmed, or reported if the narrative says so |
KIN:003 isBiologicalParentOf |
mother or father, by the parent's sex |
KIN:020 isParentFigureOf, for a social father |
bioFatherId, paternity social-only (the narrative says which) |
KIN:021 isFosterParentOf, KIN:022 isAdoptiveParentOf |
socialMotherId / socialFatherId, and fosteredIn |
| other parent figures and step-parents | socialMotherId / socialFatherId |
| partners of every kind, and every couple with a child together | a union |
| twins and siblings | the same parents, if only one of them has them recorded |
indexPatients, or the Family's proband |
proband |
vital status DECEASED |
deceased |
| diseases and phenotypic features | condition, each written with its term: sickle cell disease [MONDO:0011382] |
| an excluded disease or feature | the condition, on someone marked unaffected |
| the Family's PED-style pedigree | parents, sex, and affected or unaffected |
The ontology id written after each condition is what lets abusua2ga4gh give it the same term when the session is converted again.
abusua2ga4gh says in the narrative what the GA4GH structure cannot, in fixed
sentences that ga4gh2abusua reads back: who is a carrier, who has a condition
without an ontology term, who is affected with no condition recorded or
unaffected, who is recorded as a father although paternity is unknown, who is
a social mother or father, and who was fostered in. It reads them only from
abusua2ga4gh's own part of the narrative, after its opening sentence
("Pedigree from Abusua Pedigree Studio: ..."), and only at the start of a
sentence, so nothing written there by a person is taken for one of them.
Carriers are also read from the rest of the narrative, as studio2ga4gh and
pedigree-ga4gh upgrade write them, and so are the notes that the upgrade
keeps of an abusua2ga4gh 0.2 file (reported paternity, social and foster
parents).
A person whose id in the file is not an Abusua id (i1, i2 …), such as a
pedigree number from studio2ga4gh, is given the next free one, and their own id
is kept in their notes ("GA4GH id: II-3"). Relationships Abusua has no place
for, such as a gestational carrier, a mitochondrial donor or cousins given on
their own, are listed in the notes the command prints.
What cannot come back
- Names. Phenopackets have no field for a name, so the GA4GH files have none to give back.
- The manually set abusua and ntoro, layout and notes, which neither standard has a place for. Abusua works out the abusua from the mother's line again when the session is opened, so only a founder's manually set one is lost.
- A condition's own wording. A matched condition comes back with its
term's label: "Sickle cell anaemia (HbSS)" becomes
sickle cell disease [MONDO:0011382]. - What a session leaves unsaid comes back said. Someone with a condition whose affected status was left unknown comes back affected, and two people with a child together come back as a union, as Abusua treats them anyway.
- From a Family alone, less again: a Family has no social or foster parents, couples without children or narrative, and a person without their own Phenopacket (an unaffected relative) has no vital status. Its PED-style pedigree gives a father without saying how certain he is, so reported paternity comes back as confirmed.
Older files
Files written by abusua2ga4gh up to 0.2 or studio2ga4gh up to 0.3 are not in
the standard's form. ga4gh2abusua recognises them and asks you to upgrade them
first, once, with pedigree-ga4gh upgrade FILE -o NEW.json, which lists every
change it makes. The upgrade removes names, as the standard has no place for
them; if you still have the session, it already has them. Files in the form of
the draft of version 1 of the GA4GH Pedigree Standard, which is not yet
approved, are recognised and refused with a message saying so.
In Python
import json
from ga4gh2abusua import to_abusua_session
with open("asante.ga4gh-pedigree.json") as fh:
pedigree = json.load(fh)
with open("asante.family.json") as fh:
family = json.load(fh)
session, notes = to_abusua_session(ga4gh_pedigree=pedigree, family=family) # or either one alone
with open("asante.json", "w") as fh:
json.dump(session, fh, indent=2)
to_session(doc) takes one document of either kind, and
ga4gh2abusua.LegacyFileError is raised for a file in an older form.
Development
pip install -e ".[test]"
pytest
The tests use fictional families in tests/data. The round-trip test converts
each session back with abusua2ga4gh, which the test extra installs.
References
- GA4GH Pedigree Standard: https://pedigree.readthedocs.io/
- GA4GH Phenopacket Schema v2 (Family): https://phenopacket-schema.readthedocs.io/
Licence
MIT
Metadata
Release files for ga4gh2abusua 0.4.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 |
|---|---|---|---|---|
| ga4gh2abusua-0.4.0.tar.gz | 30.9 kB | With provenance | Details for ga4gh2abusua-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ga4gh2abusua-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for ga4gh2abusua-0.4.0-py3-none-any.whl |
Total release size: 47.6 kB
Release files / ga4gh2abusua-0.4.0.tar.gz
| Download URL | ga4gh2abusua-0.4.0.tar.gz |
|---|---|
| Size | 30.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ac6a821b7e73764f6e0477cab69b73585af14f836f585706bf52d60d34087e42
|
|
BLAKE2b-256 checksum How to use checksums |
b269f5b5cd5514fc27637663013327dea474401c8dbda1fb7a70a916f78e64ed
|
| 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 / ga4gh2abusua-0.4.0-py3-none-any.whl
| Download URL | ga4gh2abusua-0.4.0-py3-none-any.whl |
|---|---|
| Size | 16.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
16a480fd518b0610c990ecea13f7034364726d59c4e520361dc5e498e58ac733
|
|
BLAKE2b-256 checksum How to use checksums |
a8e0421107d27c388601cb85c012c071658f499f8d8bc7550eaf4fcf27d8526b
|
| 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 ga4gh2abusua 0.4.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 ga4gh2abusua-0.4.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.