aixcalibuha.sensitivity_analysis package

This package contains classes to perform sensitivity analysis with.

Submodules

aixcalibuha.sensitivity_analysis.fast module

Adds the FASTAnalyzer to the available classes of sensitivity analysis.

class aixcalibuha.sensitivity_analysis.fast.FASTAnalyzer(sim_api, **kwargs)[source]

Bases: SenAnalyzer

FAST method from SALib https://salib.readthedocs.io/en/latest/api.html#fast-fourier-amplitude-sensitivity-test A variance-based method which can compute the sensitivity measures ‘S1’ and ‘ST’.

Additional arguments:

Parameters:

M (int) – Default 4, used for the fast-method
seed – Used for the fast-method

analysis_function(x, y)[source]

Use the SALib.analyze.fast method to analyze the simulation results.

Parameters:

x (np.array) – placeholder for the X parameter of the morris method not used for sobol
y (np.array) – The NumPy array containing the model outputs

Returns:

returns the result of the SALib.analyze.fast method (from the documentation: Returns a dictionary with keys ‘S1’ and ‘ST’, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file.)

property analysis_variables: The analysis variables of the FAST method

create_sampler_demand()[source]: Function to create the sampler parameters for the fast method

generate_samples()[source]

Run the sampler for fast and return the results.

Returns:: The list of samples generated as a NumPy array with one row per sample and each row containing one value for each variable name in problem[‘names’].
Return type:: np.ndarray

aixcalibuha.sensitivity_analysis.morris module

Adds the MorrisAnalyzer to the available classes of sensitivity analysis.

class aixcalibuha.sensitivity_analysis.morris.MorrisAnalyzer(sim_api, **kwargs)[source]

Bases: SenAnalyzer

Moris method from SALib https://salib.readthedocs.io/en/latest/api.html#method-of-morris An elementary effects (One-At-A-Time) method which computes the sensitivity measures ‘mu’, ‘mu_star’ and ‘sigma’ with a confidence interval for mu_star.

Additional arguments:

Parameters:

num_levels (int) – Default num_samples, used for the morris-method
optimal_trajectories – Used for the morris-method
local_optimization (bool) – Default True, used for the morris-method

analysis_function(x, y)[source]

Use the SALib.analyze.morris method to analyze the simulation results.

Parameters:

x (np.array) – the X parameter of the morris method (The NumPy matrix containing the model inputs)
y (np.array) – The NumPy array containing the model outputs

Returns:

returns the result of the SALib.analyze.sobol method (from the documentation: a dictionary with cols mu, mu_star, sigma, and mu_star_conf, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file.)

property analysis_variables: The analysis variables of the sobol method

create_sampler_demand()[source]: Function to create the sampler parameters for the morris method

generate_samples()[source]

Run the sampler specified for morris and return the results.

Returns:: The list of samples generated as a NumPy array with one row per sample and each row containing one value for each variable name in problem[‘names’].
Return type:: np.ndarray

aixcalibuha.sensitivity_analysis.pawn module

Adds the PAWNAnalyzer to the available classes of sensitivity analysis.

class aixcalibuha.sensitivity_analysis.pawn.PAWNAnalyzer(sim_api, **kwargs)[source]

Bases: SenAnalyzer

PAWN method from SALib https://salib.readthedocs.io/en/latest/api.html#pawn-sensitivity-analysis Density-based method which computes the PAWN index at ‘min’, ‘max’, ‘mean’, ‘median’ and coefficient of variation ‘cv’.

Additional arguments:

Parameters:

calc_second_order (bool) – Default True, used for the sampler of the sobol-method
s (int) – Default 10, used for the pawn-method.
sampler (str) – Which sampler should be used. Default sobol. Choose between ‘sobol’, ‘morris’ and ‘fast’.
num_levels (int) – Default num_samples, used for the sampler of the morris-method.
optimal_trajectories – Used for the sampler of the morris-method.
local_optimization (bool) – Default True, used for the sampler of the morris-method.
M (int) – Default 4, used for the sampler of the fast-method.

analysis_function(x, y)[source]

Use the SALib.analyze.pawn method to analyze the simulation results.

Parameters:

x (np.array) – placeholder for the X parameter of the morris method not used for sobol
y (np.array) – The NumPy array containing the model outputs

Returns:

returns the result of the SALib.analyze.pawn method (from the documentation: This implementation reports the PAWN index at the min, mean, median, and max across the slides/conditioning intervals as well as the coefficient of variation (CV). The median value is the typically reported value. As the CV is (standard deviation / mean), it indicates the level of variability across the slides, with values closer to zero indicating lower variation.)

property analysis_variables: The analysis variables of the PAWN method

create_sampler_demand()[source]: Function to create the sampler parameters for the sampler method

generate_samples()[source]

Run the sampler for the selected sampler and return the results.

Returns:: The list of samples generated as a NumPy array with one row per sample and each row containing one value for each variable name in problem[‘names’].
Return type:: np.ndarray

aixcalibuha.sensitivity_analysis.plotting module

Module containing functions for plotting sensitivity results

aixcalibuha.sensitivity_analysis.plotting.heatmap(result: DataFrame, cal_class: str, goal: str, ax: Axes | None = None, max_name_len: int = 15, **kwargs)[source]

Plot S2 sensitivity results from one calibration class and goal as a heatmap.

Parameters:

result (pd.DataFrame) – A second order result from run
cal_class (str) – Name of the class to plot S2 from.
goal (str) – Name of the goal to plot S2 from.
ax (matplotlib.axes) – Default is None. If an axes is given the heatmap will be plotted on it, else a new figure and axes is created.
max_name_len (int) – Default is 15. Shortens the parameter names to max_name_len characters.
show_plot (bool) – Default is True. If False, all created plots are not shown.
use_suffix (bool) – Default is False. If True, only the last suffix of a Modelica variable is displayed.

Returns:

Returns axes

aixcalibuha.sensitivity_analysis.plotting.heatmaps(result: ~pandas.core.frame.DataFrame, cal_classes: [<class 'str'>] = None, goals: [<class 'str'>] = None, max_name_len: int = 15, **kwargs)[source]

Plot S2 sensitivity results as a heatmap for multiple calibration classes and goals in one figure.

Parameters:

result (pd.DataFrame) – A second order result from run
cal_classes ([str]) – Default is a list of all calibration classes in the result. If a list of classes is given only these classes are plotted.
goals ([str]) – Default is a list of all goals in the result. If a list of goals is given only these goals are plotted.
max_name_len (int) – Default is 15. Shortens the parameter names to max_name_len characters.
show_plot (bool) – Default is True. If False, all created plots are not shown.
use_suffix (bool) – Default is False. If True, only the last suffix of a Modelica variable is displayed.

aixcalibuha.sensitivity_analysis.plotting.plot_parameter_verbose(parameter: str, single_result: ~pandas.core.frame.DataFrame, second_order_result: ~pandas.core.frame.DataFrame = None, goals: [<class 'str'>] = None, **kwargs)[source]

Plot all time dependent sensitivity measure for one parameter. For each goal an axes is created within one figure.

If second_order_results form SobolAnalyzer.run_time_dependent are given the S2 results of the interaction with each other parameter are added on top of each other and the first order result.

Parameters:

parameter (str) – Parameter to plot all sensitivity results for. If use_suffix=True, then the name must also be only the suffix.
single_result (pd.DataFrame) – First and total order result form run_time_dependent.
second_order_result (pd.DataFrame) – Default None. Second order result of SobolAnalyzer.run_time_dependent.
goals ([str]) – Default are all possible goal names. If a list of specific goal names is given only these will be plotted.
fig_axes ((fig, [ax])) – Default None. Optional custom figures and axes (see example for verbose sensitivity analysis).
show_plot (bool) – Default is True. If False, all created plots are not shown.
use_suffix (bool) – Default is True: If True, the last part after the last point of Modelica variables is used for the x ticks.
max_name_len (int) – Default is 15. Shortens the parameter names to max_name_len characters.

Returns:

Returns all created figures and axes in lists like fig, [ax] with shape (len(goals)) for the axes list

aixcalibuha.sensitivity_analysis.plotting.plot_second_order(result: ~pandas.core.frame.DataFrame, cal_classes: [<class 'str'>] = None, goals: [<class 'str'>] = None, max_name_len: int = 15, **kwargs)[source]

Plot sensitivity results of second order analysis variables. For each calibration class and goal one figure of a 3d plot is created with the barplots of the interactions for each parameter. Only working for more than 2 parameter.

Parameters:

result (pd.DataFrame) – A result from run
max_name_len (int) – Default is 15. Shortens the parameter names to max_name_len characters.
cal_classes ([str]) – Default are all possible calibration classes. If a list of names of calibration classes is given only plots for these classes are created.
goals ([str]) – Default are all possible goal names. If a list of specific goal names is given only these will be plotted.
show_plot (bool) – Default is True. If False, all created plots are not shown.
use_suffix (bool) – Default is True: If True, the last part after the last point of Modelica variables is used for the x ticks.
figs ([[fig]]) – Default None. Set own figures of subfigures for customization. Shape (len(cal_classes), len(goals))

Returns:

Returns all created figures and axes in lists like [fig], [ax]

aixcalibuha.sensitivity_analysis.plotting.plot_single(result: ~pandas.core.frame.DataFrame, cal_classes: [<class 'str'>] = None, goals: [<class 'str'>] = None, max_name_len: int = 15, **kwargs)[source]

Plot sensitivity results of first and total order analysis variables. For each calibration class one figure is created, which shows for each goal an axis with a barplot of the values of the analysis variables.

Parameters:

result (pd.DataFrame) – A result from run
max_name_len (int) – Default is 15. Shortens the parameter names to max_name_len characters.
cal_classes ([str]) – Default are all possible calibration classes. If a list of names of calibration classes is given only plots for these classes are created.
goals ([str]) – Default are all possible goal names. If a list of specific goal names is given only these will be plotted.
show_plot (bool) – Default is True. If False, all created plots are not shown.
figs_axes (([fig], [ax])) – Default None. Set own figures of subfigures with corresponding axes for customization.
use_suffix (bool) – Default is True: If True, the last part after the last point of Modelica variables is used for the x ticks.

Returns:

Returns all created figures and axes in lists like [fig], [ax] with shapes (len(cal_classes)), (len(cal_classes), len(goals))

aixcalibuha.sensitivity_analysis.plotting.plot_single_second_order(result: ~pandas.core.frame.DataFrame, para_name: str, cal_classes: [<class 'str'>] = None, goals: [<class 'str'>] = None, max_name_len: int = 15, **kwargs)[source]

Plot the value of S2 from one parameter with all other parameters.

Parameters:

result (pd.DataFrame) – Second order result from run.
para_name (str) – Name of the parameter of which the results should be plotted.
cal_classes ([str]) – Default are all possible calibration classes. If a list of names of calibration classes is given only plots for these classes are created.
goals ([str]) – Default are all possible goal names. If a list of specific goal names is given only these will be plotted.
max_name_len (int) – Default is 15. Shortens the parameter names to max_name_len characters.
show_plot (bool) – Default is True. If False, all created plots are not shown.
use_suffix (bool) – Default is True: If True, the last part after the last point of Modelica variables is used for the x ticks.
figs_axes (([fig], [ax])) – Default None. Set own figures of subfigures with corresponding axes for customization.

Returns:

Returns all created figures and axes in lists like [fig], [ax] with shapes (len(cal_classes)), (len(cal_classes), len(goals))

aixcalibuha.sensitivity_analysis.plotting.plot_time_dependent(result: ~pandas.core.frame.DataFrame, parameters: [<class 'str'>] = None, goals: [<class 'str'>] = None, analysis_variables: [<class 'str'>] = None, plot_conf: bool = True, **kwargs)[source]

Plot time dependent sensitivity results without interactions from run_time_dependent().

For each goal one figure is created with one axes for each analysis variable. In these plots the time dependent sensitivity of the parameters is plotted. The confidence interval can also be plotted.

Parameters:

result (pd.DataFrame) – A result from run_time_dependent without second order results.
parameters ([str]) – Default all parameters. List of parameters to plot the sensitivity.
analysis_variables ([str]) – Default all analysis_variables. List of analysis variables to plot.
plot_conf (bool) – Default True. If true, the confidence intervals for each parameter are plotted.
goals ([str]) – Default are all possible goal names. If a list of specific goal names is given only these will be plotted.
figs_axes (([fig], [ax])) – Default None. Optional custom figures and axes (see example for verbose sensitivity analysis).
show_plot (bool) – Default is True. If False, all created plots are not shown.
use_suffix (bool) – Default is True: If True, the last part after the last point of Modelica variables is used for the x ticks.
max_name_len (int) – Default is 50. Shortens the parameter names to max_name_len characters.

Returns:

Returns all created figures and axes in lists like [fig], [ax] with shapes (len(goals)), (len(goals), len(analysis_variables))

aixcalibuha.sensitivity_analysis.sensitivity_analyzer module

Package containing modules for sensitivity analysis. The module contains the relevant base-classes.

class aixcalibuha.sensitivity_analysis.sensitivity_analyzer.SenAnalyzer(sim_api: SimulationAPI, num_samples: int, **kwargs)[source]

Bases: ABC

Class to perform a Sensitivity Analysis.

Parameters:

sim_api (SimulationAPI) – Simulation-API used to simulate the samples
num_samples (int) – The parameter N to the sampler methods of sobol and morris. NOTE: This is not the number of samples produced, but relates to the total number of samples produced in a manner dependent on the sampler method used. See the documentation of the specific method in the SALib for more information.
cd (str,os.path.normpath) – The path for the current working directory. Logger and results will be stored here.
fail_on_error (boolean) – Default is False. If True, the calibration will stop with an error if the simulation fails. See also: ret_val_on_error
ret_val_on_error (float,np.NAN) – Default is np.NAN. If fail_on_error is false, you can specify here which value to return in the case of a failed simulation. Possible options are np.NaN, np.inf or some other high numbers. be aware that this max influence the solver.
save_files (boolean) – Default False. If true, all simulation files for each iteration will be saved!
suffix_files (str) – Default ‘csv’. Specifies the data format to store the simulation files in. Options are ‘csv’, ‘hdf’, ‘parquet’.
parquet_engine (str) – The engine to use for the data format parquet. Supported options can be extracted from the ebcpy.TimeSeriesData.save() function. Default is ‘pyarrow’.
savepath_sim (str,os.path.normpath) – Default is cd. Own directory for the time series data sets of all simulations during the sensitivity analysis. The own dir can be necessary for large data sets, because they can crash IDE during indexing when they are in the project folder.

abstract analysis_function(x, y)[source]

Use the method to analyze the simulation results.

Parameters:

x (np.array) – the X parameter of the method (The NumPy matrix containing the model inputs)
y (np.array) – The NumPy array containing the model outputs

abstract property analysis_variables: List[str]

Indicate which variables are able to be selected for analysis

Returns:: A list of strings
Return type:: List[str]

static create_problem(tuner_paras, scale=False) → dict[source]: Create function for later access if multiple calibration-classes are used.

abstract create_sampler_demand() → dict[source]

Return the sampler parameters

Returns:: dict: A dict with the sampler demand

eval_statistical_measure(cal_class, results, verbose=True)[source]: Evaluates statistical measures of results on single core

abstract generate_samples()[source]

Run the sampler specified by method and return the results.

Returns:: The list of samples generated as a NumPy array with one row per sample and each row containing one value for each variable name in problem[‘names’].
Return type:: np.ndarray

static load_from_csv(path)[source]

Load sensitivity results which were saved with the run() or run_time_dependent() function.

For second order results use the load_second_order_from_csv() function of the SobolAnalyzer.

plot(result)[source]

Plot the results of the sensitivity analysis method from run().

Parameters:: result (pd.DataFrame) – Dataframe of the results like from the run() function.
Return tuple of matplotlib objects (fig, ax):

run(calibration_classes, merge_multiple_classes=True, **kwargs)[source]

Execute the sensitivity analysis for each class and return the result.

Parameters:

calibration_classes (CalibrationClass,list) – Either one or multiple classes for calibration with same tuner-parameters.
merge_multiple_classes (bool) – Default True. If False, the given list of calibration-classes is handled as-is. This means if you pass two CalibrationClass objects with the same name (e.g. “device on”), the calibration process will run for both these classes stand-alone. This will automatically yield an intersection of tuner-parameters, however may have advantages in some cases.
verbose (bool) – Default False. If True, in addition to the combined Goals of the Classes (saved under index Goal: all), the sensitivity measures of the individual Goals will also be calculated and returned.
scale – Default is False. If True the bounds of the tuner-parameters will be scaled between 0 and 1.
use_fist_sim (bool) – Default False. If True, the simulations of the first calibration class will be used for all other calibration classes with their relevant time intervals. The simulations must be stored on a hard-drive, so it must be used with either save_files or load_files.
n_cpu (int) – Default is 1. The number of processes to use for the evaluation of the statistical measure. For n_cpu > 1 only one simulation file is loaded at once in a process and dumped directly after the evaluation of the statistical measure, so that only minimal memory is used. Use this option for large analyses. Only implemented for save_files=True or load_sim_files=True.
load_sim_files (bool) – Default False. If True, no new simulations are done and old simulations are loaded. The simulations and corresponding samples will be loaded from self.savepath_sim like they were saved from self.save_files. Currently, the name of the sim folder must be “simulations_CAL_CLASS_NAME” and for the samples “samples_CAL_CLASS_NAME”. The usage of the same simulations for different calibration classes is not supported yet.
save_results (bool) – Default True. If True, all results are saved as a csv in cd. (samples, statistical measures and analysis variables).
plot_result (bool) – Default True. If True, the results will be plotted.

Returns:

Returns a pandas.DataFrame. The DataFrame has a Multiindex with the levels Class, Goal and Analysis variable. The Goal name of combined goals is ‘all’. The variables are the tuner-parameters. For the Sobol Method and calc_second_order returns a tuple of DataFrames (df_1, df_2) where df_2 contains the second oder analysis variables and has an extra index level Interaction, which also contains the variables.

Return type:

pandas.DataFrame

run_time_dependent(cal_class: CalibrationClass, **kwargs)[source]

Calculate the time dependent sensitivity for all the single goals in the calibration class.

Parameters:

cal_class (CalibrationClass) – Calibration class with tuner-parameters to calculate sensitivity for. Can include dummy target date.
scale – Default is False. If True the bounds of the tuner-parameters will be scaled between 0 and 1.
load_sim_files (bool) – Default False. If True, no new simulations are done and old simulations are loaded. The simulations and corresponding samples will be loaded from self.savepath_sim like they were saved from self.save_files. Currently, the name of the sim folder must be “simulations_CAL_CLASS_NAME” and for the samples “samples_CAL_CLASS_NAME”.
save_results (bool) – Default True. If True, all results are saved as a csv in cd. (samples and analysis variables).
n_steps (int) – Default is all time steps. If the problem is large, the evaluation of all time steps at once can cause a memory error. Then n_steps defines how many time_steps are evaluated at once in chunks. This increases the needed time exponentially and the simulation files must be saved.
plot_result (bool) – Default True. If True, the results will be plotted.

Returns:

Returns a pandas.DataFrame.

Return type:

pandas.DataFrame

save_for_reproduction(title: str, path: Path | None = None, files: list | None = None, exclude_sim_files: bool = False, remove_saved_files: bool = False, **kwargs)[source]

Save the settings of the SenAnalyzer and SimApi in order to reproduce the simulations and sensitivity analysis method. All saved results will be also saved in the reproduction archive. The simulations can be excluded from saving.

Parameters:

title (str) – Title of the study
path (pathlib.Path) – Where to store the .zip file. If not given, self.cd is used.
files (list) – List of files to save along the standard ones. Examples would be plots, tables etc.
exclude_sim_files (bool) – Default False. If True, the simulation files will not be saved in the reproduction archive.
remove_saved_files (bool) – Default False. If True, the result and simulation files will be moved instead of just copied.
kwargs (dict) – All keyword arguments except title, files, and path of the function save_reproduction_archive. Most importantly, log_message may be specified to avoid input during execution.

static select_by_threshold(calibration_classes, result, analysis_variable, threshold)[source]

Automatically select sensitive tuner parameters based on a given threshold of a given analysis variable from a sensitivity result. Uses only the combined goals.

Parameters:

calibration_classes (list) – List of aixcalibuha.data_types.CalibrationClass objects that you want to automatically select sensitive tuner-parameters.
result (pd.DataFrame) – Result object of sensitivity analysis run
analysis_variable (str) – Analysis variable to use for the selection
threshold (float) – Minimal required value of given key

Returns:

list calibration_classes

static select_by_threshold_verbose(calibration_class: CalibrationClass, result: DataFrame, analysis_variable: str, threshold: float, calc_names_for_selection: List[str] | None = None)[source]

Select tuner-parameters of single calibration class with verbose sensitivity results. This function selects tuner-parameters if their sensitivity is equal or greater than the threshold in just one target value of one calibration class in the sensitivity result. This can be more robust because a small sensitivity in one target value and state of the system can mean that the parameter can also be calibrated in a global calibration class which calibrates multiple states and target values at the same time and has there not directly the same sensitivity as in the isolated view of a calibration class for only one state.

Parameters:

calibration_class (CalibrationClass) – The calibration class from which the tuner parameters will be selected.
result (pd.DataFrame) – Sensitivity results to use for the selection. Can include multiple classes.
analysis_variable (str) – The analysis variable to use for the selection.
threshold (float) – Minimal required value of given analysis variable.
calc_names_for_selection (List[str]) – Specifies which calibration classes in the sensitivity results will be used for the selection. Default are all classes.

simulate_samples(cal_class, **kwargs)[source]

Creates the samples for the calibration class and simulates them.

Parameters:

cal_class – One class for calibration. Goals and tuner_paras have to be set
scale – Default is False. If True the bounds of the tuner-parameters will be scaled between 0 and 1.

Returns:

Returns two lists. First a list with the simulation results for each sample. If save_files the list contains the filepaths to the results Second a list of the samples.

Return type:

list

aixcalibuha.sensitivity_analysis.sobol module

Adds the SobolAnalyzer to the available classes of sensitivity analysis.

class aixcalibuha.sensitivity_analysis.sobol.SobolAnalyzer(sim_api, **kwargs)[source]

Bases: SenAnalyzer

Sobol method from SALib https://salib.readthedocs.io/en/latest/api.html#sobol-sensitivity-analysis A variance-based method which can compute the sensitivity measures ‘S1’, ‘ST’ and ‘S2’ with their confidence intervals.

Additional arguments:

Parameters:

calc_second_order (bool) – Default True, used for the sobol-method
seed (int) – Used for the sobol-method

analysis_function(x, y)[source]

Use the SALib.analyze.sobol method to analyze the simulation results.

Parameters:

x (np.array) – placeholder for the X parameter of the morris method not used for sobol
y (np.array) – The NumPy array containing the model outputs

Returns:

returns the result of the SALib.analyze.sobol method (from the documentation: a dictionary with cols S1, S1_conf, ST, and ST_conf, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file. If calc_second_order is True, the dictionary also contains cols S2 and S2_conf.)

property analysis_variables: The analysis variables of the sobol method

create_sampler_demand()[source]: Function to create the sampler parameters for the morris method

generate_samples()[source]

Run the sampler for sobol and return the results.

Returns:: The list of samples generated as a NumPy array with one row per sample and each row containing one value for each variable name in problem[‘names’].
Return type:: np.ndarray

static load_second_order_from_csv(path)[source]: Load second order sensitivity results which were saved with the run() or run_time_dependent() function.

plot(result)[source]

Plot the results of the sensitivity analysis method from run().

Parameters:: result (pd.DataFrame) – Dataframe of the results like from the run() function.
Return tuple of matplotlib objects (fig, ax):