methylseg.MethylSegmentor

class methylseg.MethylSegmentor(analyzer, hmm_model, state_assignment_method=MethylStateAssignmentMethod.DEFINITION, out_dir='.', random_state=42)

Bases: object

Class to handle segmentation of methylation data using HMMs. Recommend CTHMM for sparse data with variable probe spacing, and the sticky categorical smoother for dense discrete state-label smoothing.

Parameters:

• analyzer (MethylStateAnalyzer)

• hmm_model (MethylSegHMM)

• state_assignment_method (MethylStateAssignmentMethod)

• random_state (int)

__init__(analyzer, hmm_model, state_assignment_method=MethylStateAssignmentMethod.DEFINITION, out_dir='.', random_state=42)

Initialize the segmentor with state-assignment and HMM backends.

Parameters:

• analyzer (MethylStateAnalyzer) – State analyzer that prepares emissions and biological labels.

• hmm_model (MethylSegHMM) – Configured HMM backend used to smooth state observations.

• state_assignment_method (MethylStateAssignmentMethod) – Strategy used to obtain state labels before segmentation.

• out_dir – Directory for segmentation artifacts and plot outputs.

• random_state (int) – Random seed used by stochastic segmentation operations.

Methods

__init__(analyzer, hmm_model[, ...])	Initialize the segmentor with state-assignment and HMM backends.
assign_states(sample_info[, chrom])	Assign coarse methylation states before HMM smoothing.
create_regions([state_col, region_min_probes])	Create regions (start, end) for contiguous segments of the same state.
plot_labels([sample_info, chrom, ...])	Plot genomic-position vs beta for HMM labels.
regions_to_bed(bed_path[, ...])	Save regions DataFrame to BED file.
segment_sample([sample_info, chrom, ...])	Segment a sample and refresh probe-level results plus raw regions.

assign_states(sample_info, chrom=None)

Assign coarse methylation states before HMM smoothing.

Parameters:

• sample_info (SampleInfo) – Prepared methylation sample to summarize and label.

• chrom (str | None) – Optional chromosome restriction for per-chromosome state assignment.

Returns:

Pair of (meth_data, emissions_df) cached on the segmentor after populating state and state_readable columns on meth_data.

Return type:

tuple

Raises:

• ValueError – If the configured state-assignment method is unknown.

• NotImplementedError – If AUTO assignment is requested.

segment_sample(sample_info=None, chrom=None, force_resegment=False)

Segment a sample and refresh probe-level results plus raw regions.

Parameters:

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

• chrom (str | None) – Optional chromosome restriction for per-chromosome segmentation.

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

Returns:

• tuple – (meth_data, hmm_model) where meth_data is the segmented probe-level table and hmm_model is the fitted backend model.

• Returns the segmented probe-level methylation table and fitted HMM

• object. Raw contiguous regions are stored on self.regions_df.

Return type:

Tuple[DataFrame, object]

create_regions(state_col='hmm_state_readable', region_min_probes=1)

Create regions (start, end) for contiguous segments of the same state.

Parameters:

• meth_data (DataFrame) – Must contain ‘CpG_chrm’, ‘CpG_beg’, ‘CpG_end’, and state_col.

• state_col (str) – Column name for the state labels.

• region_min_probes (int) – Minimum number of probes required to form a region.

Returns:

regions_df – Columns: ‘CpG_chrm’, ‘start’, ‘end’, state_col

Return type:

DataFrame

regions_to_bed(bed_path, separate_beds_by_state=False)

Save regions DataFrame to BED file.

Parameters:

• bed_path (str) – Output path for the BED file. A .bed suffix is added when it is missing.

• separate_beds_by_state (bool) – If True, write one BED per biological state instead of one combined BED file.

Returns:

Writes BED file(s) derived from self.regions_df.

Return type:

None

plot_labels(sample_info=None, chrom=None, sample_info_removed=None, overlay_regions_df=None, overlay_style='state', 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)

Plot genomic-position vs beta for HMM labels.

Parameters:

• sample_info (SampleInfo | None) – Sample to segment and plot. When omitted, uses default_sample_info.

• chrom (str | None) – Chromosome to segment and display.

• 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_style (str) – Overlay mode, either "state" or "highlight".

• 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 Plotly 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 resolved HMM labels.

• Region args only zoom the x-axis viewport; they do not create a

• highlight overlay unless one is passed explicitly.