Skip to main content

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

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)

Source distribution for ga4gh2abusua 0.4.0
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)

Table of built distributions (wheels) for ga4gh2abusua 0.4.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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