Clustering Facade

GitHub Link to Code.

Clustering plotting facade.

Provides simplified interface for creating clustering-focused plots, particularly landscape visualizations with cluster coloring.

class mdxplain.plots.services.clustering_facade.ClusteringFacade(manager, pipeline_data)

Facade for clustering visualization methods.

Provides high-level interface for creating plots of clustering results overlaid on decomposition landscapes.

Accessible via: pipeline.plots.clustering

Examples

>>> # Clustering-focused landscape
>>> pipeline.plots.clustering.landscape(
...     clustering_name="dbscan",
...     decomposition_name="pca",
...     dimensions=[0, 1],
...     show_centers=True
... )

>>> # Multi-dimensional with energy
>>> pipeline.plots.clustering.landscape(
...     clustering_name="hdbscan",
...     decomposition_name="tica",
...     dimensions=[0, 1, 2, 3],
...     show_centers=True,
...     energy_values=True
... )

__init__(manager, pipeline_data) → None

Initialize clustering plotting facade.

Parameters

managerPlotsManager

Plots manager instance for accessing cache_dir

pipeline_dataPipelineData

Pipeline data container

Returns

None

landscape(clustering_name: str, decomposition_name: str, dimensions: List[int], show_centers: bool = True, energy_values: bool = True, use_kde: bool = False, mask_empty_bins: bool = True, bins: int | str = 'auto', temperature: float = 310.15, alpha: float = 0.6, cluster_contour: bool = True, cluster_contour_voronoi: bool = False, data_scatter: bool = True, show_clusters: str | List[int] = 'all', tag_coloring: List[str] | None = None, scatter_show_all: bool = False, center_marker: str = 'X', center_size: int = 200, scatter_size: int = 1, background_color: bool | str = True, class_colors: bool | Dict | List = True, tag_densities: bool = False, title: str | None = None, xaxis_label: str | None = None, yaxis_label: str | None = None, xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, subplot_size: float = 6.0, save_fig: bool = False, filename: str | None = None, file_format: str = 'png', dpi: int = 300, title_fontsize: int | None = None, xlabel_fontsize: int | None = None, ylabel_fontsize: int | None = None, tick_fontsize: int | None = None, legend_fontsize: int | None = None, contour_label_fontsize: int | None = None) → Figure

Create landscape plot with clustering overlay.

Visualizes clustering results on decomposition landscape with cluster-colored points and optional cluster centers.

Parameters

clustering_namestr

Name of clustering to visualize (e.g., “dbscan”, “hdbscan”)

decomposition_namestr

Name of decomposition for landscape (e.g., “pca”, “tica”)

dimensionsList[int]

Dimension indices to plot (must be even number). Paired consecutively: [0,1,2,3] → [(0,1), (2,3)]

show_centersbool, default=True

Show cluster centers (default True for clustering view)

energy_valuesbool, default=False

Show free energy landscape instead of density

use_kdebool, default=False

Use KDE smoothing for background density estimation.

Default (False): Histogram-based - shows actual observations, preserves energy barriers, scientifically accurate.

KDE (True): Smooth visualization but can filter out small energy barriers and distort the landscape. Use only if you know what you do. NOT for quantitative analysis. A warning will be issued.

mask_empty_binsbool, default=True

Mask unsampled bins in the background (energy/density) as white/ transparent. Set False to fill with the maximum color for continuous fill.

binsint or str, default=”auto”

Number of bins for histogram/energy calculation

temperaturefloat, default=300.0

Temperature in Kelvin for energy calculation

alphafloat, default=0.6

Transparency for scatter points (0=transparent, 1=opaque)

cluster_contourbool, default=False

Show clusters as transparent contours instead of scatter points

cluster_contour_voronoibool, default=True

Use Voronoi-style contours (True) or KDE-based density contours (False). Only applies when cluster_contour=True

data_scatterbool, default=True

Show gray scatter points when no clustering

show_clustersUnion[str, List[int]], default=”all”

Which clusters to display: “all” or list of cluster IDs. Colors remain consistent regardless of selection

tag_coloringOptional[List[str]], default=None

Color scatter points by trajectory tags instead of clusters. Provide list of tags, e.g., [“biased”, “unbiased”]. If a frame matches multiple tags, the last tag in the list is used. When set, overrides cluster-based coloring from clustering_name

scatter_show_allbool, default=False

Show unselected points in gray (applies to both cluster and tag mode):

• Cluster mode: When show_clusters=[0,1], other clusters/noise shown in gray

• Tag mode: When tag_coloring=[“biased”], frames without this tag shown in gray

• False (default): Only show selected points, hide others (current behavior)

center_markerstr, default=’X’

Marker style for cluster centers

center_sizeint, default=200

Marker size for cluster centers

scatter_sizeint, default=1

Size of scatter points in matplotlib units. Applies to all scatter points (cluster-colored, tag-colored, gray, and unselected). Typical values: 1 (tiny), 5-10 (small), 20-50 (medium), 100+ (large). Note: Cluster centers use center_size parameter separately.

titleOptional[str], default=None

Custom overall title (overrides default)

xaxis_labelOptional[str], default=None

Custom X-axis label (default: “Component {dim_x}”)

yaxis_labelOptional[str], default=None

Custom Y-axis label (default: “Component {dim_y}”)

xlimOptional[Tuple[float, float]], default=None

X-axis limits for all subplots

ylimOptional[Tuple[float, float]], default=None

Y-axis limits for all subplots

subplot_sizefloat, default=4.0

Size of each subplot in inches

save_figbool, default=False

Save figure to file

filenameOptional[str], default=None

Custom filename (overrides auto-generated name)

file_formatstr, default=”png”

File format for saving (png, pdf, svg, etc.)

dpiint, default=300

Resolution for saved figure

title_fontsizeint, optional

Font size for the figure title.

xlabel_fontsizeint, optional

Font size for the x-axis labels.

ylabel_fontsizeint, optional

Font size for the y-axis labels.

tick_fontsizeint, optional

Font size for the tick labels.

legend_fontsizeint, optional

Font size for the legend.

contour_label_fontsizeint, optional

Font size for the contour labels.

Returns

matplotlib.figure.Figure

Created figure object

Raises

ValueError

If clustering not found

ValueError

If decomposition not found

ValueError

If dimensions invalid or odd number

ValueError

If clustering incompatible with decomposition

Examples

>>> # Basic clustering landscape with centers
>>> fig = pipeline.plots.clustering.landscape(
...     clustering_name="dbscan",
...     decomposition_name="pca",
...     dimensions=[0, 1]
... )

>>> # Multi-dimensional grid
>>> fig = pipeline.plots.clustering.landscape(
...     clustering_name="hdbscan",
...     decomposition_name="pca",
...     dimensions=[0, 1, 2, 3],
...     show_centers=True
... )

>>> # Energy landscape with custom styling
>>> fig = pipeline.plots.clustering.landscape(
...     clustering_name="dpa",
...     decomposition_name="tica",
...     dimensions=[0, 1],
...     show_centers=True,
...     energy_values=True,
...     title="DPA Clustering on TICA",
...     save_fig=True
... )

Notes

• This method is clustering-focused, so show_centers defaults to True

• Clustering and decomposition must have matching number of frames

• Cluster colors use Tab20 palette for consistency

• Auto-generated filenames include clustering name

membership(clustering_name: str, traj_selection: str | List[int] = 'all', height_per_trajectory: float = 0.3, show_frame_numbers: bool = True, show_legend: bool = True, title: str | None = None, save_fig: bool = False, filename: str | None = None, file_format: str = 'png', dpi: int = 300, title_fontsize: int | None = None, xlabel_fontsize: int | None = None, ylabel_fontsize: int | None = None, tick_fontsize: int | None = None, legend_fontsize: int | None = None) → Figure

Create cluster membership timeline plot.

Visualizes cluster assignment over time as horizontal colored bars, with each trajectory on a separate row. Clustering-focused method for analyzing temporal dynamics of cluster membership.

Parameters

clustering_namestr

Name of clustering to visualize

traj_selectionint, str, list, or “all”, default=”all”

Trajectory selection. Controls which trajectories to plot AND their order.

height_per_trajectoryfloat, default=0.3

Height in inches per trajectory bar

show_frame_numbersbool, default=True

Show frame numbers on x-axis

show_legendbool, default=True

Show cluster color legend

titleOptional[str], default=None

Custom title (auto-generated if None)

save_figbool, default=False

Save figure to file

filenameOptional[str], default=None

Custom filename (auto-generated if None)

file_formatstr, default=”png”

File format for saving

dpiint, default=300

Resolution for saved figure

title_fontsizeint, optional

Font size for the figure title.

xlabel_fontsizeint, optional

Font size for the x-axis label.

ylabel_fontsizeint, optional

Font size for the y-axis label.

tick_fontsizeint, optional

Font size for the tick labels.

legend_fontsizeint, optional

Font size for the legend.

Returns

matplotlib.figure.Figure

Created figure object

Raises

ValueError

If clustering not found

ValueError

If no trajectories match selection

Examples

>>> # All trajectories for DBSCAN clustering
>>> fig = pipeline.plots.clustering.membership("dbscan")

>>> # Specific trajectories in custom order
>>> fig = pipeline.plots.clustering.membership(
...     "hdbscan",
...     traj_selection=[2, 0, 5]
... )

>>> # Filter by tag
>>> fig = pipeline.plots.clustering.membership(
...     "dpa",
...     traj_selection="tag:system_A"
... )

>>> # Full customization
>>> fig = pipeline.plots.clustering.membership(
...     "dbscan",
...     traj_selection=[0, 1, 2],
...     height_per_trajectory=0.5,
...     title="DBSCAN Cluster Membership Over Time",
...     save_fig=True
... )

Notes

• Efficient block-based rendering for large trajectories

• Trajectory order in plot follows traj_selection order

• Colors match cluster colors from landscape plots

• Ideal for identifying conformational transitions and stability