mpedtools

Tools for working with PED and MPED (multi-phenotype PED) pedigree files. Read, write, validate, extract, merge, split, convert, and query pedigree data.

Installation

pip install mpedtools

Quick Start

Command line

# Show file summary
mpedtools info family.mped

# Validate a file
mpedtools validate family.ped

# Extract one phenotype from an MPED as a standard PED
mpedtools extract family.mped Breast_cancer -o breast_cancer.ped

# Extract all phenotypes as separate PED files
mpedtools extract-all family.mped -d ./output/

# Merge multiple PED files into one MPED
mpedtools merge pheno1.ped pheno2.ped -o combined.mped -n Condition_A Condition_B

# Split multi-family file into one file per family
mpedtools split multi_family.ped -d ./output/

# Convert between formats
mpedtools convert family.mped -f ped -o family.ped --phenotype Breast_cancer
mpedtools convert family.ped -f mped -o family.mped

# Add or remove phenotype columns
mpedtools add-phenotype family.mped New_condition -o updated.mped
mpedtools remove-phenotype family.mped Old_condition -o updated.mped

Python API

import mpedtools

# Read any PED or MPED file
ped = mpedtools.read("family.mped")

# Inspect
print(f"Families: {ped.families}")
print(f"Phenotypes: {ped.phenotype_names}")
print(f"Individuals: {len(ped.individuals)}")

# Summarise
print(mpedtools.summarise(ped))

# Validate
issues = mpedtools.validate(ped)
for issue in issues:
    print(f"[{issue.level}] {issue.message}")

# Query
affected = ped.get_affected("Breast_cancer")
carriers = ped.get_carriers("BRCA1")

# Extract single phenotype
breast = mpedtools.extract_phenotype(ped, "Breast_cancer")
mpedtools.write(breast, "breast.ped", force_format="ped")

# Merge
ped1 = mpedtools.read("condition_a.ped")
ped2 = mpedtools.read("condition_b.ped")
merged = mpedtools.merge([ped1, ped2], ["Condition_A", "Condition_B"])
mpedtools.write(merged, "combined.mped")

# Split families
families = mpedtools.split_families(ped)
for fam in families:
    mpedtools.write(fam, f"{fam.families[0]}.ped")

# Add/remove columns
updated = mpedtools.add_phenotype(ped, "New_condition", default_value=0)
trimmed = mpedtools.remove_phenotype(ped, "Old_condition")

# Parse from string
ped = mpedtools.parse(ped_text_string)

# Format to string
text = mpedtools.format_output(ped, force_format="mped")

MPED Format

The MPED (Multi-Phenotype PED) format extends the standard PED format for tracking multiple conditions. See MPED-SPECIFICATION-v1.0.md for the full specification.

Key differences from PED:

• Header line declares format version and phenotype column names
• Multiple phenotype columns (one per condition)
• Code 3 = carrier (in addition to 0=unknown, 1=unaffected, 2=affected)
• File extension: .mped

Supported Operations

Command	Description
info	Summary statistics for a PED or MPED file
validate	Check file structure, parent references, sex codes
extract	Pull one phenotype column into a standard PED file
extract-all	Extract every phenotype as a separate PED file
merge	Combine multiple PED files into one MPED
split	Separate multi-family files into one file per family
convert	Convert between PED and MPED formats
add-phenotype	Add a new phenotype column
remove-phenotype	Remove a phenotype column

License

MIT