MethylSeg

MethylSeg is a Python toolkit for identifying methylation domains from whole-genome bisulfite sequencing (WGBS) and microarray methylation data. It supports data preparation, methylation-state model training, genome segmentation, region cleaning, and visualization.

This introduces the standard workflow. For the complete API reference and example notebooks, see the MethylSeg documentation.

Hardware requirements

Memory usage depends on the input data type and dataset size. The following values were observed during testing:

Installation

Install from PyPI

python -m pip install methylseg

or install the current version from GitHub:

python -m pip install "git+https://github.com/clementlab/MethylSeg.git"

Reference files

Sample data

Three reference samples are available for use in tutorials and testing.

methylseg download_data_files

The two colon cancer samples were originally generated by Hansen et al. (2011) and were obtained from the data distributed with MethyLasso (Balaramane et al., 2024).

The liver cancer sample, TCGA-BD-A3EP-01A, was obtained from the TCGA-LIHC project through the NCI Genomic Data Commons.

References

1. Hansen, K. D., et al. Increased methylation variation in epigenetic domains across cancer types. Nature Genetics 43, 768–775 (2011).
2. Balaramane, D., Spill, Y. G., Weber, M. & Bardet, A. F. MethyLasso: a segmentation approach to analyze DNA methylation patterns and identify differentially methylated regions from whole-genome datasets. Nucleic Acids Research 52, e98 (2024).

Pretrained models

Two pretrained models are provided for tutorials, testing, and exploratory analysis:

Load a pretrained model with get_pretrained_model:

# WGBS model
wgbs_saved = MethylSegPathway.get_pretrained_model(
    out_dir=OUTPUT_DIR,
    resolution="wgbs",
)

# HM450K model
hm450k_saved = MethylSegPathway.get_pretrained_model(
    out_dir=OUTPUT_DIR,
    resolution="450k",
)

Quickstart

The default workflow trains a model on your input, segments the sample, cleans the calls, and draws a cleaned methylation state overlay.

Use resolution="wgbs" for WGBS count tables or resolution="450k" for HM450K beta-value tables. Other microarray platforms may require manually configured parameters until array-specific defaults are added.

from pathlib import Path

from methylseg import MethylSegPathway, MethylationStates
from methylseg.helper_classes import DATA_DIR

reference_dir = DATA_DIR / "reference_files"

# WGBS: replace these with your own sample name and count table.
# sample_name = "WGBS_colon-primary-tumor_1"
# sample_file = reference_dir / "WGBS_colon-primary-tumor_1_wgbs.tsv.gz"
# resolution = "wgbs"

# TCGA/HM450K alternative:
sample_name = "TCGA-BD-A3EP-01A"
sample_file = reference_dir / "TCGA-BD-A3EP-01A_450k.tsv.gz"
resolution = "450k"

sample_info, removed_df = MethylSegPathway.prepare_sample_info(
    sample_name=sample_name,
    sample_file=sample_file,
    resolution=resolution,
    remove_low_coverage_like_cpgs=True,
)

pathway = MethylSegPathway(
    train_sample_info=sample_info,
    out_dir=Path("out/quickstart") / sample_name,
)

pathway.run_pathway()

fig = pathway.plot_labels(
    sample_info=sample_info,
    sample_info_removed=removed_df,
    chrom="chr1",
    region_start=2_200_000,
    region_end=3_700_000
)

run_pathway(sample_info=sample_info, chroms=["chr1"]) performs fitting, segmentation, cleaning, and summary-file writing in one call.

Input formats

MethylSeg accepts tab-delimited .tsv and .tsv.gz files containing DNA methylation measurements. Genomic coordinates must use the 0-based, half-open coordinate system, and chromosome names must be consistent throughout each file.

Two BED-like input formats are supported.

Beta-value format

This format can be used for either WGBS or microarray data. It contains four required columns:

1. chromosome;
2. CpG start position;
3. CpG end position; and
4. methylation beta value.

For microarray data, an optional fifth column containing the probe identifier may be included. Probe identifiers are retained as metadata.

WGBS count format

This format contains five required columns:

1. chromosome;
2. CpG start position;
3. CpG end position;
4. methylated read count; and
5. total read coverage.

MethylSeg calculates the beta value internally as: $ \mathrm{beta} = \frac{\mathrm{methylated\ reads}}{\mathrm{total\ coverage}}. $

Outputs

The final output of MethylSeg consists primarily of BED files containing the identified methylation domains. Separate files are generated for each methylation state: HIGH, INTERMEDIATE, LOW, and PMD.

For each chromosome and state, MethylSeg writes:

After all requested chromosomes have been processed, MethylSeg also creates genome-wide files for each state under summary_files/:

A simplified output directory has the following structure:

methylseg_output/
├── segments_chr1_sample.wgbs_PMD.bed
├── segments_chr1_sample.wgbs_LOW.bed
├── clean_regions/
│   ├── segments_cleaned_chr1_sample.wgbs_PMD.bed
│   ├── segments_cleaned_chr1_sample.wgbs_LOW.bed
│   ├── metadata_cleaned_chr1_sample.wgbs_PMD.tsv
│   └── metadata_cleaned_chr1_sample.wgbs_LOW.tsv
└── summary_files/
    ├── segments_raw_PMD.bed
    ├── segments_raw_LOW.bed
    ├── segments_cleaned_PMD.bed
    ├── segments_cleaned_LOW.bed
    ├── metadata_cleaned_PMD.tsv
    └── metadata_cleaned_LOW.tsv

Each BED file contains 0-based, half-open genomic coordinates and the assigned methylation state. For example, segments_cleaned_PMD.bed may contain:

The BED files themselves are tab-delimited and do not contain a header.

Citation

If you use MethylSeg, please cite the software using the CITATION.cff metadata. On GitHub, select Cite this repository to copy the citation in APA or BibTeX format.

A manuscript describing MethylSeg is in preparation. Its citation will be added when available.

Planned support

See ROADMAP.md

Reporting issues

To report a bug, request a feature, or ask a question about MethylSeg, open an issue on the GitHub issue tracker.

When reporting a bug, please include:

• Your MethylSeg version
• Your Python version and operating system
• The complete error message or traceback
• A minimal example that reproduces the problem, when possible

License

MethylSeg is distributed under the BSD 3-Clause License.