methylseg.MethylSegPathway

class methylseg.MethylSegPathway(n_states=4, int_low_cutoff=0.2, int_high_cutoff=0.7, high_cutoff=0.7, window_specs=None, train_sample_info=None, train_sample_file=None, train_sample_name=None, train_chroms=None, max_cpg_per_chrom=50000, state_assignment_method=MethylStateAssignmentMethod.KMEANS, out_dir='.', random_state=42, cluster_space='pca', n_pca=5, hmm_type=None, hmm_params=None, min_region_length=5000, min_region_cpgs=6, merge_gap_bp=100000, merge_with_intermediate=True, merge_with_intermediate_gap_bp=100000)[source]

Bases: object

High-level API that coordinates preparation, training, and segmentation.

Parameters:

  • n_states (int)

  • int_low_cutoff (float)

  • int_high_cutoff (float)

  • high_cutoff (float)

  • window_specs (list[tuple[int, str]] | None)

  • train_sample_info (SampleInfo | None)

  • train_sample_file (str | None)

  • train_sample_name (str | None)

  • train_chroms (list[str] | None)

  • max_cpg_per_chrom (int | None)

  • state_assignment_method (MethylStateAssignmentMethod)

  • out_dir (str)

  • random_state (int)

  • cluster_space (str)

  • n_pca (int | None)

  • hmm_type (HMMType | None)

  • hmm_params (dict | None)

  • min_region_length (int)

  • min_region_cpgs (int)

  • merge_gap_bp (int)

  • merge_with_intermediate (bool)

  • merge_with_intermediate_gap_bp (int)

__init__(n_states=4, int_low_cutoff=0.2, int_high_cutoff=0.7, high_cutoff=0.7, window_specs=None, train_sample_info=None, train_sample_file=None, train_sample_name=None, train_chroms=None, max_cpg_per_chrom=50000, state_assignment_method=MethylStateAssignmentMethod.KMEANS, out_dir='.', random_state=42, cluster_space='pca', n_pca=5, hmm_type=None, hmm_params=None, min_region_length=5000, min_region_cpgs=6, merge_gap_bp=100000, merge_with_intermediate=True, merge_with_intermediate_gap_bp=100000)[source]

Initialize a complete methylation-state training and segmentation pathway.

Parameters:

  • n_states (int) – Number of biological methylation states to model.

  • int_low_cutoff (float) – Upper beta cutoff used to identify low-intermediate states.

  • int_high_cutoff (float) – Lower beta cutoff used to identify high-intermediate states.

  • high_cutoff (float) – Beta cutoff used to identify highly methylated states.

  • window_specs (list[tuple[int, str]] | None) – Optional (window_size_bp, label) specifications for regional emission features. Defaults depend on sample resolution.

  • train_sample_info (SampleInfo | None) – Prepared training sample. Provide this or both file-based training arguments.

  • train_sample_file (str | None) – Path to a methylation table used to prepare the training sample.

  • train_sample_name (str | None) – Sample identifier paired with train_sample_file.

  • train_chroms (list[str] | None) – Optional chromosomes used when fitting the pathway.

  • max_cpg_per_chrom (int | None) – Optional cap on CpGs retained per chromosome during training.

  • state_assignment_method (MethylStateAssignmentMethod) – Method used to assign biological states from emission features.

  • out_dir (str) – Directory for fitted artifacts, segment outputs, and plots.

  • random_state (int) – Random seed used by trainable components.

  • cluster_space (str) – Feature space used for KMeans clustering, such as "pca".

  • n_pca (int | None) – Number of PCA components retained when PCA clustering is used.

  • hmm_type (HMMType | None) – HMM backend to construct. Defaults depend on sample resolution.

  • hmm_params (dict | None) – Optional backend-specific HMM configuration mapping.

  • min_region_length (int) – Minimum genomic length in base pairs for retained regions.

  • min_region_cpgs (int) – Minimum CpG count required for retained regions.

  • merge_gap_bp (int) – Maximum gap in base pairs for merging adjacent same-state regions.

  • merge_with_intermediate (bool) – If True, allow nearby compatible regions to merge across intermediate-state intervals.

  • merge_with_intermediate_gap_bp (int) – Maximum intermediate-state gap in base pairs permitted for that merge operation.

Methods

__init__([n_states, int_low_cutoff, ...])

Initialize a complete methylation-state training and segmentation pathway.

fit_pathway([force_optimize_rules])

Train the KMeans assignment model and optional rule-based cutoffs.

from_yaml(yaml_path[, load_learned])

Reconstruct MethylSegPathway from YAML file.

generate_regions([sample_info, chrom, ...])

Segment one chromosome and return its length-filtered regions.

get_clean_regions([regions_df, ...])

Build cleaned region tracks from the raw segmentation and write them to disk.

get_pretrained_model(out_dir[, resolution, ...])

Load a packaged pretrained pathway configuration.

plot_embedding(*[, label_source, ...])

Plot PCA or UMAP embeddings for training or sample-level labels.

plot_labels(*[, label_source, sample_info, ...])

Plot genomic labels for one chromosome with optional region overlays.

prepare_sample_info(sample_name, sample_file)

Prepare a methylation file into the package's canonical sample schema.

run_on_all_chroms([sample_info, chroms, ...])

Segment a sample across all requested chromosomes and write summaries.

run_pathway([sample_info, chroms, ...])

Fit the pathway and run end-to-end segmentation for a sample.

set_out_dir(out_dir)

Update the output directory across the pathway and owned components.

subset_sample_info_by_chroms(sample_info[, ...])

Return a copy of SampleInfo restricted to selected chromosomes.

to_yaml(yaml_path[, include_learned, ...])

Serialize pathway configuration and optionally learned artifacts.
classmethod get_pretrained_model(out_dir, resolution='450k', download_if_missing=False)[source]

Load a packaged pretrained pathway configuration.

Parameters:

  • out_dir – Output directory to attach to the loaded pathway.

  • resolution – Reference model family to load, typically "450k" or WGBS.

  • download_if_missing – If True, download packaged model artifacts when the local files are missing or still Git LFS pointers.

Returns:

Restored pretrained pathway ready for segmentation.

Return type:

MethylSegPathway

Raises:

FileNotFoundError – If the requested pretrained model is unavailable locally and download_if_missing is False.

static prepare_sample_info(sample_name, sample_file, resolution='auto', min_coverage=10, remove_low_coverage_like_cpgs=False)[source]

Prepare a methylation file into the package’s canonical sample schema.

Parameters:

  • sample_name (str) – Identifier to assign to the prepared sample.

  • sample_file (str | Path) – Path to the methylation input table.

  • resolution (str) – Input format hint passed through to MethylDataPrep.

  • min_coverage (int) – Minimum WGBS coverage threshold when WGBS-style inputs are used.

  • remove_low_coverage_like_cpgs (bool) – Whether to remove beta values that resemble very low-coverage WGBS counts.

Returns:

(sample_info, removed_df) from MethylDataPrep.prepare.

Return type:

tuple

static subset_sample_info_by_chroms(sample_info, chroms=None)[source]

Return a copy of SampleInfo restricted to selected chromosomes.

Parameters:

  • sample_info (SampleInfo) – Prepared sample whose methylation table should be filtered.

  • chroms (List[str] | None) – Optional chromosome list. When omitted, preserves the full set and original chromosome order.

Returns:

New sample object containing only the requested chromosomes.

Return type:

SampleInfo

Raises:

ValueError – If the sample contains no methylation rows or the requested chromosomes are missing.

set_out_dir(out_dir)[source]

Update the output directory across the pathway and owned components.

Parameters:

out_dir (str | Path) – New output directory. It is created if needed.

Return type:

None

fit_pathway(force_optimize_rules=False)[source]

Train the KMeans assignment model and optional rule-based cutoffs.

Parameters:

force_optimize_rules (bool) – If True, rerun rule optimization even when KMeans labeling is the active state-assignment method.

generate_regions(sample_info=None, chrom='chr1', min_probes=3, sample_name=None, sample_file=None, force_resegment=False)[source]

Segment one chromosome and return its length-filtered regions.

Parameters:

  • sample_info (SampleInfo | None) – Prepared sample to segment. When omitted, uses the configured training sample or resolves sample_name/sample_file.

  • chrom (str) – Chromosome to segment.

  • min_probes (int) – Minimum number of probes required per raw contiguous region before downstream length filtering.

  • sample_name (str | None) – Alternate inputs used to prepare sample_info on the fly.

  • sample_file (str | None) – Alternate inputs used to prepare sample_info on the fly.

  • force_resegment (bool) – If True, ignore cached segmentation results and rerun the HMM.

Returns:

Region table for the requested chromosome after applying min_region_length filtering. BED files are also written to out_dir as a side effect.

Return type:

pandas.DataFrame

get_clean_regions(regions_df=None, merge_gap_bp=None, min_region_length=None, min_cpgs=None, sample_id=None, chrom=None, merge_with_intermediate=None, merge_with_intermediate_gap_bp=None, generate_summary_files=True)[source]

Build cleaned region tracks from the raw segmentation and write them to disk.

The cleaning logic is chromosome-local and proceeds left-to-right over the full sorted segmentation table. Per-chromosome cleaned outputs are written to clean_regions/ as chromosome-local BED and metadata TSV artifacts. When chrom is omitted, optional combined summary files can also be written to summary_files/segments_cleaned_{STATE}.bed and summary_files/metadata_cleaned_{STATE}.tsv.

The metadata TSV is the full cleaned record used by plotting; the BED is the slim interval export.

When merge_with_intermediate is true, cleaned LOW, PMD, and HIGH regions may each absorb adjacent Intermediate segments if they are close enough under merge_with_intermediate_gap_bp. Raw state labels are never relabeled in regions_df; only the cleaned non-intermediate outputs reflect the absorbed transitional segments.

Parameters:

  • regions_df (DataFrame | None) – Raw segmentation table. If omitted, uses self.segmentor.regions_df.

  • merge_gap_bp (int | None) – Maximum gap for ordinary same-state merging.

  • min_region_length (int | None) – Minimum cleaned region length retained after merging.

  • min_cpgs (int | None) – Minimum cleaned region probe count retained after merging.

  • sample_id (str | None) – Optional sample identifier used in per-chrom cleaned filenames.

  • chrom (str | None) – If provided, clean only this chromosome and write only chromosome-local cleaned artifacts for it.

  • merge_with_intermediate (bool | None) – Whether cleaned non-intermediate regions may absorb adjacent Intermediate segments.

  • merge_with_intermediate_gap_bp (int | None) – Maximum gap allowed when a state merges through Intermediate.

  • generate_summary_files (bool) – When chrom is None, also build combined cleaned summary files.

Returns:

A mapping of combined cleaned summary BED paths plus the directory that holds the per-chromosome cleaned artifacts. The summary mapping is empty when summary generation is skipped.

Return type:

tuple[dict[MethylationStates, Path], Path]

run_on_all_chroms(sample_info=None, chroms=None, min_probes=5, force_resegment=False, clean_regions=True)[source]

Segment a sample across all requested chromosomes and write summaries.

Parameters:

  • sample_info (SampleInfo | None) – Prepared sample to segment. When omitted, uses the pathway default sample.

  • chroms (List[str] | None) – Optional chromosome subset. When omitted, uses every chromosome present in the sample.

  • min_probes (int) – Minimum probes required per raw contiguous region.

  • force_resegment (bool) – If True, ignore cached HMM results and rerun segmentation.

  • clean_regions (bool) – If True, run cleaned-region postprocessing and emit cleaned summary files alongside raw summaries.

Returns:

Paths to the summary BED files written under out_dir.

Return type:

list of str

run_pathway(sample_info=None, chroms=None, min_probes=3, force_optimize_rules=False, force_resegment=False, clean_regions=True, verbose=True)[source]

Fit the pathway and run end-to-end segmentation for a sample.

Parameters:

  • sample_info (SampleInfo | None) – Prepared sample to segment. When omitted, uses the pathway default sample.

  • chroms (List[str] | None) – Optional chromosome subset to process.

  • min_probes (int) – Minimum probes required per raw contiguous region.

  • force_optimize_rules (bool) – If True, rerun rule optimization before segmentation.

  • force_resegment (bool) – If True, ignore cached HMM results and rerun segmentation.

  • clean_regions (bool) – If True, generate cleaned-region artifacts and cleaned summary files.

  • verbose (bool) – If True, print simple progress messages.

Returns:

Paths to the written summary BED files.

Return type:

list of str

plot_labels(*, label_source='hmm', sample_info=None, chrom=None, sample_info_removed=None, overlay_regions_df=None, overlay_state=None, use_cleaned_regions=False, region_start=None, region_end=None, x_col='CpG_beg', y_col='beta', label_title=None, show_plot=True, max_points=120000, state_colors=None)[source]

Plot genomic labels for one chromosome with optional region overlays.

Parameters:

  • label_source (str) – Label family to plot: "hmm", "kmeans", or "rule_based".

  • sample_info (SampleInfo | None) – Prepared sample to plot. When omitted, uses the pathway default sample.

  • chrom (str | None) – Chromosome to display for HMM plots, and optional restriction for analyzer-owned labels.

  • sample_info_removed (DataFrame | None) – Optional table of CpGs removed during preprocessing to show as a background layer.

  • overlay_regions_df (DataFrame | None) – Optional region table used to recolor points by overlapping intervals.

  • overlay_state (MethylationStates | str | None) – Optional biological state whose cleaned regions should be loaded when use_cleaned_regions is enabled.

  • use_cleaned_regions (bool) – If True, load chromosome-local cleaned-region metadata from disk for overlay plotting.

  • region_start (int | None) – Optional genomic start coordinate for x-axis zooming.

  • region_end (int | None) – Optional genomic end coordinate for x-axis zooming.

  • x_col (str) – Probe-level column used for the x-axis.

  • y_col (str) – Probe-level column used for the y-axis.

  • label_title (str | None) – Optional legend title override.

  • show_plot (bool) – If True, display the figure immediately.

  • max_points (int) – Maximum number of plotted points before downsampling.

  • state_colors (dict | None) – Optional biological-state color overrides.

Returns:

  • plotly.graph_objects.Figure – Interactive beta scatter plot for the requested label source.

  • use_cleaned_regions=True is a read-only plotting mode. It loads the

  • prebuilt chromosome-local cleaned metadata TSV for overlay_state from

  • clean_regions/metadata_cleaned_{chrom}_{sample_id}_{STATE}.tsv.

  • It does not generate cleaned regions on demand; call

  • get_clean_regions(..., chrom=...) first when you want cleaned

  • overlays. Region args only zoom the x-axis viewport for scatter plots.

plot_embedding(*, label_source='kmeans', sample_info=None, chrom=None, method='pca', n_components=2, top_n_loadings=5, hexbin=True, hexbin_gridsize=60, hexbin_bins='log', hexbin_mincnt=1, hexbin_alpha=None, hexbin_linewidths=None, interactive=False, include_metrics=True, include_biplot=False, label_title='State', region_start=None, region_end=None, region_chrom=None, use_pca_features=False, use_parallel=True, show_plot=True, force_resegment=False, state_colors=None)[source]

Plot PCA or UMAP embeddings for training or sample-level labels.

Parameters:

  • label_source (str) – Label family to visualize: training/sample "kmeans", "rule_based", or segmented "hmm".

  • sample_info (SampleInfo | None) – Optional sample to embed. When omitted with label_source="kmeans", the cached training embedding is used.

  • chrom (str | None) – Optional chromosome restriction for sample-level embeddings.

  • method (str) – Embedding method, either "pca" or "umap".

  • n_components (int) – Number of embedding dimensions to render.

  • top_n_loadings (int) – Number of PCA loading features to show in side tables and biplots.

  • hexbin (bool) – If True, render 2-D PCA as hexbins instead of points.

  • hexbin_gridsize (int) – Hexbin grid resolution for 2-D PCA hexbin plots.

  • hexbin_bins (str | int | list[float] | ndarray | None) – Hexbin binning strategy for 2-D PCA hexbin plots, for example "log", an integer bin count, explicit bin edges, or None.

  • hexbin_mincnt (int | None) – Minimum points required to draw a hexbin in 2-D PCA hexbin plots. Use None to let matplotlib draw all bins.

  • hexbin_alpha (float | None) – Optional global transparency multiplier for 2-D PCA hexbin plots.

  • hexbin_linewidths (float | None) – Optional hexagon border width for 2-D PCA hexbin plots.

  • interactive (bool) – If True, use interactive rendering when supported.

  • include_metrics (bool) – Include clustering-quality metrics where available.

  • include_biplot (bool) – Overlay top PCA loading vectors on 2-D PCA plots.

  • label_title (str) – Legend or colorbar title.

  • region_start (int | None) – Optional genomic interval used to highlight overlapping CpGs in PCA space.

  • region_end (int | None) – Optional genomic interval used to highlight overlapping CpGs in PCA space.

  • region_chrom (str | None) – Optional genomic interval used to highlight overlapping CpGs in PCA space.

  • use_pca_features (bool) – For UMAP, project the trained PCA features instead of scaled raw features.

  • use_parallel (bool) – Whether to allow UMAP’s parallel execution mode.

  • show_plot (bool) – If True, display the figure immediately.

  • force_resegment (bool) – If True and label_source="hmm", rerun segmentation before plotting.

  • state_colors (dict | None) – Optional biological-state color overrides.

Returns:

Matplotlib or Plotly figure object from the selected plotting path.

Return type:

object

to_yaml(yaml_path, include_learned=True, artifact_dir=None)[source]

Serialize pathway configuration and optionally learned artifacts.

Parameters:

  • yaml_path (str) – Destination YAML path.

  • include_learned (bool) – If True, persist learned clustering artifacts and cached tables.

  • artifact_dir (str | Path | None) – Optional directory where learned artifacts should be written. When provided, the YAML stores paths that resolve from yaml_path to that dedicated artifact directory.

classmethod from_yaml(yaml_path, load_learned=True)[source]

Reconstruct MethylSegPathway from YAML file.

Parameters:

  • yaml_path (str) – Path to a serialized methylseg YAML configuration file.

  • load_learned (bool) – If True, restore persisted learned models and cached artifacts referenced by the YAML.

Returns:

Reconstructed pathway configured from the YAML bundle.

Return type:

MethylSegPathway