betasieve 0.2.0

Filter-first analysis of EPICv2 duplicate CpG probes.

betaSieve

EPICv2 probe designs analysis

betaSieve is a Python package that identifies HumanMethylationEPIC v2.0 BeadChip (EPICv2) probes that exhibit high variability between measurements of different probe designs. To do so, the package evaluates probe design agreement by analyzing beta-value differences for each (CpG site, sample) pair.

Why should I care?

EPICv2 can measure the same CpG site with several probe designs. Those designs appear as separate IlmnID rows, and we observed that their β-values can disagree for the same sample.

IlmnID naming and replicate definitions adapted from Peters et al. (2024), BMC Genomics 25:251, and Supplementary File 4 (doi:10.1186/s12864-024-10027-5).

betaSieve finds sites where design disagreement is larger than expected from exact technical replicates. It can thus help to refine downstream analyses.

Please have a look at the wiki for a more detailed explanation of the background and theory behind this package.

---

Features

1. Analysis of EPICv2 IlmnIDs with different probe designs.
2. Optional threshold sweep across user-defined beta-value differences.
3. Identification of highly variable candidate IlmnIDs that should be flagged.

---

Installation

From GitHub

pip install betasieve

Dependencies are installed automatically.

---

Quick Start

Python API

from pathlib import Path
from betasieve import SieveArgs, run_beta_sieve

args = SieveArgs(
    betas_path=Path("betas.csv"),
    threshold_min=0.03,
    threshold_max=0.07,
    threshold_step=0.01,
)

results = run_beta_sieve(args)

n_candidates = (
    0 if results.candidate_cpgs is None
    else len(results.candidate_cpgs)
)

print(
    f"Threshold: {results.threshold}, "
    f"candidates: {n_candidates}"
)

Command Line

betasieve \
  --betas betas.csv \
  --threshold_min 0.03 \
  --threshold_max 0.07 \
  --threshold_step 0.01

---

Citation

If you use betaSieve in published work, please cite:

Streicher M. betaSieve: Filter-first analysis of EPICv2 duplicate CpG probes. GitHub repository. 2026.

For EPICv2 probe naming and replicate definitions (as used in the overview figure above), please also cite:

Peters TJ, Meyer B, Ryan L, Achinger-Kawecka J, Song J, Campbell EM, Qu W, Nair S, Loi-Luu P, Stricker P, Lim E, Stirzaker C, Clark SJ, Pidsley R. Characterisation and reproducibility of the HumanMethylationEPIC v2.0 BeadChip for DNA methylation profiling. BMC Genomics. 2024;25:251. https://doi.org/10.1186/s12864-024-10027-5

---

License

BSD 3-Clause License (see LICENSE).

---

Parameters

betaSieve can be configured either through the Python API (SieveArgs) or through the command-line interface.

Required Parameters

betas_path

Path to the input beta-value matrix.

Expected format:

• Rows correspond to CpG probes.
• Columns correspond to samples.
• Values must be beta values between 0 and 1.

Example:

betas_path=Path("betas.csv")

---

Threshold Selection

betaSieve requires either:

1. A fixed threshold (threshold)
2. An automatic threshold search (threshold_min, threshold_max, threshold_step)

threshold

Fixed beta-value difference threshold used to determine whether duplicate probes are considered concordant.

Range:

(0, 1]

Example:

threshold=0.05

---

threshold_min

Minimum threshold evaluated during automatic threshold search.

Example:

threshold_min=0.03

---

threshold_max

Maximum threshold evaluated during automatic threshold search.

Example:

threshold_max=0.07

---

threshold_step

Increment between tested thresholds.

Example:

threshold_step=0.01

The above configuration evaluates:

0.03, 0.04, 0.05, 0.06, 0.07

---

Statistical Parameters

fdr

Method used for multiple-testing correction. betaSieve does not implement these procedures itself; it passes the chosen method to statsmodels.stats.multitest.multipletests from the statsmodels package (source).

Default:

fdr="fdr_bh"

Available methods (as supported by statsmodels.stats.multitest.multipletests):

Method	Description
bonferroni	Bonferroni correction
sidak	Sidak correction
holm-sidak	Holm-Sidak procedure
holm	Holm procedure
simes-hochberg	Simes-Hochberg procedure
hommel	Hommel procedure
fdr_bh	Benjamini-Hochberg FDR
fdr_by	Benjamini-Yekutieli FDR
fdr_tsbh	Two-stage Benjamini-Hochberg
fdr_tsbky	Two-stage Benjamini-Krieger-Yekutieli

---

confidence

Confidence level used for confidence interval calculations.

Default:

confidence=0.95

Typical values:

Value	Interpretation
0.90	90% confidence interval
0.95	95% confidence interval
0.99	99% confidence interval

---

target_p0

Target false-positive rate used internally during threshold optimization.

Default:

target_p0=0.05

---

Output Parameters

out_dir

Directory where all results are written.

Default:

out_dir=Path("results")

Generated structure:

results/
├── csv/
├── figures/
├── report/
└── pkl/

---

report

Generate an HTML summary report.

Default:

report=True

Disable report generation:

report=False

---

pkl

Save intermediate Python objects as pickle files.

Default:

pkl=False

---

Examples

Fixed Threshold

args = SieveArgs(
    betas_path=Path("betas.csv"),
    threshold=0.05,
)

Automatic Threshold Search

args = SieveArgs(
    betas_path=Path("betas.csv"),
    threshold_min=0.03,
    threshold_max=0.07,
    threshold_step=0.01,
)