Skip to main content

studio2ped

Convert families drawn in Pedigree Studio into standard PED pedigree files, or into extended MPED (multi-phenotype PED) files when more than one condition is recorded.

Installation

pip install studio2ped

It needs Python 3.9 or later and nothing else. You can also use the standalone script, studio2ped_standalone.py, without installing anything.

Usage

Command line

# Basic conversion: writes okafor.ped, or okafor.mped if the family needs MPED
studio2ped okafor.studio.json

# Specify output name and directory
studio2ped okafor.studio.json -o my_pedigree -d ./output/

# Identify people by the labels the drawing shows, instead of pedigree numbers
studio2ped okafor.studio.json --ids drawing

# Using the standalone script
python studio2ped_standalone.py okafor.studio.json

The command prints a short summary, the files it wrote and notes on anything you should know: symbols that are not people and were left out, identifiers that had to be changed, and so on.

Commands written for version 0.1.0 still work. The difference you will notice is that people are now identified by their pedigree numbers; add --ids text to get the identifiers 0.1.0 used (see Identifying people).

Python API

import json
import studio2ped

with open("okafor.studio.json", encoding="utf-8") as f:
    session = json.load(f)

result = studio2ped.convert(session, "okafor")     # ids="drawing", "studio" or "text" to choose identifiers
print(result.summary)
for note in result.notes:
    print("Note:", note)
for filename, content in result.files:
    print(f"--- {filename} ---")
    print(content)

# From file to file
result = studio2ped.convert_file("okafor.studio.json")
for filepath, _ in result.files:
    print(f"Written: {filepath}")

What it does

The converter reads a Pedigree Studio session file and:

  1. Detects separate pedigrees: if the canvas holds several unconnected families, each is written to a file of its own.
  2. Works out the family structure from the partnership and child lines, not from where the symbols are, so a rearranged pedigree converts correctly.
  3. Leaves out symbols that are not people. Pedigree Studio stores the "no children" bar and the "infertility" double bar as children of the couple; they are not written as individuals, and a note names the couple.
  4. Gives genetic parents only. The father and mother columns of a PED file are genetic parents. A child joined to a couple by a dashed line (an adoption) gets 0 for that couple, and so does the place of a parent marked S (a gestational carrier), with a note in each case; a parent marked D (a donor) is a genetic parent. studio2ga4gh's PED-style pedigree gives the same.
  5. Extracts phenotypes from the colour key: solid fills, half fills, quartered fills and shading patterns are all recognised.
  6. Detects carrier notation: centre dots (●) and half-filled symbols mark carriers.
  7. Chooses the format:
    • one phenotype → a standard .ped file (6 columns);
    • several phenotypes, or carrier notation alongside a phenotype → an extended .mped file.

Identifying people

--ids Each person is identified by
numbers (the default) their pedigree number as Pedigree Studio shows it: the generation in Roman numerals and the position from the left, such as II-3
drawing the label the drawing shows under its numbering setting: pedigree numbers, letters (II-C, or A, B, C …) or labels typed in
studio Pedigree Studio's own id, such as p-3
text what version 0.1.0 used: the label typed in if there is one, otherwise the first line of the text under the symbol, otherwise Pedigree Studio's id

Pedigree numbers are the ones studio2ga4gh writes into the GA4GH files, so a person can be followed from one file to the other. The text under a symbol usually holds a name and an age ("Alice, 50"), so text, and drawing when the drawing has labels typed in, can put names into the file: use them only when that is acceptable for wherever the file is going.

Identifiers can't contain spaces, so spaces become underscores and other punctuation is dropped: "J. Mensah" becomes J_Mensah. studio2ga4gh makes its ids from labels the same way, so with the same choice a person has the same identifier in the PED file and in the GA4GH files. No two people may share an identifier, and 0 means "no parent" in a PED file, so if a label would be shared by two people (two cousins both labelled "26", say), would be empty or would be 0, the person is given their pedigree number instead, and a note says so.

Pedigree numbers follow the drawing, as in Pedigree Studio: a new generation starts 80 pixels or more below the first symbol of the generation above, and the "no children" and "infertility" symbols are counted in their row, even though they are not written to the file.

Output formats

Standard PED (.ped)

The standard 6-column format used by PLINK, GATK and most genetics tools:

# Family: FAM1
# FamID  IndID  FatherID  MotherID  Sex  Phenotype
FAM1     I-1    0         0         1    1
FAM1     I-2    0         0         2    1
FAM1     II-1   I-1       I-2       2    2

Phenotype codes: 0 = unknown, 1 = unaffected, 2 = affected. The columns are separated by tabs.

Extended MPED (.mped)

A multi-phenotype extension for pedigrees in which more than one condition is tracked. It adds a header line naming the phenotype columns, and a carrier status:

# MPED v1	Breast_cancer	Carrier
# FamID	IndID	FatherID	MotherID	Sex	Breast_cancer	Carrier
FAM1	I-1	0	0	1	1	1
FAM1	I-2	0	0	2	3	3
FAM1	II-1	I-1	I-2	2	2	1

Phenotype codes: 0 = unknown, 1 = unaffected, 2 = affected, 3 = carrier.

The format is easy to read by program: the first line declares the format and names the phenotype columns, the second is a header for people to read, and the data lines have the same tab-separated columns as standard PED, with one more column for each phenotype.

Column names are the condition names from the colour key, with spaces turned into underscores. An ontology id written in brackets after a name, as studio2ga4gh reads it ("Breast cancer [MONDO:0007254]"), is left out of the column name, which is then Breast_cancer, and a note says which id it had. Only the ids of ontologies studio2ga4gh can declare count (the HPO, Mondo, OMIM, Orphanet, SNOMED CT and so on): anything else in brackets, such as "Hypertension (BP:160/95)", stays part of the name. If two conditions would give the same column name, the second becomes Breast_cancer_2.

Phenotype detection

The converter maps Pedigree Studio's markings to phenotype status using the colour key:

Marking Colour key entry Status
Solid colour fill #rrggbb Affected (2)
Full shading (stripes/dots) shading:pattern:full Affected (2)
Half colour fill (one side only) #rrggbb Carrier (3)
Half shading shading:pattern:half-left Carrier (3)
Quartered fill (any quarter) #rrggbb Affected (2)
Centre dot (●) — Carrier (3)
No fill — Unaffected (1)

Phenotype names are the text typed into the colour key (for example "Breast cancer"). A colour with no text in the key is ignored.

A centre dot gives 3 in the Carrier column, and in the column of the condition the person is drawn with; on a symbol with no fill it is the first condition in the key.

Multiple pedigrees

If a drawing holds several unconnected families (common when several are drawn on the same canvas), each is written to a file of its own:

okafor_1.mped    # the first family
okafor_2.mped    # the second family

The colour key belongs to the whole drawing, so every family is written in the same format: all .ped or all .mped.

The standalone script

studio2ped_standalone.py is the whole package in one file, for computers where installing a package is awkward; it takes the same options as the studio2ped command. It is made from the package by python tools/make_standalone.py, and a test checks that the two agree.

Development

pip install -e ".[test]"
pytest

Licence

MIT

Metadata

Release files for studio2ped 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for studio2ped 0.2.0
File Size Uploaded Provenance Actions
studio2ped-0.2.0.tar.gz 45.3 kB With provenance Details for studio2ped-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for studio2ped 0.2.0
File Interpreter ABI Platform Actions
studio2ped-0.2.0-py3-none-any.whl Python 3 none any Details for studio2ped-0.2.0-py3-none-any.whl

Total release size: 64.3 kB

Release files / studio2ped-0.2.0.tar.gz

Download URL studio2ped-0.2.0.tar.gz
Size 45.3 kB
Tags Source
SHA-256 checksum
How to use checksums
57e0631745bfa35b25af0fe9e25f29d080a8115af1e9eda3c2bf8e427d74c210
BLAKE2b-256 checksum
How to use checksums
bdfc8980eb55288ef51ab3f75314dee120dd9a51e2258fd4ddb666c84a76fcfa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

Release files / studio2ped-0.2.0-py3-none-any.whl

Download URL studio2ped-0.2.0-py3-none-any.whl
Size 19.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bd67a117552b3b16d2d9ef538ea26da7ecb9e1efa38952b5516c28af21bed6d9
BLAKE2b-256 checksum
How to use checksums
cc1a8853fa51de65fc71e6414de55e143ad15ad9c62ec76ceae97f4f0931fd1c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

Security for studio2ped 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for studio2ped-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page