Decomposition Facade

GitHub Link to Code.

Decomposition plotting facade.

Provides simplified interface for creating decomposition-focused plots, particularly landscape visualizations.

class mdxplain.plots.services.decomposition_facade.DecompositionFacade(manager, pipeline_data)

Facade for decomposition visualization methods.

Provides high-level interface for creating plots of decomposition data with optional clustering overlay.

Accessible via: pipeline.plots.decomposition

Examples

>>> # Basic landscape plot
>>> pipeline.plots.decomposition.landscape(
...     decomposition_name="pca",
...     dimensions=[0, 1]
... )

>>> # Multi-dimensional with clustering
>>> pipeline.plots.decomposition.landscape(
...     decomposition_name="pca",
...     dimensions=[0, 1, 2, 3],
...     clustering_name="dbscan",
...     show_centers=True
... )
__init__(manager, pipeline_data) → None

Initialize decomposition plotting facade.

Parameters

managerPlotsManager

Plots manager instance for accessing cache_dir

pipeline_dataPipelineData

Pipeline data container

Returns

None

landscape(decomposition_name: str, dimensions: List[int], clustering_name: str | None = None, 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 for decomposition data.

Visualizes 2D projections of decomposition components with optional clustering overlay, cluster centers, and energy transformation.

Parameters

decomposition_namestr

Name of decomposition to plot

dimensionsList[int]

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

clustering_nameOptional[str], default=None

Name of clustering for color overlay

show_centersbool, default=False

Show cluster centers (requires clustering_name)

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 decomposition not found

ValueError

If dimensions invalid or odd number

ValueError

If show_centers=True but no clustering_name

ValueError

If clustering not compatible with decomposition

Examples

>>> # Single 2D landscape
>>> fig = pipeline.plots.decomposition.landscape(
...     decomposition_name="pca",
...     dimensions=[0, 1]
... )

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

>>> # Energy landscape with custom styling
>>> fig = pipeline.plots.decomposition.landscape(
...     decomposition_name="tica",
...     dimensions=[0, 1],
...     energy_values=True,
...     temperature=310.0,
...     title="TICA Free Energy Landscape",
...     axis_labels={0: "IC1", 1: "IC2"},
...     save_fig=True,
...     filename="tica_landscape.pdf",
...     file_format="pdf"
... )

Notes

  • Dimensions are paired consecutively for grid layout

  • Energy transformation uses: F = -kT * ln(P/P_max)

  • Cluster colors use Tab20 palette for consistency

  • Auto-generated filenames follow pattern: landscape_{decomp}_dim{dims}[_{clustering}][_centers][_energy].{fmt}