crstlmeth

Clinical and ReSearch Tool for anaLysis of METHylation data

crstlmeth is a modular toolkit for analyzing, visualizing, and inspecting tabix-indexed bedMethyl data.

It supports haplotype-resolved methylation analysis, copy-number visualization, cohort reference creation, CpG-level methylation profiles, and an interactive Streamlit web interface.

Features

• Command-line interface and Streamlit web UI
• Methylation and copy-number analysis from bgzipped .bedmethyl.gz files
• Haplotype-aware sample handling for hap1, hap2, and ungrouped tracks
• CMETH cohort references with region-level and CpG-level summaries
• Interactive CpG profile plots with genomic coordinates and CpG tables
• Support for built-in kits and custom BED region files
• Reproducible CLI workflows and structured logs

Installation

Requirements:

• Python >= 3.12
• tabix
• bgzipped and tabix-indexed .bedmethyl.gz input files

From PyPI

pip install crstlmeth

From source

git clone https://github.com/IHGGM-Aachen/crstlmeth.git
cd crstlmeth
pip install -e .

Development install

git clone https://github.com/IHGGM-Aachen/crstlmeth.git
cd crstlmeth
pip install -e ".[all]"

Usage

Launch the web interface

crstlmeth web

This starts the multi-page Streamlit app on port 8501.

Show available commands

crstlmeth --help
crstlmeth reference --help
crstlmeth plot --help

Create a CMETH reference

crstlmeth reference create \
  --kit regions.bed \
  --include-cpgs \
  --description "Example cohort reference" \
  -o reference.cmeth.gz \
  CTRL001_1.bedmethyl.gz \
  CTRL001_2.bedmethyl.gz \
  CTRL001_ungrouped.bedmethyl.gz \
  CTRL002_1.bedmethyl.gz \
  CTRL002_2.bedmethyl.gz \
  CTRL002_ungrouped.bedmethyl.gz

Validate a CMETH reference

crstlmeth reference validate reference.cmeth.gz

Plot a CpG methylation profile

crstlmeth plot cpg-profile \
  --cmeth reference.cmeth.gz \
  --region "SNURF:TSS-DMR" \
  --sample-track both_haps \
  --x-mode index \
  --export-cpg-table snurf_cpg_profile.tsv \
  --out-html snurf_cpg_profile.html \
  --out snurf_cpg_profile.png \
  SAMPLE_1.bedmethyl.gz \
  SAMPLE_2.bedmethyl.gz \
  SAMPLE_ungrouped.bedmethyl.gz

Plot methylation

crstlmeth plot methylation \
  --cmeth reference.cmeth.gz \
  --kit regions.bed \
  --out methylation.png \
  SAMPLE_ungrouped.bedmethyl.gz

Plot copy number

crstlmeth plot copynumber \
  --cmeth reference.cmeth.gz \
  --kit regions.bed \
  --out copy_number.png \
  SAMPLE_1.bedmethyl.gz \
  SAMPLE_2.bedmethyl.gz \
  SAMPLE_ungrouped.bedmethyl.gz

Input expectations

Input files must be bgzipped and tabix-indexed:

sample.bedmethyl.gz
sample.bedmethyl.gz.tbi

Supported sample role suffixes are:

SAMPLE_1.bedmethyl.gz
SAMPLE_2.bedmethyl.gz
SAMPLE_ungrouped.bedmethyl.gz

SAMPLE.1.bedmethyl.gz
SAMPLE.2.bedmethyl.gz
SAMPLE.ungrouped.bedmethyl.gz

SAMPLE-1.bedmethyl.gz
SAMPLE-2.bedmethyl.gz
SAMPLE-ungrouped.bedmethyl.gz

The web sample collector detects hap1, hap2, ungrouped, and matching .tbi files before running plots.

Region input

Regions can be provided as:

• built-in kit names, for example ME030, ME032, ME034, or MLPA_all
• custom BED files

Custom BED files should contain at least four columns:

chrom    start    end    name

Coordinates are expected to be BED-style zero-based half-open intervals.

CMETH references

CMETH references store cohort-level summary statistics.

A CMETH file can contain two feature levels:

feature_type = region
feature_type = cpg

Region rows store DMR-level aggregate summaries.

CpG rows store observed CpG or methylation-locus summaries inside each parent region. These rows are used for CpG-resolution profile plots.

Small clinical or demo CMETH references may be packaged under:

crstlmeth/refs/

Large genome-wide CpG references should be generated or downloaded as external artifacts instead of being committed into the Python package.

Development checks

Run the local test suite:

python -m py_compile $(find crstlmeth tests -name "*.py")
pytest -q

Build the package:

python -m build
twine check dist/*

Build the Docker image:

docker build -t crstlmeth:dev .
docker run --rm crstlmeth:dev crstlmeth --help

License

MIT. See LICENSE.