The Pedigree workbench
Draw a family in Pedigree Studio, then turn the drawing into the files that other people and other programs need. Linkage programs read PED files, and the GA4GH Pedigree and Phenopackets files let you share a family's pedigree and findings in the international standard. The tools that do this are our Python packages, which run here in your browser. Others analyse a family as a graph and weigh up how its condition is inherited and which variants co-segregate with it (PedNet), simulate families (PedGen), and read a pedigree from a picture or a sketch, into a PED file and a drawing (PedInterp). You can use them all by pointing and clicking in the Tools tab, by typing commands in the Terminal tab, or by writing code in the Notebook tab. The Risk tab works out, from a drawing or a file, the chance that each person in a family carries its variant, and that a couple's child will be affected.
The formats, and the tools between them
The drawing is in the middle. Each arrow is a tool that turns one kind of file into another. Click an arrow to open the tool, or click a box to see what you can do with that kind of file.
Everything stays on this computer
Pedigree Studio and Python run inside this web page. Your drawings and files are kept in this browser, on this computer, and aren't sent anywhere, with one exception. If you ask Match conditions to terms or Fill in missing terms to search EBI's Ontology Lookup Service, the names you search for, and any ids you type, go to EBI. Nothing else is sent, not even the drawing. Privacy has the details, and Your files explains how to keep copies.
- Share a family in the GA4GH standardDraw, match terms, convert, check, de-identify, download
- Make a PED file for a linkage programDrawing → MPED, check the ids, take one condition out
- Draw a PED file you have been sentUpload it, draw it, tidy it, add what a PED file cannot say
- Draw a GA4GH or Phenopackets fileUpgrade it if it is old, draw it, check the key
- Check a GA4GH file, or update an old oneWhat the check reports, and how to fix each kind of problem
- Give the conditions ontology termsMatch a drawing's conditions, or fill in the terms a GA4GH file lacks
- Turn a picture of a pedigree into a PED file and a drawingRead it with PedInterp, check it, and carry on with the drawing in the Studio
- Weigh up the mode of inheritance, and rank candidate variantsPedNet: a family's loops and kinship, its mode of inheritance, and the variants that co-segregate with its condition
- Work out the risk to a pregnancyThe Risk tab: a couple's chance of an affected child, a Bayesian table with reduced penetrance, and why the mode of inheritance matters
- Run the same steps for several families, with a workflowRun an example workflow for two families, make a workflow of your own, and make one from tools you've run
- WorkflowsChain the tools together, and run them in one go
- Drawing → GA4GH Pedigree and Phenopacketsstudio2ga4gh: a drawing as the two GA4GH files
- GA4GH or Phenopackets → drawingga4gh2studio: a GA4GH file drawn in Pedigree Studio
- Drawing → PED or MPEDstudio2ped: a drawing as a PED or MPED file
- PED or MPED → drawingped2studio: a PED file drawn in Pedigree Studio
- GA4GH Pedigree ⇄ Phenopackets Familyphenotk convert: one GA4GH form into the other
- GA4GH → PED, table or YAMLphenotk convert: a GA4GH file as PED, TSV, YAML or JSON Lines
- Picture → PED file and drawingPedInterp: a pedigree read from a picture of one, or from a sketch, as a PED file and a Pedigree Studio drawing
- Match conditions to termshponorm and mondonorm: find the HPO or Mondo term for each condition in a drawing
- Fill in missing termsphenotk normalise: give terms to findings that have only a name
- Check against the standardpedigree-ga4gh validate: whether a GA4GH file is correct, and how to fix it
- Upgrade a file from an older toolpedigree-ga4gh upgrade: rewrite an older or non-standard file in the standard form
- Look inside a GA4GH filephenotk view and stats: a GA4GH file as a table, or as counts
- Compare two filesphenotk diff: what differs between two GA4GH files
- De-identifyphenotk deidentify: new ids, no dates of birth, and a key kept separately
- Keep some people or termsphenotk filter: a smaller file, with only the people or terms you choose
- One file for each personphenotk split: a Phenopacket for each person in a Family, Cohort or GA4GH Pedigree
- Put files togetherphenotk merge: Phenopackets and Families into one Cohort or Family
- Add findings to peoplephenotk add: diseases, phenotypes, onset or vital status for chosen people
- PED and MPED filesmpedtools: summary and check, one condition out, merge, split, PED ⇄ MPED
- PedNet: the graph, the mode of inheritance and the variantsThe pedigree as a graph; the mode of inheritance; candidate variants ranked by co-segregation
- Simulate a familyPedGen: a made-up family with a dominant or recessive condition
Files and standards
- Your filesThe Files tab, the examples, uploading, downloading, and where files are kept
- Which file is whichThe kinds of file, how to tell them apart, and the tools between them
- The Pedigree Studio fileWhat a .studio.json drawing holds
- The GA4GH PedigreeWhat the standard is, the form the workbench writes, and why
- PhenopacketsPhenopackets version 2: the Phenopacket, the Family and the Cohort
- KIN, the kinship termsThe Kinship Ontology's 48 relations, which the GA4GH Pedigree uses
- The PED and MPED formatsThe six columns, the codes, and the MPED header
- Ontology terms and terms filesHPO and Mondo, CURIEs, releases, and the terms file
A first session
Take ten minutes to see what the workbench is for, using one of the example families. Each step has a button that does it for you.
1 · Open a drawing
The Studio tab is Pedigree Studio. Open the Okafor family, one of the examples. It has four generations, with twin boys who have had hearing loss from birth and whose parents are cousins. The twins' grandmother has had breast cancer.
The bar above the drawing says which file the drawing belongs to. The examples can't be changed, so an example opens as a new drawing that hasn't been saved yet. Change it as much as you like, then use Save as… to keep your version in ~/pedigrees. The Studio's own toolbar and its ? button explain how to draw.
2 · Give its conditions ontology terms
The colour key names two conditions. A GA4GH file names conditions by ontology terms rather than in free text: diseases by the Mondo Disease Ontology, and signs and symptoms by the Human Phenotype Ontology (HPO). The examples come with a terms file that already matches them. For a family of your own, make one with the Match conditions to terms tool (here's how).
3 · Convert it
The Tools tab has a form for each of our tools. Drawing → GA4GH Pedigree and Phenopackets writes the family as a GA4GH Pedigree and a Phenopackets Family. The button below opens the tool with the drawing and the examples' terms file (/data/examples/example-terms.json) already chosen. Then press Run. The first run starts Python in your browser, which takes a few seconds. The very first time, it also downloads about 10 MB.
Under the form, The same in the terminal, and in Python shows exactly what the tool runs: a command for the Terminal tab and code for a notebook. You can use them to do the same job again without the form.
4 · Check the result
The files the tool writes appear under the result and are saved in ~/results. Press Check next to a file to check it against the standards. The check works in the same way as phenopacket-tools, the Phenopackets team's own validator, and it also tells you how to fix anything that's wrong.
5 · Back to a drawing, or on to a PED file
- GA4GH or Phenopackets → drawing draws a GA4GH file in Pedigree Studio, whether you made it here or someone has sent it to you.
- Drawing → PED or MPED writes the PED file that linkage programs read.
6 · Keep your work
Everything you make is kept in this browser, on this computer. To keep it anywhere else, download it with a file's Download button, or with My files → Download all my files (.zip) at the top right. Your files has the details.
The page
The help is on the left, and the workbench, with its six tabs, is on the right.
The tabs
| Tab | What it is for |
| Studio | Pedigree Studio: draw a family, open and save drawings among your files. The Studio tab |
| Tools | Our Python packages, with forms for conversions, ontology terms, checks, de-identification and PED files, and for analysing and simulating families. The Tools tab |
| Risk | The chance that each person in a family carries its variant, and that a couple's child will be affected, worked out from a drawing or a file. The Risk tab |
| Files | Your files and the examples: look at them, edit them, upload and download. Your files |
| Notebook | Python notebooks with the packages, for working in code. The Notebook |
| Terminal | The packages' commands in a Linux shell. The Terminal |
All six tabs use the same files. A file that the Tools tab writes can be opened in the Studio, read in a notebook, listed in the terminal or used in the Risk tab straight away.
The help
- Search with the box at the top. Words in titles and headings count most.
- Hide it with the button at the top left of the page, or with Ctrl+\, to give the workbench the whole window. Do the same again to bring it back. Drag the line between the help and the workbench to change their widths, or double-click it to reset them.
- Under the search box, Help for the … tab takes you to the page about the tab you're using.
- Buttons in the help do what they say: they open an example in the Studio, open a tool with a file already chosen, or run a command in the terminal. Code boxes have a Copy button, and a Run in the terminal or Add to notebook button.
At the top right
- Saved in this browser shows that your files are being stored. If the browser doesn't let the page keep them (in a private window, for example), it changes to Not kept.
- user lets you put your own name in the terminal's prompt, if you want it there. The name is kept in this browser only.
- My files lets you download all your files as a .zip, add files or folders from your computer, or delete them all with Start afresh.
- Full screen.
On a phone or tablet
The workbench works on a phone, but a pedigree is easier to draw on a larger screen. On a narrow screen, the button at the top left opens the help over the workbench, and the Tools tab's list of tools is behind All tools. On a phone, the Files tab lists your files above the file you open, which then has the whole width of the screen. Pedigree Studio has its own layout for touch screens.
If the workbench is open in two browser tabs at once, both keep their files in the same place, so one tab can overwrite what the other has saved. The workbench warns you when it finds itself open in another tab. If you see that warning, carry on in just one of them.
Walkthroughs
Each walkthrough takes you through one job from beginning to end, with a button for every step. They use the example families, so you can follow one through before you try it with a family of your own.
- Share a family in the GA4GH standardDraw, match terms, convert, check, de-identify, download
- Make a PED file for a linkage programDrawing → MPED, check the ids, take one condition out
- Draw a PED file you have been sentUpload it, draw it, tidy it, add what a PED file cannot say
- Draw a GA4GH or Phenopackets fileUpgrade it if it is old, draw it, check the key
- Check a GA4GH file, or update an old oneWhat the check reports, and how to fix each kind of problem
- Give the conditions ontology termsMatch a drawing's conditions, or fill in the terms a GA4GH file lacks
- Turn a picture of a pedigree into a PED file and a drawingRead it with PedInterp, check it, and carry on with the drawing in the Studio
- Weigh up the mode of inheritance, and rank candidate variantsPedNet: a family's loops and kinship, its mode of inheritance, and the variants that co-segregate with its condition
- Work out the risk to a pregnancyThe Risk tab: a couple's chance of an affected child, a Bayesian table with reduced penetrance, and why the mode of inheritance matters
- Run the same steps for several families, with a workflowRun an example workflow for two families, make a workflow of your own, and make one from tools you've run
You'll also find these jobs on the first page of the Tools tab, under Common tasks. There, each job links to its tools in the order you need them.
Share a family in the GA4GH standard
This walkthrough takes you from a drawing to files you can send to a collaborator, a registry or another program: a GA4GH Pedigree and a Phenopackets Family. The buttons use the Okafor family, one of the examples. With a family of your own, choose your drawing instead.
Which of the two files to send
The Phenopackets Family follows Phenopackets version 2, an approved GA4GH standard, so you can send it to anything that reads Phenopackets. The GA4GH Pedigree holds the whole family, with every relationship named by a kinship term. It's in the form proposed for the GA4GH Pedigree Standard, which is still being written. If you're not sure what the recipient reads, send both. The GA4GH Pedigree explains the difference.
1 · The drawing
Draw the family in the Studio tab, or open the drawing you have. Every condition needs a colour, and a name in the colour key (the Studio's Key button). The name is how the tools know what the colour means. Save the drawing among your files with Save as…, because the tools work on saved files.
Whatever you write under the symbols, such as names, ages and notes, stays in the drawing. The files name people by their pedigree numbers (I-1, II-3, IV-3), unless you choose otherwise in step 3.
2 · Terms for the conditions
A GA4GH file names a condition by an ontology term: a disease by its Mondo term, and a sign or symptom by its HPO term. Match conditions to terms finds the terms for the conditions in the drawing's colour key, and keeps your choices in a terms file. For each condition, choose whether it's a disease or a sign, press Suggest and pick the right term. When you've done them all, press Save.
The examples come with a terms file, /data/examples/example-terms.json, that already has these terms, so you can skip this step with the Okafor family. Give the conditions ontology terms goes through it in more detail.
3 · Convert the drawing
Drawing → GA4GH Pedigree and Phenopackets writes the two files. Choose the drawing and the terms file. Under the terms file, a table shows the term each condition will get. A condition without a term is left out of the files, so match it first. Then press Run.
It writes ~/results/okafor_ga4gh-pedigree.json and ~/results/okafor_phenopackets-family.json. They hold everyone in the drawing, with their sex, whether they're alive and their conditions as terms. They also hold the relationships between people, and say who the proband is. Some things the files have no field for, such as a pregnancy or a carrier, are noted in the GA4GH Pedigree's narrative. If something didn't go in as drawn, such as a symbol that stands for several people, the tool tells you under the result.
4 · Check the files
Press Check next to a file, or use Check against the standard in the Tools tab. It checks the file in the same way as phenopacket-tools, the Phenopackets team's own validator. For a GA4GH Pedigree, it checks the family as well. It should say Valid. Errors make a file invalid, and warnings are worth reading. Notes are for information, such as an ontology release that wasn't recorded. The example files were made by the tool in step 3, so you can try the check on them now:
5 · Look at what is in them
Look inside a GA4GH file shows a file as a table. It lists each person with their sex, status and terms, and then the relationships. It's the quickest way to make sure the files say what you meant.
6 · De-identify before the files leave you
De-identify gives everyone a new id (IND-0001, IND-0002 …) everywhere in the file, and takes out dates of birth and other ids. It can also write a key that matches the old ids to the new ones. Keep the key, and the drawing, separate from what you share.
What de-identifying does not do
It removes what the file says directly, but a family can still be recognised from what's left, such as a rare condition, the shape of a large family or people's ages. So whether a file is safe to share is a judgement for you, and for your institution's rules on sharing patient data.
7 · Download them
Each file under a result has a Download button. To take everything at once, use My files → Download all my files (.zip) at the top right.
The same in the terminal
Every step is a command, so you can do the whole job again in one go:
studio2ga4gh /data/examples/okafor.studio.json -t /data/examples/example-terms.json -d ~/results
pedigree-ga4gh validate ~/results/okafor_ga4gh-pedigree.json
phenotk view ~/results/okafor_ga4gh-pedigree.json
phenotk deidentify ~/results/okafor_phenopackets-family.json -o ~/results/okafor.deidentified.json --keyfile ~/results/okafor.key.json
Make a PED file for a linkage program
Linkage and association programs read pedigrees as PED files. A PED file has one line per person, giving their parents, their sex and whether they're affected. There are two ways to make one from a drawing, and they differ in how they deal with more than one condition and with carriers.
| From the drawing (studio2ped) | Through the GA4GH files (phenotk) |
| People are named by | their pedigree numbers (II-3), or another choice of ids | their pedigree numbers (II-3) |
| Several conditions | an MPED file with a column for each, then a PED file for each condition | one column, in which affected means having any of the conditions |
| Carriers | marked 3 in the MPED file | not marked |
| Best for | a family with several conditions, or carriers | a family with one condition, when you already have the GA4GH files |
From the drawing
1 · Write the MPED file
Drawing → PED or MPED writes a PED file for a drawing with one condition. When the drawing has more, or shows carriers, it writes an MPED file, which is a PED file with a column for each condition.
It checks the file with mpedtools straight away, and tells you if anything is wrong.
2 · Check the ids
studio2ped names each person by their pedigree number, such as II-3, just as the GA4GH files do. This means you can share the file without anyone's name in it. With People are named by, you can choose the drawing's labels or Pedigree Studio's own ids (p-ggf) instead, or the text under the symbols, which is what version 0.1 used. In the Okafor family, that text gives Grace_78 and Emeka_d_70, which are names. If two people would get the same id, the pedigree number is used instead, with a note.
3 · One condition at a time
Most linkage programs read one condition at a time. Take one condition out makes a plain PED file for one column of the MPED file, or one for each column if you leave the condition empty. A plain PED file has no code for a carrier, so carriers become unaffected (1).
Through the GA4GH files
First write the GA4GH files, following steps 1 to 3 of Share a family in the GA4GH standard. Then GA4GH → PED, table or YAML makes the PED file, with the pedigree numbers as ids.
Make it from the Phenopackets Family, because its pedigree records who is unaffected (1) as well as who is affected (2). A GA4GH Pedigree records only the conditions people have, so a PED file made from it marks everyone else 0, unknown. In the Okafor family, affected means having either condition, so the grandmother with breast cancer and the twins with hearing loss are all affected. That isn't what you need for a linkage analysis of one of the conditions. For that, take the first route.
The same in the terminal
studio2ped /data/examples/okafor.studio.json -d ~/results -o okafor
mpedtools validate ~/results/okafor.mped
mpedtools extract ~/results/okafor.mped Hearing_loss_from_birth -o ~/results/okafor_hearing.ped
phenotk convert /data/examples/okafor_phenopackets-family.json --to ped -o ~/results/okafor-numbers.ped
The PED and MPED formats describes the columns and codes.
Draw a PED file you have been sent
It's hard to read a family from a PED file. Once the file is drawn in Pedigree Studio, you can check the family at a glance, add what the PED file leaves out, and save the drawing as a picture, or go on to convert it to the GA4GH files. The example is the PED file of the Lynch family, in which several people have had bowel or pancreatic cancer.
1 · Add the file
Add the PED file to your files with My files → Add files from my computer… at the top right. Or use From my computer… under the file box of the tool in the next step. This puts the file in ~/data. The workbench recognises a PED file by its ending, .ped or .fam (PLINK's name for the same six columns), and an MPED file by .mped. If your file ends in something else, rename it.
2 · Draw it
PED or MPED → drawing lays the family out generation by generation and fills in the affected people (status 2). Choose the colour, and whether to fill the whole symbol or the left half, or to shade with a pattern. An MPED file's conditions each get a colour of their own.
The drawing is saved in ~/pedigrees. To see it, press Open the drawing in Studio under the result. If Tidy the drawing when it opens was ticked on the form, Pedigree Studio's Tidy lays the drawing out again as it opens, which usually gives the neatest result.
3 · Finish it in the Studio
A PED file gives only each person's parents, sex and affected status, so that's all the drawing has. In the Studio, you can add the rest:
- The condition's name. The colour key calls it Affected, or gives it its column name if the drawing came from an MPED file. Click the key and type the condition's name, so that the drawing can be matched to terms and converted.
- Who has died, twins, adoptions, pregnancies and the proband. To add these, select a person or a line and use the panel.
- Labels. Each person is labelled with their id from the PED file. You can add ages or notes under it if you like.
Then press Save in the bar above the drawing. Pedigree Studio's File menu exports a picture (PNG or SVG) to your computer.
The examples include the drawing that the Lynch PED file was made from, so you can compare the two:
Several families in one file
A PED file can hold several families. They're all drawn side by side in one drawing. To draw each family on its own, first split the file with One file for each family (listed under PED and MPED files).
The same in the terminal
mpedtools info /data/examples/lynch.ped
ped2studio /data/examples/lynch.ped ~/pedigrees/lynch.studio.json
studio --tidy ~/pedigrees/lynch.studio.json
studio opens a drawing in the Studio tab, and --tidy lays it out again.
Draw a GA4GH or Phenopackets file
This walkthrough shows you how to draw a GA4GH Pedigree or a Phenopackets Family in Pedigree Studio, with each condition in the colour key under its term. You can change the drawing and convert it back, and the terms come back with it.
1 · Add the file
Add it with My files → Add files from my computer…, or with From my computer… under the file box of the tool you use next. The workbench tells GA4GH files apart by what's in them, whatever they're called. If it shows a file as plain JSON, it hasn't recognised it as a GA4GH file, but Upgrade a file from an older tool may still be able to read it.
2 · If it was made by an older tool, upgrade it
Files made by studio2ga4gh 0.3 or abusua2ga4gh 0.2 aren't in the standard form, and the tools refuse them with a message explaining this. Upgrade a file from an older tool rewrites such a file in the standard form. You only need to do this once for each file. It lists what it changed, and anything it couldn't do.
The older files often name conditions without a term. The upgrade lists them, and Fill in missing terms gives them their terms from a terms file (here's how). The drawing doesn't need the terms, because a condition without one is drawn with its name, but the GA4GH files do. A GA4GH Pedigree from studio2ga4gh 0.3 recorded only whether people were affected, not what they were affected by. Draw from the Phenopackets file made with it instead, because that has the conditions.
To find out whether a file needs upgrading, open its summary in the Tools tab with the More… button next to the file. The summary says Older form if the file needs upgrading.
3 · Draw it
GA4GH or Phenopackets → drawing lays the family out from its relationships. It gives each condition a colour, and names it in the colour key with its term, such as breast cancer [MONDO:0007254].
Under the result, Open the drawing in Studio shows it. If Tidy the drawing when it opens was ticked, Pedigree Studio's Tidy lays the drawing out again as it opens.
4 · Check the drawing
How much of the family comes back depends on the file:
- From a GA4GH Pedigree: everyone, the couples (including consanguineous and separated ones), twins, adoptions, who has died, and the pregnancies and losses that its narrative records.
- From a Phenopackets Family: everyone in its pedigree, with their parents, sex and conditions. A Family's pedigree is a PED file in another form, so it has no twins and no adoptions. Draw from the GA4GH Pedigree when you have one.
People are labelled with their ids, except where the ids are pedigree numbers such as II-3, because Pedigree Studio numbers the generations itself. Pedigree Studio draws children from couples, so if only one of a child's parents is in the file, the child is given an unknown parent as the other.
The same in the terminal
pedigree-ga4gh upgrade /data/examples/older/studio2ga4gh-0.3_phenopackets-family.json -o ~/results/upgraded_phenopackets-family.json
phenotk normalise ~/results/upgraded_phenopackets-family.json --mapping /data/examples/example-terms.json --no-online -o ~/results/upgraded_phenopackets-family.json
pedigree-ga4gh validate ~/results/upgraded_phenopackets-family.json
ga4gh2studio ~/results/upgraded_phenopackets-family.json -o ~/pedigrees/upgraded.studio.json
studio --tidy ~/pedigrees/upgraded.studio.json
Check a GA4GH file, or update an old one
The check reads a GA4GH Pedigree, a Phenopackets Family or Cohort, or a single Phenopacket. It tells you whether the file is correct, and how to fix anything that isn't. Use it on files you make before you send them, and on files you're sent before you rely on them.
1 · Check the file
Check against the standard takes one file. The answer comes first – Valid or Not valid – followed by a table with a line for each finding. Each line says what's wrong, where it is in the file (a path such as individuals[4].metaData) and how to fix it.
- Errors make the file invalid, so other software may refuse it or read it wrongly.
- Warnings are about things that are allowed but probably mistaken, such as a mother recorded as male.
- Notes are for information, such as an ontology release that the file doesn't record.
The checks are those of the Phenopackets version 2 schema and of phenopacket-tools, the Phenopackets team's own validator. On top of these come the GA4GH Pedigree's own checks: KIN terms, people named in relationships, parents' sexes and loops of ancestry. Check against the standard lists them.
2 · Fix what it finds
| Finding | What it means | How to fix it |
made by an older tool (legacy-format) | studio2ga4gh 0.3 or abusua2ga4gh 0.2 wrote it, in a form the standard doesn't accept | Upgrade a file from an older tool |
the draft of version 1 (draft-form) | the file follows the draft of version 1 of the standard, which isn't approved yet (The GA4GH Pedigree) | it can't be converted yet, so ask for the file in the published form |
no ontology id (empty-term-id) | a condition is named, but has no term | Fill in missing terms |
no resource for a prefix (undeclared-prefix) | terms are used, but metaData doesn't say which ontology they come from | Upgrade adds the resource |
a field the standard does not have (unknown-field), or a required one missing (missing-field) | for example a name in subject, or no metaData | Upgrade fixes the ones it knows about, and the rest must be corrected where the file was made |
a retired KIN code (old-kin-term), or KIN's label not used (kin-label) | the relationship is written with a code from an earlier draft of KIN, or with another label | Upgrade replaces them |
not a carrier term (carrier-term) | HP:0032500 used for a carrier, as abusua2ga4gh 0.2 did, although it's the HPO term Exacerbated by tobacco use | Upgrade removes it, and a GA4GH Pedigree's narrative then says who is a carrier |
someone not in the file (unknown-person, unknown-index-patient) | a relationship or the index patient names an id that no individual has | correct the ids where the file was made |
a parent's sex (parent-sex, relation-sex), a loop of ancestry (ancestry-loop) | the family doesn't hang together | correct the drawing, and convert it again |
release not recorded (unknown-version) | the file doesn't say which release of an ontology its terms come from | nothing has to be done, but matching terms in the workbench records the release |
3 · Upgrade an older file
Upgrade a file from an older tool rewrites the file in the standard form. It lists every change, and anything it couldn't do, which usually means conditions without a term. Under the result, Check the upgraded file checks it again.
Among the things it corrects in files from abusua2ga4gh 0.2 are names inside subject, which the standard has no place for, and a sperm donor written as KIN:039, which in KIN means hasGestationalCarrier. It also corrects carriers given the HPO term HP:0032500, which is Exacerbated by tobacco use. Anything it can't tell from the file, it leaves alone and tells you about. For example, abusua2ga4gh wrote foster and social parents as adoptive parents, and only the free-text note, which the upgrade keeps in the narrative, says which they were. The GA4GH Pedigree lists what was wrong with the older files, and why.
4 · Give the remaining conditions their terms
If the upgrade couldn't give a condition its term, Fill in missing terms can, either from a terms file or by looking the name up, as Give the conditions ontology terms explains. Then check the file once more.
The same in the terminal
pedigree-ga4gh validate /data/examples/older/abusua2ga4gh-0.2_phenopackets-family.json
pedigree-ga4gh upgrade /data/examples/older/abusua2ga4gh-0.2_phenopackets-family.json -o ~/results/abusua_phenopackets-family.json
pedigree-ga4gh validate ~/results/abusua_phenopackets-family.json
pedigree-ga4gh validate ends with exit status 0 for a valid file and 1 for an invalid one, so you can use it in a script.
Give the conditions ontology terms
GA4GH and Phenopackets files name each condition by a term from an ontology, so that software and people everywhere read it in the same way. A disease is named by a term from the Mondo Disease Ontology, and a sign or symptom by a term from the Human Phenotype Ontology (HPO). This walkthrough shows you how to find the terms for a drawing's conditions, and how to fill in the terms that an existing file lacks.
For a drawing: Match conditions to terms
1 · Choose the drawing
The tool lists the conditions in the drawing's colour key, with the number of people who have each one. If you keep a terms file for a project, start from it. Conditions it already has are filled in, and your new matches are added to it.
2 · Choose where to search
- EBI's Ontology Lookup Service searches the latest releases, and finds terms that a local search can miss. It needs the internet, and it sends EBI the words you search for and any ids you type, but never the drawing.
- Copies of the ontologies on this computer work without the internet and send nothing. The tool can download the HPO (about 11 MB) into
~/ontologies for you. Mondo's file is about 50 MB, and its host doesn't let web pages download it. Instead, download mondo.obo with your browser from Mondo's download page, then add it with From my computer…. The first search of a file reads all of it, which takes several seconds.
3 · Match each condition
For each condition, the tool guesses from the name whether it's a disease (Mondo) or a sign or symptom (HPO). Change its choice if it's wrong, then press Suggest. Each suggestion shows the term's id and label, whether its label or a synonym matched, a score and the term's definition. Choose the one that's right. If none is, change the words and search again. If you already know the id, type it and press Use this id. The tool looks it up, so that its label and release are recorded.
Choose the most specific term that's true of everyone with the condition in this family. Hearing impairment (HP:0000365) is true of the Okafor twins. If their hearing loss is known to be sensorineural, Congenital sensorineural hearing impairment (HP:0008527) says more. Use a Mondo term when there's a diagnosis, and HPO terms for features without one. Read the definition, because two terms can share a name, as breast cancer (MONDO:0007254) and breast carcinoma (MONDO:0004989) nearly do.
4 · Keep the matches
Save writes the terms file, which for the Price family is ~/terms/price-terms.json. Tick Also write the ids into the drawing's colour key to make a copy of the drawing whose key reads Breast cancer [MONDO:0007254]. A drawing like that carries its terms wherever it goes, and converts without a terms file. Then press Next to open Drawing → GA4GH with the drawing and the terms file already chosen.
For a GA4GH file: Fill in missing terms
Files from older tools, or from elsewhere, may name conditions without their ids. Fill in missing terms gives each one its id from a terms file, ignoring capital letters when it matches the names. It can also look up names that aren't in the terms file. It uses a term it finds when the term's name, or one of its synonyms, is the same as the condition's name, ignoring capital letters and punctuation. With a lower threshold it takes close matches too, but each of those is a guess for you to check. It writes a log of what it decided next to the new file, ….normalised.log.json.
A file made by an older tool must be upgraded first, and the tool tells you when that's needed. To try this, upgrade the older example, then fill in its terms from the examples' terms file. The tool picks your newest file, which is the upgraded one.
A terms file
A terms file is a small JSON file. It lists each condition's name in the drawing, with its term and the release of the ontology the term came from. You can also write one by hand, giving just the id if you like.
{
"Breast cancer": {"id": "MONDO:0007254", "label": "breast cancer", "version": "2026-10-06"},
"Hearing loss from birth": {"id": "HP:0000365", "label": "Hearing impairment", "version": "2026-09-01"},
"Ovarian cancer": "MONDO:0008170"
}
One terms file can serve many drawings, and capital letters don't matter when the names are matched. Ontology terms and terms files has more.
The same in the terminal and in Python
There's no command that reads a drawing's colour key and lets you work through each condition with the mouse. That's what the tool is for. These commands convert the Price family with a terms file, then upgrade the older example and fill in its terms from the same file:
studio2ga4gh /data/examples/price.studio.json -t /data/examples/example-terms.json -d ~/results
pedigree-ga4gh upgrade /data/examples/older/studio2ga4gh-0.3_phenopackets-family.json -o ~/results/older_phenopackets-family.json
phenotk normalise ~/results/older_phenopackets-family.json --mapping /data/examples/example-terms.json --no-online -o ~/results/older.normalised.json
hponorm and mondonorm, the programs behind the searches, match the names in a GA4GH or Phenopackets file by asking you about each one as they go. This terminal can't pass your answers to them, so here they stop at the first question. They can take their answers from a file instead: hponorm FILE.json --mapping answers.json --auto-remembered -o OUT.json. In Python, their searches look like this:
from hponorm.ols import OlsClient # EBI's Ontology Lookup Service (online)
for c in OlsClient().search("hearing loss from birth", limit=5):
print(c.id, c.label, c.score)
from mondonorm.mondo import MondoIndex # a copy of Mondo on this computer
index = MondoIndex.load("/home/user/ontologies/mondo.obo", allow_download=False)
for c in index.search("breast cancer", limit=5):
print(c.id, c.label, c.score)
Turn a picture of a pedigree into a PED file and a drawing
A pedigree in a paper, a clinic letter or an old scan, or one sketched in a hurry, is only a picture. PedInterp reads one into a PED file, which the other tools can use, and into a Pedigree Studio drawing laid out as the picture is, where you can check it against the picture and add what a PED file can't hold. The example is a picture of the Lynch family, drawn as pedigrees are drawn in papers.
1 · Add the picture
Add your picture with From my computer… under the file box of the tool in the next step, or with My files → Add files from my computer… at the top right. A PNG file is best. A scan or a screenshot reads better than a photograph of a page, because the drawing needs to be dark on white, sharp, and square to the edges. A pedigree sketched by hand, with Pedigree Studio's Draw tool or on paper, can be read too: tick Drawn by hand in the next step.
2 · Read it
Picture → PED file and drawing finds the symbols and the lines, works out who is whose parent, and writes the PED file and the drawing. The people are numbered by generation, from the top, and from the left in each generation: I-1, I-2, II-1 and so on. The first time, Python downloads what PedInterp needs, about 21 MB, which takes a little while.
3 · Check it
The table under the result is the PED file's. It has a row for each person, with their parents (0 when they aren't in the picture), their sex (1 male, 2 female, 0 unknown), and whether they're affected (2) or not (1). A line under it says how many times PedInterp enlarged the picture to read it, which it chose to suit the symbols' size, and a warning follows if it thinks a line between the symbols was missed. Compare what it read with the picture: the drawing, in the next step, is the easiest way. If someone is missing or has the wrong parents, When something goes wrong says what to try.
The Lynch family's PED file in the examples was made from the drawing that the picture shows, so here the two files can be compared as well: the commands at the foot of this page do it.
4 · Open the drawing
Under the result, Open the drawing in Studio opens the drawing PedInterp made, ~/results/lynch.studio.json, in the Studio tab. It is laid out as the picture is, a row of symbols to a generation, so it is easy to set beside the picture. It has the twins, if there are any, and any couples who have no children, which a PED file can't hold. The Studio's Tidy lays it out afresh, if you'd rather.
In the Studio, put right anything misread, and add what the picture shows but PedInterp didn't read, such as who has died (in the Lynch picture, I-1, I-2, II-2 and III-2). PedInterp reads who has died, the proband and carriers only if you tick Read who has died, the proband and carriers in the tool's form, and then it writes no PED file, which can't hold them: the drawing has them, and you can make a PED file from it afterwards. Name the condition in the colour key, or give it in the tool's form before you read the picture, and the key names it with its ontology term. Then save the drawing. If you put anything right, make the PED file again from the drawing with Drawing → PED or MPED. From the drawing you can make the GA4GH files too, or look at the family with PedNet (Weigh up the mode of inheritance, and rank candidate variants).
If you untick Make a Pedigree Studio drawing too, the button under the result is Draw it instead, which makes a drawing laid out afresh: from the PED file (PED or MPED → drawing), or from the GA4GH Pedigree, if you ticked Write a GA4GH Pedigree too, which holds the twins as the drawing does.
The same in the terminal
pedinterp /data/examples/lynch.png --labels none --studio -q -d ~/results
diff <(cut -f2- ~/results/lynch.ped) <(cut -f2- /data/examples/lynch.ped) && echo "the same people, parents, sexes and status"
studio ~/results/lynch.studio.json
cut -f2- leaves out the family's id, which the two files give differently.
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- PedInterp
- Taylor N. PedInterp [software]. github.com/comparativechrono/pedigree-interpreter
- ped2studio
- Hearn TJ. ped2studio [software]. github.com/comparativechrono/ped2studio
- Pedigree Studio
- Hearn TJ. Pedigree Studio [software]. Zenodo. doi:10.5281/zenodo.20209376
Weigh up the mode of inheritance, and rank candidate variants
From a family's PED file, PedNet shows how the family is put together, weighs up how its condition is inherited, and ranks the variants found by sequencing some of its members by how well each co-segregates with the condition. This walkthrough uses three of the example families: the Okafor family, whose twin boys with hearing loss are the sons of first cousins; the Lynch family, with bowel cancer over three generations; and one of PedNet's own families, with six candidate variants.
The tools read PED files, and GA4GH Pedigrees and Phenopackets Families too. To use one of your drawings, make it into one of these first, with Drawing → PED or MPED or Drawing → GA4GH Pedigree and Phenopackets.
1 · The family as a graph
The pedigree as a graph lists the family's loops, who is inbred, and how closely the affected people are related. In the Okafor family, the twins' parents, III-2 and III-3, are first cousins: III-2's father and III-3's mother, II-2 and II-3, are brother and sister, so the marriage closes a loop through them. All five of the couple's children have an inbreeding coefficient of 1/16.
From an MPED file, PedNet takes the first condition: for the Okafor family, hearing loss from birth.
2 · The mode of inheritance
Mode of inheritance gives the probability of each mode. In the Lynch family, there is cancer in three generations in a row: in I-1, in his sons II-2 and II-3, and in II-2's daughters III-2 and III-3. Autosomal dominant inheritance has a probability of 0.97.
In the Okafor family, two affected brothers whose parents are cousins make a recessive condition almost certain, at 0.98, but they can't show whether it is autosomal or X-linked. The answer is uncertain, with autosomal recessive at 0.69 and X-linked recessive at 0.29. That is all one family can say. If other families have the same condition, put them in one PED file, and tick The families have the same condition.
3 · Rank the candidate variants
Rank candidate variants needs the PED file and the variants: a VCF file whose samples are named with the PED file's ids, or a table of genotypes. PedNet's example family has a dominant condition, and six variants found in some of its members.
var1, which all six of the affected people carry and none of the three unaffected people who were tested, comes first, with a log10 Bayes factor of 2.05: strong evidence for co-segregation (PP1_Strong). Each of the others is strong evidence against causing the condition (BS4_Strong). The variants are ranked by their odds of being the cause, which take account of whether a variant's chromosome suits the family's mode of inheritance as well as of its Bayes factor. This family's condition is almost certainly autosomal, so var5, on the X chromosome, comes fourth, below var2 and var4, though its Bayes factor is higher than theirs.
PedNet also notes genotypes that break Mendel's laws. Only III-1 carries var6, though neither of his parents does, which a new mutation in III-1 would explain. var5 breaks them three times: II-3 and III-2 don't carry it, though their fathers do, and a father passes his X chromosome to every daughter; and III-1 carries it, though his mother doesn't. A new mutation in III-1 would explain only the last of these.
The tool saves every score in a table, ~/results/dominant-ranked.tsv, which you can open in the Files tab or a spreadsheet.
Co-segregation is one line of evidence among many under the ACMG/AMP guidelines, and PP1 applies only to a gene that is known to cause the condition. The Bayes factor assumes that the PED file is right and that the genotypes were called correctly, apart from a small error rate. A variant that co-segregates may only be close to the one that causes the condition. Weigh it with the rest of the evidence.
The same in the terminal
pednet graph /data/examples/okafor.mped
pednet mode /data/examples/lynch.ped
pednet mode /data/examples/okafor.mped
pednet rank /data/examples/pednet/dominant.ped /data/examples/pednet/dominant.vcf --out ~/results/dominant-ranked.tsv
The notebook ~/notebooks/pedigree-analysis.ipynb does the same in Python, and goes on to simulated families and pictures.
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- PedNet
- Hearn TJ, Taylor N. PedNet [software]. github.com/comparativechrono/PedNet
- Co-segregation, and its strength as evidence (PP1, BS4)
- Thompson D, Easton DF, Goldgar DE (2003) A full-likelihood method for the evaluation of causality of sequence variants from family data. American Journal of Human Genetics 73(3): 652–655. doi:10.1086/378100
- Jarvik GP, Browning BL (2016) Consideration of cosegregation in the pathogenicity classification of genomic variants. American Journal of Human Genetics 98(6): 1077–1081. doi:10.1016/j.ajhg.2016.04.003
- Richards S, Aziz N, Bale S, Bick D, Das S, Gastier-Foster J, et al. (2015) Standards and guidelines for the interpretation of sequence variants: a joint consensus recommendation of the American College of Medical Genetics and Genomics and the Association for Molecular Pathology. Genetics in Medicine 17(5): 405–424. doi:10.1038/gim.2015.30
- Tavtigian SV, Greenblatt MS, Harrison SM, Nussbaum RL, Prabhu SA, Boucher KM, et al. (2018) Modeling the ACMG/AMP variant classification guidelines as a Bayesian classification framework. Genetics in Medicine 20(9): 1054–1060. doi:10.1038/gim.2017.210
- Pedigrees as Bayesian networks
- Lauritzen SL, Sheehan NA (2003) Graphical models for genetic analyses. Statistical Science 18(4): 489–514. doi:10.1214/ss/1081443232
- Kinship and inbreeding coefficients
- Wright S (1922) Coefficients of inbreeding and relationship. The American Naturalist 56(645): 330–338. doi:10.1086/279872
Work out the risk to a pregnancy
The Risk tab works out the chance that a pregnancy, or any child of a couple, will be affected, from everything known of the whole family. This walkthrough uses three of the example families: a couple who are second cousins, with cystic fibrosis in the family; the Lynch family, with bowel cancer over three generations; and the Okafor family, whose twin boys have had hearing loss from birth.
1 · A couple with cystic fibrosis in the family
Lisa (IV-1) and David (IV-2) are second cousins, and Lisa is pregnant. David's sister Amelia has cystic fibrosis, an autosomal recessive condition, and Lisa's father Michael is known to be a carrier, which is what the dot in his symbol means. The button opens the family with the numbers for cystic fibrosis in northern Europe, where 1 in 25 people carry a variant.
The pregnancy (V-1) will be affected with a chance of about 1 in 12 (8.4%). Under Everyone, click David's name. As the unaffected brother of someone affected, he is a carrier with a chance of 2/3: his Bayesian table shows the 1/4, 1/2 and 1/4 of his parents' cross, and the two copies ruled out because he is unaffected. Lisa is a carrier with a chance of about 51%. That is 1/2 from her father, and a little more, because her mother Anne, who isn't related to the family, could be a carrier too.
By hand, the pregnancy's chance is the chance that David is a carrier, times the chance that Lisa is, times 1/4: 2/3 × 1/2 × 1/4 = 1/12.
The Risk tab's chance is a little higher because it allows for Anne. To see this, find Anne (III-2) under Everyone and give her the test result doesn't have it. Lisa's chance becomes 1 in 2, and the pregnancy's exactly 1 in 12. Set the result back to — when you're done.
2 · A Bayesian table, with reduced penetrance
In the Lynch family, bowel cancer has been passed down three generations. Ann (III-4), who is 48, has had no cancer, but her father had. Take the condition to be autosomal dominant, with a penetrance of 80%.
As the daughter of an affected father, Ann had a chance of 1/2 of inheriting the variant: that is her prior. Her Bayesian table takes account of what is known of her and her daughters, IV-3 and IV-4, who are unaffected too. If Ann has the variant, the chance that all three of them are unaffected is 0.2 × 0.6 × 0.6 = 0.072, or about 1 in 14. Ann would have escaped the cancer, with a chance of 0.2, and each daughter would have either not inherited the variant or escaped the cancer, with a chance of 1/2 + 1/2 × 0.2 = 0.6. If Ann doesn't have the variant, the chance is nearly 1. These are the conditionals, and her posterior chance of having the variant is about 1 in 15 (6.7%). Her cousin Gary (III-6) has no children, so only the fact that he is unaffected counts, and his chance is about 1 in 6, as for any unaffected child of an affected parent at this penetrance.
The Risk tab doesn't allow for age, though, and bowel cancer usually starts later in life, so the fact that Ann's daughters, at 21 and 26, haven't had it says little. Under Everyone, set Test result or status for IV-3 and IV-4 to not known (leave it out). Ann's chance rises to about 1 in 6, the same as Gary's.
3 · The mode of inheritance matters
In the Okafor family, the twins Chidi and Dubem (IV-3 and IV-4) have had hearing loss from birth, and their parents, Obi and Amaka (III-2 and III-3), are first cousins. Amaka is pregnant again (IV-5). If the hearing loss is autosomal recessive, Obi and Amaka must both be carriers, and the pregnancy will be affected with a chance of 1 in 4.
If it is X-linked recessive instead, Amaka must be a carrier, and a son's X chromosome comes from her alone. Under A child of a couple, a son of theirs has a chance of 1/2 of being affected, and a daughter none, as Obi is unaffected. Before its sex is known, the pregnancy's chance is 1 in 4 again, but for a boy it is 1/2. An affected pair of brothers can't tell these two modes apart: PedNet puts autosomal recessive at 0.69 and X-linked recessive at 0.29. The Risk tab can't choose the mode for you, but it shows you what each mode would mean for the family.
4 · Your own family
Draw the family in the Studio tab, with the condition in the colour key, then choose ⋯ (More) → Work out the risks in this family. Or choose a drawing, a PED file or a GA4GH file under From, or use Risks next to a file in the Files tab. The Risk tab reads the drawing in the Studio tab again each time you come back to it, so you can go back and forth between the two: mark someone as affected or as a carrier in the Studio, then see how the chances change.
Save as a table writes everyone's chances to ~/results, as a TSV file with a row for each person. In a notebook, pandas reads it: pd.read_csv("/home/user/results/cf-cousins_risks.tsv", sep="\t").
The Risk tab describes everything on the tab, and How the chances are worked out explains the sums.
Run the same steps for several families, with a workflow
When you do the same job for one family after another, such as making the GA4GH files from each drawing, checking them and de-identifying them, a workflow does all the steps in one go. In this walkthrough you run an example for two families, make a workflow that weighs up a family's mode of inheritance from its drawing, and make another from tools you've run one at a time.
1 · Run an example
The example Share a drawing in the GA4GH standard does what Share a family's pedigree in the GA4GH standard does by hand. It makes a GA4GH Pedigree and a Phenopackets Family from a drawing, checks both, de-identifies the Family, then checks that too. It has two input files: the drawing, which is the Okafor family's to begin with, and a terms file for the conditions, which is the examples' terms file. Press Run.
The steps run one after another, and each says what it did: Wrote 2 files, or for a check, Valid: a correct GA4GH Pedigree. Open What it did under a step to see what the program printed, the files it wrote, with buttons to open or check them, and its command. The files are all in one folder, ~/results/share-a-drawing-in-the-ga4gh-standard/okafor, with the record of the run, workflow-run.json, and its commands, commands.sh.
2 · Run it for another family
Now run it for the Lynch family. Choose lynch.studio.json as the drawing (the button below does this for you), and leave the terms file as it is, because it has terms for the Lynch family's conditions too. This run's files go in a folder of their own, …/lynch, beside the Okafor family's.
The Workflows page lists both runs under Runs, and View shows either of them again. For a drawing of your own, choose it instead. If the examples' terms file doesn't have its conditions, make a terms file for them first with Match conditions to terms, and choose that file as well.
3 · Make a workflow of your own
This workflow makes a PED file from a drawing, then weighs up the family's mode of inheritance from it with PedNet.
- On the Workflows page, press New workflow. The editor opens, on an empty workflow.
- Press + Input file. The box it adds takes a Pedigree Studio drawing, which is what this workflow needs. If you click the box, you can give it a name, such as The drawing, or choose another kind of file.
- Press the + by Pedigree Studio drawing, on the right of the box. It lists the tools that read a drawing: choose Drawing → PED or MPED. Its box appears to the right, already reading the drawing.
- Press the + by PED or MPED file, on the new box, and choose Mode of inheritance.
- Click the background. Under Checks, it says Ready to run. Give the workflow a name at the top, such as Drawing to mode of inheritance, and a description under What it does.
Instead of using the +, you can add each step with + Add a step, then drag from the dot by PED or MPED file to the input of Mode of inheritance. Either way, the editor saves the workflow as you go, in ~/workflows.
Press Run, choose lynch.studio.json as the input file, and press Run again. The last step says Family FAM1: autosomal dominant, and under it are PedNet's probabilities for each mode of inheritance. Weigh up the mode of inheritance, and rank candidate variants explains them.
4 · Make one from tools you've run
If you've already done a job once, tool by tool, the Workflows page can turn what you did into a workflow.
- Make the GA4GH files from the Price family's drawing: the button below opens Drawing → GA4GH Pedigree and Phenopackets with the drawing and the terms file filled in. Press Run.
- Under the result, press Check beside the GA4GH Pedigree, then Run.
- Open the Workflows page, and press Make one from the tools you've run. The two tools you've just run are ticked. Untick any others, give the workflow a name, and press Make the workflow.
The workflow opens in the editor. The drawing and the terms file are its inputs, and the Check reads the GA4GH Pedigree that the first step writes, as it did when you ran the tools. Run it for any other drawing, as you did in step 2.
The same in the terminal
Each run's commands.sh holds the commands its steps ran. This runs the steps of the Lynch family's run again:
bash ~/results/share-a-drawing-in-the-ga4gh-standard/lynch/commands.sh
More about workflows: Workflows.
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- studio2ga4gh
- Hearn TJ. studio2ga4gh [software]. github.com/comparativechrono/studio2ga4gh
- pedigree-ga4gh
- Hearn TJ. pedigree-ga4gh [software]. github.com/comparativechrono/pedigree-ga4gh
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
- studio2ped
- Hearn TJ. studio2ped [software]. github.com/comparativechrono/studio2ped
- PedNet
- Hearn TJ, Taylor N. PedNet [software]. github.com/comparativechrono/PedNet
The Studio tab
The Studio tab is Pedigree Studio, our program for drawing pedigrees in the standard nomenclature, running inside the workbench. The bar above it connects the Studio to your files. It shows which file the drawing you're working on belongs to, saves the drawing there and takes it to the Tools tab.
The bar
| What it does |
| Drawing and the file's name | Shows the file the drawing belongs to, or not saved yet. Click it to see your other drawings, with the most recent first. Next to it you'll see saved or unsaved changes. |
| New | Starts an empty drawing. If the drawing you're working on has unsaved changes, you're asked first. |
| Open… | Opens one of your drawings, one of the examples, or a drawing from your computer. |
| Save (Ctrl+S) | Saves the drawing in its file. If the drawing doesn't have a file yet, you're asked for a name. |
| Save as… | Saves the drawing as a new file in ~/pedigrees, unless you choose another folder in your home folder. The file's name ends in .studio.json. |
| Tidy | Runs Pedigree Studio's Tidy, which lays out the whole pedigree again. Undo in the Studio puts your own layout back. |
| Convert or check… | Saves the drawing, then shows you everything you can do with it in the Tools tab. |
| ⋯ | Lets you download the drawing, show its file in the Files tab, or get help. |
Opening drawings
The examples can't be changed, so an example opens as a new drawing that hasn't been saved yet. Change it as much as you like, then use Save as… to keep your version. You might also have a drawing from somewhere else, saved from Pedigree Studio's own File menu or sent to you by someone. Open it with Open… → Open a drawing from my computer…. The workbench recognises a Pedigree Studio file by what's in it, whatever the file is called.
To open a drawing that a tool has just made, press Open the drawing in Studio in the tool's result, or type studio FILE in the terminal.
Where the drawing is kept
A saved drawing is one of your files, and like the others it's kept in this browser (Your files). Pedigree Studio also keeps the drawing you're working on, just as you left it. So if you close the page without saving, the drawing is still there when you come back. If it has a file, you'll see unsaved changes next to the file's name until you save it. If it has never been saved, the bar says not saved yet.
Pedigree Studio's own File menu still works just as it does when you use Pedigree Studio by itself. It saves the drawing as a file on your computer, opens a drawing from your computer, and exports pictures as PNG, or as SVG for documents and posters. To keep a drawing among your files, use Save on the bar.
Drawing a pedigree
Pedigree Studio's own help, under its ? button, explains how to draw, covering the symbols, the toolbar and the panels. In short:
- Add the first person with Male, Female or Unknown on the toolbar. This is usually the person the pedigree is for, and the one you mark as the proband in the panel.
- Build out from them with Add a relative. With someone selected, it adds a partner, a child, parents, or a brother or sister, already joined up.
- Join people yourself with Partners, Child and Twins. For triplets, link the third child to one of the twins; their lines are then drawn from one point.
- Describe each person in the panel. You can add notes under the symbol, mark someone as deceased and add shading for a condition. You can also put a mark inside the symbol for a carrier, a pregnancy, a donor (D) or a gestational carrier (G, which the 2025 correction to the nomenclature uses in place of S; drawings made before still show S, and the tools read it the same way).
- Click a line to mark a couple as consanguineous or separated, or to make a line of descent dashed to show an adoption.
- Tidy lays it all out again.
What the tools read from a drawing
- The colour key names the conditions. Give each condition its own colour (or a half, a third, a quarter or a pattern), and name it in the key with the Key button. A colour that the key doesn't name isn't counted as a condition. An id in brackets after the name, as in Breast cancer [MONDO:0007254], gives the condition its term (Ontology terms and terms files). A long name widens the key to fit it on one line, unless you choose Wrap the text under Long entries in the key in the Studio's File menu; then drag the key's right edge to set its width.
- The proband becomes the index patient in the GA4GH files.
- The notes under the symbols stay in the drawing. The GA4GH and PED files name people by their pedigree numbers, unless you choose otherwise.
- Carriers, pregnancies, losses, donors and gestational carriers are written in the ways the standard allows. Losses and pregnancies are written as people, and donors and gestational carriers by their KIN relationships, as are twins and triplets (drawn from one point), including those whose zygosity isn't known. Anything that has no place of its own, such as a carrier or a consultand, goes in the GA4GH Pedigree's narrative.
- A symbol that stands for several people, shown by a number inside it, is written as one person, and the tool tells you so under the result.
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- Pedigree Studio
- Hearn TJ. Pedigree Studio [software]. Zenodo. doi:10.5281/zenodo.20209376
- Pedigree nomenclature
- Bennett RL, French KS, Resta RG, Doyle DL (2008) Standardized human pedigree nomenclature: update and assessment of the recommendations of the National Society of Genetic Counselors. Journal of Genetic Counseling 17(5): 424–433. doi:10.1007/s10897-008-9169-9
- Bennett RL, French KS, Resta RG, Austin J (2022) Practice resource-focused revision: Standardized pedigree nomenclature update centered on sex and gender inclusivity: a practice resource of the National Society of Genetic Counselors. Journal of Genetic Counseling 31(6): 1238–1248. doi:10.1002/jgc4.1621
The Tools tab
The Tools tab gives you simple forms for our Python packages. Choose a file, set any options and press Run. The tool runs exactly the command you would type in the terminal, then shows you what it printed and the files it wrote. Under every form you'll find that command too, and the same job written in Python, so you can always see what the tab is doing.
Finding the tool you need
- The first page has a map of the formats and the tools that go between them. It also lists the common tasks, each with its tools in the order you use them. Click an arrow on the map to open that tool, or click a box to list everything you can do with that kind of file.
- The list on the left (All tools on a narrow screen) has every tool, arranged in groups.
- From a file, you can open the file's own page, which shows what's in it and the tools that read it. Use More… next to a file that a tool has written, the buttons in the Files tab, or Convert or check… in the Studio.
A tool's page
- The fields. You can choose from your own files or the examples, or pick a file from your computer with From my computer…. For a drawing, you can also choose The drawing in the Studio tab, which uses the drawing that's open there and saves it first. Look at it opens the file you've chosen. The names of the files the tool will write are filled in for you, and you can change them. Results go in
~/results, drawings in ~/pedigrees and terms files in ~/terms, unless you choose another folder.
- Run. The first time you run a tool on each visit, Python starts in your browser, which takes a few seconds. The very first time, it also downloads about 10 MB. The tools of PedNet, PedGen and PedInterp need more, which Python downloads the first time one of them runs, and says so under the form: about 4 MB for PedNet's, and about 21 MB in all. If a file would be overwritten, you're asked first.
- The result. You'll see Done, or the error if something went wrong, then what the program printed and the files it wrote. Each file has buttons to open it in the Studio, look at it, check it, pass it to another tool or download it.
- The same in the terminal, and in Python shows the command and the code, with buttons to run them in the Terminal tab or add them to a notebook.
More about this tool, under the title, explains what the tool does and doesn't do, and links to its page in this help. At the top right, the Python pill shows whether Python is running. Click it to see the versions of the packages.
Several tools in one go
Workflows, next to All tools, chains tools together, so that the files one tool writes go straight into the next, and runs them all in one go, on the same files again or on new ones. You can start from an example, draw your own in an editor, or turn tools you've run into a workflow (Workflows).
The tools
Convert
Ontology terms
Check and look inside
Prepare to share
PED and MPED files
Analyse and simulate
Each tool runs a package's own command, exactly as the package provides it, and the tab adds no conversions of its own. Match conditions to terms works differently, because it has no command. Instead, it searches using the packages' Python code and writes a terms file. A few commands have options that the forms leave out, such as the options for variants in phenotk add. In the terminal, man and --help describe them.
Workflows
A workflow chains the tools of the Tools tab together, so that the files one step writes go straight into the next. You choose its input files and press Run, and the steps run one after another, exactly as they would if you ran each tool yourself. Each run keeps its files in a folder of its own, with a record of how they were made. If you've used workflows in Galaxy, these will look familiar.
The Workflows page
Open it with Workflows, next to All tools at the top of the Tools tab. It lists:
- Your workflows, the ones you've made or copied, each a file in
~/workflows, with buttons to run, edit, download or delete it.
- Examples, ready to run. Edit a copy makes one yours to change.
- Runs, the newest first. View shows what a run did, step by step, and Folder opens its folder in the Files tab.
At the top, New workflow opens the editor on an empty workflow, Make one from the tools you've run turns tools you've run into a workflow, and Add a workflow file… adds one from your computer, such as one someone has sent you.
Running a workflow
Run opens a form with a box for each of the workflow's input files, numbered as they are in the editor. Each starts with the file you gave it last time, or else the one the workflow suggests, or else the first file that fits, from your own files or the examples. An optional input, such as a terms file, can be left as none. Under the inputs:
- Put the results in is the run's folder. It is named after the workflow and the first input file, such as
~/results/share-a-drawing-in-the-ga4gh-standard/okafor, with -2, -3 and so on added if that folder is taken. You can choose another, anywhere in your home folder.
- The steps lists the tools in the order they run, with any settings of their own.
Press Run, and each step shows waiting, running, then done or failed, with a line on what it did: the files it wrote, or what a check found. Python starts the first time, as it does for a tool. You can go to another tab while the steps run, and a message tells you when they have finished. Stop stops the run after the step that is running. Only one workflow runs at a time.
If a step fails, the steps that read its files don't run, and the others still do. What went wrong, under a step that failed, says why, with what the program printed. Under a step that worked, What it did has what the program printed, the files it wrote, with the same buttons as under a tool's result, and its command. When the run has finished, you can open its folder in the Files tab, open its steps as a notebook, run it again (on another file, perhaps), or edit the workflow.
What each run keeps
- The files its steps write, named as the tools name them. The GA4GH Pedigree made from
okafor.studio.json is okafor_ga4gh-pedigree.json, just as it is when you run the tool yourself. A tool that writes a set of files, such as One file for each person, puts them in a folder inside the run's folder. If a step would write a file with the same name as one an earlier step wrote, its files go in a folder of their own, named after the step, such as 4-fill-in-missing-terms.
- A record of the run,
workflow-run.json. It holds the workflow as it was, the input files, and for each step its settings, its command, what it printed and the files it wrote. Open it in the Files tab to see the run again.
- Its commands,
commands.sh. bash commands.sh in the Terminal tab runs the steps again. On your own computer, with the packages installed, it does the same, once any paths that begin /data/examples point to your copies of the examples.
Open the steps as a notebook writes a notebook in ~/notebooks with each step's Python, as the Tools tab shows it under each tool, and opens it in the Notebook tab.
The editor
New workflow, Edit on one of yours and Edit a copy on an example all open the editor, which takes up the whole width of the Tools tab. Each input file and each step is a box, numbered in the order they run. A step's input files are on the left of its box, and the files it writes are on the right, each with a dot.
- + Input file adds a file the workflow is given when it runs. Click its box to name it, to say what kind of file it is, and to choose a file to suggest. Tick Optional for a file that the steps can do without, such as a terms file.
- + Add a step adds a tool. If a box is selected, the new step goes to its right, and reads one of its files if it can.
- The + by a file lists the tools that read that kind of file. The step you choose reads it.
- Drag from a dot on the right of a box to an input on the left of another to connect them. While you drag, the inputs that can take the file grow and turn green, and the others fade: a file can only go into an input that takes its kind. Click a line to take that connection away.
- Click a box for its settings, in the column beside the boxes (below them on a narrow screen). For a step, you choose where each of its input files comes from, or press Make it an input of the workflow, and you set the tool's options, as in its form. Where its files go isn't one of them, because each run decides that. A setting that the tool works out from the name of a file, such as PedInterp's family id, is worked out when the workflow runs, unless you fill it in. A choice that a tool makes from the kind of file it's given, such as what GA4GH Pedigree ⇄ Phenopackets Family makes, is made here instead, so that the step always writes the kind of file its box shows.
- Click the background for the workflow's description and its Checks, which list what stops it running, such as an input that isn't connected. Click a check to go to its step. When nothing does, it says Ready to run.
- Tidy arranges the boxes in columns, with the inputs on the left. To move a box, drag it. On a touch screen, drag it by its title.
Your changes are saved as you go, and Saved, beside the name, tells you when they have been. Change the name at the top left, and the workflow's file is renamed to match. The download button, beside Run, saves the file, NAME.workflow.json, to your computer, to keep or to send to someone. They add it with Add a workflow file…, which puts it in their ~/workflows under a name of its own, so that a workflow of theirs with the same name is kept.
A workflow from the tools you've run
Make one from the tools you've run does what Galaxy's Extract workflow does. Run the tools in the Tools tab one after another, each on a file the one before wrote, then come to this page. Tick the tools to use (the ones that worked in the last three hours are ticked already), give the workflow a name, and press Make the workflow. A file that one of them wrote and a later one read becomes a connection between their steps. Any other file they read becomes an input of the workflow, which suggests the file you used, and the settings you chose are kept. The page lists the last 40 tools you ran.
What can be a step
- Every tool of the Tools tab, except Match conditions to terms, which asks you questions as it goes. Make the terms file with it first, then give the file to the workflow as an input, as the example Share a drawing in the GA4GH standard does.
- The checks, and the tools that only report, such as Check against the standard, Compare two files and Mode of inheritance, write no files. What they found is in the run's record, under the step.
- A set of files, such as the Phenopackets that One file for each person writes, can only go into a tool that reads several files at once: Put files together, or Put PED files together.
How they differ from Galaxy's
These workflows run in your browser, in the same Python as the tools, and nothing is sent anywhere. Each step is a package's own command, so a run's commands.sh does the same job in a terminal. There are no collections: to run a workflow on several families, run it once for each of them, and each run gets a folder of its own. Galaxy's workflow files can't be opened here, because the tools are different.
A workflow file is JSON. It holds the workflow's name and description, and its steps: each input, and each tool with its settings and the files it reads (Which file is which).
Drawing → GA4GH Pedigree and Phenopackets
studio2ga4gh turns a Pedigree Studio drawing into a GA4GH Pedigree and a Phenopackets Family. These are the files you use to share a family's pedigree and findings in the GA4GH standard.
The form
- The drawing
- Choose a Pedigree Studio file, or the drawing in the Studio tab.
- Terms for its conditions
- Choose a terms file that gives each condition in the colour key its ontology term (terms files). Under it, a table shows the term each condition will get. A condition that already has an id in the key, such as Condition X [MONDO:0009061], doesn't need a terms file. Only an ontology's id counts, so Hypertension (BP:160/95) is just a name. A condition without a term is left out, because a GA4GH file has no place for a condition without one. Match them to terms…, under the table, opens the tool that finds the missing terms.
- People are named by
- The default, and the safe choice, is pedigree numbers such as II-3. You can also choose the labels in the drawing, which are often names, or Pedigree Studio's own ids. A label becomes an id in the same way as in studio2ped (J. Mensah becomes
J_Mensah, for example), so a person has the same id in both tools' files. If an id would be empty, 0 or the same as someone else's, the pedigree number is used instead, with a note.
- Family id
- The default, FAM, gives FAM1, then FAM2 and so on if the drawing holds more than one family.
- Files to write
- You can write both files, or just one of them.
- Save in, Start of the file names
- The files are called
start_ga4gh-pedigree.json and start_phenopackets-family.json. They're saved in ~/results unless you choose another folder.
What goes into the files
| In the drawing | In the GA4GH files |
| square, circle, diamond | sex MALE, FEMALE, UNKNOWN_SEX |
| the slash through a deceased person's symbol | vital status DECEASED (otherwise ALIVE) |
| the proband's arrow, with its P | the index patient, and the Family's proband |
| a consultand's arrow (an arrow without a P) | noted in the narrative |
| fill, halves, thirds, quarters, shading | a disease (Mondo) or phenotypic feature (HPO) for each condition named in the key, once it has a term |
| a child's line from a couple | isBiologicalMotherOf, isBiologicalFatherOf (isBiologicalParentOf when the parent's sex is unknown) |
| a dashed line of descent | isAdoptiveParentOf |
| D or G in a parent's symbol (S in drawings made before the 2025 correction to the nomenclature) | isSpermDonorOf or isOvumDonorOf for D, and isGestationalCarrierOf for G or S (not a biological parent) |
| identical and non-identical twins, and twins whose zygosity isn't known (?) | isMonozygoticMultipleBirthSiblingOf, isPolyzygoticMultipleBirthSiblingOf, isMultipleBirthSiblingOf |
| consanguineous, separated and childless couples | isConsanguineousPartnerOf, isSeparatedPartnerOf, isPartnerOf |
| a pregnancy loss | a person who is DECEASED, noted in the narrative |
| the no children and infertility bars | not written as people, and given no pedigree number, as in the Studio, but noted in the narrative |
| a carrier's dot, a presymptomatic line, P | noted in the narrative, because there's no ontology term for them |
| names and notes under the symbols | not written, because Phenopackets have no field for a name, and such notes are often personal data |
Every Phenopacket has its own metaData. This lists a resource for each ontology its terms come from, with that ontology's release, taken from the terms file. The GA4GH Pedigree and Phenopackets describe the files in full.
Under the result
The tool tells you what it wrote. It also notes anything that didn't go in as drawn, such as a condition without a term, or a symbol that stands for several people (written as one person). Read the notes before you send the files.
In the terminal
studio2ga4gh /data/examples/okafor.studio.json -t /data/examples/example-terms.json -d ~/results
| Option | |
-t FILE, --terms FILE | the terms file |
-d DIR, -o START | the folder, which is made if it doesn't exist, and the start of the file names. By default, the files go in the drawing's folder and start with the drawing's name. |
--ids numbers|drawing|studio | how people are named |
--family-id ID, --created-by TEXT | the family's id, and who made the files, for metaData.createdBy |
--only pedigree|family | write one of the two files |
In Python
import json
from studio2ga4gh import convert_file
terms = json.load(open("/data/examples/example-terms.json"))
result = convert_file("/data/examples/okafor.studio.json", "okafor", "/home/user/results", terms=terms)
print(result.summary)
for note in result.warnings:
print("note:", note)
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- studio2ga4gh
- Hearn TJ. studio2ga4gh [software]. github.com/comparativechrono/studio2ga4gh
- pedigree-ga4gh
- Hearn TJ. pedigree-ga4gh [software]. github.com/comparativechrono/pedigree-ga4gh
- GA4GH Pedigree Standard
- GA4GH Pedigree Standard. Pedigree Standard: documentation, examples and the Kinship Ontology (KIN). pedigree.readthedocs.io
- GA4GH Pedigree Standard. pedigree_family_history_terminology: the Kinship Ontology (KIN), kin.owl. github.com/ga4gh/pedigree_family_history_terminology
- Jacobsen JOB. Pedigree (phenopacket-schema pull request 364, opened 24 November 2022, closed without merging 26 September 2025). github.com/ga4gh/phenopacket-schema/pull/364
- Phenopackets
- Jacobsen JOB, Baudis M, Baynam GS, Beckmann JS, Beltran S, Buske OJ, et al. (2022) The GA4GH Phenopacket schema defines a computable representation of clinical data. Nature Biotechnology 40(6): 817–820. doi:10.1038/s41587-022-01357-4
GA4GH or Phenopackets → drawing
ga4gh2studio draws a GA4GH Pedigree or a Phenopackets Family in Pedigree Studio. Each condition gets a colour and is named in the colour key with its term, so the drawing converts back to the same terms.
The form
- The GA4GH file
- Choose a GA4GH Pedigree or a Phenopackets Family. A file from an older tool must be upgraded first (Upgrade a file from an older tool), and the tool will tell you if it needs to be.
- Save the drawing as
- The drawing is saved as a
.studio.json file, in ~/pedigrees unless you choose otherwise.
- Tidy the drawing when it opens
- The tool lays the family out generation by generation, and Pedigree Studio's Tidy usually makes it neater. The tidying is done in the Studio when you open the drawing from the result, so it isn't part of the command.
What comes back
- Everyone comes back, with their sex and whether they've died. So do the couples, including consanguineous and separated ones. Twins (with ? when their zygosity isn't known), adoptions (drawn as dashed lines), donors (D), gestational carriers (G), pregnancies and losses come back too, as do the markers the narrative records, such as a carrier or a consultand. A surrogate, who gave the egg as well as carrying the pregnancy, is a genetic mother, so she's drawn as an egg donor (D), and the tool says so.
- Each condition gets a colour, and is named in the key as label [ID]. A person with two conditions is filled in halves, three in thirds, and four in quarters.
- People are labelled with their ids, except when the ids are pedigree numbers such as II-3, because Pedigree Studio shows those itself.
A Phenopackets Family's pedigree takes the form of a PED file. So a Family gives you the parents, sex and conditions, but no twins and no adoptions, while a GA4GH Pedigree gives you the whole family. If you have a GA4GH Pedigree, draw from that. Draw a GA4GH or Phenopackets file goes through it step by step.
In the terminal
ga4gh2studio /data/examples/okafor_ga4gh-pedigree.json -o ~/pedigrees/okafor-back.studio.json
studio --tidy ~/pedigrees/okafor-back.studio.json
Without -o, the drawing is written in the same folder as the GA4GH file and named after it, for example okafor.studio.json for okafor_ga4gh-pedigree.json. That isn't possible for an example, because the examples can't be changed.
This default name is often the name of the drawing the file was made from, which may hold names and notes that the GA4GH file doesn't. So if a file of that name already exists, the tool stops and tells you, rather than replacing it. Add --force if you do want it replaced. If you name the file with -o, an existing file of that name is replaced. The -g FILE and -p FILE options from version 0.3 still work.
In Python
from ga4gh2studio import convert_file
result = convert_file("/data/examples/okafor_ga4gh-pedigree.json", None, "/home/user/pedigrees/okafor-back.studio.json")
print(result.summary)
for note in result.warnings:
print("note:", note)
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- ga4gh2studio
- Hearn TJ. ga4gh2studio [software]. github.com/comparativechrono/ga4gh2studio
- pedigree-ga4gh
- Hearn TJ. pedigree-ga4gh [software]. github.com/comparativechrono/pedigree-ga4gh
- Pedigree Studio
- Hearn TJ. Pedigree Studio [software]. Zenodo. doi:10.5281/zenodo.20209376
Drawing → PED or MPED
studio2ped turns a drawing into a PED file, the table of a pedigree that linkage and association programs read. If the drawing shows several conditions or carriers, it writes an MPED file instead, which has a column for each.
The form
- The drawing
- Choose a Pedigree Studio file, or the drawing in the Studio tab.
- Save in, Start of the file name
- The file is called
start.ped or start.mped. It's saved in ~/results unless you choose another folder.
- People are named by
- Choose pedigree numbers (
II-3), the labels the drawing shows, Pedigree Studio's own ids, or the text under the symbols, which is what version 0.1 used.
What it writes
The file has one line per person. Each line gives the family, the person, their father and mother, and their sex: 1 male, 2 female or 0 unknown. Then, for each condition, there's 1 for unaffected or 2 for affected, and in an MPED file 3 for a carrier.
Each condition's column is named after the condition in the colour key, so Hearing loss from birth becomes Hearing_loss_from_birth. An ontology id written after the name is left out, so Condition X [MONDO:0009061] becomes Condition_X. Only an ontology's id is left out, though. Hypertension (BP:160/95) keeps what's in its brackets, as Hypertension_BP16095. The PED and MPED formats has the details.
The father and mother are the genetic parents, because that's how linkage programs read them. An adopted child, joined to a couple by a dashed line, gets 0 in place of those parents, with a note. So does a child carried by a gestational carrier (a parent marked G, or S in drawings made before the 2025 correction to the nomenclature). The Phenopackets Family's pedigree does this too. A donor (D) is a genetic parent, and is written as one.
After writing the file, the tool checks it with mpedtools and shows the result underneath.
By default, people are named by their pedigree numbers, such as II-3, as in the GA4GH files. The other choices can give you names. The text under a symbol is often a name, and a label may be one too. For example, Grace, 78 becomes Grace_78. Check these ids before you share the file. A label is made into an id by turning spaces into underscores and dropping other punctuation, so J. Mensah becomes J_Mensah. studio2ga4gh does the same, so a person has the same id in both tools' files. If two people would share an id, or an id would be empty or 0 (which a PED file reads as “no parent”), the person's pedigree number is used instead, and the tool tells you.
Pedigree Studio stores the no children and infertility bars as children of the couple. They aren't people, so the tool leaves them out, and the notes say which couple had them. Version 0.1 wrote them as children of unknown sex. They have no pedigree number either, in the Studio or here, and don't count in their row.
In the terminal
studio2ped /data/examples/cf-cousins.studio.json -d ~/results -o cf-cousins
mpedtools validate ~/results/cf-cousins.mped
Without -o, the file is named after the drawing, leaving out .studio.json, for example cf-cousins.mped. To use one of the other kinds of id, add --ids drawing, --ids studio or --ids text.
In Python
from studio2ped import convert_file
result = convert_file("/data/examples/cf-cousins.studio.json", output_prefix="cf-cousins", output_dir="/home/user/results")
print(result.summary)
for path, _ in result.files:
print("wrote", path)
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- studio2ped
- Hearn TJ. studio2ped [software]. github.com/comparativechrono/studio2ped
PED or MPED → drawing
ped2studio draws a PED or MPED file in Pedigree Studio, showing the people, their parents and partners, and who is affected.
The form
- The PED file
- Choose a
.ped, .fam or .mped file.
- Save the drawing as
- The drawing is saved as a
.studio.json file, in ~/pedigrees unless you choose otherwise.
- Colour for affected people, Fill, Shade with a pattern
- These set how affected people (status 2) are marked. Choose a colour to fill the whole symbol or its left half, or use stripes or dots instead of a fill. From an MPED file, each condition gets a colour of its own.
- Tidy the drawing when it opens
- When you open the drawing from the result, the Studio lays it out again with Pedigree Studio's Tidy.
What comes out
The drawing shows the founders, couples and their children, generation by generation, and labels each person with their id. In the key, the condition is called Affected. From an MPED file, each condition is named after its column instead. A PED file says nothing about twins, deaths, adoptions or pregnancies, or about what the condition is. Add those in the Studio, and name the condition in the key so that it can be given a term. If one file holds several families, they're drawn side by side. Draw a PED file you have been sent goes through it step by step.
In the terminal
ped2studio /data/examples/lynch.ped ~/pedigrees/lynch.studio.json --colour '#e67e22'
studio --tidy ~/pedigrees/lynch.studio.json
| Option | |
--colour HEX (or --color) | the colour for affected people (default #1a2332) |
--fill full|half | the whole symbol, or its left half |
--shading, --pattern stripes|dots | a pattern instead of a fill |
In Python
from ped2studio import convert_file
session = convert_file("/data/examples/lynch.ped", "/home/user/pedigrees/lynch.studio.json",
affected_color="#e67e22", use_shading=False, shading_pattern="stripes", fill_type="full")
print(len(session["persons"]), "people")
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- ped2studio
- Hearn TJ. ped2studio [software]. github.com/comparativechrono/ped2studio
- Pedigree Studio
- Hearn TJ. Pedigree Studio [software]. Zenodo. doi:10.5281/zenodo.20209376
GA4GH Pedigree ⇄ Phenopackets Family
The two GA4GH files describe the same family in two different ways. This tool turns either one into the other. You might use it, for example, when someone has sent you a file in only one of the forms.
The two forms
| GA4GH Pedigree | Phenopackets Family |
| Who is in it | everyone, each as a Phenopacket | the proband, the relatives with findings, and everyone in its pedigree |
| How they are related | relationships named with KIN terms: parents, donors, adoption, partners, twins, cousins… | a PED-style pedigree: father, mother, sex, affected or not |
| Standard | proposed for the GA4GH Pedigree Standard, still being written | Phenopackets version 2, approved |
When you convert to a Family, you lose the narrative and everything a PED-style pedigree can't say: twins, adoptions, separated couples, and the fact that a parent was a donor rather than a partner. When you convert to a GA4GH Pedigree, the relationships come from the parents in the Family's pedigree. The proband's parents are marked as consanguineous if the Family says so and the pedigree doesn't already show it. The GA4GH Pedigree has the details.
The form
- The file
- Choose a GA4GH Pedigree or a Phenopackets Family.
- Make
- The tool chooses the other form for you.
- Proband
- When you're making a Family, give the id of the person you want as the proband. If you don't, the tool uses the GA4GH Pedigree's index patient, or else the first affected person.
- Save as
- The new file is saved as
~/results/name_phenopackets-family.json or …_ga4gh-pedigree.json.
There are some things that each form can't say:
- If nothing is recorded for a person in the GA4GH Pedigree, they're in the Family's pedigree, but there's no Phenopacket for them among its relatives. Their status in the Family's pedigree is missing (unknown) rather than unaffected. That's because a GA4GH Pedigree records the conditions people have, not that they were found to have none.
- Going the other way, people who have no Phenopacket in the Family come into the GA4GH Pedigree with only their sex and parents. The Family's pedigree doesn't say whether they're alive.
So only convert between the two forms when you need to. It's better to keep both of the files that studio2ga4gh writes than to make one from the other.
In the terminal
phenotk convert /data/examples/okafor_ga4gh-pedigree.json --to family -o ~/results/okafor-again_phenopackets-family.json
phenotk convert /data/examples/okafor_phenopackets-family.json --to pedigree -o ~/results/okafor-again_ga4gh-pedigree.json
pedigree-ga4gh convert FILE --to pedigree|family -o OUT does the same.
In Python
import phenopacket_toolkit as ptk
from phenopacket_toolkit.ops import to_kind
doc = ptk.read("/data/examples/okafor_ga4gh-pedigree.json")
new, notes = to_kind(doc, "family", proband_id="IV-3")
ptk.write(new, "/home/user/results/okafor-again_phenopackets-family.json")
for note in notes:
print("note:", note)
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
- pedigree-ga4gh
- Hearn TJ. pedigree-ga4gh [software]. github.com/comparativechrono/pedigree-ga4gh
- GA4GH Pedigree Standard
- GA4GH Pedigree Standard. Pedigree Standard: documentation, examples and the Kinship Ontology (KIN). pedigree.readthedocs.io
- GA4GH Pedigree Standard. pedigree_family_history_terminology: the Kinship Ontology (KIN), kin.owl. github.com/ga4gh/pedigree_family_history_terminology
- Jacobsen JOB. Pedigree (phenopacket-schema pull request 364, opened 24 November 2022, closed without merging 26 September 2025). github.com/ga4gh/phenopacket-schema/pull/364
- Phenopackets
- Jacobsen JOB, Baudis M, Baynam GS, Beckmann JS, Beltran S, Buske OJ, et al. (2022) The GA4GH Phenopacket schema defines a computable representation of clinical data. Nature Biotechnology 40(6): 817–820. doi:10.1038/s41587-022-01357-4
GA4GH → PED, table or YAML
This tool writes a GA4GH Pedigree, or a Phenopackets Family, Cohort or Phenopacket, in another format. It can make a PED file for linkage programs, a table of people and their terms, YAML, or JSON Lines.
The formats
- A PED file
- The six columns are family, person, father, mother, sex and affected status. It uses the file's ids. In files from studio2ga4gh, these are pedigree numbers such as II-3, unless you chose otherwise. If you make it from a Phenopackets Family, the status is the one its pedigree records: 1 for unaffected, 2 for affected. If you make it from a GA4GH Pedigree, people with a condition get 2 and everyone else gets 0, which means unknown. That's because a GA4GH Pedigree records the conditions people have, not that they were found to have none. Either way, affected means having any of the file's conditions. To make a PED file for one condition out of several, use the other route in Make a PED file for a linkage program.
- A table (TSV)
- The table has a row for each person and term. Each row gives the person's id and their role (proband or relative), and whether the term is a disease or a phenotype. It also gives the term's id and label, and whether it was excluded, which means it was looked for and not found. You can open it in a spreadsheet.
- YAML
- This is the same document, written in YAML instead of JSON.
- JSON Lines
- This puts one Phenopacket on each line, for programs that read many at a time.
In the terminal
phenotk convert /data/examples/okafor_phenopackets-family.json --to ped -o ~/results/okafor.ped
phenotk convert /data/examples/okafor_ga4gh-pedigree.json --to tsv -o ~/results/okafor.tsv
column -t -s "$(printf '\t')" ~/results/okafor.tsv
--to takes ped, tsv, yaml, jsonl and json, as well as family or pedigree for the other GA4GH form. phenotk ped FILE also writes the PED file.
In Python
import phenopacket_toolkit as ptk
from phenopacket_toolkit.ops import to_format
doc = ptk.read("/data/examples/okafor_phenopackets-family.json")
print(to_format(doc, "ped"))
print(to_format(doc, "tsv"))
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
Picture → PED file and drawing
PedInterp reads a picture of a pedigree, such as one in a paper, a clinic letter or a scan, or one sketched by hand, and writes it as a PED file and a Pedigree Studio drawing, and as a GA4GH Pedigree if you ask. It finds the symbols and the lines between them, and so who is male or female, who is affected, who are partners, parents and children, and which children are twins, and, if you ask, who has died, the proband and carriers. So a pedigree sketched in a hurry, with the Studio's Draw tool or on paper, becomes a drawing you can carry on with in the Studio.
The form
- The picture
- A PNG or JPEG file, or a GIF, BMP, TIFF or WebP picture. From my computer… adds one of your own, in
~/pictures.
- Drawn by hand
- Tick it for a pedigree sketched by hand, in whole or in part: with Pedigree Studio's Draw tool, say, or begun with the Studio's symbols and finished with the Draw tool, or drawn on paper and scanned. PedInterp then allows for symbols of unequal sizes, outlines that don't quite close or that run on past where they began, symbols filled in by scribbling, and lines that wobble and stop short of what they join or run a little past it. Leave it unticked for a picture drawn with software, such as one Pedigree Studio saves, which reads more surely so. If PedInterp warns that lines may have been missed in a picture read without it, and says the pedigree may be drawn by hand, try again with it ticked.
- Read who has died, the proband and carriers
- Tick it to read three of the marks drawn on the symbols as well as their shapes and fills: a slash through the symbol of someone who has died, an arrow pointing at the proband's symbol from below on the left, and a dot in the middle of a carrier's symbol. A PED file can't hold them, so with it ticked no PED file is written: tick Make a Pedigree Studio drawing too or Write a GA4GH Pedigree too, or both, to keep them. The table shown has a column for each, True or False. See Who has died, the proband and carriers, below.
- Family id
- The family's id in the PED file, which also names the files. It starts as the picture's name.
- Save in
- The folder for the files:
~/results, unless you choose another.
- Enlarge the picture by
- Leave it empty, as it is, and PedInterp chooses: it finds the symbols in a copy of the picture 2,000 pixels across, and enlarges the picture so that they are about 200 pixels across, which reads best (100 for a sketch, about the size the Studio draws them at). A line under the table says how much it enlarged it: 5.6 times for the Lynch family's picture, which is about 1,000 pixels across, and more for a smaller picture, less for a larger one or a scan. There is some room either side: the Lynch picture reads correctly at anything from 4 to 12 times, but not at 3 or 15. If PedInterp warns that a line may have been missed, give a number a little larger or smaller than the one it chose: smaller, if the lines are very thick. It warns, too, if the picture is too small to enlarge enough, or a page too large, which reads better cut down to the pedigree.
- Make a Pedigree Studio drawing too
- It starts ticked. The family as a Pedigree Studio drawing,
FAMILY.studio.json, beside the PED file (or, with the marks read, without one), to open in the Studio tab (Open the drawing in Studio, under the result) and carry on with: put right anything misread, add names, deaths and adoptions, and save it. It is laid out as the picture is: each row of symbols is a generation, at the Studio's spacing, and everyone keeps their place, so the drawing looks like the picture, tidied. A sketch drawn small or crowded is spread out, so that the Studio's numbers have room, and the Studio's Tidy lays it out afresh if you'd rather. The drawing has what a PED file can't hold: twins, identical or not, joined as the Studio joins them, and couples who have no children. A pregnancy that was lost is the Studio's triangle, and couples who are related, such as cousins who marry, get the Studio's double line. The affected are filled in, and the colour key says Affected, or names the condition if you give one. With Read who has died, the proband and carriers, the drawing has the slashes, the proband's arrow and the carriers' dots too.
- Write a GA4GH Pedigree too
- The family as a GA4GH Pedigree,
FAMILY_ga4gh-pedigree.json, beside the PED file (or without one), which ga4gh2studio, the phenopacket toolkit, PedNet and the Risk tab read. The affected people have the condition, and the unaffected have it marked as looked for and not found. It records the twins too, and with Read who has died, the proband and carriers, who has died and who is alive, the proband, as its index patient, and in its narrative, who is a carrier (see below). The file notes which picture the family was read from, and how much it was enlarged.
- The condition's ontology term, and its name
- Shown when the drawing or the GA4GH Pedigree is ticked: the condition the pedigree is about, such as
MONDO:0007254 and breast cancer. The GA4GH Pedigree gives it to the affected, and the drawing's colour key names it with its term, breast cancer [MONDO:0007254], as ga4gh2studio names it, so that the drawing converts back to the same term (Drawing → GA4GH Pedigree and Phenopackets). Leave them empty for MONDO:0000001, disease, in the GA4GH Pedigree, and Affected in the colour key.
What it reads
PedInterp reads pedigrees drawn in the usual way, dark on white: squares, circles and diamonds, filled in for the people who are affected, with each generation in a row of its own. It follows the lines between partners, down from partners to their children, and over a family of brothers and sisters. A slash through a symbol, for someone who has died, doesn't usually stop it reading the symbol, though a slash at an odd angle can make it mistake the person's sex; and only if you ask does it read the slash itself (see Who has died, the proband and carriers, below). The father is the male partner and the mother the female one, whichever side each is drawn on. Pedigree Studio's numbers over the symbols, in grey, are taken out before the lines are read, even where they touch a line.
Twins are two children whose lines come down from one point, and identical twins have a bar across between the two lines. A PED file has no place for twins, so the PED file leaves them out, and so does the table shown when the tool has run, which is the PED file's (with a column for each mark, when they are read). The drawing and the GA4GH Pedigree record them, as Pedigree Studio's files do. The Okafor family has identical twins, IV-3 and IV-4.
With Drawn by hand, PedInterp reads pedigrees sketched roughly, as testers in a clinic sketch them with the Studio's Draw tool: in any colour, with symbols of unequal sizes, filled in with scribbles, and lines that wobble. Of 48 sketches made with the Draw tool by a program that imitates a hand, for testing, it read 40 exactly right, 445 of their 459 people right, and 20 of their 23 pairs of twins; of 24 pictures drawn with the Studio's symbols, it read every person and every pair of twins right. Twins are what it most often gets wrong in a sketch, as the bar of identical twins is short and drawn close to the other lines, and a line drawn close beside a symbol filled in with scribbles can be taken for part of it. The Okafor sketch here is one it reads right.
Some things aren't read yet: symbols that are half filled or shaded (as they sometimes are for carriers), and dashed lines. A PED file has no place for deaths, twins or adoptions anyway. So compare what PedInterp read with the picture before you use it, and a sketch most of all. The drawing is the quickest way: under the result, Open the drawing in Studio shows it laid out as the picture is, where anything misread is easy to see and to put right. If you put something right, make the PED file again from the drawing with Drawing → PED or MPED. Without the drawing, Draw it makes one from the GA4GH Pedigree, if you wrote one (GA4GH or Phenopackets → drawing), or from the PED file (PED or MPED → drawing), laid out afresh.
Who has died, the proband and carriers
With Read who has died, the proband and carriers ticked, PedInterp reads three marks on the symbols:
- A slash through the symbol, rising to the right, for someone who has died. In a symbol left empty, it is seen inside the symbol. A symbol filled in hides the slash, so there it is read from where it runs out past the symbol at both ends, as a slash drawn by hand usually does, and as the Studio draws one through a circle or a diamond. The Studio draws the slash through a filled square from corner to corner, inside it, where it can't be seen, so that one isn't read.
- An arrow pointing at the proband's symbol from below on the left, with its head by the symbol, as the Studio draws it. Drawn by hand, it reads best drawn clear of the lines.
- A dot in the middle of a carrier's symbol, thicker than the lines: dark in a symbol left empty, and white in one filled in, as the Studio draws it. A dot can't be seen in a symbol scribbled in.
Other marks aren't read: the upright line of a presymptomatic carrier, the letters the Studio writes in a symbol (P, D and S), which aren't taken for a dot, the brackets round someone adopted, and what is written beside a symbol, such as an age or a cause of death. The Okafor family's picture, as the Studio saves it, reads with its five deaths and its proband (Chidi, IV-3), among the names and ages written under the symbols, and so does the sketch of it, with Drawn by hand.
The marks were tested on 192 pedigrees drawn with the Studio and its Draw tool, a quarter with its symbols alone, a quarter begun with them and finished by hand, and half sketched throughout. Of the Studio's own marks, PedInterp found every death that can be seen (121; the other 19 were slashes through filled squares), every proband (54) and every carrier (92). Of the marks drawn by hand, it found 226 of 253 deaths, 127 of 130 carriers, and 66 of 102 probands: in the sketches, 44 of 53 arrows drawn clear of the other lines, but only 8 of 30 that crossed or touched another line or the end of a slash. It read no mark where none was drawn, and the rest of each pedigree as well as it reads the same pedigree drawn without the marks. (These counts leave out the people in a generation read with a person too many or too few, whose numbers then don't match those drawn: 62 of the 1,969.) Nor does it take a symbol shaded with the Studio's dots, or specks in a poor scan, for one with a slash.
A PED file can't hold the marks, so with them ticked, the tool writes no PED file: only the drawing, the GA4GH Pedigree or both, as you tick them. The drawing has the marks as the Studio draws them, and the GA4GH Pedigree as Drawing → GA4GH Pedigree and Phenopackets writes them: the proband as the index patient, who is a carrier in its narrative, and each person's vital status. Someone has died if a slash was read through their symbol, or if it is a triangle, for a pregnancy lost, and is alive if their symbol is left empty with no slash through it. A symbol filled in may hide a slash, as it hides the Studio's through a filled square, so the GA4GH Pedigree gives no vital status for the affected unless a slash was seen.
Who is who
On a computer of your own, PedInterp reads the labels under the symbols with the Tesseract program. A browser can't run Tesseract, so here the people are numbered by generation instead: from the top, and from the left in each generation, I-1, I-2, II-1 and so on. Pedigree Studio numbers people in the same way, and shows the numbers over the symbols in the drawing. The picture of the Lynch family was drawn where the Studio draws the family, so its numbers are the same as those in the Lynch PED file, and the PED file that PedInterp writes is the same as that one, apart from the family's id. The two pictures of the Okafor family read as the people, parents and sexes of okafor.mped, with those who have either of its conditions affected, as a picture shows who is affected but not by what.
In the terminal
pedinterp /data/examples/lynch.png --labels none -d ~/results
diff <(cut -f2- ~/results/lynch.ped) <(cut -f2- /data/examples/lynch.ped) && echo "the same people, parents, sexes and status"
pedinterp /data/examples/okafor-sketch.png --hand-drawn -f OKAFOR -d ~/results --studio --ga4gh
studio ~/results/OKAFOR.studio.json
pedinterp /data/examples/okafor-sketch.png --hand-drawn --marks -f OKAFOR_MARKED -d ~/results --studio
The second pair read the Okafor sketch, write the PED file, the drawing and the GA4GH Pedigree, and open the drawing in the Studio tab. The last reads who has died and the proband too, and writes the drawing only. What pedinterp prints is the PED file's table, as it is in the file, or with --marks the same with a column for each mark, then how much the picture was enlarged and the files it wrote.
| Option | |
-f, --family ID | the family id, which names the files (default: the picture's name) |
-d, --output-dir FOLDER | where to write the files (default: the folder you're in) |
--hand-drawn | the pedigree is sketched by hand, in whole or in part (Drawn by hand) |
--marks | read who has died, the proband and carriers too (Read who has died, the proband and carriers). No PED file is written, as it can't hold them, so give --studio, --ga4gh or both |
--upscale FACTOR | how many times to enlarge the picture (by default, as many as its symbols need: the table says how many) |
--studio | also write the family as a Pedigree Studio drawing, FAMILY.studio.json, laid out as the picture is (Make a Pedigree Studio drawing too, which the Tools tab ticks for you) |
--ga4gh | also write the family as a GA4GH Pedigree, FAMILY_ga4gh-pedigree.json |
--condition ID LABEL | with --studio or --ga4gh, the condition, as an ontology term and its name (default: MONDO:0000001 disease in the GA4GH Pedigree, and Affected in the drawing's colour key) |
--labels tesseract|none | read the labels with Tesseract, or number the people (by default, Tesseract, but not for a sketch, whose labels are written by hand). Here the people are numbered either way, but with none there's no warning that Tesseract isn't there. |
-q, --quiet | don't print the table |
In Python
from PedInterp import pedigree_processing, PED_export, Studio_export
df = pedigree_processing("LYNCH", image_path="/data/examples/lynch.png", ocr=None)
print(df.to_string(index=False))
print("wrote", PED_export(df, "/home/user/results"))
sketch = pedigree_processing("OKAFOR", image_path="/data/examples/okafor-sketch.png", ocr=None, hand_drawn=True)
print("wrote", Studio_export(sketch, "/home/user/results")) # OKAFOR.studio.json, with its identical twins
print(sketch.attrs["twins"]) # [["IV-3", "IV-4", "MZ"]]: MZ for identical twins, DZ for twins who aren't
marked = pedigree_processing("OKAFOR", image_path="/data/examples/okafor-sketch.png", ocr=None, hand_drawn=True,
marks=True)
print(marked[["IndividualID", "Deceased", "Proband", "Carrier"]].to_string(index=False))
ocr=None numbers the people, hand_drawn=True reads a sketch, and marks=True reads who has died, the proband and carriers, in the columns Deceased, Proband and Carrier: PED_export refuses such a table, and Studio_export and GA4GH_export write it. Besides the twins, attrs holds the couples PedInterp found (attrs["partners"]) and where each person was drawn (attrs["layout"]), which Studio_export lays the drawing out by. Studio_export takes a condition as condition=("MONDO:0007254", "breast cancer"), as GA4GH_export does. ocr can also be a function that reads the labels with other OCR, such as tesseract.js in a web page: PedInterp's README explains how.
PedInterp needs NumPy, pandas, OpenCV and Pillow, which Python downloads the first time you use it. That is about 21 MB, or less if PedNet or PedGen has already run, and your browser keeps them for next time.
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- PedInterp
- Taylor N. PedInterp [software]. github.com/comparativechrono/pedigree-interpreter
Match conditions to terms
This tool finds the ontology term for each condition in a drawing's colour key: a Mondo term for a disease, or an HPO term for a sign or symptom. It keeps your choices in a terms file, which Drawing → GA4GH reads. It uses the same searches as hponorm and mondonorm.
On the page
- 1 · The drawing
- The drawing's conditions are listed under 3, with the number of people who have each one. Start from a terms file fills in the conditions that the terms file already has, and the matches you make are added to it when you save.
- 2 · Search in
- Choose EBI's Ontology Lookup Service, which is online and has the latest releases, or copies of the ontologies on this computer, which work offline. For the copies, choose
hp.obo and mondo.obo from your files. You can download the HPO from here into ~/ontologies. For Mondo, download its file with your browser from Mondo's download page, then add it with From my computer….
- 3 · The conditions
- Each condition has a menu to choose a disease (Mondo) or a sign or symptom (HPO), a box for the words to search for, and a Suggest button. The tool guesses which kind it is from the name, so check it. You get up to six suggestions, each with its id and label, a score out of 100 for how well it matches, and the definition. Each also says what your words matched: the term's label, or one of its synonyms. Choose one, or type an id and press Use this id. Suggest terms for all searches for every condition that hasn't been matched yet.
- 4 · Keep the matches
- Save writes the terms file,
~/terms/drawing-terms.json. If you tick Also write the ids into the drawing's colour key, it also writes a copy of the drawing, ~/pedigrees/drawing-with-terms.studio.json. In the copy, the key has entries such as Breast cancer [MONDO:0007254]. Next opens Drawing → GA4GH with the drawing and the terms file already chosen.
What is sent where
If you use EBI's service, the words you search for and the ids you type are sent to EBI (www.ebi.ac.uk). Nothing else is sent, not even the drawing. If you use copies on this computer, nothing is sent anywhere. Downloading the HPO here fetches hp.obo from the HPO's repository on GitHub.
Good to know
- The first search of a local file reads the whole file, which takes a few seconds for the HPO and longer for Mondo. The local search can miss terms that EBI's service would find, so if the term you expect is missing, try other words.
- Each term's release is recorded with it in the terms file, and goes into the GA4GH files'
metaData. That way, anyone can tell which version of the ontology the term came from.
- If you type an id, the tool looks it up if it can. If it can't, because there's no copy of that ontology here or EBI doesn't answer, the id is used as you typed it. It's labelled with the condition's name, and the release is left out.
- If the key itself already has an id, as in Condition X [MONDO:0009061], that condition counts as matched.
Give the conditions ontology terms walks you through it, with advice on choosing a term.
In Python
There's no command for this page. hponorm and mondonorm work on GA4GH and Phenopackets files, and ask about each name as they go. You can't answer their questions in the terminal, so there they take their answers from a file. You can use their searches in a notebook:
from hponorm.hpo import HpoIndex # a copy of the HPO on this computer
index = HpoIndex.load("/home/user/ontologies/hp.obo", allow_download=False)
for c in index.search("hearing loss from birth", limit=6):
print(c.id, c.label, c.score)
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- hponorm
- Hearn TJ. hponorm [software]. github.com/comparativechrono/hponorm
- mondonorm
- Hearn TJ. mondonorm [software]. github.com/comparativechrono/mondonorm
- Human Phenotype Ontology
- Give the release you used, too (the terms file records it).
- Gargano MA, Matentzoglu N, Coleman B, Addo-Lartey EB, Anagnostopoulos AV, Anderton J, et al. (2024) The Human Phenotype Ontology in 2024: phenotypes around the world. Nucleic Acids Research 52(D1): D1333–D1346. doi:10.1093/nar/gkad1005
- Mondo Disease Ontology
- Give the release you used, too (the terms file records it).
- Vasilevsky NA, Matentzoglu NA, Toro S, Flack JE, Hegde H, Unni DR, et al. (2022) Mondo: unifying diseases for the world, by the world. medRxiv 2022.04.13.22273750. doi:10.1101/2022.04.13.22273750
Fill in missing terms
This tool gives an ontology id to every disease and phenotype in a GA4GH or Phenopackets file that has a name but no id. It takes the id from a terms file, or looks the name up. It also writes the file in the standard form, with the ontology resources that its terms need.
The form
- The file
- Choose a GA4GH Pedigree, or a Phenopackets Family, Cohort or Phenopacket. A file from an older tool must be upgraded first.
- Terms file
- Choose a file of names and their terms (terms files). Capital letters don't matter when the names are matched. The releases in the terms file are recorded in the new file's resources.
- Look up names without a term
- Choose No to use only the terms file, or look names up on EBI's Ontology Lookup Service, which is online, or in copies of the ontologies on this computer. For the copies, choose
hp.obo and mondo.obo.
- Accept a looked-up match from
- This is the lowest score, from 0.5 to 1, at which a term the tool finds is used. A term's own name scores 1 and one of its synonyms 0.98, ignoring capital letters and punctuation, and any other name scores less. So the default, 0.98, only accepts a term whose own name or synonym is the condition's name. Match conditions to terms shows the same scores out of 100. If a name's best match is less close than that, it's left without a term and listed. Entries in a terms file are always used.
- Save as
- The new file is saved as
~/results/name.normalised.json. A log of every decision goes next to it, as ….normalised.log.json.
By default, the tool doesn't guess. If neither the terms file nor a look-up finds a term for a name, its id stays empty and the summary lists it. You can lower the threshold to accept close matches as well, but each of those is a guess, and the log asks you to check it. Names that are spelt almost alike can mean opposite things. For example, Maternal hypothyroidism is not Maternal hyperthyroidism. Look at the log before you rely on a looked-up match.
Each term goes where its kind belongs. Older tools wrote every condition as a disease, so a “disease” that's given an HPO term, such as Hearing loss from birth (HP:0000365), moves to the phenotypic features. In the same way, a phenotype that's given a Mondo term moves to the diseases. The summary notes each move.
In the terminal
pedigree-ga4gh upgrade /data/examples/older/studio2ga4gh-0.3_phenopackets-family.json -o ~/results/older.json
phenotk normalise ~/results/older.json --mapping /data/examples/example-terms.json --no-online --log ~/results/older.log.json -o ~/results/older.normalised.json
pedigree-ga4gh validate ~/results/older.normalised.json
| Option | |
--mapping FILE | a terms file, or the log of an earlier run |
--no-online | use the terms file only, with no look-ups |
--backend ols|local, --hpo-file, --mondo-file, --threshold | where to look names up, and the lowest score to accept (by default 0.98, which means the term's own name or a synonym) |
--terms-only, --structure-only | only fill in terms, or only tidy the structure |
--log FILE, -o FILE, --in-place | where the log and the new file go |
In Python
import json
import phenopacket_toolkit as ptk
from phenopacket_toolkit.ops import normalise
doc = ptk.read("/home/user/results/older.json")
mapping = json.load(open("/data/examples/example-terms.json"))
new, log = normalise(doc, mapping=mapping, use_ontology=False)
ptk.write(new, "/home/user/results/older.normalised.json")
print(log.summary())
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
- hponorm
- Hearn TJ. hponorm [software]. github.com/comparativechrono/hponorm
- mondonorm
- Hearn TJ. mondonorm [software]. github.com/comparativechrono/mondonorm
Check against the standard
This tool checks a GA4GH Pedigree, or a Phenopackets Family, Cohort or Phenopacket. For each problem it finds, it tells you what the problem is, where it is in the file and how to fix it. It works from the file alone, without needing Java or an internet connection.
What is checked
The phenopacket-tools rules
phenopacket-tools is the validator for Phenopackets written by the team behind the Phenopackets schema. This check applies the same rules:
- The Phenopackets version 2 schema: which fields each part must have and which it may have, their types, the values allowed (for sex, vital status, progress status …), groups of fields where exactly one must be given, and minimum lengths and counts. A field that isn't in the schema is an error, because programs that read Phenopackets reject it.
- The ontologies: every term's id must be a CURIE (
PREFIX:ID), and every prefix used must be declared among the resources in the file's metaData, with all six of the resource's fields filled in. phenopacket-tools treats an empty field as a missing one.
- Values: ages must be ISO 8601 durations (
P45Y), and dates and times must be in the right form.
And for a GA4GH Pedigree
- Every id in the relationships and the index patients must refer to the subject of one of the individuals, and no two individuals may share an id.
- Every relation must be a current KIN term, written with KIN's own label. Retired codes from earlier drafts of KIN are reported.
- No one may be related to themselves. A biological mother must be female, and a father male. No one may have more than two genetic parents, or be their own ancestor.
And for a Family
- Everyone with a Phenopacket, whether the proband or a relative, must be in the pedigree. No one may be in it twice or have two Phenopackets.
- Every father and mother named in the pedigree must also be a person in it. A father mustn't be recorded as female, or a mother as male. No one may be both someone's father and their mother, or be their own ancestor.
- No one's id may be
0, which a PED file uses for “no parent”. If someone had that id, their children would read as having no parent.
And one mistake in older files
HP:0032500 used for a carrier. It's a real HPO term, so it's valid in form, but it means Exacerbated by tobacco use.
The check doesn't look terms up, so it can't tell whether a term is the right one for the person. It can only tell you that the term is well formed and declared.
The result
You'll see Valid or Not valid, then a line for each finding. An error means the file is invalid, a warning means something is allowed but probably a mistake, and a note is for information. Each finding has a code, such as empty-term-id, its place in the file, and how to fix it. If a file comes from an older tool, the check recognises this and gives you a button to upgrade it. Check a GA4GH file, or update an old one lists the commonest findings and their fixes.
In the terminal
pedigree-ga4gh validate /data/examples/okafor_phenopackets-family.json
pedigree-ga4gh validate --json /data/examples/older/abusua2ga4gh-0.2_phenopackets-family.json | head -20
The exit status is 0 for a valid file and 1 for an invalid one. --json prints the findings as JSON. phenotk validate FILE runs the same checks on a file in the standard form. It refuses a file from an older tool, with a message telling you to upgrade it.
In Python
import pedigree_ga4gh as pg
doc = pg.load("/data/examples/okafor_ga4gh-pedigree.json")
findings = pg.validate(doc)
print(pg.render_findings(findings))
print("valid" if pg.is_valid(findings) else "not valid")
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- pedigree-ga4gh
- Hearn TJ. pedigree-ga4gh [software]. github.com/comparativechrono/pedigree-ga4gh
- phenopacket-tools (the Phenopackets team's validator)
- Danis D, Jacobsen JOB, Wagner AH, Groza T, Beckwith MA, Rekerle L, et al. (2023) Phenopacket-tools: building and validating GA4GH Phenopackets. PLoS ONE 18(5): e0285433. doi:10.1371/journal.pone.0285433
- Phenopackets
- Jacobsen JOB, Baudis M, Baynam GS, Beckmann JS, Beltran S, Buske OJ, et al. (2022) The GA4GH Phenopacket schema defines a computable representation of clinical data. Nature Biotechnology 40(6): 817–820. doi:10.1038/s41587-022-01357-4
- GA4GH Pedigree Standard
- GA4GH Pedigree Standard. Pedigree Standard: documentation, examples and the Kinship Ontology (KIN). pedigree.readthedocs.io
- GA4GH Pedigree Standard. pedigree_family_history_terminology: the Kinship Ontology (KIN), kin.owl. github.com/ga4gh/pedigree_family_history_terminology
- Jacobsen JOB. Pedigree (phenopacket-schema pull request 364, opened 24 November 2022, closed without merging 26 September 2025). github.com/ga4gh/phenopacket-schema/pull/364
Upgrade a file from an older tool
Earlier versions of our tools, studio2ga4gh up to 0.3 and abusua2ga4gh up to 0.2, wrote GA4GH files that the standard doesn't accept. The upgrade rewrites a file like this once, in the standard form, and lists every change it made and everything it couldn't do. It tidies up other non-standard files too.
What it changes
- The form. The GA4GH Pedigree from studio2ga4gh 0.3 was the conceptual model written out as JSON. The upgrade turns it into one Phenopacket per person, with the relationships in the standard form.
- What the standard has no place for. Names are removed, because Phenopackets have no field for a name, and names are personal data. Diseases inside
subject are moved to the Phenopacket, and notes on relationships go into the narrative.
- metaData. The upgrade adds it where it's missing, with
phenopacketSchemaVersion and a resource for every ontology the terms use.
- KIN. Retired codes are replaced by the current ones, and the two people are swapped where the new term runs the other way. Labels are corrected. If a relation's code and label disagree, the label decides. For example, abusua2ga4gh's
KIN:039 isSpermDonorOf becomes KIN:004.
- Carriers. Where the phenotypic feature
HP:0032500 was written for a carrier, it's removed, because it means Exacerbated by tobacco use. In a GA4GH Pedigree, the narrative then says who is a carrier.
- Field names in proto spelling are rewritten in camelCase, the way JSON spells them, so
index_patients becomes indexPatients.
What it leaves to you
Under to do, the upgrade lists the things that only a person can decide:
- Conditions that have a name but no term. Fill in missing terms gives them their terms.
- Carriers in a Phenopacket or a Family. Phenopackets have no field for carrier status, and the only structured place for it is a genomic interpretation of the variant, if the variant is known. You can add one with
phenotk add --variant in the terminal (Add findings to people).
- Foster and social parents that abusua2ga4gh wrote as adoptive parents. Only the relationship's note tells them apart.
- The conditions in a GA4GH Pedigree from studio2ga4gh 0.3. That file records who was affected, but not by what, so convert the drawing again, or use the Phenopackets file that was made with it.
The upgrade never guesses. A file that's already standard comes back unchanged, apart from its field names. Under the result, Check the upgraded file runs the check on the new file.
A file that follows the draft of version 1 of the standard isn't an older file. It's in a newer form, which hasn't been approved (see The GA4GH Pedigree). The upgrade tells you this and leaves the file alone.
In the terminal
pedigree-ga4gh upgrade /data/examples/older/abusua2ga4gh-0.2_phenopackets-family.json -o ~/results/abusua_phenopackets-family.json
pedigree-ga4gh validate ~/results/abusua_phenopackets-family.json
phenotk upgrade FILE -o OUT does the same.
In Python
import pedigree_ga4gh as pg
doc = pg.load("/data/examples/older/abusua2ga4gh-0.2_phenopackets-family.json")
new, changes, todo = pg.upgrade(doc)
pg.dump(new, "/home/user/results/abusua_phenopackets-family.json")
for c in changes:
print("changed:", c)
for t in todo:
print("to do:", t)
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- pedigree-ga4gh
- Hearn TJ. pedigree-ga4gh [software]. github.com/comparativechrono/pedigree-ga4gh
- GA4GH Pedigree Standard
- GA4GH Pedigree Standard. Pedigree Standard: documentation, examples and the Kinship Ontology (KIN). pedigree.readthedocs.io
- GA4GH Pedigree Standard. pedigree_family_history_terminology: the Kinship Ontology (KIN), kin.owl. github.com/ga4gh/pedigree_family_history_terminology
- Jacobsen JOB. Pedigree (phenopacket-schema pull request 364, opened 24 November 2022, closed without merging 26 September 2025). github.com/ga4gh/phenopacket-schema/pull/364
- Phenopackets
- Jacobsen JOB, Baudis M, Baynam GS, Beckmann JS, Beltran S, Buske OJ, et al. (2022) The GA4GH Phenopacket schema defines a computable representation of clinical data. Nature Biotechnology 40(6): 817–820. doi:10.1038/s41587-022-01357-4
Look inside a GA4GH file
This tool shows you a GA4GH Pedigree, or a Phenopackets Family, Cohort or Phenopacket, without its JSON. You can see a table of the people and their terms, or the numbers of people, terms and relationships. It's the quickest way to see that a file says what you meant.
What it shows
- A table of the people and their terms
- There's a line for each person, with
* marking the proband. Each line gives the person's id, sex, affected status, deceased if they have died, and their terms. For a GA4GH Pedigree, the relationships follow in words, such as III-2 isBiologicalFatherOf IV-3. For a Family, the people in its pedigree who have no Phenopacket are listed at the end.
- Counts
- You'll see the number of people, by sex and by affected status, and the numbers of phenotypic features and diseases, with how many of the features are excluded. You'll also see how many terms still have no id, and which terms are the commonest. For a GA4GH Pedigree, the relationships are counted too, kind by kind.
In a GA4GH Pedigree, the affected status is MISSING for everyone without a term. This is because the file records the conditions people have, not that anyone was found to have none.
In the terminal
phenotk view /data/examples/okafor_ga4gh-pedigree.json
phenotk stats /data/examples/okafor_phenopackets-family.json
In Python
import phenopacket_toolkit as ptk
from phenopacket_toolkit.ops import render, stats, render_stats
doc = ptk.read("/data/examples/okafor_phenopackets-family.json")
print(render(doc))
print(render_stats(stats(doc)))
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
Compare two files
This tool lists what differs between two GA4GH or Phenopackets files, for example in their people, terms and relationships. It ignores the order of things. It also ignores when and by whom the files were made, because that changes every time a file is written.
In the later version, the twins' hearing loss has been found to be sensorineural, so each has a second phenotype.
When to use it
- To see what a conversion changed, by comparing a file with the same file converted to the other form and back.
- To see what's new in a second version of a family's file.
- To check that a de-identified or filtered file lost only what it should have.
Reading the result
You'll see a line for each difference, with its place in the files, such as proband.phenotypicFeatures: length 1 != 2, pedigree.persons[3].affectedStatus: 'UNAFFECTED' != 'MISSING' or narrative: only in A. Where a line gives two values, the one from the first file comes first. If you compare two different kinds of file, for example a Family with a GA4GH Pedigree, nearly everything is listed, because they're laid out differently. So compare like with like. If you tick Count differences of order and of provenance too, the tool compares everything exactly as it's written in the files.
The exit status is 0 when the files are the same and 1 when they differ, as with diff.
In the terminal
phenotk diff /data/examples/okafor_phenopackets-family.json /data/examples/okafor-later_phenopackets-family.json
phenotk convert /data/examples/okafor_ga4gh-pedigree.json --to family -o ~/results/okafor-from-pedigree.json
phenotk diff /data/examples/okafor_phenopackets-family.json ~/results/okafor-from-pedigree.json
The second comparison shows what a Family made from the GA4GH Pedigree lacks. It doesn't say who was found to be unaffected, because the GA4GH Pedigree never recorded that.
--format json writes the differences as JSON, and --strict is the same as ticking the box above.
In Python
import phenopacket_toolkit as ptk
from phenopacket_toolkit.ops import diff, render_diff
a = ptk.read("/data/examples/okafor_phenopackets-family.json")
b = ptk.read("/data/examples/okafor-later_phenopackets-family.json")
print(render_diff(diff(a, b)))
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
De-identify
This tool makes a copy of a GA4GH or Phenopackets file for sharing. Everyone gets a new id, which is used consistently everywhere in the file. Dates of birth and other ids are taken out, and you can also hide who made the file. You can keep the key from the old ids to the new ones in a separate file.
The form
- New ids
- Choose IND-0001, IND-0002 … to number the people in the order they come in the file. With codes made from the old ids (such as
IND-3f9a1c2b7d40), a person gets the same code in every file, as long as you use the same secret. This means you can follow the same person across files without their id. Or you can keep the ids as they are.
- Secret for the codes
- Use any words you like, and keep them private. Without a secret, anyone who has the old ids could make the codes again, and so match each code to its old id.
- Keep dates of birth, Ages
- Dates of birth are taken out unless you choose to keep them. You can put the age at the last encounter into bands of 5 or 10 years. For example, in 5-year bands, 47 becomes 45. Ages of onset aren't changed.
- Keep other ids
- A person's other ids (
alternateIds, such as a hospital number) are taken out unless you choose to keep them.
- Hide who made the file and when
- The
metaData has to say who made the file and when. So instead of the original createdBy and created, it says phenotk deidentify and the time of the de-identification. The record of updates and submittedBy are taken out.
- Save the key as
- This is a JSON file of old id → new id. Keep it apart from the shared file, because with it, anyone can follow the new ids back to the old ones.
What changes in the file
- The ids change everywhere: in each Phenopacket and its subject, the relationships, the index patient, a Family's pedigree, biosamples, genomic interpretations and files.
- The ids in a GA4GH Pedigree's narrative change too. For example, proband IV-3 becomes proband IND-0014. The narrative is free text, so read it before you share the file. The tool reminds you to do this. If some of the ids are bare numbers, the tool can't tell them from other numbers in the text, so it leaves the narrative unchanged and warns you.
- Nothing else changes. Terms, sexes, relationships and the shape of the family stay as they were.
De-identified is not anonymous
De-identifying removes what the file says directly. But a family can still be recognised from what's left, such as a rare condition, a large or unusual family, people's ages or where it came from. Someone who knows the family is especially likely to recognise it. It's for you to judge whether a file can be shared, and with whom, under your institution's rules and the law on patient data.
In the terminal
phenotk deidentify /data/examples/okafor_ga4gh-pedigree.json -o ~/results/okafor.deidentified.json --keyfile ~/results/okafor.key.json
phenotk view ~/results/okafor.deidentified.json
| Option | |
--remap-ids seq|hash, --keep-ids, --salt TEXT | the new ids |
--keep-dob, --bin-age 5y|10y, --keep-names, --drop-provenance | what is kept |
--keyfile FILE | where the key goes |
In Python
import json
import phenopacket_toolkit as ptk
from phenopacket_toolkit.ops import deidentify
doc = ptk.read("/data/examples/okafor_ga4gh-pedigree.json")
res = deidentify(doc, remap_ids="seq")
ptk.write(res.document, "/home/user/results/okafor.deidentified.json")
json.dump(res.crosswalk, open("/home/user/results/okafor.key.json", "w"), indent=2)
for w in res.warnings:
print("warning:", w)
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
Keep some people or terms
This tool makes a smaller file from a GA4GH or Phenopackets file. It can keep only the proband, only the affected people, one sex or the people you name, or only some terms. Use it to share no more than is needed.
The form
- People, Sex, Only these people
- Choose which people to keep: everyone, the proband or the affected people. You can also keep only one sex. If you list ids, one per line, only those people are kept.
- Only these terms
- List term ids (CURIEs), one per line. Each person then keeps only those of their terms that are on the list.
- Of the terms
- Keep both observed and excluded terms, only the observed ones, or only the ones that were looked for and not found.
- Reverse
- Drop what matches, instead of keeping it.
- Tidy the pedigree
- For a Phenopackets Family, this also removes from its pedigree the people who've been left out, with every line to them, so that the file stays valid. Relatives in the pedigree who never had a Phenopacket stay in it. In a GA4GH Pedigree, relationships and index patients that name someone who's been left out are always dropped.
The ids you list are written to a small file next to the result (…-ids.txt), and the command reads them from there. To send one person's findings without the rest of the family, use One file for each person instead, because a Family always carries its pedigree.
In the terminal
phenotk filter /data/examples/okafor_ga4gh-pedigree.json --affected --prune-pedigree -o ~/results/okafor.affected.json
phenotk filter /data/examples/okafor_ga4gh-pedigree.json --term HP:0000365 -o ~/results/okafor.hearing.json
phenotk view ~/results/okafor.affected.json
Other options are --proband-only, --sex FEMALE|MALE, --id-list FILE, --observed, --excluded and --invert. There's also --include-descendants, which uses a copy of the ontology (--hpo-file, --mondo-file) to keep the terms under a term as well.
In Python
import phenopacket_toolkit as ptk
from phenopacket_toolkit.ops import filter_document
doc = ptk.read("/data/examples/okafor_ga4gh-pedigree.json")
new = filter_document(doc, affected_only=True, prune_pedigree=True)
ptk.write(new, "/home/user/results/okafor.affected.json")
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
One file for each person
This tool splits a Phenopackets Family, a Cohort or a GA4GH Pedigree into a separate Phenopacket for each person, or for each affected person. Use it to send one person's findings without the rest of the family.
The form
- The file
- A GA4GH Pedigree, a Phenopackets Family or a Cohort.
- Only the affected people
- Tick this to make files only for the people who are affected. In a Phenopackets Family, they're the people its pedigree marks as affected. In a GA4GH Pedigree or a Cohort, they're the people with at least one disease or phenotype that is present rather than excluded.
- Save in the folder
- By default, this is
~/results/name-people. Each file is named after its person's id, such as IV-3.json.
Each Phenopacket is complete on its own, with its metaData. If a Phenopacket has none of its own, it gets a copy of the one in the file you split. A Phenopacket says nothing about relatives, so the family's structure stays behind. That's what you want when only one person's findings should be sent.
In the terminal
phenotk split /data/examples/okafor_ga4gh-pedigree.json --out-dir ~/results/okafor-people --affected-only
ls ~/results/okafor-people
In Python
import os
import phenopacket_toolkit as ptk
from phenopacket_toolkit.ops import split
doc = ptk.read("/data/examples/okafor_ga4gh-pedigree.json")
os.makedirs("/home/user/results/okafor-people", exist_ok=True)
for packet in split(doc, affected_only=True):
sid = packet.proband().subject.id
ptk.write(packet, os.path.join("/home/user/results/okafor-people", sid + ".json"))
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
Put files together
This tool merges Phenopackets, Families and GA4GH Pedigrees into one Cohort or into one Family. A Cohort is a set of people who don't have to be related.
The form
- The files
- Add two or more files, one at a time.
- Into
- Choose a Cohort, such as the probands of several families, or a Family.
- Its id, Save as
- The new file's id, and where to save it.
Who ends up in it
- A Cohort has every Phenopacket from every file. People are told apart by their ids, but pedigree numbers recur from family to family. So if a person's id has already been used in another file, as IV-3 might be in two families, that person is renamed after their file's id, for example
FAM2-IV-3. The tool tells you who it renamed. Give each family its own id when you convert it (Family id, in Drawing → GA4GH), so that the new names show which family each person came from.
- A Family is one family, so the same id means the same person. The first Phenopacket for each person is kept, and the tool tells you which were left out. The first person in the first file becomes the proband. The Family's pedigree comes from any Families among the files, and from the GA4GH Pedigrees' relationships. Anyone who is in neither is added as a founder, with no parents.
The new file's metaData declares every ontology that the files declare, with its release.
In the terminal
phenotk split /data/examples/okafor_ga4gh-pedigree.json --out-dir ~/results/okafor-people --affected-only
phenotk merge ~/results/okafor-people/IV-3.json ~/results/okafor-people/II-3.json --into cohort --id okafor-affected -o ~/results/okafor-affected.json
pedigree-ga4gh validate ~/results/okafor-affected.json
In Python
import phenopacket_toolkit as ptk
from phenopacket_toolkit.ops import merge
docs = [ptk.read(p) for p in ["/home/user/results/okafor-people/IV-3.json", "/home/user/results/okafor-people/II-3.json"]]
notes = []
new = merge(docs, into="cohort", cohort_id="okafor-affected", notes=notes)
ptk.write(new, "/home/user/results/okafor-affected.json")
for note in notes:
print("note:", note)
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
Add findings to people
This tool adds diseases or phenotypes, or a vital status, to the proband, to everyone or to one person in a GA4GH or Phenopackets file. Diseases and phenotypes can have an age of onset, and phenotypes can also be marked as looked for and not found. The drawing has no place for most of these, but the files do.
The form
- To
- Enter
proband, all, affected or unaffected (as the Family's pedigree says), or one person's id, such as IV-4. You can only give findings to people who have a Phenopacket in the file.
- Phenotypes, Diseases
- Write one term per line: its id, followed if you like by an equals sign and its label, for example
HP:0008527=Congenital sensorineural hearing impairment or MONDO:0007254=breast cancer. You can find the terms with Match conditions to terms, or on the HPO and Mondo websites.
- These phenotypes were looked for and not found
- This marks the phenotypes as excluded. Phenotypes that were looked for and not found are as useful to a diagnosis as those that were found.
- Age at onset
- An ISO 8601 age, such as
P45Y for 45 years or P6M for six months. It applies to every term you add.
- Vital status
- Alive, deceased or unknown.
If a term comes from an ontology that the file didn't use before, the ontology is declared in the file's metaData, so the file stays valid. Its release is recorded as unknown.
In the terminal, and more
phenotk add /data/examples/okafor_phenopackets-family.json --target IV-4 --phenotype "HP:0008527=Congenital sensorineural hearing impairment" --onset P0D -o ~/results/okafor-added.json
phenotk view ~/results/okafor-added.json
The command can add more than the form can. It can add a variant (--variant --gene HGNC:1884=CFTR --hgvs … --zygosity heterozygous), with --diagnosis naming the disease it explains. It can also add measurements, a cause of death, a date of birth or an age, and any field by its path (--set, --merge, --append). man phenotk and phenotk add --help list all the options.
In Python
import phenopacket_toolkit as ptk
from phenopacket_toolkit.ops import add
doc = ptk.read("/data/examples/okafor_phenopackets-family.json")
new = add(doc, "IV-4", phenotypes=[{"id_": "HP:0008527", "label": "Congenital sensorineural hearing impairment", "onset": "P0D"}])
ptk.write(new, "/home/user/results/okafor-added.json")
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
- Phenopackets
- Jacobsen JOB, Baudis M, Baynam GS, Beckmann JS, Beltran S, Buske OJ, et al. (2022) The GA4GH Phenopacket schema defines a computable representation of clinical data. Nature Biotechnology 40(6): 817–820. doi:10.1038/s41587-022-01357-4
PED and MPED files
mpedtools works with PED files, and with MPED files, which are PED files with a column for each of several conditions. Its five tools in the Tools tab summarise and check a file, take one condition out, put files together, split families apart, and turn one kind of file into the other.
The five tools
- Summary and check
- This lists the families and the people (founders and the rest, by sex), and for each condition, how many people are affected, unaffected and carriers. Then it checks for people listed twice, parents who aren't in the file, parents of the wrong sex, and status codes other than 0, 1, 2 and 3.
- Take one condition out
- This makes a plain PED file for one condition of an MPED file. Give the condition's column name, as the file's first line or the summary shows it. If you leave the name empty, you get a file for each condition. Carriers (3) become unaffected (1), because a plain PED file has no code for them.
- Put PED files together
- This puts PED files of the same people, with one condition each, into one MPED file. You can name the conditions, in the same order as the files. If you don't, each one is named after its file.
- One file for each family
- This splits a PED or MPED file of several families into a file for each family, named after the family's id.
- PED ⇄ MPED, and columns
- This turns a PED file into an MPED file, or the other way round, keeping one condition. It can also add or remove a condition column. A new column starts with everyone at the value you choose.
In the terminal
mpedtools info /data/examples/cf-cousins.mped
mpedtools validate /data/examples/cf-cousins.mped
mpedtools extract-all /data/examples/okafor.mped -d ~/results -p okafor
mpedtools convert /data/examples/lynch.ped -o ~/results/lynch.mped -f mped
| Command | |
info FILE, validate FILE | the summary; the check (exit status 1 if it finds an error) |
extract FILE CONDITION -o OUT, extract-all FILE -d DIR -p START | one condition, or each, as a plain PED file |
merge A.ped B.ped … -o OUT -n NAME … | PED files into one MPED file |
split FILE -d DIR -p START | a file for each family |
convert FILE -o OUT -f ped|mped [--phenotype NAME] | one kind into the other |
add-phenotype FILE NAME -o OUT [--default N], remove-phenotype FILE NAME -o OUT | add a column, or remove one |
In Python
import mpedtools
ped = mpedtools.read("/data/examples/okafor.mped")
print(mpedtools.summarise(ped))
for issue in mpedtools.validate(ped):
print(issue.level, issue.message)
one = mpedtools.extract_phenotype(ped, "Hearing_loss_from_birth")
mpedtools.write(one, "/home/user/results/okafor_hearing.ped", force_format="ped")
The PED and MPED formats describes the columns, the codes and the MPED header.
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- mpedtools
- Hearn TJ. mpedtools [software]. github.com/comparativechrono/mpedtools
PedNet: the graph, the mode of inheritance and the variants
PedNet analyses a pedigree as a graph: a directed acyclic graph, with a node for each person and an edge from each parent to each child. Its three tools in the Tools tab show how a family is put together, weigh up how likely each mode of inheritance is, and rank candidate variants by how well each co-segregates with the condition.
All three read a PED file, a GA4GH Pedigree or a Phenopackets Family. From an MPED file, they take the first condition, and a carrier (3) counts as unknown. A drawing has to be made into one of these first, with Drawing → PED or MPED or Drawing → GA4GH Pedigree and Phenopackets.
GA4GH files
PedNet reads a GA4GH Pedigree or a Phenopackets Family with pedigree-ga4gh, as the other tools do, so it finds the same parents: a sperm or egg donor counts as a parent, and an adoptive parent doesn't. A GA4GH Pedigree says who is affected through each person's conditions. Two more fields appear in the form when you choose a GA4GH file:
- Condition
- For a file that names several conditions, the one that makes someone affected, by its ontology id or its name, such as
HP:0000365 or Hearing impairment. Without one, anyone with any of the file's conditions is affected, and from a Phenopackets Family, the Family's own record of who is affected is used. The result says which.
- People with no record of the condition
- A GA4GH Pedigree records who has a condition, but only sometimes who doesn't. Unless you choose, PedNet takes the people with no record of it as unaffected if no one in the file is recorded as not having it, as in the files studio2ga4gh writes from drawings, and as not known if anyone is, as in the files PedGen and PedInterp write, which record both.
The pedigree as a graph
For each family in the file, this lists:
- its loops, each with the people round it. A loop through a couple who are related is from consanguinity, and a loop through no related couple is from marriage: two families who married into each other more than once.
- who is inbred, with their inbreeding coefficient, F: the chance that the two copies of a gene they have are copies of one copy in an ancestor of both their parents. The children of first cousins have F = 1/16 = 0.0625.
- how broad and how tangled it is: its width, the largest number of people none of whom is an ancestor of another, and its elimination width, which sets how much work the exact likelihoods of the other two tools take. Only a pedigree with very many loops is too tangled for them.
- the closest pairs of affected relatives, each with the name of their relationship (brother, first cousin once removed), its degree, and their kinship coefficient: the chance that a copy of a gene taken at random from one of them and a copy taken from the other are the same copy, inherited from an ancestor they share.
- network measures: the original PedNet's measures of where the affected people are, the features of their pattern that the classifier of the mode reads, and the people most central to the graph.
It can also save everyone's kinship coefficients as a table, for the autosomes or for the X chromosome, and the graph as GraphML, which Gephi, Cytoscape and other network tools open. The mating graph has a node for each couple as well, between the partners and their children. Both need one family, so if the file holds several, give the family.
Mode of inheritance
This weighs up autosomal dominant (AD), autosomal recessive (AR), X-linked dominant (XLD) and X-linked recessive (XLR) inheritance, and gives the probability of each, with the probabilities that the condition is dominant or recessive, and autosomal or X-linked. A mode is named only when its probability reaches the threshold, 0.8 unless you change it. Otherwise the answer is uncertain. The third method, network measures, works differently.
- Exact likelihoods (the default)
- PedNet treats the pedigree as a Bayesian network of everyone's genotypes, and works out exactly how likely it is that just these people are affected under each mode, averaged over four penetrances, 0.6, 0.8, 0.95 and 0.99, unless you give others, with a chance of 0.001 of being affected without the disease genotype. A family comes to notice through someone affected, the proband, so the likelihoods are worked out given that the proband has the disease genotype. If you don't say who the proband is, each affected person is taken in turn. A pattern that only a new mutation would explain comes out unlikely, because PedNet doesn't model new mutations. With several families that have the same condition, tick The families have the same condition to get one answer from them all.
- The pattern of affected people
- A classifier that learnt, from thousands of simulated families, where the affected people sit in the graph under each mode: in every generation or skipping some, passed from father to son, mostly male, the children of related parents, and so on.
- Network measures
- The original PedNet's classifier, which tells dominant from recessive by a vote. Two of the four network measures it shows have a vote each: the share of affected people who have an affected parent, and the share of generations in which someone is affected. A third vote goes to dominant inheritance, unless an affected person has two unaffected parents, which gives two votes to recessive inheritance. The classifier calls a condition dominant when all three votes say so, and recessive when it has three votes or more for recessive inheritance. Otherwise, it says uncertain. It gives no probabilities, so the threshold doesn't apply to it.
The likelihoods are the method to rely on. The classifiers show what the pattern alone suggests. PedNet takes a condition to be rare: it gives the allele a frequency of 1 in 1,000 for autosomal recessive inheritance, 1 in 2,000 for X-linked recessive, and 1 in 10,000 for the dominant modes. In Python, infer_mode takes other frequencies, as in allele_frequency={"AR": 0.01}.
Rank candidate variants
For each candidate variant, PedNet works out how likely everyone's genotypes and the pattern of affected people are if the variant causes the condition, and if it doesn't. The ratio of the two is a Bayes factor. Its strength as evidence for co-segregation (PP1) or against it (BS4), under the ACMG/AMP guidelines, is given as Supporting, Moderate or Strong: for co-segregation at Bayes factors of 2.08, 4.33 and 18.7, the odds of the guidelines as a Bayesian framework, and against it at 1/2.08, 1/4.33 and 1/18.7. On the whole, a variant scores higher the more of the affected people carry it and the fewer of the unaffected do, but who the carriers are matters too, and genotypes that can't have come from the parents count heavily against a variant.
The variants are ranked by their odds of being the cause: the Bayes factor times the probability, from who is affected, that the condition is inherited in a way that suits the variant's chromosome. So a variant on the X chromosome ranks low in a family whose condition is clearly autosomal. The table gives both, as log10 odds and log10 BF. Pairs of variants in one gene that an affected person carries both of are scored too, as compound heterozygotes under the recessive modes. Genotypes that break Mendel's laws are counted, and PedNet names anyone who carries a variant that their parents were found not to carry (on the X chromosome, a son whose mother was found not to carry it), as a new mutation in them would explain that genotype, though not necessarily the others.
- The variants
- A VCF file, plain or gzipped, whose samples are named with the PED file's ids; or a table with a row for each variant and a column for each person, holding the number of copies of the variant (0, 1 or 2) or a call such as
0/1. A table names its variants in a column variant, and can also have the columns chrom, pos, ref, alt, af (the allele frequency) and gene. Simulate a family writes one.
- Modes of inheritance
- All four, weighed up as in Mode of inheritance; the two autosomal ones; or the one you know.
- Leave out variants commoner than
- An allele frequency. Variants with no frequency in the file are kept.
- How many to show, Save every variant's scores
- The table under the result shows the best 20, unless you change it. The table you save, separated by tabs, has every variant, with every score.
If the PED file holds several families, they're taken to have the same condition, and each variant is ranked by its evidence across the families in which an affected person carries it.
In the terminal
pednet graph /data/examples/okafor.mped
pednet graph /data/examples/pednet/consanguineous.ped --kinship ~/results/fam3-kinship.tsv --graphml ~/results/fam3.graphml
pednet mode /data/examples/lynch.ped
pednet mode /data/examples/okafor.mped --method patterns
pednet rank /data/examples/pednet/dominant.ped /data/examples/pednet/dominant.vcf --out ~/results/dominant-ranked.tsv
pednet check /data/examples/cf-cousins.mped
pednet mode /data/examples/okafor_ga4gh-pedigree.json --condition HP:0000365
pednet check says what PedNet makes of a PED file: its families, the children of related parents, and anything odd, such as someone whose sex isn't recorded. man pednet gives examples and PedNet's four commands, and pednet graph --help, pednet mode --help, pednet rank --help and pednet check --help list the options of each. For a GA4GH file, --condition chooses the condition and --unrecorded unaffected or --unrecorded unknown says what to take the people with no record of it to be.
In Python
import pednet
okafor = pednet.read_ped("/data/examples/okafor.mped")["FAM1"]
print(pednet.loops(okafor))
print(pednet.inbreeding(okafor)["IV-3"])
print(pednet.relationship(okafor, "IV-3", "II-3").name)
print(pednet.infer_mode(okafor))
family = pednet.read_ped("/data/examples/pednet/dominant.ped")["FAM1"]
variants = pednet.read_vcf("/data/examples/pednet/dominant.vcf", samples=family.ids)
for s in pednet.rank_variants(family, variants)[:3]:
print(s.rank, s.id, round(s.log10_bf, 2), s.evidence)
# a GA4GH Pedigree: the same family, as studio2ga4gh wrote it
okafor = pednet.read_ga4gh("/data/examples/okafor_ga4gh-pedigree.json", condition="HP:0000365")["FAM1"]
print(okafor.affected(), okafor.notes)
How PedNet's methods work, and how well they do on simulated families, is in PedNet's README.
PedNet needs NumPy, which Python downloads with PedNet the first time one of its tools or commands runs, or a notebook imports it. That is about 4 MB, and your browser keeps it for next time.
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- PedNet
- Hearn TJ, Taylor N. PedNet [software]. github.com/comparativechrono/PedNet
- Co-segregation, and its strength as evidence (PP1, BS4)
- Thompson D, Easton DF, Goldgar DE (2003) A full-likelihood method for the evaluation of causality of sequence variants from family data. American Journal of Human Genetics 73(3): 652–655. doi:10.1086/378100
- Jarvik GP, Browning BL (2016) Consideration of cosegregation in the pathogenicity classification of genomic variants. American Journal of Human Genetics 98(6): 1077–1081. doi:10.1016/j.ajhg.2016.04.003
- Richards S, Aziz N, Bale S, Bick D, Das S, Gastier-Foster J, et al. (2015) Standards and guidelines for the interpretation of sequence variants: a joint consensus recommendation of the American College of Medical Genetics and Genomics and the Association for Molecular Pathology. Genetics in Medicine 17(5): 405–424. doi:10.1038/gim.2015.30
- Tavtigian SV, Greenblatt MS, Harrison SM, Nussbaum RL, Prabhu SA, Boucher KM, et al. (2018) Modeling the ACMG/AMP variant classification guidelines as a Bayesian classification framework. Genetics in Medicine 20(9): 1054–1060. doi:10.1038/gim.2017.210
- Pedigrees as Bayesian networks
- Lauritzen SL, Sheehan NA (2003) Graphical models for genetic analyses. Statistical Science 18(4): 489–514. doi:10.1214/ss/1081443232
- Kinship and inbreeding coefficients
- Wright S (1922) Coefficients of inbreeding and relationship. The American Naturalist 56(645): 330–338. doi:10.1086/279872
- NetworkX
- Hagberg AA, Schult DA, Swart PJ (2008) Exploring network structure, dynamics, and function using NetworkX. Proceedings of the 7th Python in Science Conference (SciPy2008), pp. 11–15. conference.scipy.org/proceedings/SciPy2008/paper_2
Simulate a family
PedGen makes up a family with an autosomal dominant or recessive condition, by Mendelian inheritance from an affected founder, and writes it as a PED file, and as a GA4GH Pedigree if you ask. Use it for teaching, or to try PedNet or the Risk tab on families whose mode of inheritance you know.
How it works
The founder has the condition. In each generation, every child gets one of each parent's two copies of the gene, at random, and each couple has between one child and the most you allow. In every generation but the last, the first child of a couple always has a partner and children, and their brothers and sisters each have them with the chance you give, so that the family has as many generations as you ask for. Partners come from a population in which the condition's allele has the frequency you give, a rare one unless you change it, and some come with their own parents, and theirs. Who is affected follows from the genotypes: one copy of the allele is enough for a dominant condition, and a recessive one needs two. As everyone's genotype is known, PedGen can write them too, as a candidate variant for Rank candidate variants.
A rare recessive condition
With a rare allele, someone who marries into the family almost never carries it, so a recessive condition seldom turns up again in the family unless relatives marry. That is so of rare recessive diseases too, which are commoner in the children of cousins. So for a recessive condition, the form lets cousins marry whenever they can, and makes families until one has at least two people affected, unless you change these. Cousins are first found among the founder's grandchildren, in the third generation, so a recessive family needs four generations or more. At the default frequency, only about one four-generation family in fifty has a second person affected, so PedGen makes about fifty families, on average, before it keeps one, which takes a few seconds.
The form
- Mode of inheritance, Generations, The most children a couple has
- The family's condition and shape: 3 generations, or 4 for a recessive condition, unless you change it.
- Seed
- A whole number. With the same seed and settings, PedGen makes the same family, here, in the terminal and in Python. Leave it empty to get a new family every time.
- Family id
- It names the PED file:
FAM1.ped, unless you change it.
- Chance that a child has a partner, and children; Chance that a partner's parents are added
- 0.6 and 0.25, unless you change them.
- Frequency of the allele among partners
- 0.001, unless you change it: a rare allele, as a rare disease's is. At 0.1, about one partner in five would carry it, and in a dominant family be affected. Partners never carry the allele gives the partners who marry in no copy of it, but their parents and grandparents, if they're added, can still carry it. A frequency of 0 keeps the allele to the founder and their descendants.
- Chance that someone marries a cousin
- 1 for a recessive condition and 0 for a dominant one, unless you change it: the chance that someone in the family who has a partner marries a cousin rather than someone from outside the family, when a cousin has no partner yet. A marriage between cousins makes a loop in the pedigree, which The pedigree as a graph shows.
- At least this many affected
- 2 for a recessive condition and 1 for a dominant one, unless you change it. PedGen makes families until one has as many affected people, as families come to notice through their affected members. If none of 1,000 has them, it stops and says what to change.
- Save everyone's genotypes too
- A table,
FAM1-genotypes.tsv, of the number of copies of the allele that each person has, as a variant called causal, for Rank candidate variants.
- Write a GA4GH Pedigree too
- The family as a GA4GH Pedigree,
FAM1_ga4gh-pedigree.json, which ga4gh2studio, the phenopacket toolkit, PedNet and the Risk tab read. Give the condition as an ontology term and its name, such as MONDO:0007739 and Huntington disease, or leave them empty for MONDO:0000001, disease. The affected people have the condition, and the unaffected have it marked as looked for and not found, so that the file records both.
Under the result, Work out its risks opens the family in the Risk tab, with the simulation's mode of inheritance and allele frequency and with full penetrance, as PedGen's model has.
What PedNet makes of it
PedNet takes a condition to be rare too: for autosomal recessive inheritance, it gives the allele a frequency of 1 in 1,000, as PedGen does. Of 30 recessive families of four generations made as the form makes them, PedNet called 16 autosomal recessive, and put that mode first in 25. Of 30 of five generations, it called 21 autosomal recessive. In a family where an affected person marries a carrier, half their children can be affected, which looks dominant (pseudodominance), and then PedNet may favour autosomal dominant inheritance. Dominant families are clearer, but in one family PedNet often can't tell autosomal from X-linked dominant inheritance unless a father passes the condition to a son.
In the terminal
pedgen --mode AD --generations 4 --seed 4 -d ~/results --genotypes ~/results/FAM1-genotypes.tsv --ga4gh --condition MONDO:0007739 "Huntington disease"
pednet mode ~/results/FAM1.ped
pednet mode ~/results/FAM1_ga4gh-pedigree.json
pednet rank ~/results/FAM1.ped ~/results/FAM1-genotypes.tsv
pedgen --mode AR --generations 4 --cousins 1 --min-affected 2 --seed 12 --family FAM2 -d ~/results
pednet graph ~/results/FAM2.ped
ped2studio ~/results/FAM2.ped ~/pedigrees/simulated.studio.json
In the terminal, the defaults are the same for both modes: 3 generations, no cousins marrying, and one person affected. Give the form's for a recessive condition as above.
| Option | |
-m, --mode AD|AR | the mode of inheritance (default: AD) |
-g, --generations N; -c, --max-children N | the number of generations (3), and the most children a couple can have (3) |
-s, --seed N | makes the family reproducible |
-f, --family ID; -d, --output-dir FOLDER | the family id, which names the file (FAM1), and where to write it |
--partners CHANCE, --ancestors CHANCE | the chance that a child has a partner (0.6), and that a partner's parents are added (0.25) |
--allele-frequency F, --unaffected-partners | the allele's frequency among partners and their ancestors (0.001); with --unaffected-partners, the partners themselves never carry it |
--cousins CHANCE | the chance that someone marries a cousin, when one has no partner yet (0) |
--min-affected N | make families until one has at least N people affected (1) |
--genotypes FILE | also write everyone's genotypes, as a table |
--ga4gh, --condition ID LABEL | also write the family as a GA4GH Pedigree, FAMILY_ga4gh-pedigree.json, with the condition as an ontology term and its name (default: MONDO:0000001 disease) |
In Python
import pednet
from PedGen import pedigree_generator, gen_PED_export, gen_GA4GH_export
# a rare recessive condition, which turns up again where cousins marry
df = pedigree_generator(max_children=3, FamilyID="SIM2", mode="AR", generation_count=4,
CousinLikelihood=1.0, min_affected=2, seed=12)
pedigree = pednet.pedigree_from_rows(df)
print(len(df), "people;", len(pednet.loops(pedigree)), "loop, where cousins married")
print(pednet.infer_mode(pedigree))
print("wrote", gen_PED_export(df, "/home/user/results"))
print("wrote", gen_GA4GH_export(df, "/home/user/results", condition=("MONDO:0009061", "cystic fibrosis")))
PedGen's plot_pedigree_tree draws a family with matplotlib. In a notebook, put import matplotlib.pyplot as plt in the same cell, so that Python loads matplotlib before PedGen needs it. Pedigree Studio draws a family better, though: draw the PED file with PED or MPED → drawing.
PedGen needs NumPy and pandas, which Python downloads the first time you use it. That is about 9 MB, or less if PedNet has already run, and your browser keeps them for next time.
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- PedGen
- Taylor N. PedGen [software]. github.com/comparativechrono/pedigree-generator
The Risk tab
The Risk tab works out the chance that someone in a family carries the family's variant, or will be affected, and the chance that a couple's child will be affected. Like a Bayesian risk calculation by hand, it takes account of everything known of the family, but it does so for the whole family at once, exactly, under the model of inheritance you choose. Below the answers, By hand has the four squares of a cross and a calculator that multiplies chances together, for working out the simpler cases yourself.
Work out the risk to a pregnancy takes you through three of the example families, step by step.
The family
From chooses the family: the drawing in the Studio tab, one of your files, or one of the examples. From my computer… adds a file from your computer to ~/pedigrees, and uses it. The Risk tab reads these files:
| File | How it is read |
| A drawing | As studio2ped reads it. Each entry in the colour key is a condition. A symbol filled with its colour, a third or a quarter filled, or shaded all over, is affected; one half filled or half shaded is a carrier, and so is someone with a dot in their symbol. An empty symbol is unaffected, except for a pregnancy (P in the symbol) or a pregnancy loss, whose status isn't known yet. Identical twins (and identical triplets) have one genotype; non-identical twins, and twins whose zygosity isn't known (?), don't. A child joined to a couple by a dashed line is adopted, so that couple aren't the child's genetic parents, and a woman marked G (or S, in drawings made before the 2025 correction to the nomenclature) is a gestational carrier, not a genetic mother. |
| A PED or MPED file | As mpedtools reads it: 2 is affected, 1 unaffected and 0 not known, and in an MPED file, 3 is a carrier. Each column of an MPED file is a condition. If the file has several families, you choose one. |
| A GA4GH Pedigree or a Phenopackets Family | In Python, with pedigree-ga4gh, as PedNet reads it. Each condition of the people in it is a choice, and so is a Family's own record of who is affected, which may put several conditions together. A GA4GH Pedigree records who has a condition, but only sometimes who doesn't. People with no record of a condition are taken as unaffected if no one in the file is recorded as not having it, and as not known if anyone is. People with no record of the condition lets you choose for yourself. |
The chances are for one condition at a time, which you choose under The condition. The line under it counts the people who are affected, who are marked as carriers and whose status isn't known. If something in the family had to be read in a particular way, such as an adoption, a note says so.
How it is inherited
- Mode of inheritance: autosomal dominant, autosomal recessive, X-linked recessive or X-linked dominant. The chances depend on it, so if you aren't sure of the mode, compare the answers under each. PedNet's Mode of inheritance weighs up which mode the pattern of affected people suggests.
- How common the variant is: the allele frequency, which is the share of the copies of the gene in the population that have the variant, or else how many people carry it. It matters most for the people who married into the family. When 1 in 25 people carry the variant, as for cystic fibrosis in northern Europe, an unaffected partner from the population is a carrier with a chance of 1 in 25. For a rare variant, it hardly changes the chances of the people born into the family.
- Penetrance: the share of the people with the variant (with two copies, under a recessive mode) who are affected. Below 100%, someone unaffected may still have the variant.
- Phenocopies and new mutations, which open under their own heading: the share of the people without the variant who are affected for another reason, and how often a new copy of the variant arises in an egg or a sperm. Both are 0 unless you give them.
Sometimes what is known of a family can't happen under the model you've chosen. For example, under a dominant mode with full penetrance and no new mutations, two unaffected parents can't have an affected child. The tab then says who can't be as they are, and what you could change.
The answers
- One person
- The person's chance of being a carrier, or of having the variant under a dominant mode or for a man under an X-linked one, and, if their own status isn't known, of being or becoming affected. Under these chances is the Bayesian table they come from. For each genotype, the table gives the prior chance, from the rest of the family; the conditional chance of what is known of the person and their descendants; the joint chance, which is the two multiplied together; and the posterior chance, which is the joint divided by the sum of the joints. How the chances are worked out explains it in full.
- A child of a couple
- The chance that a child of a couple who isn't born yet will be affected, and will be a carrier, given for a son and for a daughter under an X-linked mode. You can choose the parents of any child in the family, or a couple drawn as partners who have no children yet. If you choose someone in the family, and a partner from the population, the tab gives that person an unaffected partner who isn't related to them.
- Everyone
- Each person's chances, in a table. Click a name to see that person's chances and their Bayesian table above. With Test result or status, you can give someone a test result, such as a carrier or doesn't have it, and see how it changes everyone's chances. The Risk tab takes a test result to be certain. You can also give someone a status here: affected or unaffected, for someone the file has no record of, or not known, which leaves out whether they are affected, for someone too young to show a condition that starts later in life. These are used only in the Risk tab. They're kept in this browser for your next visit, but they aren't added to the family's file. Save as a table writes everyone's chances to a TSV file in
~/results, with a row for each person, which notebooks and spreadsheets can read.
By hand
By hand, at the bottom of the tab, shows what each child of a couple can inherit, drawn as chromosomes in a square of four equally likely children, for autosomal recessive, autosomal dominant and X-linked recessive inheritance. Under it, a calculator multiplies chances together into the chance that a baby is affected. For example, the child of the unaffected brother of someone with cystic fibrosis and a partner from the population has a chance of 2/3 × 1/25 × 1/4 = 1/150. Multiplying is right when each chance comes from a different part of the family. The rest of the tab works out every chance from the whole family at once, so it allows for what each person's relatives tell you about them as well.
From the other tabs
- In the Studio tab, ⋯ (More) → Work out the risks in this family opens the drawing you're working on. When From is The drawing in the Studio tab, the Risk tab reads the drawing again each time you come back to it, so you can change the drawing and then see the new chances.
- In the Files tab, Risks next to a drawing, a PED or MPED file or a GA4GH file opens it in the Risk tab. So does Risks next to a file that a tool has written, and Work out genetic risks on a file's page in the Tools tab.
What the chances leave out
The chances are exact for the model, but only as good as the model and what you know of the family. The model has one gene, with the same penetrance at every age and for men and women. It doesn't allow for a condition that more than one gene can cause, for linked markers, for mosaicism in a parent, or for a parent who isn't the genetic parent shown in the pedigree. Nor does it allow for age, although you can take the status of someone too young to show the condition as not known. For a condition that men who have it don't pass on, such as Duchenne muscular dystrophy, make sure that the men who had children are unaffected, giving them that status under Everyone if the file has no record of it: a man whose status isn't known might have the variant, and that changes the chances of the women descended from him. A test that can miss a variant should be left out, or allowed for with a lower penetrance, because the tab takes every test result to be right. For inherited breast, ovarian and other cancers, use a model made for them, such as CanRisk, which allows for age and for several genes. Use the Risk tab to learn and to check your own sums, and for a real family, work with a clinical genetics service.
More about the Risk tab
How the chances are worked out
The Risk tab works out each chance exactly, with Bayes' theorem, from a model of how the variant is passed on and of how it shows itself. This page describes the model and the sums, explains the Bayesian table, and says how the sums were checked.
The model
- Genotypes. Each person has 0, 1 or 2 copies of the variant. Under an X-linked mode, a man has one X chromosome, and so has 0 copies or 1. Someone whose sex isn't known, such as an early pregnancy, may be a boy or a girl, with a chance of 1/2 each. Identical twins have the same genotype.
- Founders, the people whose parents aren't in the pedigree, have genotypes from the population, in Hardy–Weinberg proportions. With an allele frequency of q, a person has two copies with a chance of q², one copy with a chance of 2q(1 − q), and none otherwise. Under an X-linked mode, a man has the variant with a chance of q. Someone with only one parent in the pedigree is given an unknown other parent, from the population.
- Children get one copy of the gene from each parent, and each of a parent's two copies is equally likely to be the one passed on. A son gets his X from his mother, and a daughter gets her father's X. With new mutations, a copy without the variant gains it, on its way to the child, with the chance you give.
- Being affected depends on the genotype. Someone with the disease genotype is affected with a chance equal to the penetrance, and anyone else with a chance equal to the phenocopy rate. The disease genotype is one copy or more under a dominant mode, and two copies under autosomal recessive; under X-linked recessive, it is a man's one copy, or two copies in a woman.
- A test result rules genotypes out. Has the variant leaves one copy or two, a carrier leaves one (or, under a dominant mode, one or two), two copies leaves two, and doesn't have it leaves none.
The sums
The chance of everything known of a family is a sum over every combination of everyone's genotypes. The chance of each combination is a product, with a part for each person: the chance of their genotype, given their parents' genotypes (or, for a founder, the population's), times the chance of what is known of them, given their genotype. A family of 20 people has more than 3 billion combinations, but the sum can be done one person at a time. Summing over one person's genotypes leaves a small table for the people they are joined to, and so on through the family. This is the peeling of Elston and Stewart (1971), in a form that works for any pedigree, which is known as variable elimination in a Bayesian network (Lauritzen and Sheehan 2003). It copes with loops, as when cousins have children together, and with any number of generations. Only a pedigree with very many loops is too much for it, and the tab says so.
A person's chance of having each genotype, given everything known, is the sum for that genotype divided by the sum for all of them, which is Bayes' theorem. The chances for a couple's child are worked out in the same way, with the child added to the pedigree.
The Bayesian table
The table under One person is the one in textbooks of risk calculation (Young 2007), but worked out from the whole family. For each of the person's genotypes, it gives:
- Prior
- the chance of the genotype, from what is known of the rest of the family: of everyone except the person, their identical twins and their descendants;
- Conditional
- the chance of what is known of the person, their identical twins and their descendants, if the person has the genotype;
- Joint
- the prior times the conditional;
- Posterior
- the joint divided by the sum of the joints: the chance of the genotype, given everything known.
The person's own status counts in the conditional, as part of what is known of them. So for the unaffected sister of someone with an autosomal recessive condition, the priors are 1/4, 1/2 and 1/4, for no copies, one and two, and the conditionals 1, 1 and 0, as she is unaffected. Some textbooks start from her chance after that, 2/3 that she is a carrier, as a prior. The posterior is the same either way.
For example, take a woman whose brother has Duchenne muscular dystrophy, an X-linked recessive condition, so that her unaffected mother is a carrier. The woman's prior chance of being a carrier is 1/2. She has two unaffected sons. If she is a carrier, the chance of that is 1/2 × 1/2 = 1/4, and if she isn't, it is 1: these are the conditionals. The joints are 1/2 × 1/4 = 1/8 and 1/2 × 1 = 1/2, so her posterior chance of being a carrier is (1/8) / (1/8 + 1/2) = 1/5.
A genotype whose chance is below 1 in a million, both before and after, is left out of the table. When every conditional is tiny, as in a large family of whom much is known, the conditionals and joints are shown as multiples of the largest conditional. This doesn't change the posteriors, which depend only on how the joints compare.
Why a textbook's answer can differ a little
Textbook sums usually leave out the chance that the people who married into the family carry the variant too, and the chance of a new mutation. The Risk tab leaves nothing out, so its answer can differ a little. Take the unaffected daughter of a man who is known to be a carrier of an autosomal recessive condition, in a population in which 1 in 25 unaffected people are carriers. A textbook gives her a chance of 1/2 of being a carrier, and her child with a partner from the population a chance of 1/2 × 1/25 × 1/4 = 1/200 of being affected. But her mother could be a carrier too, so her chance of being one is 50/99, a little more than 1/2, and her child's of being affected is 1 in 198. For the textbook's answer exactly, give the people that it takes not to carry the variant the test result doesn't have it, or make the variant very rare.
How a chance is shown
A chance that is a simple fraction, such as 2/3, 1/4 or 1 in 150, is shown as one. Otherwise, it is shown as about 1 in so many with its percentage, such as about 1 in 12 (8.4%), or, from 1 in 5 upwards, as a percentage, such as about 51%. A chance of less than 1 in a million is shown as that. The saved table has every chance to six significant figures.
How the sums were checked
The sums were checked in two ways. First, the examples of the textbooks come out as the textbooks have them. Among them are 2/3 for the unaffected brother or sister of someone with an autosomal recessive condition, and 1/150 for a child of that brother or sister with a partner from a population in which 1 in 25 people are carriers; 1/5 for the woman with two unaffected sons above, and 1/10 for her next son; 2/3 for the mother of a boy who is the only one in his family with a lethal X-linked recessive condition, when new mutations keep the condition in the population (Haldane's result); 1/6 for the unaffected child of someone with a dominant condition of 80% penetrance; and 1/64 for a child of first cousins whose shared grandfather carries a rare recessive variant. Second, for hundreds of small random pedigrees, under every mode, and with reduced penetrance, phenocopies, new mutations, test results, identical twins and loops, every chance was compared with the same chance worked out by brute force, adding up every way the copies of the gene could have been passed down. They all agree. The checks are in the workbench's repository, in tests/risk.
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- Risk calculation in genetic counselling, with Bayesian tables
- Young ID (2007) Introduction to Risk Calculation in Genetic Counseling, 3rd edition. Oxford University Press, Oxford.
- The likelihood of a pedigree, worked out one person at a time (peeling)
- Elston RC, Stewart J (1971) A general model for the genetic analysis of pedigree data. Human Heredity 21: 523–542. doi:10.1159/000152448
- Pedigrees as Bayesian networks
- Lauritzen SL, Sheehan NA (2003) Graphical models for genetic analyses. Statistical Science 18(4): 489–514. doi:10.1214/ss/1081443232
Your files
Your drawings, your notebooks and the files the tools write are all kept in a home folder, ~ (/home/user), which every tab shares. The Files tab shows them, along with the examples.
The folders
| Folder | What goes in it |
~/pedigrees | drawings (.studio.json) saved with the Studio's Save as…, and drawings the tools make |
~/results | what the tools write, unless you choose another folder, and a folder for each run of a workflow |
~/workflows | your workflows (.workflow.json), from the Workflows page of the Tools tab |
~/terms | terms files, from Match conditions to terms |
~/ontologies | copies of the HPO and Mondo, for searching without the internet |
~/notebooks | notebooks, starting with pedigree-tools.ipynb |
~/data | files added from your computer with a tool's From my computer… |
~/examples | your own copies of the examples, made with Copy to my files |
/data/examples | the examples, which can't be changed. To change one, copy it with Copy to my files. |
The Files tab
Click a file to look at it. JSON, PED files and text open in an editor, where you save your changes with Save or Ctrl+S. A drawing opens in the Studio tab, and a notebook in the Notebook tab. The buttons above a pedigree file lead to the tools that use it: Draw in Studio, Check, Convert… and More…. Each file and folder also has a menu (⋯), where you can rename, duplicate, delete or download it, copy its path, or open its folder in the terminal.
Adding files
- My files → Add files from my computer… or Add a folder from my computer…, at the top right. You can also drag files onto the Files tab.
- In a folder's menu: Upload files here….
- In a tool, under a file box: From my computer….
- In the Studio: Open… → Open a drawing from my computer….
Downloading files
- Download, next to a file a tool has written, or in a file's menu.
- Download as a .zip, in a folder's menu.
- My files → Download all my files (.zip), for everything in your home folder.
- In the terminal:
download FILE, or zip then download.
Where the files are kept
Your files stay in this browser, on this computer. The workbench keeps them in the browser's own storage for this site (IndexedDB), so they're still there when you come back. They aren't sent anywhere, and they aren't on any other computer, or in another browser on this one.
- The browser may not keep them in a private window, and it deletes them if you clear this site's data. Saved in this browser, at the top right, tells you whether they're being kept.
- Browsers give each site a share of the disk, which is usually plenty. My files shows how much is used.
- On a computer that other people use, anyone who opens the workbench in your browser account can see your files. My files → Start afresh deletes them all, along with your notebooks and the drawing in the Studio.
Keep copies of what matters
A browser's storage isn't a backup. Download anything you need to keep, especially your drawings, and store it with the rest of your work.
Which file is which
The workbench works with a handful of kinds of file. Most of them are JSON. The end of a file's name, such as .studio.json, usually shows which kind it is, and the workbench also looks inside a JSON file to tell.
| Kind | Named | What it is |
| Pedigree Studio drawing | *.studio.json | The drawing: every symbol, line and label, and the colour key (the format). |
| GA4GH Pedigree | *_ga4gh-pedigree.json | The whole family: a Phenopacket for each person and the relationships between them (the GA4GH Pedigree). |
| Phenopackets Family | *_phenopackets-family.json | The proband and relatives with findings, as Phenopackets, and a PED-style pedigree (Phenopackets). |
| Phenopacket, Cohort | *.json | One person's findings; a set of Phenopackets. |
| PED file, MPED file | *.ped, *.fam; *.mped | The pedigree as a table for linkage programs. An MPED file has a column for each of several conditions (PED and MPED). |
| Terms file | *-terms.json | Condition names and their ontology terms (terms files). |
| Ontology | hp.obo, mondo.obo | A copy of the HPO or Mondo, to search without the internet. |
| Picture | *.png, *.jpg | A picture of a pedigree, which Picture → PED file and drawing reads. |
| VCF file | *.vcf, *.vcf.gz | Variants found by sequencing, with each person's genotypes, for Rank candidate variants. |
| Table of genotypes | *-genotypes.tsv | A row for each variant and a column for each person, as Simulate a family writes it. The workbench recognises one by its name, or by a first column called variant. |
| Workflow | *.workflow.json | Tools chained together: the files the workflow is given, its steps, the settings of each, and which files each reads (Workflows). |
| Record of a workflow's run | workflow-run.json | What one run of a workflow did: its input files, and each step's settings, command and output. It is in the run's folder, beside commands.sh. |
| Other | *.tsv, *.yaml, *.jsonl, *.log.json, *.graphml | What the tools export: a table (such as PedNet's kinship coefficients or its variants' scores), YAML, JSON Lines, a log of decisions, or a graph for network tools. |
How the workbench tells them apart
The workbench looks at the name first. Then, for a JSON file, it looks at what's inside: a drawing has persons and partnerships, a GA4GH Pedigree has individuals and relationships, a Family has a proband, a Cohort has members and a Phenopacket has a subject. A workflow, and the record of a run, begin with a key of their own (pedigree_workbench_workflow, pedigree_workbench_workflow_run). If the workbench doesn't recognise a file, it shows it as plain JSON or text. In the Tools tab, a file's page shows its kind, with a summary of what's in it.
Files made by studio2ga4gh 0.3 or abusua2ga4gh 0.2 are recognised as GA4GH files, but in an older form that the standard doesn't accept. A file like this has Older form on its page, and Upgrade a file from an older tool rewrites it.
The Pedigree Studio file
A drawing is a JSON file, and it's the same whether you save it with the Studio tab's Save or with Pedigree Studio's own File menu. It records what the drawing looks like, with its symbols, lines, positions and colours, rather than the family as data. The converters turn it into data.
What is in it
| Field | What it holds |
persons | One entry per symbol: its id, shape (male, female, unknown, their adopted forms, miscarriage for a pregnancy loss, and the no-offspring and infertile bars), position, the text under it, deceased, proband, consultand, the mark inside it (centerText: dot for a carrier, line for a presymptomatic carrier, D for a donor, G for a gestational carrier (S in drawings made before the 2025 correction to the nomenclature), P for a pregnancy, or a number when the symbol stands for several people), and how it's filled: fillMode, fillColor, halves, thirds, quarters and the shading pattern. |
partnerships | The lines between partners: the two people, and the type (normal, consanguineous, separated, consanguineous-separated). |
childLinks | The lines from a couple to each child, dashed for adoption. |
twinLinks | Twins: the two children, and identical, nonidentical or unknown (zygosity not known, drawn with ?). Triplets and more are children joined through two or more twin links; their lines are drawn from one point. |
legendLabels | The colour key: each colour (or pattern) and the condition's name. This is how the tools know which condition a fill means. |
labels, numberingMode, … | Free text placed on the drawing, how generations are numbered, and layout settings. |
Here's part of the Okafor drawing:
"persons": [
{"id": "p-nnamdi", "shape": "male", "x": 512, "y": 160, "text": "Nnamdi\nd. 82", "deceased": true,
"proband": false, "fillMode": "none", ...},
...
],
"partnerships": [{"id": "pship-1", "fromId": "p-nnamdi", "toId": "p-adanna", "type": "normal"}, ...],
"childLinks": [{"id": "child-5", "partnershipId": "pship-1", "childId": "p-emeka", "dashed": false}, ...],
"twinLinks": [{"id": "twin-17", "child1Id": "p-chidi", "child2Id": "p-dubem", "type": "identical"}],
"legendLabels": {"#2980b9": "Hearing loss from birth", "#c0392b": "Breast cancer"}
Personal data in a drawing
The text under the symbols is whatever was typed there, which is often names, ages and dates of birth. In a drawing made by another program, even the ids may be names, such as p-nnamdi in the examples. Treat a drawing as you would the family's notes. The GA4GH files, and the PED files from studio2ped, leave the text out and name people by pedigree numbers. But you can ask studio2ped to use the text as ids instead (Drawing → PED or MPED).
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- Pedigree Studio
- Hearn TJ. Pedigree Studio [software]. Zenodo. doi:10.5281/zenodo.20209376
The GA4GH Pedigree
The Global Alliance for Genomics and Health (GA4GH) is writing a standard for pedigrees. This page explains what the standard looks like so far, how the workbench writes a GA4GH Pedigree and why, and what was wrong with the files our older tools wrote.
The standard so far
The GA4GH Pedigree Standard is still being developed. Its published documentation describes a conceptual model, in which a pedigree is a set of individuals and the relationships between them. Each relationship is named with a term from the Kinship Ontology, KIN. The model isn't a file format of its own. Instead, other standards carry it, in two forms:
- In Phenopackets. A new message called Pedigree was proposed for the Phenopackets schema in November 2022. In it, the individuals are Phenopackets and the relationships are named by KIN terms. In September 2025 the proposal was closed without being merged, because the Pedigree group hadn't reached a decision yet. It isn't in any release of Phenopackets.
- In HL7 FHIR. There's a draft implementation guide for this form. Each person is a FHIR Patient, and each relationship is a FamilyMemberHistory.
Neither form has been approved yet. The approved GA4GH format that the workbench writes is Phenopackets version 2. That's the format of the Phenopackets Family, and of the Phenopackets inside the GA4GH Pedigree.
The form the workbench writes
A GA4GH Pedigree from the workbench uses the Phenopackets form of the proposal. It's written in the same way as Phenopackets' JSON, with field names in camelCase:
{
"id": "FAM1",
"narrative": "Pedigree drawn in Pedigree Studio: 16 people; proband IV-3. …",
"date": "2026-10-17",
"indexPatients": ["IV-3"],
"individuals": [
{
"id": "FAM1-II-3",
"subject": {"id": "II-3", "vitalStatus": {"status": "ALIVE"}, "sex": "FEMALE"},
"diseases": [{"term": {"id": "MONDO:0007254", "label": "breast cancer"}}],
"metaData": {
"created": "2026-10-17T09:00:00Z", "createdBy": "studio2ga4gh 0.4.0",
"resources": [{"id": "mondo", "name": "Mondo Disease Ontology", "version": "2026-10-06",
"namespacePrefix": "MONDO", "iriPrefix": "http://purl.obolibrary.org/obo/MONDO_", …}],
"phenopacketSchemaVersion": "2.0"
}
},
…
],
"relationships": [
{"individualId": "I-1", "relation": {"id": "KIN:028", "label": "isBiologicalFatherOf"}, "relativeId": "II-3"},
…
]
}
- Every individual is a complete Phenopacket version 2, with its own
metaData. This means everything about a person – their sex, whether they're alive, their diseases and phenotypes – is held in a structure that is approved and can be checked. Only the wrapper, with its list of individuals and its relationships, comes from the proposal.
- Each relationship is written once, as one current KIN term, in what the standard calls the reduced form. Each parent is linked to each child. Partners are linked only if they have no children together, or if they're related or separated. All the twins in a set are linked to one of them. Brothers and sisters aren't linked at all, because the parents they share already show that. The page on KIN lists the terms.
- People are named by their pedigree numbers (II-3) unless you choose otherwise. Phenopackets have no field for a name, so names are never written as such. If you choose to name people by the drawing's labels, though, their ids may be names.
- A condition without an ontology term is left out, with a note, because a disease or phenotype without an id is invalid.
- Some things the standard has no field for, such as a carrier or a pregnancy, are noted in the
narrative so that they aren't lost.
Why this form
- The Phenopackets Family that goes with it is already Phenopackets version 2, and the phenopacket toolkit is built around Phenopackets. So there's one model throughout.
- Because each individual is a Phenopacket, everything recorded about a person can be checked against an approved schema, in the same way that phenopacket-tools, the Phenopackets team's own validator, checks it.
- The standard's own published examples use this form.
If the GA4GH settles on a different form, only one package, pedigree-ga4gh, will have to change, and the upgrade will rewrite files that are in this form.
One implementation
All of the workbench's tools read and write GA4GH files through one package, pedigree-ga4gh. This means studio2ga4gh, ga4gh2studio and the phenopacket toolkit can no longer disagree about the form. The package's check applies the rules of the Phenopackets schema and of phenopacket-tools, the Phenopackets team's validator, as well as the GA4GH Pedigree's own rules (Check against the standard).
Version 1, in draft
Since June 2026, the Pedigree group has been drafting version 1 of the standard. It hasn't been merged or approved yet, and it may change during review. As drafted, it would give the GA4GH Pedigree a schema of its own:
- People would be listed with their sex assigned at birth, their dates and their genetic parents. They would be linked to their Phenopackets, rather than being Phenopackets themselves. Whether someone is affected would be recorded in their Phenopacket.
- A relationship would have separate biological and social KIN terms, a twin type, and a flag for consanguinity.
- KIN itself would gain 22 terms and retire ten. Three of the terms it would retire are ones the workbench writes:
KIN:003, for a biological parent whose sex isn't known, and the two terms for partners who are related.
Until version 1 is approved, the workbench follows the published version. The tools recognise a file in the draft's form and tell you what it is, rather than misreading it, but they can't convert it yet. When version 1 is approved, the change will be in one package, pedigree-ga4gh, and the Phenopackets Family will stay the same. Then the upgrade will rewrite the files the workbench writes now.
What was wrong with the older files
Previously, studio2ga4gh and abusua2ga4gh each wrote GA4GH files in their own way, and the phenopacket toolkit had a “dialect” for reading each of them. Neither way was correct:
| Tool | What it wrote | Why it was wrong |
| studio2ga4gh 0.3, GA4GH Pedigree | people with sex, deceased and affected on them, and relationships with individual and relative | It's the conceptual model written straight out as JSON. Neither form of the standard looks like this, and no other software reads it. |
| studio2ga4gh 0.3, Phenopackets | Phenopackets without metaData, or without its schema version; conditions with an empty id | Each of these is invalid in Phenopackets version 2. |
| abusua2ga4gh 0.2 | names and diseases inside subject; notes on relationships; no metaData; empty resource versions | Phenopackets have no such fields, and readers reject fields they don't recognise. metaData is also required. |
| abusua2ga4gh 0.2, KIN | KIN:039 for a sperm donor; KIN:011 with another label; foster and social parents as adoptive parents (KIN:022) | KIN:039 is hasGestationalCarrier, and a sperm donor is KIN:004. KIN calls KIN:011 isPolyzygoticMultipleBirthSiblingOf. For foster and social parents, KIN has KIN:021 isFosterParentOf and KIN:020 isParentFigureOf. |
| abusua2ga4gh 0.2, carriers | the phenotype HP:0032500 “Heterozygous carrier” | HP:0032500 is Exacerbated by tobacco use. The HPO has no term for a carrier, because being a carrier isn't a phenotype. |
| phenopacket-toolkit 0.3 | read both of the forms above | Reading two incorrect forms kept them alive. The toolkit now reads only the standard form, and refuses the older ones with a message. |
The tools recognise files in the older forms, and Upgrade a file from an older tool rewrites them in the standard form. You only need to do this once.
Two things that are not errors
A Family may leave out consanguinousParents when it's false. That's because proto3 JSON may leave out default values, and phenopacket-tools fills it in before checking. The workbench always writes it, though, because a check against the JSON schema alone asks for it. Also, a Phenopacket that uses no ontology terms, such as one for a relative with nothing recorded, needs no resources. A resource is only needed for each ontology whose terms are used. (The field is spelt consanguinous, as the schema spells it.)
Sources
- GA4GH, Pedigree (the product page, which says it's in development).
- The GA4GH Pedigree Standard's documentation: the conceptual model, how to use it (including the reduced form), the examples, and KIN.
- phenopacket-schema, pull request 364, “Pedigree” (opened on 24 November 2022, and closed without being merged on 26 September 2025).
- The Phenopackets version 2 schema, and phenopacket-tools.
- KIN, in ga4gh/pedigree_family_history_terminology.
- The draft of version 1: ga4gh/pedigree pull request 50, and for KIN pull request 55 (neither has been merged).
- The FHIR implementation guide (draft 0.1.0).
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- GA4GH Pedigree Standard
- GA4GH Pedigree Standard. Pedigree Standard: documentation, examples and the Kinship Ontology (KIN). pedigree.readthedocs.io
- GA4GH Pedigree Standard. pedigree_family_history_terminology: the Kinship Ontology (KIN), kin.owl. github.com/ga4gh/pedigree_family_history_terminology
- Jacobsen JOB. Pedigree (phenopacket-schema pull request 364, opened 24 November 2022, closed without merging 26 September 2025). github.com/ga4gh/phenopacket-schema/pull/364
- Phenopackets
- Jacobsen JOB, Baudis M, Baynam GS, Beckmann JS, Beltran S, Buske OJ, et al. (2022) The GA4GH Phenopacket schema defines a computable representation of clinical data. Nature Biotechnology 40(6): 817–820. doi:10.1038/s41587-022-01357-4
- phenopacket-tools (the Phenopackets team's validator)
- Danis D, Jacobsen JOB, Wagner AH, Groza T, Beckwith MA, Rekerle L, et al. (2023) Phenopacket-tools: building and validating GA4GH Phenopackets. PLoS ONE 18(5): e0285433. doi:10.1371/journal.pone.0285433
- pedigree-ga4gh
- Hearn TJ. pedigree-ga4gh [software]. github.com/comparativechrono/pedigree-ga4gh
Phenopackets
Phenopackets are the GA4GH's approved standard for describing a person's clinical findings – their phenotypes and diseases, and the genetic findings behind them – in a form that computers can read. Version 2 is the current version, and it's the one the workbench writes.
The three messages
- A Phenopacket
- A record of one person. The
subject gives the person's id, sex, vital status and age. The phenotypicFeatures are HPO terms, each observed or excluded, with an onset and severity. The diseases are Mondo terms, and the interpretations are genetic findings. There's also metaData.
- A Family
- A record of one family. The
proband and the relatives with findings are each a Phenopacket. The pedigree lists everyone in the form of a PED file: family, person, father, mother, sex and affected status. consanguinousParents says whether the proband's parents are related, and the Family also has its own metaData.
- A Cohort
- A set of people who needn't be related. Each of them is a Phenopacket.
What the workbench puts in a Family
- The proband is the drawing's proband (the index patient), and the relatives are the other people with a condition. A relative with nothing to record is in the pedigree, but doesn't have a Phenopacket.
- The parents in the pedigree are the genetic ones: biological parents, and egg and sperm donors. Adoptive, foster and step-parents aren't genetic parents, so they aren't written there.
consanguinousParents is worked out from the relationships. It's true when the proband's parents are marked consanguineous, or are related as second cousins or closer, which is what KIN means by consanguineous partners.
- Each Phenopacket has its own
metaData, and so does the Family.
metaData and resources
Every metaData records when the file was made and what made it (created, createdBy). It also gives the schema version (phenopacketSchemaVersion: 2.0), and a resource for each ontology whose terms are used, with that ontology's release:
"resources": [{"id": "hp", "name": "human phenotype ontology", "url": "http://purl.obolibrary.org/obo/hp.owl",
"version": "2026-09-01", "namespacePrefix": "HP", "iriPrefix": "http://purl.obolibrary.org/obo/HP_"}]
Every term's prefix (HP in HP:0000365) must be declared there. This is the rule of phenopacket-tools that files break most often. The release comes from the terms file, the ontology file that was searched, or EBI's service. If none of them gives the release, it's unknown.
The workbench knows the resources of 24 ontologies, from the HPO and Mondo to SNOMED CT and ICD-10-CM. It also keeps any other resource that a file it reads declares in full. If a term comes from an ontology that the workbench can't declare, the term is left out with a warning, rather than making the file invalid.
In JSON
Phenopackets are defined in Protocol Buffers, and written as JSON in the way proto3 writes it. Field names are in camelCase (phenotypicFeatures), and values that are their defaults may be left out. Readers also accept the proto spelling (phenotypic_features). The workbench writes camelCase and reads both.
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- Phenopackets
- Jacobsen JOB, Baudis M, Baynam GS, Beckmann JS, Beltran S, Buske OJ, et al. (2022) The GA4GH Phenopacket schema defines a computable representation of clinical data. Nature Biotechnology 40(6): 817–820. doi:10.1038/s41587-022-01357-4
- phenopacket-tools (the Phenopackets team's validator)
- Danis D, Jacobsen JOB, Wagner AH, Groza T, Beckwith MA, Rekerle L, et al. (2023) Phenopacket-tools: building and validating GA4GH Phenopackets. PLoS ONE 18(5): e0285433. doi:10.1371/journal.pone.0285433
KIN, the kinship terms
The Kinship Ontology, KIN, is the GA4GH Pedigree Standard's vocabulary of relationships. Each relationship in a GA4GH Pedigree is one KIN term, such as KIN:027 isBiologicalMotherOf.
How a relationship is written
{"individualId": "III-3", "relation": {"id": "KIN:027", "label": "isBiologicalMotherOf"}, "relativeId": "IV-3"}
It reads as a sentence: III-3 is the biological mother of IV-3. The label is taken word for word from KIN. A symmetric relation, such as one between partners, twins or cousins, is written only once, in one direction.
The terms the converters use
| In the drawing | KIN |
| mother, father (a parent of unknown sex) | KIN:027 isBiologicalMotherOf, KIN:028 isBiologicalFatherOf (KIN:003 isBiologicalParentOf) |
| adoption | KIN:022 isAdoptiveParentOf |
| sperm and egg donors, a gestational carrier | KIN:004 isSpermDonorOf, KIN:038 isOvumDonorOf, KIN:005 isGestationalCarrierOf (and, read by ga4gh2studio, KIN:006 isSurrogateOvumDonorOf, drawn as an egg donor) |
| identical and non-identical twins, and twins whose zygosity isn't known | KIN:010 isMonozygoticMultipleBirthSiblingOf, KIN:011 isPolyzygoticMultipleBirthSiblingOf, KIN:009 isMultipleBirthSiblingOf |
| partners: consanguineous, separated, or with no children | KIN:030 isConsanguineousPartnerOf, KIN:050 isSeparatedPartnerOf, KIN:051 isSeparatedConsanguineousPartnerOf, KIN:026 isPartnerOf |
Brothers and sisters, grandparents, aunts and cousins aren't written, because they follow from the parents.
The 48 relationship terms
The terms come from kin.owl in KIN's repository, ga4gh/pedigree_family_history_terminology (commit 71616ea of 16 September 2024, which is still its latest). This is the file behind http://purl.org/ga4gh/kin.owl. KIN also has KIN:031, hasSex, but that's a property of one person rather than a relationship between two people. So the table leaves it out, and the workbench never uses it.
Retired codes
Earlier drafts of KIN had codes that the current version doesn't have, and some of them turn up in older files. The check reports them, and the upgrade replaces them:
| Retired code | Becomes |
KIN:033 | KIN:003 isBiologicalParentOf |
KIN:034 | KIN:032 isBiologicalChildOf |
KIN:035 | KIN:036 isGrandchildOf |
KIN:037 | KIN:017 isGrandparentOf |
KIN:040 | KIN:028 isBiologicalFatherOf – with the two people swapped |
KIN:041 | KIN:027 isBiologicalMotherOf – with the two people swapped |
KIN:042 | KIN:038 isOvumDonorOf – with the two people swapped |
KIN:043 | KIN:006 isSurrogateOvumDonorOf – with the two people swapped |
KIN:044 | KIN:004 isSpermDonorOf – with the two people swapped |
KIN:045 | KIN:047 isGreatGrandchildOf |
KIN:048 | KIN:050 isSeparatedPartnerOf |
KIN:049 | KIN:051 isSeparatedConsanguineousPartnerOf |
KIN version 1, in draft
A revised KIN is being drafted alongside version 1 of the standard (see The GA4GH Pedigree), and it hasn't been merged yet. It would add 22 terms (KIN:200 to KIN:221), which tell biological relatives apart from social and legal ones. It would also retire ten terms. Among them are KIN:003, which KIN:200 would replace, and KIN:030 and KIN:051, whose consanguinity would become a flag on the relationship.
Ten codes would keep their number but have a narrower meaning. For example, KIN:017 isGrandparentOf would become isSocialLegalGrandparentOf. Until the draft is merged, the terms above are KIN's current ones, and they're what the workbench writes.
In the terminal
pedigree-ga4gh kin
pedigree-ga4gh kin | grep -i sibling
References
If you use this program in your work, cite the papers below, and give the version you used (Versions, and how to cite):
- GA4GH Pedigree Standard
- GA4GH Pedigree Standard. Pedigree Standard: documentation, examples and the Kinship Ontology (KIN). pedigree.readthedocs.io
- GA4GH Pedigree Standard. pedigree_family_history_terminology: the Kinship Ontology (KIN), kin.owl. github.com/ga4gh/pedigree_family_history_terminology
- Jacobsen JOB. Pedigree (phenopacket-schema pull request 364, opened 24 November 2022, closed without merging 26 September 2025). github.com/ga4gh/phenopacket-schema/pull/364
The PED and MPED formats
A PED file is a pedigree written as a table, with one line per person. Linkage and association programs read PED files, and PLINK reads them as .fam files. An MPED file is a PED file with a column for each of several conditions.
The columns
| Column | Holds |
| 1 · family | The family's id, such as FAM1 |
| 2 · person | The person's id, which is unique within the family |
| 3 · father, 4 · mother | The genetic parents' ids, or 0 for a founder (someone with no parents in the file). Adoptive parents and a gestational carrier aren't genetic parents, so studio2ped writes 0 in their place. |
| 5 · sex | 1 male, 2 female, 0 unknown |
| 6 · status | 1 unaffected, 2 affected, 0 unknown |
FAM1 I-1 0 0 1 2
FAM1 II-2 I-1 I-2 1 2
FAM1 III-2 II-2 II-1 2 2
The columns are separated by tabs or spaces. Some programs write -9 for an unknown status, but the workbench writes 0, and mpedtools warns about -9. An unknown parent may be -9 too, and mpedtools reads that as 0.
MPED files
An MPED file starts with a line that names its condition columns, and it has one status column for each condition:
# MPED v1 Cystic_fibrosis Carrier
# FamID IndID FatherID MotherID Sex Cystic_fibrosis Carrier
FAM1 Michael John p-jw 1 3 3
FAM1 Amelia Philip Ruth 2 2 1
In an MPED file, 3 marks a carrier. A plain PED file has no code for a carrier, so when you take one condition out, a carrier becomes unaffected.
Which tool for what
- To make a PED file from a drawing, use Drawing → PED or MPED, or go through the GA4GH files. Make a PED file for a linkage program compares the two ways.
- To draw a PED file, use PED or MPED → drawing.
- To check PED files, take conditions out of them, or merge and split them, use mpedtools.
- To read a PED file from a picture of a pedigree, use Picture → PED file and drawing, and to make one up, Simulate a family.
- To analyse a family, with its loops, kinship, mode of inheritance and candidate variants, use PedNet. It reads PED files, and the first condition of an MPED file.
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- mpedtools
- Hearn TJ. mpedtools [software]. github.com/comparativechrono/mpedtools
- studio2ped
- Hearn TJ. studio2ped [software]. github.com/comparativechrono/studio2ped
- ped2studio
- Hearn TJ. ped2studio [software]. github.com/comparativechrono/ped2studio
Ontology terms and terms files
An ontology is a curated list of terms, each with an id, a label, a definition and its place among the others. GA4GH files name conditions with these terms, so that software everywhere reads breast cancer in the same way, whatever it was called in the clinic.
The two ontologies
- The Human Phenotype Ontology (HPO)
- The HPO covers phenotypes, which are signs and symptoms such as
HP:0000365 Hearing impairment. In a Phenopacket they're recorded as phenotypicFeatures, and they can be marked excluded, which means they were looked for and not found.
- The Mondo Disease Ontology
- Mondo covers diseases, such as
MONDO:0007254 breast cancer. It brings them together from other disease vocabularies, including OMIM, Orphanet and ICD. In a Phenopacket they're recorded as diseases.
Use a Mondo term when there's a diagnosis, and HPO terms for what was seen, with or without one.
Ids and releases
- An id is a CURIE: a prefix, a colon and a number, such as
HP:0000365 or MONDO:0007254. Some web pages write HP_0000365, which is the same term, but the workbench writes the colon.
- New releases of the ontologies come out every month or so. A term may change its label, and now and then a term is made obsolete and replaced. So each GA4GH file records in its
metaData the release that its terms came from.
Where a condition gets its term
- In the drawing's colour key, as an id in brackets after the name, such as Condition X [MONDO:0009061]. It must be an ontology's id. Hypertension (BP:160/95), for example, is read as a name. The drawing then carries its term wherever it goes. Match conditions to terms can write the ids into a copy of the drawing.
- In a terms file, which you give to Drawing → GA4GH or to Fill in missing terms.
The terms file
A terms file is a JSON file that maps each condition's name, as it appears in the colour key, to its term. Match conditions to terms writes it, with each term's label and release:
{
"Breast cancer": {"id": "MONDO:0007254", "label": "breast cancer", "version": "2026-10-06"},
"Hearing loss from birth": {"id": "HP:0000365", "label": "Hearing impairment", "version": "2026-09-01"}
}
- An id on its own will do, as in
"Ovarian cancer": "MONDO:0008170". If there's no label, the condition's own name is used, and if there's no release, the release is recorded as unknown.
- Capital letters don't matter when the names are matched, so one terms file can serve many drawings in a project.
- The log that Fill in missing terms writes (
….log.json) can be used as a terms file too.
Looking terms up
You can search the HPO and Mondo on their own websites, on EBI's Ontology Lookup Service, or here with Match conditions to terms. That tool searches online through EBI, or offline in copies of the ontologies (hp.obo, mondo.obo). Give the conditions ontology terms has advice on choosing a term.
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- Human Phenotype Ontology
- Give the release you used, too (the terms file records it).
- Gargano MA, Matentzoglu N, Coleman B, Addo-Lartey EB, Anagnostopoulos AV, Anderton J, et al. (2024) The Human Phenotype Ontology in 2024: phenotypes around the world. Nucleic Acids Research 52(D1): D1333–D1346. doi:10.1093/nar/gkad1005
- Mondo Disease Ontology
- Give the release you used, too (the terms file records it).
- Vasilevsky NA, Matentzoglu NA, Toro S, Flack JE, Hegde H, Unni DR, et al. (2022) Mondo: unifying diseases for the world, by the world. medRxiv 2022.04.13.22273750. doi:10.1101/2022.04.13.22273750
The Notebook
The Notebook tab runs Python notebooks in your browser, with all the pedigree packages installed. They're the same .ipynb files that Jupyter uses. The tab is for work the forms don't cover, such as many families at once, your own checks, or a record of an analysis that can be run again.
The notebooks to start from
~/notebooks/pedigree-tools.ipynb walks you through the packages. It covers reading a drawing, converting it and checking the result, the family as Python objects, the phenopacket toolkit, PED files, and running commands from a cell. ~/notebooks/pedigree-analysis.ipynb goes on to PedNet, PedGen and PedInterp: a family as a graph, its kinship and loops, its mode of inheritance, candidate variants, simulated families, and a pedigree read from a picture. Run their cells from the top. If you've deleted one, its button here brings back a fresh copy.
Working in a notebook
- Run a cell with Shift+Enter, or use Run all to run every cell from the top. The first cell you run starts Python, which takes a few seconds, and the very first time it also downloads about 10 MB.
- Code and Text add cells, and text cells are written in Markdown. Use a cell's menu to move, duplicate, clear or delete it.
- Stop stops a cell that's running for too long, and Restart forgets all the variables. The variables button lists everything the notebook has defined.
- The notebook is saved in your files as you work. Download gives you a copy as a Jupyter notebook, a Python script, or a web page with its results.
- As in Jupyter, a notebook starts in its own folder. It uses the same files as the other tabs: the examples in
/data/examples, and your home folder, /home/user.
Commands in a cell
As in Jupyter, a line that starts with ! runs a command, and lines that start with % are the notebook's own commands:
!studio2ga4gh /data/examples/okafor.studio.json -t /data/examples/example-terms.json -d ~/results -o okafor-nb
!pedigree-ga4gh validate ~/results/okafor-nb_ga4gh-pedigree.json
| |
!command | Runs a command, as in the Terminal tab. The pedigree programs and python run in the notebook's own Python. To use them in a pipe or with redirection (| or >), use the Terminal tab. |
%cd, %pwd, %ls | Change or show the folder, or list the files in it |
%pip install NAME | Installs a pure-Python package from PyPI, for this visit |
%%writefile FILE, %%bash, %%capture, %time, %run | Work as they do in Jupyter |
The packages
These packages are installed: studio2ga4gh, ga4gh2studio, studio2ped, ped2studio, mpedtools, hponorm, mondonorm, phenopacket-toolkit and pedigree-ga4gh. PedNet (pednet), PedGen and PedInterp are loaded, with NumPy, pandas, OpenCV and Pillow as they need them, when a cell first imports one of them or runs one of their commands. They're the versions that come with the workbench (Versions). PyYAML is installed too. The packages in Python shows the main functions of each one. Every tool in the Tools tab shows its Python code under The same in the terminal, and in Python, with an Add to notebook button.
The Tools tab, the Notebook tab and the Terminal tab share one Python, which the Risk tab uses too, to read GA4GH files. While a notebook cell is running, a tool waits for it to finish, and the other way round.
The packages in Python
These are the main functions of each package, for use in notebooks and scripts. You can add each box to the open notebook. The packages' own help, such as help(studio2ga4gh.convert_file), tells you more.
studio2ga4gh, ga4gh2studio
import json
from studio2ga4gh import convert_file, parse_session
# a drawing as Python objects: people, couples, pedigree numbers, the colour key
drawing = parse_session(json.load(open("/data/examples/okafor.studio.json")))
print(drawing.legend, drawing.numbers())
# the drawing → the two GA4GH files (terms: a terms file, as a dict)
terms = json.load(open("/data/examples/example-terms.json"))
result = convert_file("/data/examples/okafor.studio.json", "okafor-py", "/home/user/results", terms=terms)
print(result.summary, result.warnings)
# and back: a GA4GH file → a drawing
from ga4gh2studio import convert_file as draw
print(draw("/home/user/results/okafor-py_ga4gh-pedigree.json", None, "/home/user/pedigrees/okafor-py.studio.json").summary)
pedigree_ga4gh: reading, checking, upgrading
import pedigree_ga4gh as pg
doc = pg.load("/data/examples/okafor_ga4gh-pedigree.json")
findings = pg.validate(doc) # [] when the file is correct
print(pg.render_findings(findings), pg.is_valid(findings))
# any GA4GH form → a Kindred: members, their terms, the KIN relations between them
kindred, notes = pg.from_document(doc)
for m in kindred.members[:3]:
print(m.id, m.sex, [t.label for t in m.terms])
print(kindred.genetic_parents("IV-3")) # (father, mother, notes)
# and a Kindred → either form
family, warnings = pg.to_phenopackets_family(kindred, created_by="my notebook")
# an older file, rewritten in the standard form
old = pg.load("/data/examples/older/abusua2ga4gh-0.2_phenopackets-family.json")
new, changes, todo = pg.upgrade(old)
print(len(changes), "changes;", todo)
phenopacket_toolkit: what phenotk does
import phenopacket_toolkit as ptk
from phenopacket_toolkit.ops import render, stats, render_stats, filter_document, deidentify, to_kind, to_format
doc = ptk.read("/data/examples/okafor_ga4gh-pedigree.json") # a Document, whatever its kind
print(doc.kind, render(doc))
print(render_stats(stats(doc)))
affected = filter_document(doc, affected_only=True)
family, notes = to_kind(doc, "family")
print(to_format(family, "ped"))
shared = deidentify(doc, remap_ids="seq")
ptk.write(shared.document, "/home/user/results/okafor-py.deidentified.json")
The other operations – normalise, diff, split, merge, add and sort – are in phenopacket_toolkit.ops too.
mpedtools
import mpedtools
ped = mpedtools.read("/data/examples/cf-cousins.mped")
print(mpedtools.summarise(ped))
print([(i.level, i.message) for i in mpedtools.validate(ped)])
cf = mpedtools.extract_phenotype(ped, "Cystic_fibrosis")
mpedtools.write(cf, "/home/user/results/cf.ped", force_format="ped")
pednet: a family as a graph
import pednet
families = pednet.read_ped("/data/examples/okafor.mped") # {family id: pedigree}; from an MPED file, its first condition
okafor = families["FAM1"]
graph = pednet.pedigree_graph(okafor) # a networkx DiGraph, parent → child
print(graph.number_of_nodes(), "people;", [loop.people for loop in pednet.loops(okafor)])
ids, phi = pednet.kinship_matrix(okafor) # everyone's kinship coefficients
print(pednet.inbreeding(okafor)["IV-3"], pednet.relationship(okafor, "IV-3", "III-3").name)
result = pednet.infer_mode(okafor) # exact likelihoods; or classify_by_patterns(okafor)
print(result.call, {m.mode: round(m.posterior, 3) for m in result.modes})
family = pednet.read_ped("/data/examples/pednet/recessive.ped")["FAM2"]
variants = pednet.read_vcf("/data/examples/pednet/recessive.vcf", samples=family.ids)
for s in pednet.rank_variants(family, variants, modes="AR")[:3]:
print(s.rank, s.id, round(s.log10_bf, 2), s.evidence)
infer_shared_mode and rank_variants_across take several families with the same condition. pedigree_from_rows makes a pedigree from a table with the PED columns, such as PedGen and PedInterp make.
PedGen and PedInterp: simulated families, and pictures
import pednet
from PedGen import pedigree_generator
from PedInterp import pedigree_processing, Studio_export
sim = pedigree_generator(max_children=3, FamilyID="SIM1", mode="AD", generation_count=4, seed=4)
print(pednet.infer_mode(pednet.pedigree_from_rows(sim)).call)
read = pedigree_processing("LYNCH", image_path="/data/examples/lynch.png", ocr=None)
print(read.head())
sketch = pedigree_processing("OKAFOR", image_path="/data/examples/okafor-sketch.png", ocr=None, hand_drawn=True)
print(sketch.attrs["twins"])
print("wrote", Studio_export(sketch, "/home/user/results"))
marked = pedigree_processing("OKAFOR", image_path="/data/examples/okafor-sketch.png", ocr=None, hand_drawn=True,
marks=True)
print(marked[["IndividualID", "Deceased", "Proband", "Carrier"]].tail(5))
Both make pandas tables with the PED columns. gen_PED_export and PED_export write them as PED files. PedInterp lists the twins it finds in attrs["twins"], as a PED file can't hold them, and Studio_export writes what it read as a Pedigree Studio drawing, laid out as the picture is, twins and all. hand_drawn=True reads a pedigree sketched by hand, and marks=True who has died, the proband and carriers, which a PED file can't hold (Picture → PED file and drawing).
hponorm, mondonorm: searching the ontologies
from mondonorm.mondo import MondoIndex # a copy of Mondo among your files (or: from mondonorm.ols import OlsClient)
index = MondoIndex.load("/home/user/ontologies/mondo.obo", allow_download=False)
for c in index.search("bowel cancer", limit=5):
print(c.id, c.label, c.score, c.matched_on)
hponorm.hpo.HpoIndex does the same for the HPO. OlsClient().search(…) searches EBI's Ontology Lookup Service over the internet instead.
Many families at once
import glob, json, os
from studio2ga4gh import convert_file
import pedigree_ga4gh as pg
terms = json.load(open("/data/examples/example-terms.json"))
os.makedirs("/home/user/results/all", exist_ok=True)
for path in sorted(glob.glob("/data/examples/*.studio.json")):
name = os.path.basename(path).replace(".studio.json", "")
result = convert_file(path, name, "/home/user/results/all", terms=terms, family_id=name.upper())
for out, _ in result.files:
print(os.path.basename(out), "valid" if pg.is_valid(pg.validate(pg.load(out))) else "NOT valid")
The Terminal
The Terminal tab is a Linux-style shell in your browser. The pedigree programs are commands in it, and they run exactly as they do on a computer where the packages have been installed with pip. Every tool in the Tools tab shows its command, with a button to run it here.
The pedigree programs
| Command | What it does |
studio2ga4gh | a drawing → a GA4GH Pedigree and a Phenopackets Family |
ga4gh2studio | a GA4GH Pedigree or Phenopackets Family → a drawing |
studio2ped, ped2studio | a drawing → a PED or MPED file, and back |
mpedtools | PED and MPED files: info, validate, extract, merge, split, convert … |
phenotk | the phenopacket toolkit: view, stats, validate, normalise, filter, deidentify, convert, upgrade, diff, split, merge, add, ped, sort |
pedigree-ga4gh | the GA4GH implementation that studio2ga4gh, ga4gh2studio and phenotk share: validate, upgrade, convert, kin |
hponorm, mondonorm | match the names in a GA4GH file to HPO or Mondo terms (see below) |
pednet | a PED file as a graph: graph (loops, kinship, inbreeding, the closest affected relatives), mode (the mode of inheritance), rank (candidate variants by co-segregation), check |
pedgen | simulate a family with a dominant or recessive condition, as a PED file |
pedinterp | a picture of a pedigree, or a sketch of one (--hand-drawn) → a PED file, and a Pedigree Studio drawing with any twins (--studio) |
studio FILE | open a drawing in the Studio tab (--tidy lays it out from scratch) |
man NAME shows examples and the options, and NAME --help shows just the options, from the program itself. Each program also runs as python -m pedwb NAME …. The first time pednet, pedgen or pedinterp runs, Python downloads it, with NumPy and whatever else it needs, and says so: from about 4 MB for pednet to about 21 MB in all.
cd ~/results
studio2ga4gh /data/examples/lynch.studio.json -t /data/examples/example-terms.json -d . -o lynch
pedigree-ga4gh validate lynch_ga4gh-pedigree.json
phenotk view lynch_phenopackets-family.json | grep -i cancer
ls -l
The shell
- It's bash, so you can use pipes, redirection, variables, loops, functions and scripts (
bash script.sh). ↑ and ↓ recall earlier commands, Tab completes names, and Ctrl+C stops a command.
- The text programs –
cat, head, grep, sed, cut, sort, uniq, wc, diff, column and others – were written for this terminal, modelled on the GNU ones. NAME --help tells you which options each one has.
python runs Python scripts, python -c "…" and python -m json.tool FILE. pip install NAME adds pure-Python packages, for this visit.
curl and wget download through the browser, from servers that let web pages download from them, such as EBI and raw.githubusercontent.com. download FILE saves a file or folder to your computer.
- A few things aren't available here: programs that aren't in the list (
help lists all the ones that are), background jobs with &, and sudo.
for f in /data/examples/*.studio.json; do
name=$(basename "$f" .studio.json)
studio2ga4gh "$f" -t /data/examples/example-terms.json -d ~/results/all -o "$name" --family-id "$name"
done
for f in ~/results/all/*_ga4gh-pedigree.json; do echo "$(basename "$f"): $(pedigree-ga4gh validate "$f" | tail -1)"; done
hponorm and mondonorm here
As they go, these two programs ask you about each name and wait for you to type an answer. This terminal can't pass your answers to a program while it's running, so they stop at the first question, keeping the choices made so far. Here, they take their answers from a file instead:
{"hearing loss from birth": {"id": "HP:0000365", "label": "Hearing impairment"}}
hponorm FILE.json --mapping answers.json --auto-remembered -o OUT.json
For most jobs, phenotk normalise FILE --mapping terms.json is simpler. It accepts the workbench's terms files unchanged, and fills in diseases and phenotypes in one go. To match names by pointing and clicking, use Match conditions to terms.
Keeping a session
export-session session.ipynb saves the commands of this session, with their output, as a notebook, and so does the Save session button above the terminal. export-session session.sh saves them as a script.
On your own computer
The packages that run here are ordinary Python packages, so the commands and code that the workbench shows you will also work on your own computer: in a pipeline, on a server, or over many families at once.
Installing them
All of them except pedwb, the workbench's own runner, PedGen and PedInterp are on PyPI, at the same versions as here (Versions). They need Python 3.9 or later.
pip install pedigree-ga4gh studio2ga4gh ga4gh2studio studio2ped ped2studio mpedtools hponorm mondonorm phenopacket-toolkit
If you installed them before October 2026, add --upgrade to that command. The earlier releases of studio2ga4gh, ga4gh2studio and phenopacket-toolkit write or read the older forms that the workbench now upgrades.
PedNet is on PyPI too, at the same version as here, and needs NumPy and networkx, which pip installs with it. The commands for PedGen and PedInterp aren't released yet, so install those two from GitHub for now. The workbench's copies can be a little newer, built from a change that is waiting to be merged: the versions page gives the commit each was built from, and the workbench's own copies, below, are the same. PedInterp needs OpenCV, and to read the labels under the symbols, the Tesseract program (its README says how to install it).
pip install PedNet
pip install "git+https://github.com/comparativechrono/pedigree-generator" "git+https://github.com/comparativechrono/pedigree-interpreter"
Each package installs its own command: studio2ga4gh, ga4gh2studio, studio2ped, ped2studio, mpedtools, hponorm, mondonorm, phenotk, pedigree-ga4gh, pednet, pedgen and pedinterp. They take the same options as in the Terminal tab, so the commands that the Tools tab shows will work on your computer once you change the paths to those of your own files. In Python, the imports are the ones described in The packages in Python.
The workbench's own copies
You can also download the exact copies of the packages that the workbench uses, in one archive. This is handy on a computer that can't reach PyPI, and it includes the workbench's own runner, pedwb.
unzip pedigree-tools.zip -d pedigree-tools
export PYTHONPATH="$PWD/pedigree-tools"
python -m pedwb studio2ga4gh okafor.studio.json -t example-terms.json -d results
python -m pedwb pedigree-ga4gh validate results/okafor_ga4gh-pedigree.json
PedNet, PedGen and PedInterp, with networkx, are in a second archive, which needs NumPy, pandas, OpenCV and Pillow (pip install numpy pandas opencv-python pillow). Unzip it into the same folder.
python -m pedwb PROGRAM … runs any of the programs, just as the terminal here does. Most of them also run as python -m studio2ga4gh …, python -m phenopacket_toolkit … and so on. In Python, put the folder on PYTHONPATH (or in sys.path) and import the packages as usual.
What else they use
- PyYAML is needed only for YAML files:
pip install pyyaml.
- rapidfuzz is optional (
pip install rapidfuzz). If it's installed, hponorm's and mondonorm's searches of local copies of the ontologies also find names that are alike letter by letter but share no word. You don't need it for speed, and the scores are the same without it.
- rich, if it's installed, gives hponorm and mondonorm their coloured questions.
Apart from these, and what PedNet, PedGen and PedInterp need (above), everything they use is part of Python's standard library. On your own computer, hponorm and mondonorm can also ask you their questions as they go, which they can't do in the terminal here.
Versions, and how to cite
These are the versions that this copy of the workbench runs. When you report work done with it, say which versions you used. The files record them too, in their metaData (for example createdBy: studio2ga4gh 0.4.0).
| Package | Version |
| studio2ped | 0.2.1 |
| ped2studio | 0.2.2 |
| studio2ga4gh | 0.4.1 |
| ga4gh2studio | 0.4.1 |
| mpedtools | 0.1.0 |
| hponorm | 1.1.0 |
| mondonorm | 1.1.0 |
| phenopacket-toolkit (phenotk) | 0.4.0 |
| pedigree-ga4gh | 1.0.0 |
| pedwb (the workbench's own runner, not on PyPI) | 1.0.0 |
| PedNet (loaded when first used) | 2.1.0 |
| PedGen (loaded when first used) | 0.1.4.dev13, a development version built from GitHub (commit 93a642d), not on PyPI yet |
| PedInterp (loaded when first used) | 0.1.8.dev32, a development version built from GitHub (commit 8795c98), not on PyPI yet |
| networkx (which PedNet and PedGen use) (loaded when first used) | 3.4.2 |
| Pedigree Studio | 2.3.0 (commit df2b033 of 2026-10-31) |
Python itself comes from Pyodide, which is downloaded from jsDelivr the first time Python starts. To see which version you have, type python --version in the terminal, or click the Python pill in the Tools tab.
The same as on PyPI
Every package here except pedwb, the workbench's own runner, PedGen and PedInterp is the version released on PyPI. So pip install on your own computer gives you exactly the code that runs in the workbench. PedGen and PedInterp are built from GitHub, with changes made for the workbench that will be in their next releases. They have their commands, pedgen and pedinterp, and write GA4GH Pedigrees as well as PED files; PedGen writes a table of genotypes for PedNet, and PedInterp reads children drawn straight under their parents, twins, and pedigrees sketched by hand, and, when asked, who has died, the proband and carriers, and writes what it reads as a Pedigree Studio drawing too. The releases of October 2026 brought these changes:
- PedNet 2.1.0 reads GA4GH Pedigrees and Phenopackets Families as well as PED files, so a family drawn in the Studio, simulated by PedGen or read from a picture by PedInterp goes to it as it is, conditions and all.
- PedNet 2.0.0 analyses pedigrees as graphs: their loops, kinship and inbreeding, the pattern of affected people, and, with the graph as a Bayesian network, exact likelihoods for the mode of inheritance and for how well candidate variants co-segregate with a condition (PedNet). It keeps the network metric classifier of the earlier PedNet, by Nick Taylor.
- pedigree-ga4gh 1.0.0 is new. It's the one implementation of the GA4GH Pedigree and of Phenopackets that studio2ga4gh, ga4gh2studio and the phenopacket toolkit share, so they all read and write the same, corrected form (The GA4GH Pedigree).
- studio2ga4gh 0.4.1, ga4gh2studio 0.4.1 and studio2ped 0.2.1 read a parent marked G as a gestational carrier, not a genetic parent, as they read S. studio2ga4gh writes twins whose zygosity isn't known as isMultipleBirthSiblingOf, and notes a consultand in the narrative, and ga4gh2studio draws them back. ga4gh2studio draws a surrogate who gave the egg as an egg donor (D), since she's a genetic mother. All three read a symbol divided into thirds, one part for each of three conditions, and ga4gh2studio draws three conditions that way. studio2ped and studio2ga4gh number only people, not the bars for no children and infertility, as Pedigree Studio 2.3.0 does.
- studio2ga4gh, ga4gh2studio and phenopacket-toolkit 0.4.0 read and write their GA4GH files through pedigree-ga4gh. The toolkit also fixes faults in 0.3.0 that made some of its files invalid. Its
normalise now fills in a term only when the name is the term's label or one of its synonyms, unless you ask it to accept close matches too.
- studio2ped 0.2.0 names people by their pedigree numbers by default, as studio2ga4gh does, and puts only genetic parents in the father and mother columns. It also leaves out the no children and infertility bars, which aren't people.
- ped2studio 0.2.2 keeps apart families that reuse the same ids.
- hponorm and mondonorm 1.1.0 score the results from EBI's Ontology Lookup Service by how well they match, take synonyms into account, and ignore capital letters in terms files. They no longer treat names that are spelt alike but mean different things, such as hypothyroidism and hyperthyroidism, as close matches, and they search a local copy of an ontology much faster.
The releases before these were 0.3.0 of studio2ga4gh, ga4gh2studio and phenopacket-toolkit, 0.1.0 of studio2ped, 0.2.1 of ped2studio, and 1.0.0 of hponorm and mondonorm. mpedtools is still at version 0.1.0. On your own computer explains how to install the packages outside the browser.
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- Pedigree Studio
- Hearn TJ. Pedigree Studio [software]. Zenodo. doi:10.5281/zenodo.20209376
- studio2ga4gh
- Hearn TJ. studio2ga4gh [software]. github.com/comparativechrono/studio2ga4gh
- ga4gh2studio
- Hearn TJ. ga4gh2studio [software]. github.com/comparativechrono/ga4gh2studio
- studio2ped
- Hearn TJ. studio2ped [software]. github.com/comparativechrono/studio2ped
- ped2studio
- Hearn TJ. ped2studio [software]. github.com/comparativechrono/ped2studio
- mpedtools
- Hearn TJ. mpedtools [software]. github.com/comparativechrono/mpedtools
- hponorm
- Hearn TJ. hponorm [software]. github.com/comparativechrono/hponorm
- mondonorm
- Hearn TJ. mondonorm [software]. github.com/comparativechrono/mondonorm
- phenopacket-toolkit (phenotk)
- Hearn TJ. phenopacket-toolkit [software]. pypi.org/project/phenopacket-toolkit
- pedigree-ga4gh
- Hearn TJ. pedigree-ga4gh [software]. github.com/comparativechrono/pedigree-ga4gh
- PedNet
- Hearn TJ, Taylor N. PedNet [software]. github.com/comparativechrono/PedNet
- PedGen
- Taylor N. PedGen [software]. github.com/comparativechrono/pedigree-generator
- PedInterp
- Taylor N. PedInterp [software]. github.com/comparativechrono/pedigree-interpreter
- Phenopackets
- Jacobsen JOB, Baudis M, Baynam GS, Beckmann JS, Beltran S, Buske OJ, et al. (2022) The GA4GH Phenopacket schema defines a computable representation of clinical data. Nature Biotechnology 40(6): 817–820. doi:10.1038/s41587-022-01357-4
- phenopacket-tools (the Phenopackets team's validator)
- Danis D, Jacobsen JOB, Wagner AH, Groza T, Beckwith MA, Rekerle L, et al. (2023) Phenopacket-tools: building and validating GA4GH Phenopackets. PLoS ONE 18(5): e0285433. doi:10.1371/journal.pone.0285433
- Human Phenotype Ontology
- Give the release you used, too (the terms file records it).
- Gargano MA, Matentzoglu N, Coleman B, Addo-Lartey EB, Anagnostopoulos AV, Anderton J, et al. (2024) The Human Phenotype Ontology in 2024: phenotypes around the world. Nucleic Acids Research 52(D1): D1333–D1346. doi:10.1093/nar/gkad1005
- Mondo Disease Ontology
- Give the release you used, too (the terms file records it).
- Vasilevsky NA, Matentzoglu NA, Toro S, Flack JE, Hegde H, Unni DR, et al. (2022) Mondo: unifying diseases for the world, by the world. medRxiv 2022.04.13.22273750. doi:10.1101/2022.04.13.22273750
- GA4GH Pedigree Standard
- GA4GH Pedigree Standard. Pedigree Standard: documentation, examples and the Kinship Ontology (KIN). pedigree.readthedocs.io
- GA4GH Pedigree Standard. pedigree_family_history_terminology: the Kinship Ontology (KIN), kin.owl. github.com/ga4gh/pedigree_family_history_terminology
- Jacobsen JOB. Pedigree (phenopacket-schema pull request 364, opened 24 November 2022, closed without merging 26 September 2025). github.com/ga4gh/phenopacket-schema/pull/364
- Pedigree nomenclature
- Bennett RL, French KS, Resta RG, Doyle DL (2008) Standardized human pedigree nomenclature: update and assessment of the recommendations of the National Society of Genetic Counselors. Journal of Genetic Counseling 17(5): 424–433. doi:10.1007/s10897-008-9169-9
- Bennett RL, French KS, Resta RG, Austin J (2022) Practice resource-focused revision: Standardized pedigree nomenclature update centered on sex and gender inclusivity: a practice resource of the National Society of Genetic Counselors. Journal of Genetic Counseling 31(6): 1238–1248. doi:10.1002/jgc4.1621
- Co-segregation, and its strength as evidence (PP1, BS4)
- Thompson D, Easton DF, Goldgar DE (2003) A full-likelihood method for the evaluation of causality of sequence variants from family data. American Journal of Human Genetics 73(3): 652–655. doi:10.1086/378100
- Jarvik GP, Browning BL (2016) Consideration of cosegregation in the pathogenicity classification of genomic variants. American Journal of Human Genetics 98(6): 1077–1081. doi:10.1016/j.ajhg.2016.04.003
- Richards S, Aziz N, Bale S, Bick D, Das S, Gastier-Foster J, et al. (2015) Standards and guidelines for the interpretation of sequence variants: a joint consensus recommendation of the American College of Medical Genetics and Genomics and the Association for Molecular Pathology. Genetics in Medicine 17(5): 405–424. doi:10.1038/gim.2015.30
- Tavtigian SV, Greenblatt MS, Harrison SM, Nussbaum RL, Prabhu SA, Boucher KM, et al. (2018) Modeling the ACMG/AMP variant classification guidelines as a Bayesian classification framework. Genetics in Medicine 20(9): 1054–1060. doi:10.1038/gim.2017.210
- Pedigrees as Bayesian networks
- Lauritzen SL, Sheehan NA (2003) Graphical models for genetic analyses. Statistical Science 18(4): 489–514. doi:10.1214/ss/1081443232
- Kinship and inbreeding coefficients
- Wright S (1922) Coefficients of inbreeding and relationship. The American Naturalist 56(645): 330–338. doi:10.1086/279872
- NetworkX
- Hagberg AA, Schult DA, Swart PJ (2008) Exploring network structure, dynamics, and function using NetworkX. Proceedings of the 7th Python in Science Conference (SciPy2008), pp. 11–15. conference.scipy.org/proceedings/SciPy2008/paper_2
- Pyodide
- The Pyodide development team. Pyodide: Python in the browser. pyodide.org
Privacy
The workbench is a web page that does its work in your browser. Your drawings and files aren't uploaded anywhere, and there's no server behind the page that sees them.
What stays on this computer
- Your files, drawings and notebooks, which are kept in this browser's storage for the site (Your files).
- The drawing that's open in the Studio tab, which Pedigree Studio keeps in the same storage.
- Small settings: the tab you were on, the help page you were reading, and the name you gave the terminal.
The page has no cookies, no accounts and no analytics.
What the page fetches and sends
| When | From | What is sent |
| Python first starts | cdn.jsdelivr.net (Pyodide) | nothing of yours, because it's an ordinary download |
| PedNet, PedGen or PedInterp first runs | cdn.jsdelivr.net (NumPy, pandas, OpenCV, Pillow) | nothing of yours: the same kind of download. The pictures PedInterp reads stay here. |
| Match conditions to terms, or Fill in missing terms, with EBI's service | www.ebi.ac.uk (the Ontology Lookup Service) | the words you search for, or the ids you type, but not the drawing or anything else in the file |
| Downloading the HPO in Match conditions to terms | raw.githubusercontent.com | an ordinary download |
curl, wget, pip install in the terminal or a notebook | wherever you point them | whatever you send |
If you choose copies of the ontologies on this computer in the term tools, nothing about the family leaves the computer at all.
Patient data
Pedigrees are personal data about whole families, including people who haven't consented to anything. Use the workbench as your institution's rules on patient data allow, and follow this advice:
- Prefer pedigree numbers to names. The GA4GH and PED files use them by default, and the drawing is the only place names need to be.
- If you name people in any other way, such as by the drawing's labels, Pedigree Studio's ids or the text under the symbols, check the ids before you share the file, because they're often names (Drawing → PED or MPED).
- De-identify files before you pass them on, and keep the key separately (De-identify). Remember that de-identified doesn't mean anonymous.
- On a shared computer, download your work and use My files → Start afresh when you finish.
When something goes wrong
These are the common problems, and what to do about each one.
- Python doesn't start
- The first time you use it, the workbench downloads Python (about 10 MB) from cdn.jsdelivr.net. If your network blocks that site, or you're offline, the tools, the notebook and the programs can't run, although the Studio and the Files tab still work, and so does the Risk tab, except for GA4GH files. Try again on another network. After the first time, the browser usually keeps a copy.
- “This GA4GH Pedigree was written by studio2ga4gh 0.3 or earlier …”
- The file is in an older form, which the tools no longer read. Upgrade a file from an older tool rewrites it, and you only need to do this once.
- A condition is missing from the GA4GH files
- It has no ontology term, so it was left out, and the tool mentioned this under its result. Give it a term with Match conditions to terms, then convert the drawing again with the terms file. Check that the name in the terms file is the same as the name in the colour key. Capital letters don't matter, but spelling does.
- A colour isn't counted as a condition
- The colour key doesn't name it. Open the drawing in the Studio tab, click the key, and type the condition's name next to that colour.
- “EBI's Ontology Lookup Service did not answer”
- Either the service is down or slow, or your network blocks www.ebi.ac.uk. Try again later, or search copies of the ontologies on this computer instead (2 · Search in).
- The PED file has names as ids, or the same id twice
- studio2ped names people by their pedigree numbers, unless you choose otherwise in People are named by. The drawing's labels, Pedigree Studio's own ids and the text under the symbols can all be names, so choose pedigree numbers instead. A PED file made by studio2ped 0.1 always used the text under the symbols, which can give names or the same id twice, so make it again (Make a PED file for a linkage program).
- The drawing a tool made looks untidy
- Press Tidy in the Studio tab, or tick Tidy the drawing when it opens before you run the tool.
- The Studio tab shows the wrong drawing, or none
- The bar above the drawing shows which file it belongs to. Open… lets you open any of your drawings, and the file button lists the most recent ones.
- A tool waits for a long time
- A notebook cell may be running. The tools share the notebook's Python, so they wait for the cell to finish. You can stop the cell in the Notebook tab. The first search of a local copy of Mondo also takes a while, because it reads the whole file. The first time a tool of PedNet, PedGen or PedInterp runs, Python downloads it, with what it needs, which is up to about 21 MB, and says so under the form.
- “… couldn't be downloaded – check the internet connection”
- PedNet, PedGen and PedInterp need NumPy and other packages, which come from cdn.jsdelivr.net, as Python does. If the connection drops, or your network blocks that site, run the tool again once it's back.
- Picture → PED file and drawing misses someone, or gives someone the wrong parents
- PedInterp needs a clear drawing: dark on white, square to the edges, with each generation in a row of its own and the lines meeting the symbols. A photograph of a page reads worse than a scan or a screenshot. If the pedigree was sketched by hand, even in part, tick Drawn by hand (
--hand-drawn in the terminal): PedInterp suggests it when it thinks lines were missed. PedInterp chooses how much to enlarge the picture from the size of its symbols, and a line under the table says how much. If it warns that a line may have been missed, give Enlarge the picture by (or --upscale) a number a little larger or smaller (smaller, if the lines are very thick). If no symbols are found in a page with a small pedigree on it, cut the picture down to the pedigree. In a sketch, a line that stops well short of what it joins, a symbol drawn over a line, a scribble that runs out past a symbol, a line drawn close beside a symbol filled in by scribbling, or a small triangle can be misread, and so can the lines to twins drawn close over their symbols, and two brothers' or sisters' lines drawn leaning towards each other, which are taken for twins': draw it again with a little more room, or correct the drawing afterwards. Half-filled or shaded symbols and dashed lines aren't read yet. Whatever the picture, check what PedInterp read against it: the drawing it makes is laid out as the picture is, so the two are easy to compare. Correct the drawing in the Studio, and make the PED file again from it with Drawing → PED or MPED.
- PedNet says that an option needs --family
- The kinship table, the graph file and a proband are for one family. If the PED file holds several, give the family's id in Family.
- PedNet calls a family that PedGen simulated as recessive something else
- Check the form's settings for a recessive condition: four generations or more, cousins who marry, and at least two people affected (Simulate a family). With only the founder affected, nothing shows how a condition is inherited. With a commoner allele than PedGen's default of 0.001, carriers who marry in make a recessive condition look like other modes to PedNet, which takes the allele to be rare. Even so, one family is not always enough: PedNet calls about half of PedGen's four-generation recessive families autosomal recessive, and is uncertain about most of the rest, though it puts autosomal recessive first in five of six. In a family where an affected person marries a carrier, the condition can look dominant.
- Simulate a family takes a long time, or says that none of 1,000 families had enough affected
- A rare recessive condition seldom turns up twice in a family, so PedGen may have to make many families to find one with as many affected people as you asked for. Let cousins marry (1 is whenever they can), give more generations or children, or ask for fewer affected people.
- A workflow can't run, or one of its steps failed
- If the workflow can't run, its Run page lists why, such as an input that isn't connected. Open it in the editor, where Checks lists the same things and takes you to each step. If a step failed, open What went wrong under it. It shows the tool's own error, the one you'd see if you ran the tool yourself, and the steps that read its files didn't run. Put right the step's settings in the editor, or choose another input file, and run it again (Workflows).
- A workflow's run says stopped
- A workflow runs in this page, so closing or reloading the page stops it, and the steps that hadn't run are marked stopped. The files of the steps that had finished are in the run's folder. Run the workflow again.
- hponorm or mondonorm stops straight away in the terminal
- They ask you questions as they go, and this terminal can't pass your answers to them. Give them the answers in a file, or use Fill in missing terms or Match conditions to terms instead (The Terminal).
- My files have gone
- Are you using the same browser, on the same computer, and not a private window? The browser keeps the files for this site only. If your browser clears site data when it closes, it deletes them too, so download anything you want to keep.
- “The workbench is open in another tab or window too”
- Both tabs keep files in the same place, so one can overwrite what the other has saved. Close one of them.
Reporting a fault
If a tool fails and shows Python’s traceback (for reporting a fault) under the result, or a file the workbench made doesn't pass its own check, that's a fault. Report it on the workbench's issues page. Include the traceback and, if you can, a file that shows the problem, such as one of the examples, or a made-up file that does the same thing. Never attach a family's real data, even de-identified.
Credits and licences
The Pedigree workbench is made by the Hearn lab. It brings Pedigree Studio and the Python packages together in one page, using the framework of the lab's Bioinformatics workbench. It's built from open-source software and open standards, each under its own licence, and THIRD_PARTY.md lists them with their versions.
Made by us
| Component | Licence |
Pedigree Studio (Timothy J Hearn), copied into assets/studio | MIT |
| pedigree-ga4gh, studio2ped, ped2studio, studio2ga4gh, ga4gh2studio, mpedtools, hponorm, mondonorm, phenopacket-toolkit (Tim Hearn) | MIT |
| PedNet (Tim Hearn and Nick Taylor) | MIT |
| PedGen and PedInterp (Nick Taylor, with changes by Tim Hearn) | MIT |
| pedwb, which runs the packages in the workbench | MIT |
| The workbench: the page, the help, the Tools tab, the shell, the notebook and the editor (from the Bioinformatics workbench) | MIT |
Made by others
| Component | Licence |
| KIN, the Kinship Ontology (GA4GH Pedigree Standard), whose codes, labels and definitions are included in pedigree-ga4gh | Apache 2.0 |
| Pyodide (Python for the browser) and PyYAML, loaded from jsDelivr when Python starts | MPL 2.0 (Python: PSF licence); PyYAML: MIT |
| networkx, which PedNet and PedGen use, included in their archive | BSD 3-clause |
| NumPy, pandas (with python-dateutil, pytz and six), OpenCV and Pillow, loaded from jsDelivr when PedNet, PedGen or PedInterp first runs | NumPy and pandas: BSD 3-clause; OpenCV: Apache 2.0; Pillow: MIT-CMU; python-dateutil: Apache 2.0 or BSD 3-clause; pytz and six: MIT |
| CodeMirror 5 (the editors) | MIT |
| marked (Markdown) | MIT |
| DOMPurify | Apache 2.0 or MPL 2.0 |
| JSZip | MIT or GPL 3 |
Standards and data
- The Phenopackets schema and phenopacket-tools, by the GA4GH. The workbench's checks follow their rules.
- The Human Phenotype Ontology and the Mondo Disease Ontology, which you search through EBI's Ontology Lookup Service or in copies you download. No copy of either comes with the workbench.
- The example families come from the lab's pedigree practical, and have been made into Pedigree Studio drawings. The files made from them were written by the packages themselves.
References
If you use these programs in your work, cite the papers below, and give the versions you used (Versions, and how to cite):
- Pedigree Studio
- Hearn TJ. Pedigree Studio [software]. Zenodo. doi:10.5281/zenodo.20209376
- Phenopackets
- Jacobsen JOB, Baudis M, Baynam GS, Beckmann JS, Beltran S, Buske OJ, et al. (2022) The GA4GH Phenopacket schema defines a computable representation of clinical data. Nature Biotechnology 40(6): 817–820. doi:10.1038/s41587-022-01357-4
- phenopacket-tools (the Phenopackets team's validator)
- Danis D, Jacobsen JOB, Wagner AH, Groza T, Beckwith MA, Rekerle L, et al. (2023) Phenopacket-tools: building and validating GA4GH Phenopackets. PLoS ONE 18(5): e0285433. doi:10.1371/journal.pone.0285433
- Human Phenotype Ontology
- Give the release you used, too (the terms file records it).
- Gargano MA, Matentzoglu N, Coleman B, Addo-Lartey EB, Anagnostopoulos AV, Anderton J, et al. (2024) The Human Phenotype Ontology in 2024: phenotypes around the world. Nucleic Acids Research 52(D1): D1333–D1346. doi:10.1093/nar/gkad1005
- Mondo Disease Ontology
- Give the release you used, too (the terms file records it).
- Vasilevsky NA, Matentzoglu NA, Toro S, Flack JE, Hegde H, Unni DR, et al. (2022) Mondo: unifying diseases for the world, by the world. medRxiv 2022.04.13.22273750. doi:10.1101/2022.04.13.22273750
- GA4GH Pedigree Standard
- GA4GH Pedigree Standard. Pedigree Standard: documentation, examples and the Kinship Ontology (KIN). pedigree.readthedocs.io
- GA4GH Pedigree Standard. pedigree_family_history_terminology: the Kinship Ontology (KIN), kin.owl. github.com/ga4gh/pedigree_family_history_terminology
- Jacobsen JOB. Pedigree (phenopacket-schema pull request 364, opened 24 November 2022, closed without merging 26 September 2025). github.com/ga4gh/phenopacket-schema/pull/364
- Pedigree nomenclature
- Bennett RL, French KS, Resta RG, Doyle DL (2008) Standardized human pedigree nomenclature: update and assessment of the recommendations of the National Society of Genetic Counselors. Journal of Genetic Counseling 17(5): 424–433. doi:10.1007/s10897-008-9169-9
- Bennett RL, French KS, Resta RG, Austin J (2022) Practice resource-focused revision: Standardized pedigree nomenclature update centered on sex and gender inclusivity: a practice resource of the National Society of Genetic Counselors. Journal of Genetic Counseling 31(6): 1238–1248. doi:10.1002/jgc4.1621
- PedNet
- Hearn TJ, Taylor N. PedNet [software]. github.com/comparativechrono/PedNet
- PedGen
- Taylor N. PedGen [software]. github.com/comparativechrono/pedigree-generator
- PedInterp
- Taylor N. PedInterp [software]. github.com/comparativechrono/pedigree-interpreter
- NetworkX
- Hagberg AA, Schult DA, Swart PJ (2008) Exploring network structure, dynamics, and function using NetworkX. Proceedings of the 7th Python in Science Conference (SciPy2008), pp. 11–15. conference.scipy.org/proceedings/SciPy2008/paper_2
- Pyodide
- The Pyodide development team. Pyodide: Python in the browser. pyodide.org