Metadata-Version: 2.4
Name: mpedtools
Version: 0.1.0
Summary: Tools for working with PED and MPED (multi-phenotype PED) pedigree files
Author-email: Tim Hearn <tjh70@cam.ac.uk>
License: MIT
Project-URL: Homepage, https://github.com/comparativechrono/mpedtools
Project-URL: Issues, https://github.com/comparativechrono/mpedtools/issues
Keywords: pedigree,genetics,ped,mped,phenotype,clinical-genetics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
pip install mpedtools
```

## Quick Start

### Command line

```bash
# 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

```python
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
