Metadata-Version: 2.4
Name: pype-mr
Version: 1.0.0
Summary: PheWAS analysis, visualization, and Mendelian randomization in Python
Author: Taykhoom Dalal
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/TaykhoomDalal/pype
Project-URL: Documentation, https://taykhoomdalal.github.io/pype/
Project-URL: Issues, https://github.com/TaykhoomDalal/pype/issues
Project-URL: Paper, https://doi.org/10.1016/j.patter.2024.100982
Keywords: biobank,mendelian-randomization,phenome-wide-association-study,phewas
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: matplotlib>=3.7
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: statsmodels>=0.14
Requires-Dist: textalloc>=1.2.3
Provides-Extra: annotations
Requires-Dist: mygene>=3.2; extra == "annotations"
Requires-Dist: myvariant>=1.0; extra == "annotations"
Provides-Extra: test
Requires-Dist: build>=1.2; extra == "test"
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

<h1 align="center">
  <img src="assets/pype_logo.png" width="48" alt="">
  <img src="docs/assets/pype_wordmark.png" width="180" alt="PYPE">
</h1>

<p align="center"><strong>Python pipeline for PheWAS and Mendelian randomization</strong></p>

PYPE runs phenome-wide association studies (PheWAS), creates PheWAS plots, and performs Mendelian randomization (MR) in Python.

[User guide](https://taykhoomdalal.github.io/pype/) | [Roadmap](https://taykhoomdalal.github.io/pype/roadmap.html) | [Reference paper](https://doi.org/10.1016/j.patter.2024.100982)

## Features

- PheWAS with genotype or phenotype predictors
- Covariate-adjusted linear regression
- Bonferroni, Sidak, and Benjamini-Hochberg correction
- Manhattan, volcano, and category enrichment plots
- Variant-to-gene mapping and optional BioThings annotations
- Eleven MR methods, including MR-Egger, weighted median, weighted mode, and MR-PRESSO

## Installation

```bash
python -m pip install pype-mr
```

Optional annotation dependencies:

```bash
python -m pip install "pype-mr[annotations]"
```

## Reproduce the paper

The public Mendelian randomization analyses can be rerun from a GitHub source checkout using the Le Goallec and Neale Lab summary statistics:

```bash
python -m pip install -e . openpyxl
python reproducibility/reproduce_paper.py
```

See [`reproducibility/README.md`](reproducibility/README.md) for the data boundary and expected outputs.

## PheWAS

Pass one dataframe containing phenotypes and covariates, and another containing the predictors. Both dataframes must have the same sample index.

```python
import pandas as pd
import pype

phenotypes = pd.DataFrame({
    "trait_a": [1.2, 2.0, 1.5, 3.1],
    "trait_b": [0.0, 1.0, 0.0, 1.0],
    "age": [50, 61, 47, 70],
})

predictors = pd.DataFrame({
    "variant_1": [0, 1, 1, 2],
})

results = pype.phenome_wide_association(
    phenotypes,
    predictors,
    outcomes=["trait_a", "trait_b"],
    covariates=["age"],
    min_sample_count=3,
)
```

The result uses consistent snake_case columns: `outcome`, `predictor`, `sample_count`, `total_sample_count`, `negative_log10_pvalue`, `pvalue`, `beta`, and `standard_error`.

## Plotting

Plots use the PheWAS result dataframe plus a small metadata table containing phenotype descriptions and categories.

```python
import pandas as pd
import pype
from pype.plotting import category_enrichment, manhattan, volcano

metadata = pd.DataFrame({
    "outcome": ["trait_a", "trait_b"],
    "description": ["Trait A", "Trait B"],
    "category": ["Measurements", "Diagnoses"],
})
results = pype.add_phenotype_metadata(results, metadata)

manhattan(results, "manhattan.png")
category_enrichment(results, "category_enrichment.png")
volcano(results, "volcano.png")
```

## Mendelian randomization

Exposure and outcome dataframes must contain:

| Column | Description |
| --- | --- |
| `variant_id` | Variant identifier |
| `chromosome` | Chromosome |
| `effect_allele` | Effect allele |
| `other_allele` | Other allele |
| `beta` | Effect estimate |
| `standard_error` | Standard error |
| `pvalue` | P-value |
| `sample_size` | Sample size, optional |

```python
import pandas as pd
import pype

exposure = pd.read_csv("exposure.tsv", sep="\t")
outcome = pd.read_csv("outcome.tsv", sep="\t")

results, diagnostics = pype.mendelian_randomization(
    exposure,
    outcome,
    exposure_name="exposure_trait",
    outcome_name="outcome_trait",
    methods=("ivw", "egger", "weighted_median"),
    seed=0,
)
```

Use `methods="all"` to run every available method. PYPE aligns effect alleles, flips reversed effects, and removes incompatible or ambiguous palindromic variants before analysis.

Available methods:

- Inverse variance weighted
- MR-Egger
- Simple, weighted, and penalized weighted median
- Simple, weighted, penalized, and NOME mode estimators
- MR-PRESSO

## Data

Tests use synthetic data. Study data are supplied by users under the access terms of their data source.

## License

Apache License 2.0. See `LICENSE.md`.

## Citation

```bibtex
@article{Dalal2024PYPE,
  title   = {PYPE: A pipeline for phenome-wide association and Mendelian randomization in investigator-driven biobank scale analysis},
  author  = {Dalal, Taykhoom and Patel, Chirag J.},
  journal = {Patterns},
  year    = {2024},
  volume  = {5},
  number  = {6},
  pages   = {100982},
  doi     = {10.1016/j.patter.2024.100982},
  url     = {https://doi.org/10.1016/j.patter.2024.100982}
}
```
