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.

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.

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.

pip install betasieve

Dependencies are installed automatically.

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}"
)

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

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

BSD 3-Clause License (see LICENSE).

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

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")

betaSieve requires either:

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

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

Range:

(0, 1]

Example:

threshold=0.05

Minimum threshold evaluated during automatic threshold search.

Example:

threshold_min=0.03

Maximum threshold evaluated during automatic threshold search.

Example:

threshold_max=0.07

Increment between tested thresholds.

Example:

threshold_step=0.01

The above configuration evaluates:

0.03, 0.04, 0.05, 0.06, 0.07

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):

Confidence level used for confidence interval calculations.

Default:

confidence=0.95

Typical values:

Target false-positive rate used internally during threshold optimization.

Default:

target_p0=0.05

Directory where all results are written.

Default:

out_dir=Path("results")

Generated structure:

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

Generate an HTML summary report.

Default:

report=True

Disable report generation:

report=False

Save intermediate Python objects as pickle files.

Default:

pkl=False

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

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