eispy2d.experiments package#

Submodules#

eispy2d.experiments.benchmark module#

Benchmark Class for Performance Evaluation of Inverse Scattering Algorithms.

This module provides the Benchmark class for systematic performance evaluation of electromagnetic inverse scattering algorithms. It extends the Experiment class to handle multiple test sets and provides comprehensive analysis tools including parallel processing capabilities, statistical analysis, and visualization functions.

The Benchmark class supports various parallelization strategies and provides methods for plotting results, generating box plots, violin plots, and statistical comparisons between different algorithms.

Classes#

Benchmarkexp.Experiment: Main class for benchmarking inverse scattering algorithms.

Functions#

_run_testsetfunction: Helper function to run a single test set with parallelization.

Constants#

TESTSETstr: Key for test set data in serialization.
PARALLELIZE_TESTSETSstr: Parallelization mode for test sets.
PARALLELIZE_METHODSstr: Parallelization mode for methods.
PARALLELIZE_TESTSstr: Parallelization mode for individual tests.

class eispy2d.experiments.benchmark.Benchmark(name='', method=None, discretization=None, testset=None, import_filename=None, import_filepath='')#

Bases: Experiment

Benchmark Class for Performance Evaluation of Inverse Scattering Algorithms.

This class provides a comprehensive framework for systematic performance evaluation of electromagnetic inverse scattering algorithms. It extends the Experiment class to handle multiple test sets and provides various analysis and visualization tools.

The Benchmark class supports different parallelization strategies to efficiently run large-scale performance evaluations and provides statistical analysis capabilities for comparing algorithm performance.

Parameters:

name (str, default: '') – Name identifier for the benchmark instance.
method (InverseMethod or list of InverseMethod, optional) – Single method or list of methods to be benchmarked.
discretization (Discretization or list of Discretization, optional) – Single discretization or list of discretizations to be used.
testset (TestSet or list of TestSet, optional) – Single test set or list of test sets for evaluation.
import_filename (str, optional) – Filename to import previously saved benchmark state.
import_filepath (str, default: '') – Path to the file containing saved benchmark state.

testset#

Test set(s) used for benchmarking.

Type:: TestSet or list of TestSet

results#

Results from benchmark execution.

Type:: numpy.ndarray

_single_testset#

Whether using a single test set or multiple.

Type:: bool

_testset_available#

Whether test set data is available.

Type:: bool

import_testsets(filename, filepath='')#: Import test sets from files.

run(parallelization=None)#: Execute the benchmark with optional parallelization.

plot(indicator, \*\*kwargs)#: Generate line plots of benchmark results.

boxplot(indicator, \*\*kwargs)#: Generate box plots of benchmark results.

violinplot(indicator, \*\*kwargs)#: Generate violin plots of benchmark results.

save(file_path='', save_testset=False)#: Save benchmark state to file.

importdata(file_name, file_path='')#: Import benchmark state from file.

__init__(name='', method=None, discretization=None, testset=None, import_filename=None, import_filepath='')#

Initialize the Benchmark instance.

Parameters:

name (str, default: '') – Name identifier for the benchmark instance.
method (InverseMethod or list of InverseMethod, optional) – Single method or list of methods to be benchmarked.
discretization (Discretization or list of Discretization, optional) – Single discretization or list of discretizations to be used.
testset (TestSet or list of TestSet, optional) – Single test set or list of test sets for evaluation.
import_filename (str, optional) – Filename to import previously saved benchmark state.
import_filepath (str, default: '') – Path to the file containing saved benchmark state.

Raises:

WrongTypeInput – If testset is not None, TestSet, or list of TestSet.

boxplot(indicator, axis=None, testset=None, method=None, yscale=None, show=False, file_name=None, file_path='', file_format='eps', title=None, fontsize=10, color='b', notch=False)#

Generate box plots of benchmark results.

Creates box plots showing the distribution of algorithm performance across test instances. Useful for comparing algorithm variability and identifying outliers.

Parameters:

indicator (str or list of str) – Performance indicator(s) to plot. Must be valid result indicators.
axis (matplotlib.axes.Axes or numpy.ndarray of Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
testset (int or str or list, optional) – Test set(s) to include in plot. Can be indices, names, or list.
method (int or str or list, optional) – Method(s) to include in plot. Can be indices, names, or list.
yscale ({'linear', 'log'}, optional) – Y-axis scale for the plot.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file (without extension).
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.
title (str or bool or list of str, optional) – Title(s) for the plot(s). Can be string, boolean, or list.
fontsize (int, default: 10) – Font size for plot text.
color (str, default: 'b') – Color for the box plots.
notch (bool, default: False) – Whether to draw notched box plots.

Returns:

The axes used for plotting (if show=False and file_name=None).

Return type:

matplotlib.axes.Axes or numpy.ndarray of Axes

Raises:

MissingAttributesError – If results are not available.
WrongTypeInput – If indicator has wrong type.
WrongValueInput – If indicator values are invalid.

compare(indicator, method=None, testset=None, reference=None, all2all=False, all2one=None, samples='methods')#

Perform statistical comparison of algorithm performance.

Conducts statistical tests to compare the performance of different algorithms, providing p-values and significance tests for determining if performance differences are statistically significant.

Parameters:

indicator (str) – Performance indicator to compare.
method (int or str or list, optional) – Method(s) to include in comparison.
testset (int or str or list, optional) – Test set(s) to include in comparison.
reference (int or str, optional) – Reference method for comparison.
all2all (bool, default: False) – Whether to perform all-to-all comparison.
all2one (int or str, optional) – Method to use as reference for all-to-one comparison.
samples ({'methods', 'testsets'}, default: 'methods') – Whether to compare across methods or test sets.

Returns:

Dictionary containing statistical comparison results including p-values and test statistics.

Return type:

dict

Raises:

WrongTypeInput – If indicator is None or invalid.

confint(indicator, method=None, testset=None, print_info=True, print_obj=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, show=False, file_name=None, file_path='', file_format='eps', fontsize=10, axis=None, title=None, confidence_level=0.95, group='methods')#

Compute and visualize confidence intervals for performance indicators.

Calculates confidence intervals for algorithm performance metrics and creates visualizations to show the statistical uncertainty in the performance estimates.

Parameters:

indicator (str) – Performance indicator to compute confidence intervals for.
method (int or str or list, optional) – Method(s) to include in analysis.
testset (int or str or list, optional) – Test set(s) to include in analysis.
print_info (bool, default: True) – Whether to print confidence interval information.
print_obj (file-like object, default: sys.stdout) – File object to write information to.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file.
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.
fontsize (int, default: 10) – Font size for plot text.
axis (matplotlib.axes.Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
title (str, optional) – Title for the plot.
confidence_level (float, default: 0.95) – Confidence level for interval computation (between 0 and 1).
group ({'methods', 'testsets'}, default: 'methods') – Whether to group by methods or test sets.

Returns:

Dictionary containing confidence interval information including lower bounds, upper bounds, and means.

Return type:

dict

Raises:

WrongTypeInput – If indicator is None or invalid.

evolution(indicator, axis=None, method=None, testset=None, labels=None, xlabel=None, title=None, fontsize=10, yscale=None, variable='testset', show=False, file_name=None, file_path='', file_format='eps')#

Plot evolution of performance indicators across test sets or methods.

Creates plots showing how algorithm performance evolves across different test sets or methods, useful for analyzing trends and comparing algorithm behavior.

Parameters:

indicator (str) – Performance indicator to plot.
axis (matplotlib.axes.Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
method (int or str or list, optional) – Method(s) to include in plot.
testset (int or str or list, optional) – Test set(s) to include in plot.
labels (list of str, optional) – Custom labels for the plot lines.
xlabel (str, optional) – Label for the x-axis.
title (str, optional) – Title for the plot.
fontsize (int, default: 10) – Font size for plot text.
yscale ({'linear', 'log'}, optional) – Y-axis scale for the plot.
variable ({'testset', 'method'}, default: 'testset') – Variable to plot evolution across.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file.
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.

Raises:

Error – If called with single method and single testset.

import_testsets(filename, filepath='')#

Import test sets from files.

Loads test set(s) from the specified file(s) and sets them as the benchmark’s test set(s).

Parameters:

filename (str or list of str) – Name(s) of the file(s) containing test set data.
filepath (str or list of str, default: '') – Path(s) to the file(s). If single string, used for all files. If list, must have same length as filename.

Raises:

WrongTypeInput – If filename or filepath are not str or list of str.
WrongValueInput – If filepath list length doesn’t match filename list length.

importdata(file_name, file_path='')#

Import benchmark state from file.

Loads a previously saved benchmark configuration from file.

Parameters:

file_name (str) – Name of the file containing saved benchmark state.
file_path (str, default: '') – Path to the file containing saved benchmark state.

Notes

This method restores the benchmark configuration including methods, discretizations, and test set references. If test set data was not saved with the benchmark, the test sets need to be imported separately.

normality(indicator, axis=None, method=None, testset=None, fontsize=None, title=None, show=False, file_name=None, file_path='', file_format='eps')#

Test and visualize normality of performance indicators.

Performs statistical normality tests and creates Q-Q plots to assess whether the performance indicators follow a normal distribution. This is useful for determining appropriate statistical tests.

Parameters:

indicator (str) – Performance indicator to test for normality.
axis (matplotlib.axes.Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
method (int or str or list, optional) – Method(s) to include in analysis.
testset (int or str or list, optional) – Test set(s) to include in analysis.
fontsize (int, optional) – Font size for plot text.
title (str, optional) – Title for the plot.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file.
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.

Raises:

WrongTypeInput – If indicator is not a string.
WrongValueInput – If indicator is not a valid performance indicator.

plot(indicator, axis=None, testset=None, method=None, yscale=None, show=False, file_name=None, file_path='', file_format='eps', title=None, fontsize=10)#

Generate line plots of benchmark results.

Creates line plots showing the performance of algorithms across test instances. Supports multiple indicators, methods, and test sets.

Parameters:

indicator (str or list of str) – Performance indicator(s) to plot. Must be valid result indicators.
axis (matplotlib.axes.Axes or numpy.ndarray of Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
testset (int or str or list, optional) – Test set(s) to include in plot. Can be indices, names, or list.
method (int or str or list, optional) – Method(s) to include in plot. Can be indices, names, or list.
yscale ({'linear', 'log'}, optional) – Y-axis scale for the plot.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file (without extension).
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.
title (str or bool or list of str, optional) – Title(s) for the plot(s). Can be string, boolean, or list.
fontsize (int, default: 10) – Font size for plot text.

Returns:

The axes used for plotting (if show=False and file_name=None).

Return type:

matplotlib.axes.Axes or numpy.ndarray of Axes

Raises:

MissingAttributesError – If results are not available.
WrongTypeInput – If indicator has wrong type.
WrongValueInput – If indicator values are invalid.

reconstruction(image='contrast', mode=None, indicator=None, axis=None, testset=None, method=None, test=None, show=False, file_name=None, file_path='', file_format='eps', title=None, fontsize=10, source=None)#

Display reconstruction results from benchmark execution.

Visualizes the reconstructed images from algorithm execution, allowing comparison of different methods and test cases.

Parameters:

image ({'contrast', 'total field'}, default: 'contrast') – Type of image to display.
mode (str, optional) – Display mode for the reconstruction.
indicator (str, optional) – Performance indicator to use for selection.
axis (matplotlib.axes.Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
testset (int or str or list, optional) – Test set(s) to include in visualization.
method (int or str or list, optional) – Method(s) to include in visualization.
test (int or str or list, optional) – Specific test instance(s) to visualize.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file.
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.
title (str, optional) – Title for the plot.
fontsize (int, default: 10) – Font size for plot text.
source (int, optional) – Source index for field visualization.

Raises:

MissingAttributesError – If results are not available.

run(parallelization=None)#

Execute the benchmark with optional parallelization.

Runs all methods on all test sets and stores the results. Supports various parallelization strategies to improve performance for large benchmarks.

Parameters:

parallelization ({None, False, True, 'test', 'testset', 'method'}, optional) – Parallelization strategy: - None or False: No parallelization (sequential execution) - True: Parallel execution of tests (single method, single testset) - ‘test’: Parallelize individual test instances - ‘testset’: Parallelize test sets - ‘method’: Parallelize methods

Raises:

MissingAttributesError – If testset is not available.
WrongValueInput – If parallelization parameter has invalid value.

Notes

The method automatically sets stochastic algorithms to AVERAGE_CASE mode for consistent benchmarking. Results are stored in the results attribute as a numpy array.

save(file_path='', save_testset=False)#

Save benchmark state to file.

Saves the benchmark configuration and optionally the test set data to a file for later retrieval.

Parameters:

file_path (str, default: '') – Path where to save the benchmark file.
save_testset (bool, default: False) – Whether to save the full test set data or just references. If False, only test set names are saved.

Notes

The file is saved with the benchmark’s name as filename using pickle serialization. Test set data can be large, so save_testset=False is recommended for most use cases.

property testset#

Get the test set(s) used for benchmarking.

Returns:: The test set(s) or their names if not loaded.
Return type:: TestSet or list of TestSet or str or list of str

violinplot(indicator, axis=None, testset=None, method=None, yscale=None, show=False, file_name=None, file_path='', file_format='eps', title=None, fontsize=10, color='b', notch=False)#

Generate violin plots of benchmark results.

Creates violin plots showing the probability density of algorithm performance across test instances. Combines aspects of box plots and kernel density estimation to show distribution shape.

Parameters:

indicator (str or list of str) – Performance indicator(s) to plot. Must be valid result indicators.
axis (matplotlib.axes.Axes or numpy.ndarray of Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
testset (int or str or list, optional) – Test set(s) to include in plot. Can be indices, names, or list.
method (int or str or list, optional) – Method(s) to include in plot. Can be indices, names, or list.
yscale ({'linear', 'log'}, optional) – Y-axis scale for the plot.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file (without extension).
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.
title (str or bool or list of str, optional) – Title(s) for the plot(s). Can be string, boolean, or list.
fontsize (int, default: 10) – Font size for plot text.
color (str, default: 'b') – Color for the violin plots.
notch (bool, default: False) – Whether to draw notched violin plots.

Returns:

The axes used for plotting (if show=False and file_name=None).

Return type:

matplotlib.axes.Axes or numpy.ndarray of Axes

Raises:

MissingAttributesError – If results are not available.
WrongTypeInput – If indicator has wrong type.
WrongValueInput – If indicator values are invalid.

eispy2d.experiments.casestudy module#

Case Study Module for Electromagnetic Inverse Scattering

This module provides the CaseStudy class, which extends the Experiment class to handle comprehensive case studies for electromagnetic inverse scattering problems. A case study includes test data, method configuration, and tools for statistical analysis, visualization, and comparison of reconstruction results.

The CaseStudy class supports both deterministic and stochastic methods, parallel execution strategies, and comprehensive result analysis including convergence plots, boxplots, statistical comparisons, and confidence intervals.

Classes#

CaseStudyExtends experiment.Experiment: Comprehensive case study framework for inverse scattering problems

Constants#

TESTstr: Dictionary key for test data storage
STOCHASTIC_RUNSstr: Dictionary key for number of stochastic runs
SAVE_STOCHASTIC_RUNSstr: Dictionary key for stochastic run saving flag
PARALLELIZE_METHODstr: Parallelization strategy for methods
PARALLELIZE_EXECUTIONSstr: Parallelization strategy for executions
PERMITTIVITYstr: Identifier for permittivity property
CONDUCTIVITYstr: Identifier for conductivity property
BOTH_PROPERTIESstr: Identifier for both electromagnetic properties
CONTRASTstr: Identifier for contrast property
ALL_EXECUTIONSstr: Mode for displaying all stochastic executions
BEST_EXECUTIONstr: Mode for displaying best stochastic execution

Examples

>>> # Create a case study with single method
>>> case = CaseStudy(name='test_case', method=my_method,
...                  discretization=my_disc, test=my_test)
>>> case.run(parallelization=True)
>>> case.reconstruction(show=True)

>>> # Create a case study with multiple methods
>>> case = CaseStudy(name='comparison', method=[method1, method2],
...                  discretization=my_disc, test=my_test)
>>> case.run()
>>> case.boxplot('total_error', show=True)
>>> case.compare('total_error')

class eispy2d.experiments.casestudy.CaseStudy(name=None, method=None, discretization=None, test=None, stochastic_runs=30, save_stochastic_runs=False, import_filename=None, import_filepath='')#

Bases: Experiment

Comprehensive case study framework for electromagnetic inverse scattering.

This class extends the Experiment class to provide a complete framework for conducting case studies in electromagnetic inverse scattering problems. It supports both deterministic and stochastic methods, parallel execution, and comprehensive result analysis including statistical comparisons and visualizations.

A case study includes: - Test data (ground truth) for validation - One or more inverse scattering methods - Discretization parameters - Stochastic execution configuration - Result analysis and visualization tools

Parameters:

name (str, optional) – Name identifier for the case study
method (object or list of objects, optional) – Inverse scattering method(s) to be evaluated
discretization (object or list of objects, optional) – Discretization parameters for the methods
test (InputData or str, optional) – Test data for validation or filename if string
stochastic_runs (int, default=30) – Number of stochastic executions for statistical analysis
save_stochastic_runs (bool, default=False) – Whether to save individual stochastic execution results
import_filename (str, optional) – Filename to import case study configuration from
import_filepath (str, default='') – Path to import file

test#

Test data for validation

Type:: InputData or str

s_nexec#

Number of stochastic executions

Type:: int

s_save#

Flag for saving stochastic runs

Type:: bool

results#

Results from method execution(s)

Type:: object or list

run(parallelization=None, save_stochastic_executions=False)#: Execute the case study with specified parallelization

reconstruction(image='contrast', \*\*kwargs)#: Visualize reconstruction results

convergence(indicator, \*\*kwargs)#: Plot convergence analysis

boxplot(indicator, \*\*kwargs)#: Create boxplot for statistical analysis

compare(indicator, method=None, all2all=False, all2one=None)#: Perform statistical comparison between methods

confint(indicator, \*\*kwargs)#: Calculate and visualize confidence intervals

Examples

>>> # Single method case study
>>> case = CaseStudy(name='bim_test', method=bim_method,
...                  discretization=disc, test=test_data)
>>> case.run(parallelization=True)
>>> case.reconstruction(show=True)

>>> # Multiple method comparison
>>> methods = [bim_method, born_method]
>>> case = CaseStudy(name='comparison', method=methods,
...                  discretization=disc, test=test_data)
>>> case.run()
>>> case.compare('total_error')
>>> case.boxplot('total_error', show=True)

>>> # Stochastic analysis
>>> case = CaseStudy(name='stochastic', method=pso_method,
...                  discretization=disc, test=test_data,
...                  stochastic_runs=50, save_stochastic_runs=True)
>>> case.run()
>>> case.convergence('total_error', mean=True, show=True)

__init__(name=None, method=None, discretization=None, test=None, stochastic_runs=30, save_stochastic_runs=False, import_filename=None, import_filepath='')#

Initialize a case study for electromagnetic inverse scattering.

Creates a new case study with specified parameters or imports from an existing saved case study file.

Parameters:

name (str, optional) – Name identifier for the case study
method (object or list of objects, optional) – Inverse scattering method(s) to be evaluated
discretization (object or list of objects, optional) – Discretization parameters for the methods
test (InputData or str, optional) – Test data for validation or filename if string
stochastic_runs (int, default=30) – Number of stochastic executions for statistical analysis
save_stochastic_runs (bool, default=False) – Whether to save individual stochastic execution results
import_filename (str, optional) – Filename to import case study configuration from
import_filepath (str, default='') – Path to import file

Examples

>>> # Create new case study
>>> case = CaseStudy(name='test', method=my_method,
...                  discretization=my_disc, test=my_test)

>>> # Import from saved file
>>> case = CaseStudy(import_filename='saved_case.pkl')

__str__()#

Return string representation of the case study.

Creates a formatted string containing comprehensive information about the case study configuration, including inherited experiment details, test data status, and stochastic execution parameters.

Returns:: Formatted string representation of the case study
Return type:: str

Examples

>>> print(case)
CASE STUDY
Name: my_case
Method: Born Iterative Method
Test: test_scenario_1
Save stochastic runs? yes
Number of stochastic runs: 50

boxplot(indicator, axis=None, method=None, file_name=None, file_path='', file_format='eps', show=False, fontsize=10, title=None, mean=False, yscale=None, notch=False)#

Create boxplot visualization for stochastic method results.

Generates boxplot visualizations of performance indicators for stochastic methods to show statistical distributions of results across multiple executions.

Parameters:

indicator (str or list of str) – Performance indicator(s) to plot (e.g., ‘total_error’, ‘data_error’)
axis (matplotlib.axes.Axes or ndarray, optional) – Axes for plotting. If None, new figure is created
method (int, str, or list, optional) – Method indices or names to plot. If None, all stochastic methods are used
file_name (str, optional) – Name for saving the figure
file_path (str, default='') – Path for saving the figure
file_format (str, default='eps') – Format for saving the figure
show (bool, default=False) – Whether to display the figure
fontsize (int, default=10) – Font size for labels and titles
title (str, bool, list, or None, optional) – Figure title(s). If None, automatic titles are used
mean (bool, default=False) – Whether to show mean indicators (unused parameter)
yscale (str, optional) – Y-axis scale (‘linear’, ‘log’, etc.)
notch (bool, default=False) – Whether to show notches in boxplots

Returns:

(fig, ax) if axis is None and show is False

Return type:

tuple or None

Raises:

error.Error – If no stochastic methods with saved runs are available
error.WrongTypeInput – If indicator is not string or list of strings
error.WrongValueInput – If indicator is not in the valid indicator set

Examples

>>> # Basic boxplot
>>> case.boxplot('total_error', show=True)

>>> # Multiple indicators
>>> case.boxplot(['total_error', 'data_error'], show=True)

>>> # Compare stochastic methods
>>> case.boxplot('total_error', method=[0, 1], show=True)

>>> # Boxplot with notches
>>> case.boxplot('total_error', notch=True, show=True)

compare(indicator, method=None, all2all=False, all2one=None)#

Perform statistical comparison between methods.

Conducts statistical tests to compare performance indicators between different methods. Supports pairwise comparisons and multiple comparison procedures for stochastic methods.

Parameters:

indicator (str or list of str) – Performance indicator(s) to compare (e.g., ‘total_error’, ‘data_error’)
method (int, str, or list, optional) – Method indices or names to compare. If None, all methods are used
all2all (bool, default=False) – Whether to perform all-to-all comparisons in multiple comparison
all2one (int, optional) – Index of reference method for all-to-one comparisons

Raises:

error.WrongTypeInput – If indicator is not string or list of strings
error.WrongValueInput – If indicator is not in the valid indicator set
error.Error – If case study configuration is invalid for comparison

Notes

The method automatically selects appropriate statistical tests: - Two-sample tests for stochastic vs. stochastic comparisons - One-sample tests for stochastic vs. deterministic comparisons - Multiple comparison procedures for more than two methods

Only stochastic methods with saved runs can be compared statistically. Deterministic methods are included as reference points.

Examples

>>> # Compare two methods
>>> case.compare('total_error', method=[0, 1])

>>> # Compare multiple indicators
>>> case.compare(['total_error', 'data_error'])

>>> # All-to-one comparison
>>> case.compare('total_error', all2one=0)

>>> # All-to-all comparison
>>> case.compare('total_error', all2all=True)

confint(indicator, method=None, axis=None, file_name=None, file_path='', file_format='eps', show=False, fontsize=10, title=None, print_info=True, print_obj=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, confidence_level=0.95, xscale=None)#

Calculate and visualize confidence intervals for performance indicators.

Computes confidence intervals for performance indicators from stochastic method executions and creates visualization plots with optional statistical information output.

Parameters:

indicator (str or list of str) – Performance indicator(s) to analyze (e.g., ‘total_error’, ‘data_error’)
method (int, str, or list, optional) – Method indices or names to analyze. If None, all methods are used
axis (matplotlib.axes.Axes or ndarray, optional) – Axes for plotting. If None, new figure is created
file_name (str, optional) – Name for saving the figure
file_path (str, default='') – Path for saving the figure
file_format (str, default='eps') – Format for saving the figure
show (bool, default=False) – Whether to display the figure
fontsize (int, default=10) – Font size for labels and titles
title (str, bool, list, or None, optional) – Figure title(s). If None, automatic titles are used
print_info (bool, default=True) – Whether to print statistical information
print_obj (file-like object, default=sys.stdout) – Object to print statistical information to
confidence_level (float, default=0.95) – Confidence level for interval calculation (0 < confidence_level < 1)
xscale (str, optional) – X-axis scale (‘linear’, ‘log’, etc.)

Returns:

Axes object if axis is None and show is False

Return type:

matplotlib.axes.Axes or None

Raises:

error.WrongTypeInput – If indicator is not string or list of strings
error.WrongValueInput – If indicator is not in the valid indicator set

Notes

Confidence intervals are calculated using appropriate statistical methods based on the distribution of the performance indicator values. The method requires stochastic methods with saved executions.

Examples

>>> # Basic confidence interval plot
>>> case.confint('total_error', show=True)

>>> # Multiple indicators with custom confidence level
>>> case.confint(['total_error', 'data_error'],
...              confidence_level=0.99, show=True)

>>> # Specific method analysis
>>> case.confint('total_error', method=0, show=True)

convergence(indicator, axis=None, method=None, file_name=None, file_path='', file_format='eps', show=False, fontsize=10, title=None, mean=False, yscale=None, sample_rate=None, widths=None, color=None, legend_size=None)#

Plot convergence analysis for performance indicators.

Visualizes the convergence behavior of specified performance indicators throughout the iterative process. Supports both deterministic and stochastic methods with options for mean curves and boxplots.

Parameters:

indicator (str or list of str) – Performance indicator(s) to plot (e.g., ‘total_error’, ‘data_error’)
axis (matplotlib.axes.Axes or ndarray, optional) – Axes for plotting. If None, new figure is created
method (int, str, or list, optional) – Method indices or names to plot. If None, all methods are used
file_name (str, optional) – Name for saving the figure
file_path (str, default='') – Path for saving the figure
file_format (str, default='eps') – Format for saving the figure
show (bool, default=False) – Whether to display the figure
fontsize (int, default=10) – Font size for labels and titles
title (str, bool, list, or None, optional) – Figure title(s). If None, automatic titles are used
mean (bool, default=False) – Whether to show mean curves for stochastic methods
yscale (str, optional) – Y-axis scale (‘linear’, ‘log’, etc.)
sample_rate (int, optional) – Sampling rate for stochastic convergence (default=20)
widths (float or array-like, optional) – Width of boxplots for stochastic methods
color (str, optional) – Color for plots
legend_size (int, optional) – Font size for legend

Returns:

(fig, axis) if axis is None and show is False

Return type:

tuple or None

Raises:

error.WrongTypeInput – If indicator is not string or list of strings
error.WrongValueInput – If indicator is not in the valid indicator set

Examples

>>> # Basic convergence plot
>>> case.convergence('total_error', show=True)

>>> # Multiple indicators
>>> case.convergence(['total_error', 'data_error'], show=True)

>>> # Mean convergence for stochastic methods
>>> case.convergence('total_error', mean=True, show=True)

>>> # Compare methods
>>> case.convergence('total_error', method=[0, 1], show=True)

importdata(file_name, file_path='')#

Import case study configuration from a saved file.

Loads a previously saved case study configuration including test data, stochastic execution parameters, and all inherited experiment settings.

Parameters:

file_name (str) – Name of the file to import from
file_path (str, default='') – Path to the file location

Examples

>>> case = CaseStudy()
>>> case.importdata('my_case.pkl', '/path/to/files/')

reconstruction(image='contrast', axis=None, method=None, file_name=None, file_path='', file_format='eps', show=False, fontsize=10, title=None, indicator=None, include_true=False, mode='all')#

Visualize reconstruction results from the case study.

Creates visualization plots of the reconstructed electromagnetic properties, with options to include ground truth, compare multiple methods, and handle stochastic results.

Parameters:

image (str, default='contrast') – Property to visualize: - ‘epsilon_r’: Relative permittivity - ‘sigma’: Conductivity - ‘both’: Both properties - ‘contrast’: Contrast function
axis (matplotlib.axes.Axes or ndarray, optional) – Axes for plotting. If None, new figure is created
method (int, str, or list, optional) – Method indices or names to plot. If None, all methods are used
file_name (str, optional) – Name for saving the figure
file_path (str, default='') – Path for saving the figure
file_format (str, default='eps') – Format for saving the figure
show (bool, default=False) – Whether to display the figure
fontsize (int, default=10) – Font size for labels and titles
title (str, bool, or None, optional) – Figure title. If None, automatic titles are used
indicator (str, optional) – Performance indicator for selecting best execution
include_true (bool, default=False) – Whether to include ground truth in the visualization
mode (str, default='all') – Mode for stochastic results: - ‘all’: Show all executions - ‘best’: Show only best execution

Returns:

Axes object if axis is None and show is False

Return type:

matplotlib.axes.Axes or None

Raises:

error.WrongValueInput – If image type is invalid for the problem configuration

Examples

>>> # Basic reconstruction plot
>>> case.reconstruction(show=True)

>>> # Include ground truth with both properties
>>> case.reconstruction(image='both', include_true=True, show=True)

>>> # Compare specific methods
>>> case.reconstruction(method=[0, 1], show=True)

>>> # Save reconstruction plot
>>> case.reconstruction(file_name='reconstruction',
...                    file_path='/results/', show=True)

run(parallelization=None, save_stochastic_executions=False)#

Execute the case study with the configured methods.

Runs the inverse scattering method(s) on the test data with specified parallelization strategy. Supports both deterministic and stochastic methods with different parallelization approaches.

Parameters:

parallelization (bool, str, or None, default=None) – Parallelization strategy: - None or True: Enable parallelization (default strategy) - False: Disable parallelization - ‘method’: Parallelize across methods - ‘executions’: Parallelize across executions
save_stochastic_executions (bool, default=False) – Whether to save individual stochastic execution results (parameter name kept for backward compatibility)

Raises:

error.MissingAttributesError – If test data is not available

Notes

The method automatically detects single vs. multiple methods and applies appropriate parallelization strategies:

For single deterministic methods: Simple parallel execution
For single stochastic methods: Parallel stochastic executions
For multiple methods: Choice between method-level or execution-level parallelization

Examples

>>> # Run with default parallelization
>>> case.run()

>>> # Run without parallelization
>>> case.run(parallelization=False)

>>> # Run with method-level parallelization
>>> case.run(parallelization='method')

save(file_path='', save_test=False)#

Save the case study configuration to a file.

Saves the complete case study configuration including test data, stochastic execution parameters, and all inherited experiment settings using pickle serialization.

Parameters:

file_path (str, default='') – Path where the file will be saved
save_test (bool, default=False) – Whether to save the complete test data object or just the name

Examples

>>> case.save('/path/to/save/', save_test=True)

property test#

Get the test data for validation.

Returns:: Test data object, filename string, or None if not set
Return type:: InputData or str or None

eispy2d.experiments.experiment module#

class eispy2d.experiments.experiment.Experiment(name, method=None, discretization=None)#

Bases: ABC

__init__(name, method=None, discretization=None)#

Initialize an Experiment instance.

Parameters:

name (str) – Name identifier for the experiment.
method (InverseSolver or list of InverseSolver, optional) – Single method or list of methods to be evaluated.
discretization (Discretization or list of Discretization, optional) – Single discretization or list of discretizations to be used.

Raises:

WrongTypeInput – If parameters have invalid types.
Error – If discretization list length doesn’t match method list length.

property discretization#

abstractmethod importdata(file_name, file_path='')#

Import experiment state from a file.

Parameters:

file_name (str) – Name of the file to import from.
file_path (str, default: '') – Path to the file location.

Returns:

Dictionary containing the imported data.

Return type:

dict

property method#

abstractmethod save(file_path='')#

Save the experiment state to a file.

Parameters:: file_path (str, default: '') – Path where to save the file.
Returns:: Dictionary containing the experiment data.
Return type:: dict

eispy2d.experiments.experiment.final_value(indicator, result)#

Extract final value of an indicator from a Result object or array.

Parameters:

indicator (str or list of str) – Indicator name(s) to extract.
result (Result or numpy.ndarray or list) – Result object(s) containing the indicator data.

Returns:

Final value(s) of the indicator(s).

Return type:

numpy.ndarray

Raises:

WrongTypeInput – If indicator or result have invalid types.
WrongValueInput – If indicator is not valid.

Module contents#

Experiments module for eispy2d.

Provides framework for systematic algorithm evaluation: - base: Abstract base class for experiments - casestudy: Single test case studies with analysis tools - benchmark: Multi-test benchmarking with statistical comparison

class eispy2d.experiments.Benchmark(name='', method=None, discretization=None, testset=None, import_filename=None, import_filepath='')#

Bases: Experiment

Benchmark Class for Performance Evaluation of Inverse Scattering Algorithms.

Parameters:

name (str, default: '') – Name identifier for the benchmark instance.
method (InverseMethod or list of InverseMethod, optional) – Single method or list of methods to be benchmarked.
discretization (Discretization or list of Discretization, optional) – Single discretization or list of discretizations to be used.
testset (TestSet or list of TestSet, optional) – Single test set or list of test sets for evaluation.
import_filename (str, optional) – Filename to import previously saved benchmark state.
import_filepath (str, default: '') – Path to the file containing saved benchmark state.

testset#

Test set(s) used for benchmarking.

Type:: TestSet or list of TestSet

results#

Results from benchmark execution.

Type:: numpy.ndarray

_single_testset#

Whether using a single test set or multiple.

Type:: bool

_testset_available#

Whether test set data is available.

Type:: bool

import_testsets(filename, filepath='')#: Import test sets from files.

run(parallelization=None)#: Execute the benchmark with optional parallelization.

plot(indicator, \*\*kwargs)#: Generate line plots of benchmark results.

boxplot(indicator, \*\*kwargs)#: Generate box plots of benchmark results.

violinplot(indicator, \*\*kwargs)#: Generate violin plots of benchmark results.

save(file_path='', save_testset=False)#: Save benchmark state to file.

importdata(file_name, file_path='')#: Import benchmark state from file.

__init__(name='', method=None, discretization=None, testset=None, import_filename=None, import_filepath='')#

Initialize the Benchmark instance.

Parameters:

name (str, default: '') – Name identifier for the benchmark instance.
method (InverseMethod or list of InverseMethod, optional) – Single method or list of methods to be benchmarked.
discretization (Discretization or list of Discretization, optional) – Single discretization or list of discretizations to be used.
testset (TestSet or list of TestSet, optional) – Single test set or list of test sets for evaluation.
import_filename (str, optional) – Filename to import previously saved benchmark state.
import_filepath (str, default: '') – Path to the file containing saved benchmark state.

Raises:

WrongTypeInput – If testset is not None, TestSet, or list of TestSet.

Generate box plots of benchmark results.

Creates box plots showing the distribution of algorithm performance across test instances. Useful for comparing algorithm variability and identifying outliers.

Parameters:

indicator (str or list of str) – Performance indicator(s) to plot. Must be valid result indicators.
axis (matplotlib.axes.Axes or numpy.ndarray of Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
testset (int or str or list, optional) – Test set(s) to include in plot. Can be indices, names, or list.
method (int or str or list, optional) – Method(s) to include in plot. Can be indices, names, or list.
yscale ({'linear', 'log'}, optional) – Y-axis scale for the plot.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file (without extension).
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.
title (str or bool or list of str, optional) – Title(s) for the plot(s). Can be string, boolean, or list.
fontsize (int, default: 10) – Font size for plot text.
color (str, default: 'b') – Color for the box plots.
notch (bool, default: False) – Whether to draw notched box plots.

Returns:

The axes used for plotting (if show=False and file_name=None).

Return type:

matplotlib.axes.Axes or numpy.ndarray of Axes

Raises:

MissingAttributesError – If results are not available.
WrongTypeInput – If indicator has wrong type.
WrongValueInput – If indicator values are invalid.

compare(indicator, method=None, testset=None, reference=None, all2all=False, all2one=None, samples='methods')#

Perform statistical comparison of algorithm performance.

Conducts statistical tests to compare the performance of different algorithms, providing p-values and significance tests for determining if performance differences are statistically significant.

Parameters:

indicator (str) – Performance indicator to compare.
method (int or str or list, optional) – Method(s) to include in comparison.
testset (int or str or list, optional) – Test set(s) to include in comparison.
reference (int or str, optional) – Reference method for comparison.
all2all (bool, default: False) – Whether to perform all-to-all comparison.
all2one (int or str, optional) – Method to use as reference for all-to-one comparison.
samples ({'methods', 'testsets'}, default: 'methods') – Whether to compare across methods or test sets.

Returns:

Dictionary containing statistical comparison results including p-values and test statistics.

Return type:

dict

Raises:

WrongTypeInput – If indicator is None or invalid.

Compute and visualize confidence intervals for performance indicators.

Calculates confidence intervals for algorithm performance metrics and creates visualizations to show the statistical uncertainty in the performance estimates.

Parameters:

indicator (str) – Performance indicator to compute confidence intervals for.
method (int or str or list, optional) – Method(s) to include in analysis.
testset (int or str or list, optional) – Test set(s) to include in analysis.
print_info (bool, default: True) – Whether to print confidence interval information.
print_obj (file-like object, default: sys.stdout) – File object to write information to.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file.
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.
fontsize (int, default: 10) – Font size for plot text.
axis (matplotlib.axes.Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
title (str, optional) – Title for the plot.
confidence_level (float, default: 0.95) – Confidence level for interval computation (between 0 and 1).
group ({'methods', 'testsets'}, default: 'methods') – Whether to group by methods or test sets.

Returns:

Dictionary containing confidence interval information including lower bounds, upper bounds, and means.

Return type:

dict

Raises:

WrongTypeInput – If indicator is None or invalid.

Plot evolution of performance indicators across test sets or methods.

Creates plots showing how algorithm performance evolves across different test sets or methods, useful for analyzing trends and comparing algorithm behavior.

Parameters:

indicator (str) – Performance indicator to plot.
axis (matplotlib.axes.Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
method (int or str or list, optional) – Method(s) to include in plot.
testset (int or str or list, optional) – Test set(s) to include in plot.
labels (list of str, optional) – Custom labels for the plot lines.
xlabel (str, optional) – Label for the x-axis.
title (str, optional) – Title for the plot.
fontsize (int, default: 10) – Font size for plot text.
yscale ({'linear', 'log'}, optional) – Y-axis scale for the plot.
variable ({'testset', 'method'}, default: 'testset') – Variable to plot evolution across.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file.
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.

Raises:

Error – If called with single method and single testset.

import_testsets(filename, filepath='')#

Import test sets from files.

Loads test set(s) from the specified file(s) and sets them as the benchmark’s test set(s).

Parameters:

filename (str or list of str) – Name(s) of the file(s) containing test set data.
filepath (str or list of str, default: '') – Path(s) to the file(s). If single string, used for all files. If list, must have same length as filename.

Raises:

WrongTypeInput – If filename or filepath are not str or list of str.
WrongValueInput – If filepath list length doesn’t match filename list length.

importdata(file_name, file_path='')#

Import benchmark state from file.

Loads a previously saved benchmark configuration from file.

Parameters:

file_name (str) – Name of the file containing saved benchmark state.
file_path (str, default: '') – Path to the file containing saved benchmark state.

Notes

normality(indicator, axis=None, method=None, testset=None, fontsize=None, title=None, show=False, file_name=None, file_path='', file_format='eps')#

Test and visualize normality of performance indicators.

Performs statistical normality tests and creates Q-Q plots to assess whether the performance indicators follow a normal distribution. This is useful for determining appropriate statistical tests.

Parameters:

indicator (str) – Performance indicator to test for normality.
axis (matplotlib.axes.Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
method (int or str or list, optional) – Method(s) to include in analysis.
testset (int or str or list, optional) – Test set(s) to include in analysis.
fontsize (int, optional) – Font size for plot text.
title (str, optional) – Title for the plot.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file.
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.

Raises:

WrongTypeInput – If indicator is not a string.
WrongValueInput – If indicator is not a valid performance indicator.

plot(indicator, axis=None, testset=None, method=None, yscale=None, show=False, file_name=None, file_path='', file_format='eps', title=None, fontsize=10)#

Generate line plots of benchmark results.

Creates line plots showing the performance of algorithms across test instances. Supports multiple indicators, methods, and test sets.

Parameters:

indicator (str or list of str) – Performance indicator(s) to plot. Must be valid result indicators.
axis (matplotlib.axes.Axes or numpy.ndarray of Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
testset (int or str or list, optional) – Test set(s) to include in plot. Can be indices, names, or list.
method (int or str or list, optional) – Method(s) to include in plot. Can be indices, names, or list.
yscale ({'linear', 'log'}, optional) – Y-axis scale for the plot.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file (without extension).
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.
title (str or bool or list of str, optional) – Title(s) for the plot(s). Can be string, boolean, or list.
fontsize (int, default: 10) – Font size for plot text.

Returns:

The axes used for plotting (if show=False and file_name=None).

Return type:

matplotlib.axes.Axes or numpy.ndarray of Axes

Raises:

MissingAttributesError – If results are not available.
WrongTypeInput – If indicator has wrong type.
WrongValueInput – If indicator values are invalid.

Display reconstruction results from benchmark execution.

Visualizes the reconstructed images from algorithm execution, allowing comparison of different methods and test cases.

Parameters:

image ({'contrast', 'total field'}, default: 'contrast') – Type of image to display.
mode (str, optional) – Display mode for the reconstruction.
indicator (str, optional) – Performance indicator to use for selection.
axis (matplotlib.axes.Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
testset (int or str or list, optional) – Test set(s) to include in visualization.
method (int or str or list, optional) – Method(s) to include in visualization.
test (int or str or list, optional) – Specific test instance(s) to visualize.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file.
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.
title (str, optional) – Title for the plot.
fontsize (int, default: 10) – Font size for plot text.
source (int, optional) – Source index for field visualization.

Raises:

MissingAttributesError – If results are not available.

run(parallelization=None)#

Execute the benchmark with optional parallelization.

Runs all methods on all test sets and stores the results. Supports various parallelization strategies to improve performance for large benchmarks.

Parameters:

Raises:

MissingAttributesError – If testset is not available.
WrongValueInput – If parallelization parameter has invalid value.

Notes

The method automatically sets stochastic algorithms to AVERAGE_CASE mode for consistent benchmarking. Results are stored in the results attribute as a numpy array.

save(file_path='', save_testset=False)#

Save benchmark state to file.

Saves the benchmark configuration and optionally the test set data to a file for later retrieval.

Parameters:

file_path (str, default: '') – Path where to save the benchmark file.
save_testset (bool, default: False) – Whether to save the full test set data or just references. If False, only test set names are saved.

Notes

The file is saved with the benchmark’s name as filename using pickle serialization. Test set data can be large, so save_testset=False is recommended for most use cases.

property testset#

Get the test set(s) used for benchmarking.

Returns:: The test set(s) or their names if not loaded.
Return type:: TestSet or list of TestSet or str or list of str

Generate violin plots of benchmark results.

Creates violin plots showing the probability density of algorithm performance across test instances. Combines aspects of box plots and kernel density estimation to show distribution shape.

Parameters:

indicator (str or list of str) – Performance indicator(s) to plot. Must be valid result indicators.
axis (matplotlib.axes.Axes or numpy.ndarray of Axes, optional) – Matplotlib axes to plot on. If None, new figure is created.
testset (int or str or list, optional) – Test set(s) to include in plot. Can be indices, names, or list.
method (int or str or list, optional) – Method(s) to include in plot. Can be indices, names, or list.
yscale ({'linear', 'log'}, optional) – Y-axis scale for the plot.
show (bool, default: False) – Whether to display the plot.
file_name (str, optional) – Name for saving the plot file (without extension).
file_path (str, default: '') – Path where to save the plot file.
file_format (str, default: 'eps') – File format for saving the plot.
title (str or bool or list of str, optional) – Title(s) for the plot(s). Can be string, boolean, or list.
fontsize (int, default: 10) – Font size for plot text.
color (str, default: 'b') – Color for the violin plots.
notch (bool, default: False) – Whether to draw notched violin plots.

Returns:

The axes used for plotting (if show=False and file_name=None).

Return type:

matplotlib.axes.Axes or numpy.ndarray of Axes

Raises:

MissingAttributesError – If results are not available.
WrongTypeInput – If indicator has wrong type.
WrongValueInput – If indicator values are invalid.

class eispy2d.experiments.CaseStudy(name=None, method=None, discretization=None, test=None, stochastic_runs=30, save_stochastic_runs=False, import_filename=None, import_filepath='')#

Bases: Experiment

Comprehensive case study framework for electromagnetic inverse scattering.

Parameters:

name (str, optional) – Name identifier for the case study
method (object or list of objects, optional) – Inverse scattering method(s) to be evaluated
discretization (object or list of objects, optional) – Discretization parameters for the methods
test (InputData or str, optional) – Test data for validation or filename if string
stochastic_runs (int, default=30) – Number of stochastic executions for statistical analysis
save_stochastic_runs (bool, default=False) – Whether to save individual stochastic execution results
import_filename (str, optional) – Filename to import case study configuration from
import_filepath (str, default='') – Path to import file

test#

Test data for validation

Type:: InputData or str

s_nexec#

Number of stochastic executions

Type:: int

s_save#

Flag for saving stochastic runs

Type:: bool

results#

Results from method execution(s)

Type:: object or list

run(parallelization=None, save_stochastic_executions=False)#: Execute the case study with specified parallelization

reconstruction(image='contrast', \*\*kwargs)#: Visualize reconstruction results

convergence(indicator, \*\*kwargs)#: Plot convergence analysis

boxplot(indicator, \*\*kwargs)#: Create boxplot for statistical analysis

compare(indicator, method=None, all2all=False, all2one=None)#: Perform statistical comparison between methods

confint(indicator, \*\*kwargs)#: Calculate and visualize confidence intervals

Examples

>>> # Single method case study
>>> case = CaseStudy(name='bim_test', method=bim_method,
...                  discretization=disc, test=test_data)
>>> case.run(parallelization=True)
>>> case.reconstruction(show=True)

>>> # Multiple method comparison
>>> methods = [bim_method, born_method]
>>> case = CaseStudy(name='comparison', method=methods,
...                  discretization=disc, test=test_data)
>>> case.run()
>>> case.compare('total_error')
>>> case.boxplot('total_error', show=True)

>>> # Stochastic analysis
>>> case = CaseStudy(name='stochastic', method=pso_method,
...                  discretization=disc, test=test_data,
...                  stochastic_runs=50, save_stochastic_runs=True)
>>> case.run()
>>> case.convergence('total_error', mean=True, show=True)

__init__(name=None, method=None, discretization=None, test=None, stochastic_runs=30, save_stochastic_runs=False, import_filename=None, import_filepath='')#

Initialize a case study for electromagnetic inverse scattering.

Creates a new case study with specified parameters or imports from an existing saved case study file.

Parameters:

name (str, optional) – Name identifier for the case study
method (object or list of objects, optional) – Inverse scattering method(s) to be evaluated
discretization (object or list of objects, optional) – Discretization parameters for the methods
test (InputData or str, optional) – Test data for validation or filename if string
stochastic_runs (int, default=30) – Number of stochastic executions for statistical analysis
save_stochastic_runs (bool, default=False) – Whether to save individual stochastic execution results
import_filename (str, optional) – Filename to import case study configuration from
import_filepath (str, default='') – Path to import file

Examples

>>> # Create new case study
>>> case = CaseStudy(name='test', method=my_method,
...                  discretization=my_disc, test=my_test)

>>> # Import from saved file
>>> case = CaseStudy(import_filename='saved_case.pkl')

__str__()#

Return string representation of the case study.

Creates a formatted string containing comprehensive information about the case study configuration, including inherited experiment details, test data status, and stochastic execution parameters.

Returns:: Formatted string representation of the case study
Return type:: str

Examples

>>> print(case)
CASE STUDY
Name: my_case
Method: Born Iterative Method
Test: test_scenario_1
Save stochastic runs? yes
Number of stochastic runs: 50

boxplot(indicator, axis=None, method=None, file_name=None, file_path='', file_format='eps', show=False, fontsize=10, title=None, mean=False, yscale=None, notch=False)#

Create boxplot visualization for stochastic method results.

Generates boxplot visualizations of performance indicators for stochastic methods to show statistical distributions of results across multiple executions.

Parameters:

indicator (str or list of str) – Performance indicator(s) to plot (e.g., ‘total_error’, ‘data_error’)
axis (matplotlib.axes.Axes or ndarray, optional) – Axes for plotting. If None, new figure is created
method (int, str, or list, optional) – Method indices or names to plot. If None, all stochastic methods are used
file_name (str, optional) – Name for saving the figure
file_path (str, default='') – Path for saving the figure
file_format (str, default='eps') – Format for saving the figure
show (bool, default=False) – Whether to display the figure
fontsize (int, default=10) – Font size for labels and titles
title (str, bool, list, or None, optional) – Figure title(s). If None, automatic titles are used
mean (bool, default=False) – Whether to show mean indicators (unused parameter)
yscale (str, optional) – Y-axis scale (‘linear’, ‘log’, etc.)
notch (bool, default=False) – Whether to show notches in boxplots

Returns:

(fig, ax) if axis is None and show is False

Return type:

tuple or None

Raises:

error.Error – If no stochastic methods with saved runs are available
error.WrongTypeInput – If indicator is not string or list of strings
error.WrongValueInput – If indicator is not in the valid indicator set

Examples

>>> # Basic boxplot
>>> case.boxplot('total_error', show=True)

>>> # Multiple indicators
>>> case.boxplot(['total_error', 'data_error'], show=True)

>>> # Compare stochastic methods
>>> case.boxplot('total_error', method=[0, 1], show=True)

>>> # Boxplot with notches
>>> case.boxplot('total_error', notch=True, show=True)

compare(indicator, method=None, all2all=False, all2one=None)#

Perform statistical comparison between methods.

Conducts statistical tests to compare performance indicators between different methods. Supports pairwise comparisons and multiple comparison procedures for stochastic methods.

Parameters:

indicator (str or list of str) – Performance indicator(s) to compare (e.g., ‘total_error’, ‘data_error’)
method (int, str, or list, optional) – Method indices or names to compare. If None, all methods are used
all2all (bool, default=False) – Whether to perform all-to-all comparisons in multiple comparison
all2one (int, optional) – Index of reference method for all-to-one comparisons

Raises:

error.WrongTypeInput – If indicator is not string or list of strings
error.WrongValueInput – If indicator is not in the valid indicator set
error.Error – If case study configuration is invalid for comparison

Notes

Only stochastic methods with saved runs can be compared statistically. Deterministic methods are included as reference points.

Examples

>>> # Compare two methods
>>> case.compare('total_error', method=[0, 1])

>>> # Compare multiple indicators
>>> case.compare(['total_error', 'data_error'])

>>> # All-to-one comparison
>>> case.compare('total_error', all2one=0)

>>> # All-to-all comparison
>>> case.compare('total_error', all2all=True)

Calculate and visualize confidence intervals for performance indicators.

Computes confidence intervals for performance indicators from stochastic method executions and creates visualization plots with optional statistical information output.

Parameters:

indicator (str or list of str) – Performance indicator(s) to analyze (e.g., ‘total_error’, ‘data_error’)
method (int, str, or list, optional) – Method indices or names to analyze. If None, all methods are used
axis (matplotlib.axes.Axes or ndarray, optional) – Axes for plotting. If None, new figure is created
file_name (str, optional) – Name for saving the figure
file_path (str, default='') – Path for saving the figure
file_format (str, default='eps') – Format for saving the figure
show (bool, default=False) – Whether to display the figure
fontsize (int, default=10) – Font size for labels and titles
title (str, bool, list, or None, optional) – Figure title(s). If None, automatic titles are used
print_info (bool, default=True) – Whether to print statistical information
print_obj (file-like object, default=sys.stdout) – Object to print statistical information to
confidence_level (float, default=0.95) – Confidence level for interval calculation (0 < confidence_level < 1)
xscale (str, optional) – X-axis scale (‘linear’, ‘log’, etc.)

Returns:

Axes object if axis is None and show is False

Return type:

matplotlib.axes.Axes or None

Raises:

error.WrongTypeInput – If indicator is not string or list of strings
error.WrongValueInput – If indicator is not in the valid indicator set

Notes

Confidence intervals are calculated using appropriate statistical methods based on the distribution of the performance indicator values. The method requires stochastic methods with saved executions.

Examples

>>> # Basic confidence interval plot
>>> case.confint('total_error', show=True)

>>> # Multiple indicators with custom confidence level
>>> case.confint(['total_error', 'data_error'],
...              confidence_level=0.99, show=True)

>>> # Specific method analysis
>>> case.confint('total_error', method=0, show=True)

Plot convergence analysis for performance indicators.

Visualizes the convergence behavior of specified performance indicators throughout the iterative process. Supports both deterministic and stochastic methods with options for mean curves and boxplots.

Parameters:

indicator (str or list of str) – Performance indicator(s) to plot (e.g., ‘total_error’, ‘data_error’)
axis (matplotlib.axes.Axes or ndarray, optional) – Axes for plotting. If None, new figure is created
method (int, str, or list, optional) – Method indices or names to plot. If None, all methods are used
file_name (str, optional) – Name for saving the figure
file_path (str, default='') – Path for saving the figure
file_format (str, default='eps') – Format for saving the figure
show (bool, default=False) – Whether to display the figure
fontsize (int, default=10) – Font size for labels and titles
title (str, bool, list, or None, optional) – Figure title(s). If None, automatic titles are used
mean (bool, default=False) – Whether to show mean curves for stochastic methods
yscale (str, optional) – Y-axis scale (‘linear’, ‘log’, etc.)
sample_rate (int, optional) – Sampling rate for stochastic convergence (default=20)
widths (float or array-like, optional) – Width of boxplots for stochastic methods
color (str, optional) – Color for plots
legend_size (int, optional) – Font size for legend

Returns:

(fig, axis) if axis is None and show is False

Return type:

tuple or None

Raises:

error.WrongTypeInput – If indicator is not string or list of strings
error.WrongValueInput – If indicator is not in the valid indicator set

Examples

>>> # Basic convergence plot
>>> case.convergence('total_error', show=True)

>>> # Multiple indicators
>>> case.convergence(['total_error', 'data_error'], show=True)

>>> # Mean convergence for stochastic methods
>>> case.convergence('total_error', mean=True, show=True)

>>> # Compare methods
>>> case.convergence('total_error', method=[0, 1], show=True)

importdata(file_name, file_path='')#

Import case study configuration from a saved file.

Loads a previously saved case study configuration including test data, stochastic execution parameters, and all inherited experiment settings.

Parameters:

file_name (str) – Name of the file to import from
file_path (str, default='') – Path to the file location

Examples

>>> case = CaseStudy()
>>> case.importdata('my_case.pkl', '/path/to/files/')

Visualize reconstruction results from the case study.

Creates visualization plots of the reconstructed electromagnetic properties, with options to include ground truth, compare multiple methods, and handle stochastic results.

Parameters:

image (str, default='contrast') – Property to visualize: - ‘epsilon_r’: Relative permittivity - ‘sigma’: Conductivity - ‘both’: Both properties - ‘contrast’: Contrast function
axis (matplotlib.axes.Axes or ndarray, optional) – Axes for plotting. If None, new figure is created
method (int, str, or list, optional) – Method indices or names to plot. If None, all methods are used
file_name (str, optional) – Name for saving the figure
file_path (str, default='') – Path for saving the figure
file_format (str, default='eps') – Format for saving the figure
show (bool, default=False) – Whether to display the figure
fontsize (int, default=10) – Font size for labels and titles
title (str, bool, or None, optional) – Figure title. If None, automatic titles are used
indicator (str, optional) – Performance indicator for selecting best execution
include_true (bool, default=False) – Whether to include ground truth in the visualization
mode (str, default='all') – Mode for stochastic results: - ‘all’: Show all executions - ‘best’: Show only best execution

Returns:

Axes object if axis is None and show is False

Return type:

matplotlib.axes.Axes or None

Raises:

error.WrongValueInput – If image type is invalid for the problem configuration

Examples

>>> # Basic reconstruction plot
>>> case.reconstruction(show=True)

>>> # Include ground truth with both properties
>>> case.reconstruction(image='both', include_true=True, show=True)

>>> # Compare specific methods
>>> case.reconstruction(method=[0, 1], show=True)

>>> # Save reconstruction plot
>>> case.reconstruction(file_name='reconstruction',
...                    file_path='/results/', show=True)

run(parallelization=None, save_stochastic_executions=False)#

Execute the case study with the configured methods.

Runs the inverse scattering method(s) on the test data with specified parallelization strategy. Supports both deterministic and stochastic methods with different parallelization approaches.

Parameters:

parallelization (bool, str, or None, default=None) – Parallelization strategy: - None or True: Enable parallelization (default strategy) - False: Disable parallelization - ‘method’: Parallelize across methods - ‘executions’: Parallelize across executions
save_stochastic_executions (bool, default=False) – Whether to save individual stochastic execution results (parameter name kept for backward compatibility)

Raises:

error.MissingAttributesError – If test data is not available

Notes

The method automatically detects single vs. multiple methods and applies appropriate parallelization strategies:

For single deterministic methods: Simple parallel execution
For single stochastic methods: Parallel stochastic executions
For multiple methods: Choice between method-level or execution-level parallelization

Examples

>>> # Run with default parallelization
>>> case.run()

>>> # Run without parallelization
>>> case.run(parallelization=False)

>>> # Run with method-level parallelization
>>> case.run(parallelization='method')

save(file_path='', save_test=False)#

Save the case study configuration to a file.

Saves the complete case study configuration including test data, stochastic execution parameters, and all inherited experiment settings using pickle serialization.

Parameters:

file_path (str, default='') – Path where the file will be saved
save_test (bool, default=False) – Whether to save the complete test data object or just the name

Examples

>>> case.save('/path/to/save/', save_test=True)

property test#

Get the test data for validation.

Returns:: Test data object, filename string, or None if not set
Return type:: InputData or str or None

class eispy2d.experiments.Experiment(name, method=None, discretization=None)#

Bases: ABC

__init__(name, method=None, discretization=None)#

Initialize an Experiment instance.

Parameters:

name (str) – Name identifier for the experiment.
method (InverseSolver or list of InverseSolver, optional) – Single method or list of methods to be evaluated.
discretization (Discretization or list of Discretization, optional) – Single discretization or list of discretizations to be used.

Raises:

WrongTypeInput – If parameters have invalid types.
Error – If discretization list length doesn’t match method list length.

property discretization#

abstractmethod importdata(file_name, file_path='')#

Import experiment state from a file.

Parameters:

file_name (str) – Name of the file to import from.
file_path (str, default: '') – Path to the file location.

Returns:

Dictionary containing the imported data.

Return type:

dict

property method#

abstractmethod save(file_path='')#

Save the experiment state to a file.

Parameters:: file_path (str, default: '') – Path where to save the file.
Returns:: Dictionary containing the experiment data.
Return type:: dict