ped2studio 0.2.0

Convert PED and MPED pedigree files to Pedigree Studio session JSON

ped2studio

Convert standard PED pedigree files into Pedigree Studio session JSON files.

Installation

pip install ped2studio

Or use the standalone script (ped2studio_standalone.py) with no installation required — it needs only Python 3.9+.

Usage

Command line

# Basic conversion (standard PED)
ped2studio family.ped family.json

# MPED file (auto-detected, each phenotype gets its own colour)
ped2studio family.mped family.json

# Use a specific colour for affected individuals (single-phenotype only)
ped2studio family.ped family.json --colour "#c0392b"

# Use left-half fill instead of full shape
ped2studio family.ped family.json --fill half

# Combine half fill with a colour
ped2studio family.ped family.json --fill half --colour "#c0392b"

# Use shading pattern instead of colour
ped2studio family.ped family.json --shading --pattern stripes

# Use half-shape dot shading
ped2studio family.ped family.json --shading --pattern dots --fill half

Python API

import ped2studio

# From a PED string (default: full solid black)
session = ped2studio.convert(ped_text)

# From an MPED string (auto-detected, multi-colour)
session = ped2studio.convert(mped_text)

# From file to file (works with both .ped and .mped)
ped2studio.convert_file("family.mped", "family.json")

# With options (single-phenotype files only)
session = ped2studio.convert(
    ped_text,
    affected_color="#c0392b",   # colour for affected (when not using shading)
    fill_type="half",           # 'full' or 'half'
    use_shading=True,           # use pattern instead of colour
    shading_pattern="stripes",  # 'stripes' or 'dots'
)

Standalone script

python ped2studio_standalone.py family.ped family.json
python ped2studio_standalone.py family.ped family.json --fill half --colour "#c0392b"
python ped2studio_standalone.py family.ped family.json --shading --pattern dots --fill half

MPED Support

MPED (Multi-Phenotype PED) files are automatically detected and handled. When an MPED file has multiple phenotype columns, each phenotype is assigned a distinct colour from the Pedigree Studio palette and a legend is generated mapping colours to phenotype names.

Visual mapping for multi-phenotype files:

Individual Status	Pedigree Studio Rendering
Affected for 1 phenotype	Solid fill with that phenotype's colour
Affected for 2-4 phenotypes	Quartered fill with each phenotype's colour
Carrier for 1 phenotype	Half fill (left) with that phenotype's colour
Carrier column = 3	Centre dot (●)
Unaffected	No fill

For single-phenotype MPED files, the --color, --fill, and --shading options work as normal.

PED file format

The tool reads the standard 6-column PED format:

FamilyID  IndividualID  FatherID  MotherID  Sex  Phenotype

Column	Description
FamilyID	Family identifier (preserved but not used for grouping)
IndividualID	Unique identifier for the individual
FatherID	Father's IndividualID, or 0 if unknown
MotherID	Mother's IndividualID, or 0 if unknown
Sex	1 = male, 2 = female, 0 = unknown
Phenotype	2 = affected, 1 = unaffected, 0 or -9 = unknown

Additional columns beyond column 6 (e.g. genotype data) are ignored. Lines starting with # are treated as comments. Both tab and space delimiters are supported.

How it works

1. Parse the PED file into individuals with parent references
2. Build mating units (each unique father+mother pair with their children)
3. Assign generations (founders = generation 0, children = max parent generation + 1)
4. Layout individuals using Pedigree Studio's default spacing (partner gap = 104px, child height = 130px, sibling spacing = 104px)
5. Emit a Pedigree Studio v4 session JSON with persons, partnerships, child links, and legend

The output can be imported directly into Pedigree Studio via the Import JSON button. Positions may need manual adjustment for complex pedigrees.

Mapping to Pedigree Studio features

PED field	Pedigree Studio feature
Sex = 1	male shape (square)
Sex = 2	female shape (circle)
Sex = 0	unknown shape (diamond)
Phenotype = 2	Solid colour fill, half colour fill, or shading pattern (configurable via --fill, --color, --shading, --pattern)
Phenotype = 1	No fill
Father+Mother pair	Partnership line
Child of a pair	Child link from partnership to individual

License

MIT