sensitivity package¶

Python sensitivity analysis - run models with varying inputs to produce visualizations including gradient DataFrames and hex-bin plots

Submodules¶

sensitivity.colors module¶

sensitivity.df module¶

sensitivity.df.sensitivity_df(sensitivity_values, func, result_name='Result', labels=None, **func_kwargs)[source]¶

Creates a DataFrame containing the results of sensitivity analysis.

Runs func with the cartesian product of the possible values for each argument, passed in sensitivity_values.

Parameters:

sensitivity_values¶ (Dict[str, Any]) – Dictionary where keys are func’s argument names and values are lists of possible values to use for that argument.
func¶ (Callable) – Function that accepts arguments with names matching the keys of sensitivity_values, and outputs a scalar value.
result_name¶ (str) – Name for result shown in graph color bar label
labels¶ (Optional[Dict[str, str]]) – Optional dictionary where keys are arguments of the function and values are the displayed names for these arguments in the styled DataFrames and plots
func_kwargs¶ – Additional arguments to pass to func, regardless of the sensitivity values picked

Return type:

DataFrame

Returns:

a DataFrame containing the results from sensitivity analysis on func

sensitivity.hexbin module¶

sensitivity.hexbin.sensitivity_hex_plots(sensitivity_values, func, result_name='Result', agg_func=<function mean>, reverse_colors=False, grid_size=8, color_map='RdYlGn', **func_kwargs)[source]¶

Create hexbin plots showing how the func result varies with a passed dictionary of input values. Automatically creates a plot for each pair of input parameters passed.

Parameters:

sensitivity_values¶ (Dict[str, Any]) – Dictionary where keys are func’s argument names and values are lists of possible values to use for that argument.
func¶ (Callable) – Function that accepts arguments with names matching the keys of sensitivity_values, and outputs a scalar value.
result_name¶ (str) – Name for result shown in graph color bar label
agg_func¶ (Callable) – If there are multiple results within the hex parameter area, function to aggregate those results to get a single value for the hex area. The function should accept a sequence of values and return a scalar.
reverse_colors¶ (bool) – Default is for red to represent low values of result, green for high values. Set reverse_colors=True to have green represent low values of result and red for high values.
grid_size¶ (int) – Number of hex bins on each axis. E.g. passing 5 would create a 5x5 grid, 25 hex bins.
color_map¶ (str) – matplotlib color map, default is RdYlGn (red, yellow, green). See https://matplotlib.org/3.3.2/tutorials/colors/colormaps.html
func_kwargs¶ – Additional arguments to pass to func, regardless of the sensitivity values picked

Return type:

Figure

Returns:

Sensitivity analysis hex bin sub plot figure

sensitivity.main module¶

class sensitivity.main.SensitivityAnalyzer(sensitivity_values, func, result_name='Result', agg_func=<function mean>, reverse_colors=False, grid_size=8, func_kwargs_dict=None, num_fmt=None, color_map='RdYlGn', labels=None)[source]¶

Bases: object

Runs sensitivity analysis based on the passed function and possible values for each argument.

Runs func with the cartesian product of the possible values for each argument, passed in sensitivity_values. Exposes the DataFrame containing the results, a styled version of the DataFrame, and a Hex-Bin plot.

Parameters:

sensitivity_values¶ (Dict[str, Any]) – Dictionary where keys are func’s argument names and values are lists of possible values to use for that argument.
func¶ (Callable) – Function that accepts arguments with names matching the keys of sensitivity_values, and outputs a scalar value.
result_name¶ (str) – Name for result shown in graph color bar label
agg_func¶ (Callable) – If there are multiple results within the hex parameter area, function to aggregate those results to get a single value for the hex area. The function should accept a sequence of values and return a scalar.
reverse_colors¶ (bool) – Default is for red to represent low values of result, green for high values. Set reverse_colors=True to have green represent low values of result and red for high values.
grid_size¶ (int) – Number of hex bins on each axis. E.g. passing 5 would create a 5x5 grid, 25 hex bins.
func_kwargs¶ – Additional arguments to pass to func, regardless of the sensitivity values picked
num_fmt¶ (Optional[str]) – used to apply additional styling to DataFrames. Should be a number format string in the same style as would be passed to df.style.format, e.g. ‘${:,.2f}’ for USD formatting
color_map¶ (str) – matplotlib color map, default is RdYlGn (red, yellow, green). See https://matplotlib.org/3.3.2/tutorials/colors/colormaps.html
labels¶ (Optional[Dict[str, str]]) – Optional dictionary where keys are arguments of the function and values are the displayed names for these arguments in the styled DataFrames and plots

Returns:

Sensitivity analysis hex bin sub plot figure

Examples:

>>> from sensitivity import SensitivityAnalyzer
>>>
>>> # Some example function
>>> def add_5_to_values(value1, value2):
>>>     return value1 + value2 + 5
>>>
>>> # The values to be passed for each parameter of the function
>>> sensitivity_values = {
>>>     'value1': [1, 2, 3],
>>>     'value2': [4, 5, 6],
>>> }
>>>
>>> sa = SensitivityAnalyzer(
>>>     sensitivity_values,
>>>     add_5_to_values
>>> )
>>>
>>> # Plain DataFrame Containing Values
>>> sa.df
>>>
>>> # Styled DataFrame
>>> sa.styled_dfs()
>>>
>>> # Hex-Bin Plot
>>> sa.plot()

__init__(sensitivity_values, func, result_name='Result', agg_func=<function mean>, reverse_colors=False, grid_size=8, func_kwargs_dict=None, num_fmt=None, color_map='RdYlGn', labels=None)¶

agg_func(axis=None, dtype=None, out=None, keepdims=<no value>, *, where=<no value>)¶

Compute the arithmetic mean along the specified axis.

Returns the average of the array elements. The average is taken over the flattened array by default, otherwise over the specified axis. float64 intermediate and return values are used for integer inputs.

aarray_like

Array containing numbers whose mean is desired. If a is not an array, a conversion is attempted.

axisNone or int or tuple of ints, optional

Axis or axes along which the means are computed. The default is to compute the mean of the flattened array.

New in version 1.7.0.

If this is a tuple of ints, a mean is performed over multiple axes, instead of a single axis or all the axes as before.

dtypedata-type, optional

Type to use in computing the mean. For integer inputs, the default is float64; for floating point inputs, it is the same as the input dtype.

outndarray, optional

Alternate output array in which to place the result. The default is None; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See Output type determination for more details.

keepdimsbool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

If the default value is passed, then keepdims will not be passed through to the mean method of sub-classes of ndarray, however any non-default value will be. If the sub-class’ method does not implement keepdims any exceptions will be raised.

wherearray_like of bool, optional

Elements to include in the mean. See ~numpy.ufunc.reduce for details.

New in version 1.20.0.

mndarray, see dtype parameter above: If out=None, returns a new array containing the mean values, otherwise a reference to the output array is returned.

average : Weighted average std, var, nanmean, nanstd, nanvar

The arithmetic mean is the sum of the elements along the axis divided by the number of elements.

Note that for floating-point input, the mean is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-precision accumulator using the dtype keyword can alleviate this issue.

By default, float16 results are computed using float32 intermediates for extra precision.

>>> a = np.array([[1, 2], [3, 4]])
>>> np.mean(a)
2.5
>>> np.mean(a, axis=0)
array([2., 3.])
>>> np.mean(a, axis=1)
array([1.5, 3.5])

In single precision, mean can be inaccurate:

>>> a = np.zeros((2, 512*512), dtype=np.float32)
>>> a[0, :] = 1.0
>>> a[1, :] = 0.1
>>> np.mean(a)
0.54999924

Computing the mean in float64 is more accurate:

>>> np.mean(a, dtype=np.float64)
0.55000000074505806 # may vary

Specifying a where argument:

>>> a = np.array([[5, 9, 13], [14, 10, 12], [11, 15, 19]])
>>> np.mean(a)
12.0
>>> np.mean(a, where=[[True], [False], [False]])
9.0

color_map: str = 'RdYlGn'¶

func: Callable¶

func_kwargs_dict: Optional[Dict[str, Any]] = None¶

grid_size: int = 8¶

labels: Optional[Dict[str, str]] = None¶

num_fmt: Optional[str] = None¶

plot(**kwargs)[source]¶

Creates hex-bin plots of the sensitivity analysis results

Parameters:: kwargs¶ – agg_func, reverse_colors, grid_size, color_map (see SensitivityAnalyzer)
Return type:: Figure
Returns:: Matplotlib Figure containing one or more plots of sensitivity analysis results

result_name: str = 'Result'¶

reverse_colors: bool = False¶

property sensitivity_cols: List[str]¶

Return type:: List[str]

sensitivity_values: Dict[str, Any]¶

styled_dfs(disp=True, **kwargs)[source]¶

Creates Pandas Styler objects showing a gradient over the sensitivity results

Parameters:

disp¶ (bool) – Whether to display the Styler objects before returning
kwargs¶ – reverse_colors, agg_func, num_fmt, color_map (see SensitivityAnalyzer)

Return type:

Union[Styler, Dict[Sequence[str], Styler]]

Returns: