API reference

Public dataframe columns and Python identifiers use snake_case. Counts end in _count, p-values use pvalue, and uncertainty uses standard_error.

Top-level functions

The three main functions are available directly from import pype.

`pype.phenome_wide_association`

View source

phenome_wide_association(
    phenotypes,
    predictors,
    outcomes=None,
    covariates=None,
    min_sample_count=1000,
)

Run each predictor against each selected outcome with complete-case ordinary least squares.

Parameter	Description
`phenotypes`	Dataframe containing outcomes and covariates.
`predictors`	Dataframe containing one or more numeric predictors with the same index.
`outcomes`	Outcome column names. Defaults to every phenotype column outside `covariates`.
`covariates`	Optional covariate column names.
`min_sample_count`	Minimum complete-case sample count required for a regression result.

Returns: A dataframe sorted by pvalue. See result columns.

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

`pype.add_phenotype_metadata`

View source

add_phenotype_metadata(
    results,
    metadata,
    result_field="outcome",
    metadata_field="outcome",
    description_column="description",
    category_column="category",
)

Join phenotype descriptions and plotting categories to PheWAS results.

Parameter	Description
`results`	PheWAS result dataframe.
`metadata`	Metadata dataframe or path to a delimited file.
`result_field`	Identifier column in the result dataframe.
`metadata_field`	Matching identifier column in metadata.
`description_column`	Optional readable description column.
`category_column`	Required plotting category column.

Returns: A copy of the result dataframe with category and optional description.

`pype.mendelian_randomization`

View source

mendelian_randomization(
    exposure,
    outcome,
    exposure_name="exposure",
    outcome_name="outcome",
    methods=("ivw", "egger", "weighted_median"),
    config=None,
    seed=None,
)

Validate and harmonize exposure and outcome summary statistics, then run selected MR estimators.

Parameter	Description
`exposure`	Exposure summary-statistic dataframe.
`outcome`	Outcome summary-statistic dataframe.
`exposure_name`	Name written into output column names and diagnostics.
`outcome_name`	Outcome label written to the result dataframe.
`methods`	Method key, iterable of keys, or `"all"`.
`config`	Optional method parameter dictionary. Defaults load from `pype.mr/defaults.json`.
`seed`	Seed for bootstrap and empirical-distribution methods.

Returns: (results, diagnostics). Results use method, exposure, outcome, pvalue, beta, standard_error, and variant_count. Diagnostics contains heterogeneity, MR-Egger intercept, and MR-PRESSO results when requested.

Method keys are listed on the MR methods page.

Configuration keys

Key	Used by
`bootstrap_iterations`	Median and mode standard errors.
`penalty_constant`	Penalized median and penalized mode.
`bandwidth_scale`	Mode estimators.
`run_outlier_test`	MR-PRESSO outlier detection.
`run_distortion_test`	MR-PRESSO corrected-estimate comparison.
`significance_threshold`	MR-PRESSO tests.
`simulation_count`	MR-PRESSO empirical distributions.

Plotting

`pype.plotting.manhattan`

View source

manhattan(
    results,
    output,
    alpha=0.05,
    correction="bonferroni",
    title=None,
    annotate=False,
    annotation_count=2,
    annotation_width=30,
    color_map="tab20",
    seed=None,
    width=15,
    height=8,
    dpi=300,
)

Plot association significance by phenotype category. Writes the image and a significant-result TSV.

`pype.plotting.category_enrichment`

View source

category_enrichment(
    results,
    output,
    alpha=0.05,
    correction="bonferroni",
    title=None,
    width=15,
    height=8,
    dpi=300,
)

Plot the percentage of significant associations within each phenotype category.

`pype.plotting.volcano`

View source

volcano(
    results,
    output,
    alpha=0.05,
    correction="bonferroni",
    title=None,
    annotate=False,
    annotation_count=5,
    annotation_width=30,
    width=15,
    height=8,
    dpi=300,
)

Create one effect-size versus significance plot per predictor. Writes images and significant-result TSVs.

Annotations

`pype.annotations.annotate_genes`

View source

annotate_genes(
    gene_intervals_file,
    variants,
    results,
    upstream_kb=10,
    downstream_kb=10,
    output_directory=None,
    output_prefix="pype",
)

Find genes whose intervals fall within the selected upstream and downstream distances from each variant.

variants requires variant_id, chromosome, and position. Distances are in kilobases. See gene interval format.

`pype.annotations.annotate_variants_and_genes`

View source

annotate_variants_and_genes(
    results,
    output_directory,
    variant_fields=("dbsnp",),
    gene_fields=("summary",),
)

Write one summary file per significant variant using MyVariant.info and MyGene.info. Install the annotations extra first.

MR utilities

`pype.mr.harmonize`

View source

harmonize(exposure, outcome)

Match variants by variant_id and chromosome, align allele pairs, flip reversed outcome effects, and remove incompatible or ambiguous palindromic rows.

`pype.mr.standardize_variants`

View source

standardize_variants(data)

Validate required summary-statistic columns, normalize chromosome and allele values, and resolve duplicates with sample size.

Common exceptions

Condition	Exception
Phenotype and predictor indexes differ	`ValueError`
Requested outcome, covariate, metadata, or MR columns are missing	`ValueError`
Exposure and outcome names are identical	`ValueError`
An unsupported MR method key is supplied	`ValueError`
Variants do not overlap or all fail harmonization	`ValueError`
Optional annotation clients are unavailable	`ImportError`