Feature Facade
GitHub Link to Code.
Facade for manual feature visualization.
Provides simplified interface for creating plots based on manual feature and DataSelector selection.
- class mdxplain.plots.services.feature_facade.FeatureFacade(manager, pipeline_data)
Facade for manual feature visualization.
Provides high-level interface for creating visualizations from manually selected features and DataSelectors. Simplifies access to specialized plotters while managing pipeline data and configuration.
Examples
>>> # Access via plots manager >>> facade = plots_manager.feature >>> fig = facade.violins("my_selector", ["cluster_0", "cluster_1"]) >>> fig = facade.densities("my_selector", ["cluster_0", "cluster_1"]) >>> fig = facade.time_series("my_selector", ["cluster_0", "cluster_1"])
- __init__(manager, pipeline_data) None
Initialize feature facade.
Parameters
- managerPlotsManager
Plots manager instance
- pipeline_dataPipelineData
Pipeline data container
Returns
- None
Initializes FeatureFacade instance
- violins(feature_selector: str, data_selectors: List[str], contact_transformation: bool = True, max_cols: int = 4, long_labels: bool = False, contact_threshold: float | None = 4.5, title: str | None = None, legend_title: str | None = None, legend_labels: Dict[str, str] | None = None, save_fig: bool = False, filename: str | None = None, file_format: str = 'png', dpi: int = 300, title_fontsize: int | None = None, subplot_title_fontsize: int | None = None, ylabel_fontsize: int | None = None, tick_fontsize: int | None = None, legend_fontsize: int | None = None, legend_title_fontsize: int | None = None) Figure
Create violin plots from manual feature selection.
Visualizes the distribution of feature values showing separate violins for each DataSelector group with cluster-consistent colors.
Parameters
- feature_selectorstr
Name of feature selector
- data_selectorsList[str]
DataSelector names to plot
- contact_transformationbool, default=True
If True, automatically convert contact features to distances. If False, plot contacts as binary values with Gaussian smoothing.
- max_colsint, default=4
Maximum number of columns in grid layout
- long_labelsbool, default=False
If True, use long descriptive labels for discrete features (e.g., “Contact”/”Non-Contact”, “Alpha helix”/”Loop”). If False, use short labels (e.g., “C”/”NC”, “H”/”C”).
- contact_thresholdfloat, optional
Distance threshold in Angstrom for drawing contact threshold line
- titlestr, optional
Custom plot title
- legend_titlestr, optional
Custom legend title
- legend_labelsDict[str, str], optional
Custom labels for DataSelectors in legend
- save_figbool, default=False
Save figure to file
- filenamestr, optional
Custom filename
- file_formatstr, default=”png”
File format for saving
- dpiint, default=300
Resolution for saved figure
- title_fontsizeint, optional
Font size for the main title.
- subplot_title_fontsizeint, optional
Font size for the subplot titles.
- 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 entries.
- legend_title_fontsizeint, optional
Font size for the legend title.
Returns
- matplotlib.figure.Figure
Figure object containing violin plots
Raises
- ValueError
If feature selector or data selectors not found
Examples
>>> # Basic violin plot >>> fig = facade.violins( ... feature_selector="my_selector", ... data_selectors=["cluster_0", "cluster_1"] ... )
>>> # With custom layout >>> fig = facade.violins( ... feature_selector="my_selector", ... data_selectors=["cluster_0", "cluster_1"], ... max_cols=3 ... )
>>> # Save to file >>> fig = facade.violins( ... feature_selector="my_selector", ... data_selectors=["cluster_0", "cluster_1"], ... save_fig=True, ... filename="features.pdf", ... file_format="pdf" ... )
Notes
Each feature gets its own subplot with violins for all DataSelectors
Y-axis shows feature values with units (Distance, Angle, etc.)
Grid layout controlled by max_cols parameter
- densities(feature_selector: str, data_selectors: List[str], contact_transformation: bool = True, max_cols: int = 4, long_labels: bool = False, kde_bandwidth: str | float = 'scott', base_sigma: float = 0.05, max_sigma: float = 0.12, alpha: float = 0.3, line_width: float = 2.0, contact_threshold: float | None = 4.5, title: str | None = None, legend_title: str | None = None, legend_labels: Dict[str, str] | None = None, save_fig: bool = False, filename: str | None = None, file_format: str = 'png', dpi: int = 300, title_fontsize: int | None = None, subplot_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, legend_title_fontsize: int | None = None, fill: bool = True, discrete_plot_mode: str = 'density', colors: str | Dict[str, str] | None = None, vertical_markers: Dict[int | str, float | List[float]] | None = None, vertical_marker_labels: str | Dict[int | str, str] | None = None, vertical_marker_label_colors: str | Dict[str, str] | None = None) Figure
Create density plots from manual feature selection.
Visualizes feature distributions as overlaid density curves in grid layout. Each feature gets one grid cell with curves for each DataSelector group using cluster-consistent colors.
Parameters
- feature_selectorstr
Name of feature selector
- data_selectorsList[str]
DataSelector names to plot
- contact_transformationbool, default=True
If True, convert contact features to distances. If False, plot contacts with Gaussian smoothing.
- max_colsint, default=4
Maximum number of columns in grid layout
- long_labelsbool, default=False
If True, use long descriptive labels for discrete features
- kde_bandwidthstr or float, default=”scott”
KDE bandwidth for continuous features
- base_sigmafloat, default=0.05
Minimum Gaussian width for binary contact features
- max_sigmafloat, default=0.12
Maximum Gaussian width for binary contact features
- alphafloat, default=0.3
Transparency for filled density curves
- line_widthfloat, default=2.0
Width of density curve contour lines
- fillbool, default=True
If True, draw filled density areas in addition to contour lines. If False, draw contour lines only.
- discrete_plot_modestr, default=”density”
Rendering mode for discrete features:
“density”: Gaussian-smoothed discrete distributions
“bar”: grouped probability bars
- colorsstr or Dict[str, str], optional
Color configuration for DataSelectors:
str: matplotlib colormap name
dict: explicit DataSelector -> color mapping
None: automatic cluster-consistent DataSelector mapping (cluster_* names keep their cluster color)
- vertical_markersDict[int or str, float or List[float]], optional
Optional vertical guide markers keyed by DataSelector.
- vertical_marker_labelsstr or dict, optional
Optional labels for marker legend entries. Use one shared label string or dict[key] = label.
- vertical_marker_label_colorsstr or dict, optional
Optional legend color override for marker labels: one shared color or dict[label] = color.
- contact_thresholdfloat, optional
Distance threshold for contact threshold line
- titlestr, optional
Custom plot title
- legend_titlestr, optional
Custom legend title
- legend_labelsDict[str, str], optional
Custom labels for DataSelectors in legend
- save_figbool, default=False
Save figure to file
- filenamestr, optional
Custom filename
- file_formatstr, default=”png”
File format for saving
- dpiint, default=300
Resolution for saved figure
- title_fontsizeint, optional
Font size for the main title.
- subplot_title_fontsizeint, optional
Font size for the subplot titles.
- 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 entries.
- legend_title_fontsizeint, optional
Font size for the legend title.
Returns
- matplotlib.figure.Figure
Figure object containing density plots
Raises
- ValueError
If feature selector or data selectors not found
Examples
>>> # Basic density plot >>> fig = facade.densities( ... feature_selector="my_selector", ... data_selectors=["cluster_0", "cluster_1"] ... )
>>> # Custom KDE bandwidth >>> fig = facade.densities( ... feature_selector="my_selector", ... data_selectors=["cluster_0", "cluster_1"], ... kde_bandwidth=0.5 ... )
>>> # Save to file >>> fig = facade.densities( ... feature_selector="my_selector", ... data_selectors=["cluster_0", "cluster_1"], ... save_fig=True, ... filename="densities.pdf", ... file_format="pdf" ... )
Notes
Features displayed in grid layout with max_cols per row
Discrete features use Gaussian smoothing
Continuous features use KDE
Colors consistent with clustering via ColorMappingHelper
- time_series(feature_selector: str, traj_selection: int | str | List | all = 'all', use_time: bool = True, tags_for_coloring: List[str] | None = None, allow_multi_tag_plotting: bool = False, clustering_name: str | None = None, membership_per_feature: bool = False, membership_traj_selection: str | int | List = 'all', contact_transformation: bool = True, max_cols: int = 2, long_labels: bool = False, subplot_height: float = 2.5, membership_bar_height: float | None = None, show_legend: bool = True, contact_threshold: float | None = 4.5, title: str | None = None, save_fig: bool = False, filename: str | None = None, file_format: str = 'png', dpi: int = 300, smoothing: bool = True, smoothing_method: str = 'savitzky', smoothing_window: int = 51, smoothing_polyorder: int = 3, show_unsmoothed_background: bool = True, title_fontsize: int | None = None, subplot_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, legend_title_fontsize: int | None = None, discrete_plot_style: str = 'step', discrete_layout: str = 'auto', discrete_offset_span: float = 0.28, discrete_auto_offset_threshold: int = 15, thickness: float = 1.0, colors: str | Dict[str, str] | None = None, vertical_markers: Dict[int | str, float | List[float]] | None = None, vertical_marker_labels: str | Dict[int | str, str] | None = None, vertical_marker_label_colors: str | Dict[str, str] | None = None, vertical_marker_mode: str = 'auto') Figure
Create time series plots from manual feature selection.
Visualizes temporal evolution of selected features as line plots with one subplot per feature. Each trajectory is shown as a separate line, optionally colored by trajectory number or tags.
Parameters
- feature_selectorstr
Name of feature selector
- traj_selectionint, str, list, or “all”, default=”all”
Trajectories to plot
- use_timebool, default=True
If True, use Time (ns) for x-axis. If False, use frame numbers.
- tags_for_coloringlist of str, optional
Tags to use for trajectory coloring
- allow_multi_tag_plottingbool, default=False
Plot multi-tag trajectories multiple times
- clustering_namestr, optional
Name of clustering for membership visualization
- membership_per_featurebool, default=False
Show membership bar below each feature subplot
- membership_traj_selectionint, str, list, or “all”, default=”all”
Trajectories to include in membership visualization
- contact_transformationbool, default=True
Convert contact features to distances
- max_colsint, default=2
Maximum number of columns in grid layout
- long_labelsbool, default=False
Use long descriptive labels for discrete features
- subplot_heightfloat, default=2.5
Height per feature subplot in inches
- membership_bar_heightfloat, optional
Height per trajectory in membership bar
- show_legendbool, default=True
Show legend for trajectory/tag colors
- contact_thresholdOptional[float], default=4.5
Distance threshold for contact threshold line
- titlestr, optional
Custom plot title
- save_figbool, default=False
Save figure to file
- filenamestr, optional
Custom filename
- file_formatstr, default=”png”
File format for saving
- dpiint, default=300
Resolution for saved figure
- smoothingbool, default=True
Enable or disable data smoothing for continuous features. Discrete features are always plotted without smoothing.
- smoothing_methodstr, default=”savitzky”
Smoothing method (“moving_average” or “savitzky”)
- smoothing_windowint, default=51
Window size for smoothing in frames
- smoothing_polyorderint, default=3
Polynomial order for Savitzky-Golay filter (ignored for moving_average)
- show_unsmoothed_backgroundbool, default=True
Show unsmoothed data as transparent background line when smoothing is enabled
- discrete_plot_stylestr, default=”step”
Rendering style for discrete features: “line”, “step”, “segments”, or “scatter”.
- discrete_layoutstr, default=”auto”
Discrete rendering layout mode: “auto”, “overlay”, “offset”, or “occupancy”. In “occupancy”, discrete lines represent states as probabilities over time instead of individual trajectories.
- discrete_offset_spanfloat, default=0.28
Vertical half-span for discrete “offset” layout.
- discrete_auto_offset_thresholdint, default=15
Number of discrete traces at which “auto” switches to “offset”.
- thicknessfloat, default=1.0
Global rendering thickness for all feature traces: marker size factor for “scatter” and line width for line-based styles.
- colorsstr or Dict[str, str], optional
Color configuration for trajectories/tags:
str: matplotlib colormap name
dict: explicit mapping (trajectory_name -> color or tag -> color)
None: automatic palette assignment. Uses tag colors if tag coloring is active, otherwise trajectory colors.
- vertical_markersDict[int or str, float or List[float]], optional
Optional vertical guide markers. Keys are trajectory selectors or tag names (depending on vertical_marker_mode), values are x-positions where colored vertical lines are drawn.
- vertical_marker_labelsstr or dict, optional
Optional legend labels for marker lines. Use one shared label string or dict[key] = label.
- vertical_marker_label_colorsstr or dict, optional
Optional legend color override for marker labels: one shared color or dict[label] = color.
- vertical_marker_modestr, default=”auto”
Marker key interpretation mode: “auto”, “trajectory”, or “tag”. In “auto”, tag mode is used when tag coloring is active. In “trajectory” mode with tag coloring enabled, the first matching tag color per trajectory is used.
- title_fontsizeint, optional
Font size for the main title.
- subplot_title_fontsizeint, optional
Font size for the subplot titles.
- 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 entries.
- legend_title_fontsizeint, optional
Font size for the legend title.
Returns
- matplotlib.figure.Figure
Figure object containing time series plots
Raises
- ValueError
If feature selector not found
Examples
>>> # Basic time series plot >>> fig = facade.time_series( ... feature_selector="my_selector" ... )
>>> # With cluster membership visualization >>> fig = facade.time_series( ... feature_selector="my_selector", ... clustering_name="dbscan", ... membership_per_feature=True ... )
>>> # Save to file >>> fig = facade.time_series( ... feature_selector="my_selector", ... save_fig=True, ... filename="timeseries.pdf", ... file_format="pdf" ... )
Notes
Each feature gets its own subplot with all trajectories overlaid
X-axis shows either Time (ns) or frame numbers
Contact features automatically converted to distances (default)
Cluster membership shown as colored horizontal bars