Visualization¶

Publication-quality plotting for MCMC diagnostics, NLSQ fit results, experimental data overlays, interactive dashboards, and summary reports.

MCMC Plots¶

Visualization for MCMC/CMC results.

heterodyne.viz.mcmc_plots.plot_posterior(result, params=None, save_path=None, figsize=None)[source]

Plot posterior distributions.

Parameters:

result (CMCResult) – CMC result with samples
params (list[str] | None) – Parameters to plot (None for all)
save_path (Path | str | None) – Optional save path
figsize (tuple[float, float] | None) – Optional figure size

Return type:

Figure

Returns:

Matplotlib figure

heterodyne.viz.mcmc_plots.plot_trace(result, params=None, save_path=None)[source]

Plot trace plots for MCMC chains.

Parameters:

result (CMCResult) – CMC result with samples
params (list[str] | None) – Parameters to plot
save_path (Path | str | None) – Optional save path

Return type:

Figure

Returns:

Matplotlib figure

heterodyne.viz.mcmc_plots.plot_corner(result, params=None, save_path=None)[source]

Plot corner plot showing parameter correlations.

Parameters:

result (CMCResult) – CMC result
params (list[str] | None) – Parameters to include
save_path (Path | str | None) – Optional save path

Return type:

Figure

Returns:

Matplotlib figure

heterodyne.viz.mcmc_plots.plot_forest(samples, param_names=None, credible_interval=0.94, save_path=None, figsize=None, dpi=150)[source]

Forest plot with highest-density interval (HDI) bars.

Each parameter is rendered as a horizontal bar spanning its HDI, with a dot at the posterior mean. Multiple chains/shards are overlaid with slight vertical offsets when the sample array is 2-D (n_chains, n_samples).

Parameters:

samples (dict[str, ndarray]) – Dictionary mapping parameter names to arrays of shape (n_samples,) or (n_chains, n_samples).
param_names (list[str] | None) – Ordered list of parameter names to include. When None, all keys of samples are used (sorted).
credible_interval (float) – Probability mass for the HDI bars. Must be in (0, 1). Default is 0.94 (94% HDI).
save_path (Path | str | None) – Optional path to save the figure.
figsize (tuple[float, float] | None) – Figure size (width, height). Auto-computed when None.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

Raises:

ValueError – If credible_interval is not in (0, 1).

heterodyne.viz.mcmc_plots.plot_energy(samples, save_path=None, figsize=(8, 5), dpi=150)[source]

Energy transition vs marginal energy diagnostic plot (NUTS).

Compares the distribution of the Hamiltonian energy at each transition (energy) with the marginal energy distribution (energy_diff = energy[1:] - energy[:-1]). Good mixing produces overlapping distributions; a separated pair indicates poor exploration of the posterior.

Parameters:

samples (dict[str, ndarray]) – Sample dictionary. Must contain an "energy" key with a 1-D array of Hamiltonian energies recorded by NUTS.
save_path (Path | str | None) – Optional save path.
figsize (tuple[float, float]) – Figure size (width, height).
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

heterodyne.viz.mcmc_plots.plot_autocorrelation(samples, param_names=None, max_lag=50, save_path=None, figsize=None, dpi=150)[source]

Per-parameter autocorrelation function plot.

Displays the sample autocorrelation function (ACF) up to max_lag for each requested parameter. Rapid decay to zero indicates efficient mixing; slow decay indicates high autocorrelation and low effective sample size.

Parameters:

samples (dict[str, ndarray]) – Dictionary mapping parameter names to sample arrays of shape (n_samples,) or (n_chains, n_samples).
param_names (list[str] | None) – Parameters to include. Defaults to all keys.
max_lag (int) – Maximum lag to compute. Clamped to n_samples - 1.
save_path (Path | str | None) – Optional save path.
figsize (tuple[float, float] | None) – Figure size. Auto-computed when None.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

heterodyne.viz.mcmc_plots.plot_rank_histogram(samples, param_names=None, save_path=None, figsize=None, dpi=150)[source]

Rank histogram (rank plot) for assessing between-chain mixing.

For each parameter, the combined samples from all chains are ranked. Each chain’s samples are assigned their global ranks, and the rank distribution for each chain is plotted as a histogram. Uniform rank histograms indicate well-mixed chains; U-shaped or spike-tailed histograms indicate convergence problems.

Requires sample arrays of shape (n_chains, n_samples); 1-D arrays are treated as single-chain and produce a trivially uniform plot (logged as a warning).

Parameters:

samples (dict[str, ndarray]) – Dictionary mapping parameter names to arrays of shape (n_chains, n_samples) or (n_samples,).
param_names (list[str] | None) – Parameters to include. Defaults to all keys.
save_path (Path | str | None) – Optional save path.
figsize (tuple[float, float] | None) – Figure size. Auto-computed when None.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

heterodyne.viz.mcmc_plots.plot_posterior_predictive(c2_observed, c2_predicted, times, phi_angle=None, n_samples_overlay=50, save_path=None, figsize=(14, 5), dpi=150)[source]

Posterior predictive check — model vs observed data overlay.

Displays three panels:

Observed c2 two-time matrix.
Posterior predictive mean (average over c2_predicted samples).
Residual observed - mean_predicted with symmetric colour scale.

Parameters:

c2_observed (ndarray) – Observed correlation matrix, shape (n_t, n_t).
c2_predicted (ndarray) – Posterior predictive draws, shape (n_posterior, n_t, n_t) or (n_t, n_t) for a single prediction.
times (ndarray) – 1-D time axis of length n_t.
phi_angle (float | None) – Optional azimuthal angle in degrees for the title.
n_samples_overlay (int) – Number of random diagonal slices to overlay on a fourth panel (0 disables the panel).
save_path (Path | str | None) – Optional save path.
figsize (tuple[float, float]) – Figure size.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

Raises:

ValueError – If array shapes are inconsistent.

heterodyne.viz.mcmc_plots.plot_shard_comparison(shard_results, param_names=None, save_path=None, figsize=None, dpi=150)[source]

Cross-shard posterior comparison for CMC diagnostics.

Overlays the marginal posterior histograms of each shard for every requested parameter. When shards produce similar posteriors, the histograms overlap; when they diverge, the plot reveals multi-modality or data heterogeneity.

Parameters:

shard_results (list[dict[str, ndarray]]) – List of sample dictionaries, one per shard. Each dictionary maps parameter names to 1-D sample arrays.
param_names (list[str] | None) – Parameters to compare. Defaults to keys found in the first shard.
save_path (Path | str | None) – Optional save path.
figsize (tuple[float, float] | None) – Figure size. Auto-computed when None.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

Raises:

ValueError – If shard_results is empty.

heterodyne.viz.mcmc_plots.plot_divergence_scatter(samples, divergent_mask, param_pairs=None, save_path=None, figsize=None, dpi=150)[source]

Scatter plot highlighting divergent transitions.

Plots pairs of parameters as scatter plots, colouring divergent transitions in red and non-divergent transitions in grey. Divergent transitions that cluster in parameter space indicate problematic posterior geometry (e.g., funnel-shaped posteriors).

Parameters:

samples (dict[str, ndarray]) – Dictionary mapping parameter names to 1-D sample arrays of the same length.
divergent_mask (ndarray) – Boolean array of length n_samples where True marks a divergent transition.
param_pairs (list[tuple[str, str]] | None) – List of (param_x, param_y) tuples to plot. Defaults to all adjacent pairs of sorted parameter names.
save_path (Path | str | None) – Optional save path.
figsize (tuple[float, float] | None) – Figure size. Auto-computed when None.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

Raises:

ValueError – If divergent_mask length does not match sample length, or if a requested parameter is missing from samples.

heterodyne.viz.mcmc_plots.plot_rhat_summary(rhat_dict, threshold=1.01, save_path=None, figsize=None, dpi=150)[source]

R-hat bar chart with convergence threshold line.

Renders one bar per parameter coloured green (converged, R-hat < threshold) or red (not converged). A dashed horizontal line marks threshold.

Parameters:

rhat_dict (dict[str, float]) – Dictionary mapping parameter names to their R-hat scalar values.
threshold (float) – Convergence threshold. The standard criterion is R-hat < 1.01 (strict) or < 1.1 (relaxed). Default is 1.01.
save_path (Path | str | None) – Optional save path.
figsize (tuple[float, float] | None) – Figure size. Auto-computed when None.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

Raises:

ValueError – If rhat_dict is empty.

ArviZ Integration¶

Convert CMC results to ArviZ InferenceData and render standard ArviZ diagnostic plots (trace, posterior, pair plots).

ArviZ-based MCMC visualization for heterodyne analysis.

Provides publication-quality trace, posterior, and pair plots using ArviZ, with graceful fallback to the basic mcmc_plots module when ArviZ is not installed.

heterodyne.viz.mcmc_arviz.to_inference_data(cmc_result)[source]

Convert a CMCResult to an ArviZ InferenceData object.

Delegates to cmc_result_to_arviz in the results module.

Parameters:

cmc_result (CMCResult) – Completed CMC analysis result with posterior samples.

Return type:

Any

Returns:

arviz.InferenceData with posterior group.

Raises:

ImportError – If ArviZ is not installed.
ValueError – If samples are empty.

heterodyne.viz.mcmc_arviz.plot_arviz_trace(result, var_names=None, save_path=None)[source]

Plot MCMC trace using ArviZ, with fallback to basic plots.

Parameters:

result (CMCResult) – CMC result with posterior samples.
var_names (list[str] | None) – Parameter names to plot. None plots all.
save_path (Path | str | None) – Path to save the figure. None displays interactively.

Return type:

Figure | None

Returns:

Matplotlib Figure, or None if ArviZ not available and fallback used.

heterodyne.viz.mcmc_arviz.plot_arviz_posterior(result, var_names=None, hdi_prob=0.95, save_path=None)[source]

Plot posterior distributions using ArviZ.

Parameters:

result (CMCResult) – CMC result with posterior samples.
var_names (list[str] | None) – Parameter names to plot. None plots all.
hdi_prob (float) – Highest density interval probability. Default 0.95.
save_path (Path | str | None) – Path to save the figure.

Return type:

Figure | None

Returns:

Matplotlib Figure, or None on fallback.

heterodyne.viz.mcmc_arviz.plot_arviz_pair(result, var_names=None, save_path=None)[source]

Plot pairwise posterior relationships using ArviZ.

Parameters:

result (CMCResult) – CMC result with posterior samples.
var_names (list[str] | None) – Parameter names to include. None uses all.
save_path (Path | str | None) – Path to save the figure.

Return type:

Figure | None

Returns:

Matplotlib Figure.

MCMC Diagnostics Plots¶

MCMC convergence diagnostic plots for heterodyne analysis.

Provides visualization of convergence metrics including ESS evolution, adaptation summaries, and divergence analysis for NUTS sampling.

heterodyne.viz.mcmc_diagnostics.plot_ess_evolution(result, save_path=None)[source]

Plot effective sample size (ESS) across parameters.

Shows bulk and tail ESS as a grouped bar chart, with a horizontal reference line at the minimum recommended ESS (400).

Parameters:

result (CMCResult) – CMC result with ESS diagnostics.
save_path (Path | str | None) – Path to save the figure.

Return type:

Figure

Returns:

Matplotlib Figure.

heterodyne.viz.mcmc_diagnostics.plot_adaptation_summary(result, save_path=None)[source]

Plot R-hat convergence diagnostic across parameters.

Shows R-hat values as a bar chart with a horizontal reference line at the convergence threshold (1.1).

Parameters:

result (CMCResult) – CMC result with R-hat diagnostics.
save_path (Path | str | None) – Path to save the figure.

Return type:

Figure

Returns:

Matplotlib Figure.

heterodyne.viz.mcmc_diagnostics.plot_divergence_scatter(result, save_path=None)[source]

Plot divergence analysis scatter plot.

If divergence information is available in result metadata, shows a scatter plot of parameter values for divergent vs non-divergent transitions. Falls back to a posterior density summary if no divergence info is available.

Parameters:

result (CMCResult) – CMC result.
save_path (Path | str | None) – Path to save the figure.

Return type:

Figure

Returns:

Matplotlib Figure.

heterodyne.viz.mcmc_diagnostics.plot_kl_divergence_matrix(result, save_path=None)[source]

Plot pairwise KL divergence heatmap between parameter posteriors.

Computes histogram-based KL divergence for each pair of parameters using 50-bin histograms with epsilon smoothing.

Parameters:

result (CMCResult) – CMC result with posterior samples.
save_path (Path | str | None) – Path to save the figure.

Return type:

Figure

Returns:

Matplotlib Figure.

heterodyne.viz.mcmc_diagnostics.plot_convergence_diagnostics(result, save_path=None)[source]

Plot a 2x2 MCMC convergence summary figure.

Panels:: (0,0) ESS bulk bar chart (0,1) R-hat bar chart with threshold (1,0) BFMI bar chart per chain with threshold (1,1) Text summary of key convergence statistics

Parameters:

result (CMCResult) – CMC result with convergence diagnostics.
save_path (Path | str | None) – Path to save the figure.

Return type:

Figure

Returns:

Matplotlib Figure.

MCMC Dashboard¶

MCMC Summary Dashboard Visualization.

Provides a comprehensive multi-panel CMC summary dashboard combining convergence diagnostics, trace plots, and posterior histograms.

heterodyne.viz.mcmc_dashboard.plot_cmc_summary_dashboard(result, figsize=(16, 12), save_path=None, dpi=150)[source]

Create comprehensive multi-panel CMC summary dashboard.

Combines key diagnostic plots into a single figure: - Panel 1: R-hat per parameter (convergence quality) - Panel 2: ESS per parameter (sampling efficiency) - Panel 3: Trace plots (selected parameters) - Panel 4: Posterior histograms (selected parameters)

Parameters:

result (CMCResult) – CMC result object with posterior samples and diagnostics.
figsize (tuple[float, float]) – Figure size (width, height).
save_path (str | Path | None) – If provided, save figure to this path.
dpi (int) – DPI for saved figure.

Returns:

Matplotlib figure object.

Return type:

Figure

Examples

>>> plot_cmc_summary_dashboard(cmc_result, save_path='cmc_summary.png')

NLSQ vs CMC Comparison¶

Side-by-side overlays comparing NLSQ point estimates with CMC posterior distributions across angles.

NLSQ vs CMC comparison plots for heterodyne analysis.

Provides side-by-side visualization of point estimates (NLSQ) against posterior distributions (CMC) for assessing consistency between optimization and Bayesian inference results.

heterodyne.viz.mcmc_comparison.plot_nlsq_vs_cmc(nlsq_result, cmc_result, save_path=None)[source]

Plot NLSQ point estimates against CMC posterior distributions.

For each shared parameter, shows the posterior distribution as a violin/box and overlays the NLSQ point estimate with error bars.

Parameters:

nlsq_result (NLSQResult) – NLSQ optimization result.
cmc_result (CMCResult) – CMC Bayesian result with posterior samples.
save_path (Path | str | None) – Path to save the figure.

Return type:

Figure

Returns:

Matplotlib Figure.

heterodyne.viz.mcmc_comparison.plot_multi_angle_comparison(results_by_phi, save_path=None)[source]

Plot parameter posteriors across multiple phi angles.

Creates a grid showing how posterior distributions vary with detector angle, useful for assessing angle-dependent systematics.

Parameters:

results_by_phi (dict[float, CMCResult]) – Dict mapping phi angle (degrees) to CMCResult.
save_path (Path | str | None) – Path to save the figure.

Return type:

Figure

Returns:

Matplotlib Figure.

NLSQ Plots¶

Visualization for NLSQ fitting results.

heterodyne.viz.nlsq_plots.plot_nlsq_fit(c2_data, result, t=None, save_path=None, figsize=(15, 5))[source]

Plot NLSQ fit comparison.

Creates three-panel figure: 1. Experimental data 2. Fitted model 3. Residuals

Parameters:

c2_data (ndarray) – Experimental correlation data
result (NLSQResult) – NLSQ fitting result
t (ndarray | None) – Optional time array
save_path (Path | str | None) – Optional path to save figure
figsize (tuple[float, float]) – Figure size

Return type:

Figure

Returns:

Matplotlib figure

heterodyne.viz.nlsq_plots.plot_residual_map(result, c2_data, t=None, save_path=None)[source]

Plot detailed residual analysis.

Parameters:

result (NLSQResult) – NLSQ result
c2_data (ndarray) – Original data
t (ndarray | None) – Time array
save_path (Path | str | None) – Optional save path

Return type:

Figure

Returns:

Matplotlib figure

heterodyne.viz.nlsq_plots.plot_parameter_uncertainties(result, save_path=None)[source]

Plot parameter values with uncertainties.

Parameters:

result (NLSQResult) – NLSQ result
save_path (Path | str | None) – Optional save path

Return type:

Figure

Returns:

Matplotlib figure

heterodyne.viz.nlsq_plots.plot_fit_surface(c2_exp, c2_fit, times, phi_angle=None, save_path=None, figsize=(14, 5), dpi=150)[source]

Side-by-side 2D heatmaps: experimental data, fit, and residuals.

Three panels are rendered with per-panel percentile-based colour scaling so that structure is visible in both the experimental and fitted matrices even when their absolute ranges differ.

Parameters:

c2_exp (ndarray) – Experimental correlation matrix, shape (n_t, n_t).
c2_fit (ndarray) – Fitted model correlation matrix, shape (n_t, n_t).
times (ndarray) – 1-D time axis of length n_t (seconds).
phi_angle (float | None) – Optional azimuthal angle in degrees for the title.
save_path (Path | str | None) – Optional path to save the figure.
figsize (tuple[float, float]) – Figure size (width, height).
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

Raises:

ValueError – If c2_exp and c2_fit have different shapes.

heterodyne.viz.nlsq_plots.plot_per_angle_residuals(residuals, phi_angles, times, save_path=None, figsize=None, dpi=150)[source]

Per-angle 2D residual heatmap.

Renders one heatmap panel per phi angle, showing the signed residual (experimental - fitted) on a symmetric diverging colour scale.

Parameters:

residuals (ndarray) – 3-D array of shape (n_angles, n_t, n_t).
phi_angles (ndarray) – 1-D array of azimuthal angles in degrees, length n_angles.
times (ndarray) – 1-D time axis of length n_t (seconds).
save_path (Path | str | None) – Optional path to save the figure.
figsize (tuple[float, float] | None) – Figure size. Auto-computed when None.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

Raises:

ValueError – If residuals.shape[0] differs from len(phi_angles).

heterodyne.viz.nlsq_plots.plot_parameter_evolution(history, param_names, save_path=None, figsize=None, dpi=150)[source]

Parameter values across multistart optimisation attempts.

Displays the trajectory of each parameter’s best-so-far value and the individual starting-point results as scatter dots, making it easy to see whether multistart has converged on a consistent solution.

Parameters:

history (list[dict[str, Any]]) –
List of result records, one per multistart attempt (ordered by attempt index). Each record must contain:
- "params" – 1-D array of parameter values, same length as param_names.
- "loss" – scalar loss value for this attempt.
- "converged" – bool flag (optional, default True).
param_names (list[str]) – Parameter names corresponding to the "params" arrays.
save_path (Path | str | None) – Optional save path.
figsize (tuple[float, float] | None) – Figure size. Auto-computed when None.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

Raises:

ValueError – If history is empty or param_names is empty.

heterodyne.viz.nlsq_plots.plot_scaling_comparison(solver_scaling, lstsq_scaling, phi_angles, param_labels=('contrast', 'offset'), save_path=None, figsize=(10, 5), dpi=150)[source]

Contrast and offset comparison: solver vs least-squares post-hoc.

Side-by-side bar charts compare the contrast and offset values produced by the nonlinear solver with those derived from the post-hoc linear least-squares scaling step. Significant disagreement may indicate a poorly conditioned solver or overfitting.

Parameters:

solver_scaling (ndarray) – Array of shape (n_angles, 2) containing [contrast, offset] from the nonlinear solver for each phi angle.
lstsq_scaling (ndarray) – Array of shape (n_angles, 2) containing [contrast, offset] from the least-squares scaling step.
phi_angles (ndarray) – 1-D array of phi angles in degrees, length n_angles.
param_labels (tuple[str, str]) – Labels for the two scaling parameters. Default is ("contrast", "offset").
save_path (Path | str | None) – Optional save path.
figsize (tuple[float, float]) – Figure size.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

Raises:

ValueError – If array shapes are inconsistent.

heterodyne.viz.nlsq_plots.plot_chi_squared_landscape(chi2_values, param_values, param_name, best_value=None, save_path=None, figsize=(8, 5), dpi=150)[source]

1-D chi-squared profile plot for a single parameter.

Displays how the reduced chi-squared changes as one parameter is swept through a range of values (all other parameters fixed at their best-fit values). The minimum of the profile locates the best-fit value; the width at Δχ² = 1 gives the 68% confidence interval for that parameter.

Parameters:

chi2_values (ndarray) – 1-D array of reduced chi-squared values, length n_sweep.
param_values (ndarray) – 1-D array of parameter values swept, length n_sweep.
param_name (str) – Human-readable parameter name for axis labels.
best_value (float | None) – Optional known best-fit value; if provided, a vertical dashed line is drawn at this position.
save_path (Path | str | None) – Optional save path.
figsize (tuple[float, float]) – Figure size.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

Raises:

ValueError – If chi2_values and param_values have different lengths.

heterodyne.viz.nlsq_plots.plot_multistart_summary(results, save_path=None, figsize=(12, 5), dpi=150)[source]

Loss distribution and convergence summary across multistart attempts.

Three panels:

Loss histogram — distribution of final loss values across all starts, with the best loss marked.
Loss rank plot — loss values sorted in ascending order to reveal the shape of the basin landscape.
Convergence fraction — pie chart of converged vs non-converged starts.

Parameters:

results (list[dict[str, Any]]) –
List of result dictionaries, one per multistart attempt. Each record must contain:
- "loss" – scalar final loss.
- "converged" – bool convergence flag.
save_path (Path | str | None) – Optional save path.
figsize (tuple[float, float]) – Figure size.
dpi (int) – Resolution for saved figures.

Return type:

Figure

Returns:

Matplotlib figure.

Raises:

ValueError – If results is empty.

heterodyne.viz.nlsq_plots.plot_simulated_data(config, contrast, offset, phi_angles_str, plots_dir, data=None)[source]

Generate heatmap plots of theoretical/simulated C2 data.

Constructs the heterodyne model from config, evaluates the forward model for each phi angle, and saves per-angle heatmaps plus a combined diagonal plot.

Parameters:

config (dict[str, Any]) – Configuration dictionary with model parameters.
contrast (float) – Optical contrast for scaling.
offset (float) – Baseline offset.
phi_angles_str (str | None) – Comma-separated phi angles (e.g. "0,45,90").
plots_dir (Path) – Output directory for plots.
data (dict[str, Any] | None) – Optional experimental data dict for extracting phi angles.

Return type:

None

heterodyne.viz.nlsq_plots.generate_nlsq_plots(phi_angles, c2_exp, c2_theoretical_scaled, residuals, t1, t2, output_dir, config=None, use_datashader=True, parallel=True, *, c2_solver_scaled=None)[source]

Generate 3-panel heatmaps (experimental | fit | residuals) per angle.

For each phi angle, creates a 1x3 subplot figure showing experimental data, theoretical fit, and residuals side by side.

Parameters:

phi_angles (ndarray) – Scattering angles in degrees, shape (n_angles,).
c2_exp (ndarray) – Experimental correlation, shape (n_angles, n_t1, n_t2).
c2_theoretical_scaled (ndarray) – Scaled theoretical fits, same shape.
residuals (ndarray) – Residuals exp - fit, same shape.
t1 (ndarray) – First time array in seconds.
t2 (ndarray) – Second time array in seconds.
output_dir (Path) – Directory for output PNG files.
config (Any) – Optional config for color scaling options.
use_datashader (bool) – When True and Datashader backend is available, emit a rasterized nlsq_overview_datashader.png covering all angles (fast preview for large matrices). The per-angle matplotlib panels are still produced regardless.
parallel (bool) – Reserved for future parallel generation.
c2_solver_scaled (ndarray | None) – Optional solver-computed C2 to display instead of c2_theoretical_scaled.

Return type:

None

heterodyne.viz.nlsq_plots.generate_and_plot_fitted_simulations(result, data, config, output_dir, angle_filter_func=None)[source]

Generate forward simulations from fitted parameters and plot.

Uses the fitted parameters from result to evaluate the heterodyne model, saves the simulated C2 to NPZ, and generates per-angle heatmap plots.

Parameters:

result (Any) – Optimization result with fitted parameters.
data (dict[str, Any]) – Experimental data dictionary.
config (dict[str, Any]) – Configuration dictionary.
output_dir (Path) – Root output directory (simulated_data/ subdirectory is created automatically).
angle_filter_func (Any | None) – Optional angle filter applied to data before simulation.

Return type:

None

Experimental Plots¶

Visualization for experimental XPCS data.

heterodyne.viz.experimental_plots.plot_correlation(c2, t=None, title='Two-Time Correlation', save_path=None, cmap='viridis', vmin=None, vmax=None)[source]

Plot two-time correlation matrix.

Parameters:

c2 (ndarray) – Correlation matrix, shape (N, N)
t (ndarray | None) – Time array
title (str) – Plot title
save_path (Path | str | None) – Optional save path
cmap (str) – Colormap name
vmin (float | None) – Color scale limits
vmax (float | None) – Color scale limits

Return type:

Figure

Returns:

Matplotlib figure

heterodyne.viz.experimental_plots.plot_g1_components(model, params=None, save_path=None)[source]

Plot g1 correlation components (reference and sample).

Parameters:

model (HeterodyneModel) – HeterodyneModel instance
params (ndarray | None) – Parameter array (uses model’s current params if None)
save_path (Path | str | None) – Optional save path

Return type:

Figure

Returns:

Matplotlib figure

heterodyne.viz.experimental_plots.plot_diagonal_decay(c2, t=None, fitted_c2=None, save_path=None)[source]

Plot diagonal of correlation matrix (autocorrelation decay).

Parameters:

c2 (ndarray) – Correlation matrix
t (ndarray | None) – Time array
fitted_c2 (ndarray | None) – Optional fitted correlation matrix
save_path (Path | str | None) – Optional save path

Return type:

Figure

Returns:

Matplotlib figure

heterodyne.viz.experimental_plots.plot_phi_dependence(c2_multi_phi, phi_angles, t_slice=None, save_path=None)[source]

Plot phi angle dependence of correlation.

Parameters:

c2_multi_phi (ndarray) – Correlation data, shape (n_phi, N, N)
phi_angles (ndarray) – Array of phi angles
t_slice (int | None) – Time index for slice (None for t=0)
save_path (Path | str | None) – Optional save path

Return type:

Figure

Returns:

Matplotlib figure

heterodyne.viz.experimental_plots.plot_experimental_data(data, plots_dir, angle_filter_func=None)[source]

Generate validation plots of experimental data.

Parameters:

data (dict[str, Any]) – Data dictionary containing: - c2_exp: Experimental correlation data (n_phi, n_t1, n_t2) or (n_t1, n_t2) - t1: Time array 1 (optional) - t2: Time array 2 (optional) - phi_angles_list: Phi angles in degrees (optional) - config: Configuration dict for angle filtering (optional)
plots_dir (Path) – Output directory for plot files
angle_filter_func (Any | None) – Function to apply angle filtering. Signature: (phi_angles, c2_exp, data) -> (filtered_indices, filtered_phi, filtered_c2)

Return type:

None

heterodyne.viz.experimental_plots.plot_fit_comparison(result, data, plots_dir)[source]

Generate comparison plots between fit and experimental data.

Parameters:

result (Any) – Optimization result object
data (dict[str, Any]) – Experimental data dictionary
plots_dir (Path) – Output directory for plot files

Return type:

None

Diagonal Overlay Diagnostics¶

Two-time correlation diagonal statistics for validating stationarity and ergodicity of the measured correlation function.

Diagnostic overlay plots for XPCS analysis.

Provides visualisations that aid interactive assessment of correlation data, residuals, fitting weights, and parameter sensitivities.

heterodyne.viz.diagnostics.plot_diagonal_overlay(c2, corrected_c2, times, ax=None)[source]

Show before/after diagonal correction on c2.

Overlays the diagonal of the original and corrected correlation matrices so the user can verify that diagonal artefacts have been removed.

Parameters:

c2 (ndarray) – Original correlation matrix, shape (N, N).
corrected_c2 (ndarray) – Corrected correlation matrix, shape (N, N).
times (ndarray) – 1-D time array of length N.
ax (Axes | None) – Optional existing Axes; one is created if None.

Return type:

Axes

Returns:

The matplotlib Axes containing the plot.

heterodyne.viz.diagnostics.plot_residual_map(residuals, times, ax=None)[source]

2-D heatmap of fit residuals.

Parameters:

residuals (ndarray) – Residual matrix, shape (N, N).
times (ndarray) – 1-D time array of length N.
ax (Axes | None) – Optional existing Axes.

Return type:

Axes

Returns:

The matplotlib Axes containing the heatmap.

heterodyne.viz.diagnostics.plot_weight_map(weights, times, ax=None)[source]

Visualise the fitting weight matrix.

Parameters:

weights (ndarray) – Weight matrix, shape (N, N).
times (ndarray) – 1-D time array of length N.
ax (Axes | None) – Optional existing Axes.

Return type:

Axes

Returns:

The matplotlib Axes containing the heatmap.

heterodyne.viz.diagnostics.plot_convergence_trace(losses, ax=None, log_scale=True)[source]

Plot optimization convergence trace.

Parameters:

losses (ndarray) – Loss values per iteration, shape (n_iter,).
ax (Axes | None) – Optional existing Axes.
log_scale (bool) – Use log scale for y-axis.

Return type:

Axes

Returns:

The matplotlib Axes.

heterodyne.viz.diagnostics.plot_trace_posterior(samples, param_names=None, figsize=None)[source]

Trace + posterior density plots for MCMC samples.

Creates a two-column layout: left column shows trace plots, right column shows marginal posterior histograms.

Parameters:

samples (dict[str, ndarray]) – Dict mapping parameter names to sample arrays, each of shape (n_samples,) or (n_chains, n_samples).
param_names (list[str] | None) – Subset of parameter names to plot (default: all).
figsize (tuple[float, float] | None) – Optional figure size.

Return type:

Figure

Returns:

The matplotlib Figure.

heterodyne.viz.diagnostics.plot_pair_correlation(samples, param_names=None, ax=None)[source]

Parameter correlation matrix heatmap.

Parameters:

samples (dict[str, ndarray]) – Dict mapping parameter names to 1-D sample arrays.
param_names (list[str] | None) – Subset of names to include (default: all).
ax (Axes | None) – Optional existing Axes.

Return type:

Axes

Returns:

The matplotlib Axes.

heterodyne.viz.diagnostics.plot_residual_histogram(residuals, ax=None)[source]

Histogram of residuals with Gaussian overlay.

Parameters:

residuals (ndarray) – Residual array (any shape, will be flattened).
ax (Axes | None) – Optional existing Axes.

Return type:

Axes

Returns:

The matplotlib Axes.

heterodyne.viz.diagnostics.plot_parameter_sensitivity(sensitivity_dict, ax=None)[source]

Bar chart of per-parameter sensitivity values.

Parameters:

sensitivity_dict (dict[str, float]) – Mapping of parameter name to sensitivity value.
ax (Axes | None) – Optional existing Axes.

Return type:

Axes

Returns:

The matplotlib Axes containing the bar chart.

class heterodyne.viz.diagnostics.DiagonalOverlayResult[source]

Bases: object

Statistics from comparing diagonals of experimental vs fitted C2 surfaces.

phi_index: Angle index used for extraction.

raw_diagonal: Diagonal of the experimental C2.

solver_diagonal: Diagonal of the solver-fitted C2.

posthoc_diagonal: Diagonal of the post-hoc corrected C2.

raw_variance: Variance of the raw diagonal.

solver_variance: Variance of the solver diagonal.

posthoc_variance: Variance of the post-hoc diagonal.

solver_rmse: RMSE between raw and solver diagonals.

posthoc_rmse: RMSE between raw and post-hoc diagonals.

phi_index: int

raw_diagonal: ndarray

solver_diagonal: ndarray

posthoc_diagonal: ndarray

raw_variance: float

solver_variance: float

posthoc_variance: float

solver_rmse: float

posthoc_rmse: float

__init__(phi_index, raw_diagonal, solver_diagonal, posthoc_diagonal, raw_variance, solver_variance, posthoc_variance, solver_rmse, posthoc_rmse)

heterodyne.viz.diagnostics.compute_diagonal_overlay_stats(c2_exp, c2_solver, c2_posthoc, *, phi_index=0)[source]

Compute diagonal overlay statistics for visual validation.

Extracts the diagonal from each C2 matrix at the given angle index and computes variance and RMSE metrics.

Parameters:

c2_exp (ndarray) – Experimental C2, shape (n_phi, N, N).
c2_solver (ndarray | None) – Solver-fitted C2, shape (n_phi, N, N).
c2_posthoc (ndarray) – Post-hoc corrected C2, shape (n_phi, N, N).
phi_index (int) – Angle index to extract.

Return type:

DiagonalOverlayResult

Returns:

DiagonalOverlayResult with diagonal arrays and metrics.

Raises:

ValueError – If c2_solver is None.

MCMC Report¶

MCMC analysis report generation for heterodyne analysis.

Generates comprehensive Markdown reports summarizing NLSQ and CMC results including parameter tables, convergence diagnostics, and fit quality metrics.

class heterodyne.viz.mcmc_report.ReportConfig[source]

Bases: object

Configuration for report generation.

include_diagnostics: Include convergence diagnostic tables.

include_timing: Include timing information.

include_correlation: Include parameter correlation analysis.

ci_level: Credible interval level (“95” or “89”).

float_precision: Decimal places for floating-point values.

include_diagnostics: bool = True

include_timing: bool = True

include_correlation: bool = True

ci_level: str = '95'

float_precision: int = 4

__init__(include_diagnostics=True, include_timing=True, include_correlation=True, ci_level='95', float_precision=4)

heterodyne.viz.mcmc_report.generate_report(nlsq_results=None, cmc_results=None, output_dir=None, config=None)[source]

Generate a comprehensive Markdown analysis report.

Creates a structured summary of the fitting results including: - Parameter estimates with uncertainties - Convergence diagnostics (R-hat, ESS, BFMI) - Fit quality metrics (chi-squared, cost) - Timing and configuration summary

Parameters:

nlsq_results (list[NLSQResult] | None) – List of NLSQ results (one per phi angle).
cmc_results (list[CMCResult] | None) – List of CMC results (one per phi angle).
output_dir (Path | str | None) – Directory to write the report file. If None, returns the report as a string instead of writing.
config (ReportConfig | None) – Report configuration. Uses defaults if None.

Return type:

Path | str

Returns:

Path to the written report file, or the report string if output_dir is None.