calibrain.Visualizer#

class calibrain.Visualizer(base_save_path='results/figures', logger=None)[source]#

Methods

`plot_active_sources`(x_one_trial_one_time, ...)	Plot the active sources at a specific time step, or averaged across time, comparing ground truth and estimated values.
`plot_all`(x, x_active_indices, x_hat, ...[, ...])	Comprehensive visualization wrapper that generates all plots for experiment analysis.
`plot_calibration`(nominal_coverage, ...[, ...])	Plot calibration curves and errors.
`plot_ci`(x_one_trial_one_time, ...[, ...])
`plot_pointwise_coverage_map`(x, ci_lower, ...)	Plot spatial maps showing point-wise coverage for different confidence levels.
`plot_pre_post_calibration_curves`(...[, ...])	Plot pre- and post-calibration curves for uncertainty quantification.
`plot_reconstructed_active_sources`(...[, ...])	Plot reconstructed source waveforms overlaid in a single plot.
`plot_sensor_signals`(ERP_config, y[, ...])	Plot sensor signals for a single dataset (no trial dimension).
`plot_source_and_sensors`(x_one_trial, ...[, ...])	Visualize source activity and sensor measurements.
`plot_source_signals`(ERP_config, x[, ...])	Plot source signals for a single dataset (no trial dimension).
`plot_stc_3d_brain`(ERP_config, x_one_trial, ...)	Plot source estimates with complete headless support.

__init__(base_save_path='results/figures', logger=None)[source]#

plot_pointwise_coverage_map(x, ci_lower, ci_upper, nominal_coverages, file_name='pointwise_coverage_map', save_path=None, show=False)[source]#

Plot spatial maps showing point-wise coverage for different confidence levels.

Parameters:

x (ndarray) – True source activity, shape (n_sources,) or (n_sources, n_times).
ci_lower (ndarray) – Lower confidence bounds, shape (n_coverages, n_sources).
ci_upper (ndarray) – Upper confidence bounds, shape (n_coverages, n_sources).
nominal_coverages (ndarray) – Nominal coverage levels.

plot_source_signals(ERP_config, x, x_active_indices=None, units=None, unitmult=None, title='Source Signals', save_dir=None, file_name=None, show=True)[source]#

Plot source signals for a single dataset (no trial dimension).

Parameters:

ERP_config (dict) – ERP configuration dictionary.
x (np.ndarray) – Source activity. Shape (n_sources, n_times) for fixed orientation or (n_sources, 3, n_times) for free orientation.
x_active_indices (np.ndarray, optional) – Indices of active sources.
units (str or int, optional) – Units for the source signals.
unitmult (int, optional) – Unit multiplier.
title (str, optional) – Title for the plot.
save_dir (str, optional) – Directory to save the plot.
file_name (str, optional) – Filename for the saved plot.
show (bool, optional) – Whether to show the plot.

plot_sensor_signals(ERP_config, y, channels=None, units=None, unitmult=None, title='Sensor Signals', save_dir=None, file_name=None, show=True)[source]#

Plot sensor signals for a single dataset (no trial dimension).

Parameters:

ERP_config (dict) – ERP configuration dictionary.
y (np.ndarray) – Sensor data. Shape (n_sensors, n_times).
channels (Sequence[int] or str, optional) – Channel indices to plot, or “all”.
units (str or int, optional) – Units for the sensor signals.
unitmult (int, optional) – Unit multiplier.
title (str, optional) – Title for the plot.
save_dir (str, optional) – Directory to save the plot.
file_name (str, optional) – Filename for the saved plot.
show (bool, optional) – Whether to show the plot.

plot_stc_3d_brain(ERP_config, x_one_trial, x_hat_one_trial, orientations, source_units, source_unitmult, sample_idx, subject, fwd_path, save_dir=None, file_name=None, show=False)[source]#: Plot source estimates with complete headless support.

plot_source_and_sensors(x_one_trial, x_active_indices, y_clean_one_trial, y_noisy_one_trial, nnz, ERP_config=None, source_units=202(FIFF_UNIT_AM), source_unitmult=None, sensor_units=107(FIFF_UNIT_V), sensor_unitmult=None, orientation_type='fixed', max_sensors=3, plot_sensors_together=False, shift=20.0, figsize=(14, 10), file_name='data_simulation.png', save_path='results/figures/data_sim.png', show=False)[source]#

Visualize source activity and sensor measurements.

Plots active source time courses and compares clean vs. noisy sensor signals. Includes a line indicating stimulus onset. Uses self.tmin and self.tmax for the time axis.

Parameters:

x (np.ndarray) – Source activity. Shape depends on orientation type.
y_clean (np.ndarray) – Clean sensor measurements (n_sensors, n_times).
y_noisy (np.ndarray) – Noisy sensor measurements (n_sensors, n_times).
active_sources (Optional[np.ndarray], optional) – Indices of non-zero (active) sources. If None, they are determined from x, by default None.
nnz_to_plot (int, optional) – Number of non-zero sources to plot. If -1, plot all non-zero sources found, by default -1.
sfreq (float, optional) – Sampling frequency in Hz, by default self.sfreq.
max_sensors (int, optional) – Maximum number of sensors to plot, by default 3.
plot_sensors_together (bool, optional) – If True, plot all sensors on the same subplot. If False, stack plots vertically, by default False.
shift (float, optional) – Vertical shift between sensors when plotting together, by default 20.0.
figsize (Tuple[float, float], optional) – Figure size for the plot, by default (14, 10).
save_path (Optional[str], optional) – Path to save the figure. If None, the figure is not saved, by default ‘results/figures/data_sim.png’.
show (bool, optional) – If True, display the plot, by default False.

Return type:

None

plot_active_sources(x_one_trial_one_time, x_hat_one_trial_one_time, x_active_indices, x_hat_active_indices, n_sources, source_units=202(FIFF_UNIT_AM), source_unitmult=None, orientation_type='fixed', save_path=None, file_name=None, title=None, show=True)[source]#

Plot the active sources at a specific time step, or averaged across time, comparing ground truth and estimated values.

Parameters:

x (np.ndarray) – Ground truth values for components specified by active_indices.
x_hat (np.ndarray) – Estimated values for components specified by active_indices.
x_active_indices (np.ndarray) – Indices of active sources in the ground truth.
x_hat_active_indices (np.ndarray) – Indices of active sources in the estimated values.
n_sources (int) – Total number of sources.
source_units (str, optional) – Units for the source signals, by default FIFF.FIFF_UNIT_AM
orientation_type (str, optional) – Orientation type for the plot, by default “fixed”
save_path (Optional[str], optional) – Path to save the plot, by default None
file_name (Optional[str], optional) – Name of the file to save the plot, by default None
title (Optional[str], optional) – Title of the plot, by default None
show (bool, optional) – Whether to show the plot, by default True

plot_reconstructed_active_sources(ERP_config, x_hat_trial, x_active_indices, units=202(FIFF_UNIT_AM), unitmult=None, max_sources=6, save_dir=None, file_name=None, show=False)[source]#

Plot reconstructed source waveforms overlaid in a single plot.

This is a convenience wrapper around plot_source_signals() for reconstructed sources.

Parameters:

ERP_config (dict) – ERP configuration dictionary to derive time axis.
x_hat_trial (np.ndarray) – Reconstructed source activity (n_sources, n_times) or (n_sources, 3, n_times).
x_active_indices (Sequence[int]) – Indices of ground-truth active sources to visualize.
units (str | int, optional) – Source unit (FIFF constant or string). Default FIFF.FIFF_UNIT_AM.
unitmult (int, optional) – FIFF multiplier (e.g., FIFF_UNITM_N).
max_sources (int, optional) – Maximum number of sources to display. Default 6.
save_dir (str, optional) – Directory to save the plot.
file_name (str, optional) – Filename for the saved plot.
show (bool, optional) – Whether to show the plot.

plot_ci(x_one_trial_one_time, x_hat_one_trial_one_time, x_active_indices, x_hat_active_indices, n_sources, source_units, source_unitmult, ci_lower, ci_upper, confidence_levels, orientation_type='fixed', sharey=True, file_name='active_sources_ci', save_path=None, show=True, figsize=(12, 6))[source]#

plot_calibration(nominal_coverage, pre_empirical_coverage, post_empirical_coverage, pre_weights=None, post_weights=None, file_name='calibration_curve', save_path=None, show=False)[source]#

Plot calibration curves and errors. Accepts either a single curve or stacked curves (runs x levels). When multiple curves are provided, the mean and standard deviation across runs are displayed; optional weights can be used to compute weighted statistics.

Parameters:

nominal_coverage (ndarray) – Array of nominal coverage levels (confidence levels).
pre_empirical_coverage (ndarray | ndarray runs x levels) – Empirical coverage before calibration.
post_empirical_coverage (ndarray | ndarray runs x levels) – Empirical coverage after calibration.
pre_weights (array-like, optional) – Sample weights for the pre-calibration curves.
post_weights (array-like, optional) – Sample weights for the post-calibration curves.

plot_pre_post_calibration_curves(confidence_levels, nominal_coverages, empirical_coverages_pre, empirical_coverages_post, file_name='pre_post_calibration_curve', save_path='uncertainty_analysis', show=False)[source]#: Plot pre- and post-calibration curves for uncertainty quantification. :type confidence_levels: :param confidence_levels: Array of confidence levels. :type confidence_levels: ndarray :type nominal_coverages: :param nominal_coverages: Array of nominal coverage values. :type nominal_coverages: ndarray :type empirical_coverages_pre: :param empirical_coverages_pre: Array of empirical coverage values before calibration. :type empirical_coverages_pre: ndarray :type empirical_coverages_post: :param empirical_coverages_post: Array of empirical coverage values after calibration. :type empirical_coverages_post: ndarray :type file_name: :param file_name: Name of the file to save the plot, by default ‘pre_post_calibration_curve’. :type file_name: str, optional :type save_path: :param save_path: Path to save the plot, by default ‘uncertainty_analysis’. :type save_path: str, optional :type show: :param show: Whether to display the plot, by default False. :type show: bool, optional

plot_all(x, x_active_indices, x_hat, x_hat_active_indices, y_clean, y_noisy, n_sources=1, subject=None, fwd_path=None, nnz=1, ERP_config=None, sample_idx=0, source_units=202(FIFF_UNIT_AM), source_unitmult=None, sensor_units=107(FIFF_UNIT_V), sensor_unitmult=None, confidence_levels=None, nominal_coverages=None, empirical_coverages=None, empirical_coverages_post_cal=None, ci_lower=None, ci_upper=None, orientation_type='fixed', result=None, experiment_dir=None)[source]#

Comprehensive visualization wrapper that generates all plots for experiment analysis.

This is a high-level wrapper function that orchestrates multiple visualization methods to create a complete set of plots for ERP source localization analysis.

Generated Visualizations: - Source signal plots - Sensor signal plots (stacked and concatenated) - 3D brain surface plots (if available) - Source-sensor comparison plots - Active source analysis plots - Confidence interval plots - Calibration curve plots

Called Methods: - plot_source_signals() - Source time series visualization - plot_sensor_signals() - Sensor measurements visualization - plot_stc_3d_brain() - 3D brain surface visualization - plot_source_and_sensors() - Combined source-sensor plots - plot_active_sources() - Active source comparison - plot_ci() - Confidence interval visualization - plot_calibration_curve() - Uncertainty calibration analysis

Parameters:

x (np.ndarray) – Ground truth source activity, shape (n_sources, n_times)
x_active_indices (np.ndarray) – Active source indices
x_hat (np.ndarray) – Estimated source activity
x_hat_active_indices (np.ndarray) – Estimated active source indices
y_clean (np.ndarray) – Clean sensor measurements, shape (n_sensors, n_times)
y_noisy (np.ndarray) – Noisy sensor measurements, shape (n_sensors, n_times)
n_sources (int, optional) – Total number of sources, by default 1
subject (str, optional) – Subject name for brain plots
fwd_path (str, optional) – Forward model path
nnz (int, optional) – Number of non-zero sources, by default 1
ERP_config (dict, optional) – ERP configuration parameters
sample_idx (int, optional) – Time sample index for brain plots, by default 0
source_units (str, optional) – Source signal units, by default FIFF.FIFF_UNIT_AM
sensor_units (str, optional) – Sensor signal units, by default FIFF.FIFF_UNIT_V
confidence_levels (np.ndarray, optional) – Confidence levels for uncertainty analysis
nominal_coverages (dict, optional) – Nominal coverage data for calibration
empirical_coverages (dict, optional) – Empirical coverage data for calibration
empirical_coverages_post_cal (dict, optional) – Post-calibration empirical coverage data
ci_lower (np.ndarray, optional) – Lower confidence bounds
ci_upper (np.ndarray, optional) – Upper confidence bounds
orientation_type (str, optional) – Source orientation type, by default “fixed”
result (dict, optional) – Analysis results containing metrics
experiment_dir (str, optional) – Experiment directory for saving plots

Notes

This wrapper function automatically saves all plots to organized subdirectories: - data_simulation/ - Data visualization plots - uncertainty_analysis/ - Uncertainty quantification plots

All plots are saved with show=False for batch processing compatibility.

Examples

>>> viz = Visualizer(base_save_path="results/figures")
>>> viz.plot_all(
...     x_trials=x_trials,
...     x_active_indices_trials=active_indices,
...     x_hat=x_hat,
...     # ... other parameters
... )