vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization package¶

Submodules¶

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.centroids module¶

Centroid Visualization Plots.

Contains plotting functions for visualizing cluster centroid simulation results: - Reflectivity curves from forward simulation - Parameter bar charts comparing centroid values

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.centroids.create_centroid_plots(app, centroid_results: List[Dict], q_values, original_data, param_names: List[str], spectrum_idx: int, samples: ndarray | None = None, cluster_labels: ndarray | None = None)¶

Orchestrate creation of all centroid-related plots.

Parameters:

app – VIPR application instance
centroid_results – List of dicts with centroid info and curves
q_values – Q-values for x-axis
original_data – Original experimental data
param_names – List of parameter names
spectrum_idx – Spectrum index
samples – Original parameter samples (for box-plot uncertainty visualization)
cluster_labels – Cluster assignments (for box-plot uncertainty visualization)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.corner module¶

Clustered Corner Plot.

Contains all logic for creating the enhanced corner plot with cluster overlay. Shows posterior distributions with identified cluster modes.

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.corner.create_clustered_corner_plot(app, samples, cluster_labels, param_names, spectrum_idx, centroid_results=None)¶

Create improved corner plot with cluster overlay.

Features: - Top-N cluster filtering (shows only 3 largest if >4 exist) - Better color palette (tab10) with higher contrast - Filled contours with transparency gradients - Cluster-specific 1D histograms - “Mode” terminology with percentages - Optional polished parameter markers

Parameters:

app – VIPR application instance
samples – Parameter samples (num_samples, num_params)
cluster_labels – Cluster assignments
param_names – Parameter names
spectrum_idx – Spectrum index
centroid_results – Optional list of centroid results (for polished markers)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.interactive module¶

Interactive cluster visualization data export.

Exports cluster analysis data via DataCollector for interactive Plotly-based visualization in the frontend. Enables: - Interactive corner plots with clickable clusters - Synchronized reflectivity curve highlighting - Real-time cluster selection without server round-trips

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.interactive.add_centroid_summary_csv(app, param_names: List[str], centroid_results: List[Dict], spectrum_idx: int = 0)¶

Export cluster centroids as a compact CSV file.

Creates a separate CSV with one row per cluster containing: - Parameter values at centroid position - Cluster metadata (size, label) - Optionally polished parameter values

This is ideal for external matplotlib processing as it provides a compact summary of cluster centers without duplicating data across thousands of rows.

Example output (3 clusters, 2 parameters):: cluster_id,cluster_label,size,Thickness_L1,Roughness_L1 0,0,1500,45.2,3.1 1,1,2000,48.7,2.8 2,2,500,42.3,4.2

Parameters:

app – VIPR application instance
param_names – List of parameter names
centroid_results – List of dicts with centroid info (from simulation.py)
spectrum_idx – Spectrum index (for multi-spectrum batches)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.interactive.add_interactive_cluster_data(app, samples: ndarray, cluster_labels: ndarray, param_names: List[str], centroid_results: List[Dict], q_values: Any, original_data: Any | None, spectrum_idx: int = 0)¶

Export all interactive cluster visualization data to DataCollector.

This is the main entry point that exports both corner plot and curves data for interactive frontend visualization. Called by the clustering orchestrator after matplotlib visualizations are created.

Parameters:

app – VIPR application instance (with datacollector)
samples – Parameter samples array (num_samples, num_params)
cluster_labels – Cluster assignment for each sample
param_names – List of parameter names
centroid_results – List of dicts with centroid info (from simulation.py)
q_values – Q-values for reflectivity curves
original_data – Original experimental data (if available)
spectrum_idx – Spectrum index (for multi-spectrum batches)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.interactive.add_interactive_corner_data(app, samples: ndarray, cluster_labels: ndarray, param_names: List[str], centroid_results: List[Dict], spectrum_idx: int = 0)¶

Export corner plot data for interactive frontend visualization.

Creates a diagram with per-parameter value lists and cluster labels. Frontend can use this to render an interactive scatter plot matrix (corner plot) where users can click on clusters.

Data structure: - One list per parameter with all sample values - One list with cluster labels for coloring - Metadata with parameter names and cluster info

Parameters:

app – VIPR application instance
samples – Parameter samples array (num_samples, num_params)
cluster_labels – Cluster assignment for each sample (num_samples,)
param_names – List of parameter names
centroid_results – List of dicts with centroid info (from simulation.py)
spectrum_idx – Spectrum index (for multi-spectrum batches)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.interactive.add_interactive_curves_data(app, centroid_results: List[Dict], q_values: Any, original_data: Any | None, spectrum_idx: int = 0)¶

Export reflectivity curves data for synchronized visualization.

Creates a diagram with experimental data and simulated curves for each cluster centroid. Frontend can use this to render an interactive line plot that responds to cluster selection in the corner plot.

Parameters:

app – VIPR application instance
centroid_results – List of dicts with centroid info and curves
q_values – Q-values for x-axis (tensor or array)
original_data – Original experimental data (if available)
spectrum_idx – Spectrum index (for multi-spectrum batches)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.marginals module¶

Per-Cluster Marginal Distributions.

Creates 1D histograms for each parameter within each cluster, showing the uncertainty of individual parameters within each solution.

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.marginals.create_cluster_marginals(app, samples: ndarray, cluster_labels: ndarray, param_names: list, spectrum_idx: int, cluster_sizes: list, centroid_results=None)¶

Create 1D marginal histograms for each parameter within each cluster.

This shows the uncertainty of individual parameters WITHIN each cluster solution, complementing the multivariate clustering analysis. Optionally overlays centroid positions (unpolished and polished) as vertical lines.

Parameters:

app – VIPR application instance
samples – Parameter samples (num_samples, num_params)
cluster_labels – Cluster assignments
param_names – Names of parameters
spectrum_idx – Spectrum index
cluster_sizes – List of (label, size) tuples sorted by size descending
centroid_results – Optional list of centroid dicts with ‘centroid’ and ‘polished_params’ keys for overlay visualization

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.parallel_coordinates module¶

Parallel Coordinates Visualization.

Visualizes high-dimensional parameter distributions with cluster coloring. Features: - Quantile clipping to remove outliers - Separability-based axis sorting - Stratified sampling for cleaner visualization

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.parallel_coordinates.create_parallel_coordinates_plot(app, samples: ndarray, cluster_labels: ndarray, param_names: List[str], spectrum_idx: int, seed: int | None = None, cluster_sizes: list | None = None)¶

Create parallel coordinates plot with cluster coloring.

Features: - Axes sorted by separability (best cluster discriminators first) - Quantile clipping (1-99%) to remove outliers - Stratified sampling for cleaner visualization

Parameters:

app – VIPR application instance
samples – Parameter samples (num_samples, num_params)
cluster_labels – Cluster assignments for each sample
param_names – List of parameter names
spectrum_idx – Spectrum index
seed – Optional random seed for reproducible sampling (default: None)
cluster_sizes – List of (label, size) tuples sorted by size descending (default: None)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.utils module¶

Visualization Utility Functions.

Shared helper functions used across multiple visualization modules. This ensures DRY (Don’t Repeat Yourself) principle compliance.

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.utils.add_units_to_param(param_name: str) → str¶

Add appropriate units to parameter names for axis labels.

Parameters:: param_name – Parameter name (e.g., ‘thickness’, ‘sld’)
Returns:: Parameter name with appropriate units appended

Examples

>>> add_units_to_param('thickness')
'thickness (Å)'
>>> add_units_to_param('sld')
'sld (10⁻⁶ Å⁻²)'
>>> add_units_to_param('other_param')
'other_param'

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.validation module¶

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.validation.create_validation_plots(app, samples: ndarray, cluster_labels: ndarray, spectrum_idx: int, cluster_sizes: list)¶

Create cluster validation plots (silhouette only).

BIC/AIC analysis is now in the separate model_selection hook.

Parameters:

app – VIPR application instance
samples – Parameter samples (num_samples, num_params)
cluster_labels – Cluster assignments
spectrum_idx – Spectrum index
cluster_sizes – List of (label, size) tuples sorted by size descending

Module contents¶

Visualization Package API.

Provides a clean, high-level interface to all plotting functions related to cluster analysis. This facade hides the internal module structure from external consumers.

Public API:

create_validation_plots: Silhouette and BIC plots
create_clustered_corner_plot: Corner plot with cluster overlay
create_cluster_marginals: 1D marginal distributions per cluster
create_centroid_plots: Reflectivity curves and parameter charts
create_parallel_coordinates_plot: Parallel coordinates for parameter correlations
add_interactive_cluster_data: Export interactive data to DataCollector (NEW)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.add_interactive_cluster_data(app, samples: ndarray, cluster_labels: ndarray, param_names: List[str], centroid_results: List[Dict], q_values: Any, original_data: Any | None, spectrum_idx: int = 0)¶

Export all interactive cluster visualization data to DataCollector.

This is the main entry point that exports both corner plot and curves data for interactive frontend visualization. Called by the clustering orchestrator after matplotlib visualizations are created.

Parameters:

app – VIPR application instance (with datacollector)
samples – Parameter samples array (num_samples, num_params)
cluster_labels – Cluster assignment for each sample
param_names – List of parameter names
centroid_results – List of dicts with centroid info (from simulation.py)
q_values – Q-values for reflectivity curves
original_data – Original experimental data (if available)
spectrum_idx – Spectrum index (for multi-spectrum batches)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.create_centroid_plots(app, centroid_results: List[Dict], q_values, original_data, param_names: List[str], spectrum_idx: int, samples: ndarray | None = None, cluster_labels: ndarray | None = None)¶

Orchestrate creation of all centroid-related plots.

Parameters:

app – VIPR application instance
centroid_results – List of dicts with centroid info and curves
q_values – Q-values for x-axis
original_data – Original experimental data
param_names – List of parameter names
spectrum_idx – Spectrum index
samples – Original parameter samples (for box-plot uncertainty visualization)
cluster_labels – Cluster assignments (for box-plot uncertainty visualization)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.create_cluster_marginals(app, samples: ndarray, cluster_labels: ndarray, param_names: list, spectrum_idx: int, cluster_sizes: list, centroid_results=None)¶

Create 1D marginal histograms for each parameter within each cluster.

Parameters:

app – VIPR application instance
samples – Parameter samples (num_samples, num_params)
cluster_labels – Cluster assignments
param_names – Names of parameters
spectrum_idx – Spectrum index
cluster_sizes – List of (label, size) tuples sorted by size descending
centroid_results – Optional list of centroid dicts with ‘centroid’ and ‘polished_params’ keys for overlay visualization

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.create_clustered_corner_plot(app, samples, cluster_labels, param_names, spectrum_idx, centroid_results=None)¶

Create improved corner plot with cluster overlay.

Parameters:

app – VIPR application instance
samples – Parameter samples (num_samples, num_params)
cluster_labels – Cluster assignments
param_names – Parameter names
spectrum_idx – Spectrum index
centroid_results – Optional list of centroid results (for polished markers)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.create_parallel_coordinates_plot(app, samples: ndarray, cluster_labels: ndarray, param_names: List[str], spectrum_idx: int, seed: int | None = None, cluster_sizes: list | None = None)¶

Create parallel coordinates plot with cluster coloring.

Features: - Axes sorted by separability (best cluster discriminators first) - Quantile clipping (1-99%) to remove outliers - Stratified sampling for cleaner visualization

Parameters:

app – VIPR application instance
samples – Parameter samples (num_samples, num_params)
cluster_labels – Cluster assignments for each sample
param_names – List of parameter names
spectrum_idx – Spectrum index
seed – Optional random seed for reproducible sampling (default: None)
cluster_sizes – List of (label, size) tuples sorted by size descending (default: None)

vipr_reflectometry.flow_models.postprocess.cluster.clustering.visualization.create_validation_plots(app, samples: ndarray, cluster_labels: ndarray, spectrum_idx: int, cluster_sizes: list)¶

Create cluster validation plots (silhouette only).

BIC/AIC analysis is now in the separate model_selection hook.

Parameters:

app – VIPR application instance
samples – Parameter samples (num_samples, num_params)
cluster_labels – Cluster assignments
spectrum_idx – Spectrum index
cluster_sizes – List of (label, size) tuples sorted by size descending