Plot Manager

GitHub Link to Code.

Plots manager for trajectory analysis visualizations.

Central manager for all plotting functionality, providing access to decomposition-focused and clustering-focused plot methods, as well as direct plotting capabilities.

class mdxplain.plots.manager.plots_manager.PlotsManager(use_memmap: bool = True, chunk_size: int = 2000, cache_dir: str = './cache')

Manager for all plotting operations.

Provides five access patterns: 1. Direct: pipeline.plots.landscape(…), pipeline.plots.membership(…) 2. Decomposition-focused: pipeline.plots.decomposition.landscape(…) 3. Clustering-focused: pipeline.plots.clustering.landscape(…) 4. Feature importance: pipeline.plots.feature_importance.violins(…) 5. Manual feature: pipeline.plots.feature.violins(…)

Examples

>>> # Direct access
>>> pipeline.plots.landscape(
...     decomposition_name="pca",
...     dimensions=[0, 1]
... )

>>> # Decomposition-focused
>>> pipeline.plots.decomposition.landscape(
...     decomposition_name="pca",
...     dimensions=[0, 1]
... )

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

>>> # Feature importance violin plots
>>> pipeline.plots.feature_importance.violins(
...     feature_importance_name="tree_analysis",
...     n_top=10
... )

>>> # Manual feature violin plots
>>> pipeline.plots.feature.violins(
...     feature_selector="my_selector",
...     data_selectors=["cluster_0", "cluster_1"]
... )

__init__(use_memmap: bool = True, chunk_size: int = 2000, cache_dir: str = './cache') → None

Initialize plots manager.

Parameters

use_memmapbool, default=True

Whether to use memory mapping for large datasets

chunk_sizeint, default=2000

Chunk size for memory-efficient processing

cache_dirstr, default=”./cache”

Directory for cache files

Returns

None

property decomposition: DecompositionFacade

Access decomposition-focused plotting methods.

Returns

DecompositionFacade

Decomposition plotting interface

Note

Pipeline data is passed as None here because it will be automatically injected later when the facade methods are called.

Examples

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

property clustering: ClusteringFacade

Access clustering-focused plotting methods.

Returns

ClusteringFacade

Clustering plotting interface

Note

Pipeline data is passed as None here because it will be automatically injected later when the facade methods are called.

Examples

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

property feature_importance: FeatureImportanceFacade

Access feature importance visualization methods.

Returns

FeatureImportanceFacade

Feature importance plotting interface

Note

Pipeline data is passed as None here because it will be automatically injected later when the facade methods are called.

Examples

>>> # Create violin plots for top features
>>> pipeline.plots.feature_importance.violins(
...     feature_importance_name="tree_analysis",
...     n_top=10
... )

>>> # Create density plots
>>> pipeline.plots.feature_importance.densities(
...     feature_importance_name="tree_analysis",
...     n_top=10
... )

property feature: FeatureFacade

Access manual feature visualization methods.

Returns

FeatureFacade

Manual feature plotting interface

Note

Pipeline data is passed as None here because it will be automatically injected later when the facade methods are called.

Examples

>>> # Create violin plots for selected features
>>> pipeline.plots.feature.violins(
...     feature_selector="my_selector",
...     data_selectors=["cluster_0", "cluster_1"]
... )

>>> # Create density plots
>>> pipeline.plots.feature.densities(
...     feature_selector="my_selector",
...     data_selectors=["cluster_0", "cluster_1"]
... )

>>> # Create time series plots
>>> pipeline.plots.feature.time_series(
...     feature_selector="my_selector",
...     data_selectors=["cluster_0", "cluster_1"]
... )

landscape(pipeline_data, 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 directly from plots manager.

Convenience method for quick landscape visualization without going through decomposition or clustering facades.

Parameters

decomposition_namestr

Name of decomposition to plot (e.g., “pca”, “tica”)

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

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.). When using ‘svg’, text elements remain editable in SVG editors.

dpiint, default=300

Resolution for saved figure

title_fontsizeint, optional

Font size for figure title (default: 14)

xlabel_fontsizeint, optional

Font size for X-axis labels (default: 12)

ylabel_fontsizeint, optional

Font size for Y-axis labels (default: 12)

tick_fontsizeint, optional

Font size for tick labels (default: 10)

legend_fontsizeint, optional

Font size for legend entries (default: 10)

contour_label_fontsizeint, optional

Font size for contour labels (default: 10)

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

>>> # Simple landscape
>>> fig = pipeline.plots.landscape(
...     decomposition_name="pca",
...     dimensions=[0, 1]
... )

>>> # With clustering overlay
>>> fig = pipeline.plots.landscape(
...     decomposition_name="pca",
...     dimensions=[0, 1],
...     clustering_name="dbscan",
...     show_centers=True
... )

>>> # Energy landscape with saving
>>> fig = pipeline.plots.landscape(
...     decomposition_name="tica",
...     dimensions=[0, 1, 2, 3],
...     energy_values=True,
...     save_fig=True,
...     filename="tica_energy_landscape.pdf",
...     file_format="pdf"
... )

Notes

This is a direct convenience method. For more specialized workflows, consider using:

• pipeline.plots.decomposition.landscape() for decomposition focus

• pipeline.plots.clustering.landscape() for clustering focus

membership(pipeline_data, clustering_name: str, traj_selection: int | str | List | all = '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. Uses efficient block-based rendering for performance.

Parameters

clustering_namestr

Name of clustering to visualize

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

Trajectory selection (uses TrajectoryData.get_trajectory_indices()). 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 (png, pdf, svg, etc.). When using ‘svg’, text elements remain editable in SVG editors.

dpiint, default=300

Resolution for saved figure

title_fontsizeint, optional

Font size for title (default: 14)

xlabel_fontsizeint, optional

Font size for X-axis label (default: 12)

ylabel_fontsizeint, optional

Font size for Y-axis trajectory labels (default: 11)

tick_fontsizeint, optional

Font size for tick labels (default: 10)

legend_fontsizeint, optional

Font size for legend entries (default: 10)

Returns

matplotlib.figure.Figure

Created figure object

Raises

ValueError

If clustering not found or no trajectories selected

Examples

>>> # All trajectories in original order
>>> fig = pipeline.plots.membership("dbscan")

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

>>> # By tag selection
>>> fig = pipeline.plots.membership(
...     "hdbscan",
...     traj_selection="tag:system_A"
... )

>>> # Customized appearance with saving
>>> fig = pipeline.plots.membership(
...     "dpa",
...     traj_selection=[0, 1, 2],
...     height_per_trajectory=0.5,
...     title="DPA Clustering Timeline",
...     save_fig=True,
...     filename="dpa_membership.pdf",
...     file_format="pdf"
... )

Notes

• Uses block-based rendering: O(transitions) not O(frames)

• Trajectory order in plot matches order in traj_selection

• Colors consistent with other plots via ColorMappingHelper

• Noise points (-1) shown in black

• Best for visualizing temporal dynamics of cluster assignments