1. User API

This section describes the main API users are expected to interact with.

1.1. Functions

Create sensitivity profilers for given models.

Example:

import ipysensitivityprofiler as isp

def f1(x):
    return -0.1 * x[:, 0] ** 3 - 0.5 * x[:, 1] ** 2

def f2(x):
    return -0.2 * x[:, 0] ** 3 - 0.25 * x[:, 1] ** 2

isp.profiler(
    models=[f1, f2],
    xmin=[-5, -5],
    xmax=[5, 5],
    ymin=[-10],
    ymax=[10],
    x0=[1, 1],
    resolution=100,
    xlabels=["x1", "x2"],
    ylabels=["y"],
)

Args:

models: List[callable]: List of callable functions with the same signature y = f(x). There will be one profile per model. x must be a numpy array of shape (-1, nx) and y an array of shape (-1, ny).
xmin: Union[List[float], np.ndarray]: Lower bounds of inputs.
xmax: Union[List[float], np.ndarray]: Upper bounds of inputs.
ymin: Union[List[float], np.ndarray]: Lower bounds of outputs.
ymax: Union[List[float], np.ndarray]: Upper bounds of outputs.

x0: Union[List[float], np.ndarray] Defaults to use for initial x0 (red dot in plots). Default is None (which turns into mean of range).

resolution: int, optional: Line resolution. Default is 25 points.
width: int, optional: Width of each plot. Default is 300 pixels.
height: int, optional: Height of each plot. Default is None (match width).
xlabels: List[str]: Labels to use for inputs. Default is None (which becomes x1, x2, …)
ylabels: Union[List[float], np.ndarray]: Labels to use for outputs. Default is None (which becomes y1, y2, …)

Returns:

Profiler: Jupyter Widget.

1.2. Classes

class ipysensitivityprofiler.Profiler(**kwargs: Any)

Bases: VBox

Profiler Widget.

Attributes:

view: View: Profiler widget controlled by controller.
controller: Controller: Widget to control profilers

__init__(view: View, controller: Controller, **kwargs: Any) → None: Public constructor

class ipysensitivityprofiler.Controller(**kwargs: Any)

Bases: VBox

Control panel for profiler.

Attributes:

range_sliders: Dict[str, List[W.FloatRangeSlider]]:: Range sliders to control axis limits of inputs and outputs:

range_sliders = {
    "x": [...],  # list of range sliders associated with inputs
    "y": [...],  # list of range sliders associated with outputs
}

sliders: List[W.FloatSlider]: Sliders to control input values (and automatically update view).

__init__(view: View, **kwargs: Any)

Public constructor.

view: View: Profiler widget to be controlled by controller.

class ipysensitivityprofiler.View(**kwargs: Any)

Bases: Box

Widget to display grid of sensivity profiles.

predict: Callable: Callable function with signature y = f(x) where x must be a numpy array of shape (-1, n_x) and y an array of shape (-1, n_y).

xmin: ndarray: An array of shape (n_x,) representing the lower bound on the inputs

xmax: ndarray: An array of shape (n_x,) representing the upper bound on the inputs

ymin: ndarray: An array of shape (n_y,) representing the lower bound on the outputs

ymax: ndarray: An array of shape (n_y,) representing the upper bound on the outputs

width: int: The width of each figure in pixels. Default is 300.

height: int: The height of each figure in pixels. Default is 300.

resolution: int: The number of point in each curve. Default is 25.

x0: ndarray: The point about which to compute the sensitivities

y0: ndarray: The value of the outputs evaluates at x0

xlabels: List[str]: The name of each input

ylabels: List[str]: The name of each output

data: Data: object in charge of updating data

grid: GridspecLayout: Grid containing all figures

__init__(**kwargs: Any): Public constructor

save_png(xlabel: str, ylabel: str, filename: str | None = None) → None

Save figure as PNG.

Args:

xlabel: str: The label of the input shown in the figure.
ylabel: str: The label of the output shown in the figure.
filename: str, optional: File name to save to. Default is “profiler_{xlabel}_vs_{ylabel}.png”

2. Core API

This section describes backend support functions and classes. It is intended for developers.

class ipysensitivityprofiler._data.Data(**kwargs: Any)

Bases: HasTraits

Automatically evaluate outputs whenever inputs change.

This class is in charge of managing source data and calling user prediction models as needed.

xlabels: List[str]: An instance of a Python list.

ylabels: List[str]: An instance of a Python list.

predict: Callable: Callback that calls user provided models to update data as needed.

x: ndarray[Any, dtype[_ScalarType_co]]: A numpy array trait type.

y: ndarray[Any, dtype[_ScalarType_co]]: A numpy array trait type.

__init__(**kwargs: Any) → None

property n_x: int: Number of inputs.

property n_y: int: Number of outputs.

property N: int: Number of models (i.e. number of lines on plot).

ipysensitivityprofiler._utils.create_grid(x0: ndarray[Any, dtype[_ScalarType_co]], xmin: ndarray[Any, dtype[_ScalarType_co]], xmax: ndarray[Any, dtype[_ScalarType_co]], resolution: int = 10) → ndarray[Any, dtype[_ScalarType_co]]

Generate grid data for sensitivity profilers.

Args:

x0: NDArray: Local point about which to plot sensivities. Array of shape (n,) where n is the number of input variables.
xmin: NDArray: Min bound for plotting sensitivities. Array of shape (n,)
xmax: NDArray: Max bound for plotting sensitivities. Array of shape (n,)
resolution: int, optional: Number of points between xmin and xmax. Default is 10.

Returns:

NDArray: Array of shape (resolution * n, n)

Example:

x = create_grid(
    x0=[ 0, 1, 2],
    xmin=[-5, -5, -5],
    xmax=[ 5, 5, 5],
    resolution=10,
)

>> x = [[-5,  1,  2],
        [-3,  1,  2],
        [-2,  1,  2],
        [-1,  1,  2],
        [ 0,  1,  2],
        [ 0,  1,  2],
        [ 1,  1,  2],
        [ 2,  1,  2],
        [ 3,  1,  2],
        [ 5,  1,  2],
        [ 0, -5,  2],
        [ 0, -3,  2],
        [ 0, -2,  2],
        [ 0, -1,  2],
        [ 0,  0,  2],
        [ 0,  0,  2],
        [ 0,  1,  2],
        [ 0,  2,  2],
        [ 0,  3,  2],
        [ 0,  5,  2],
        [ 0,  1, -5],
        [ 0,  1, -3],
        [ 0,  1, -2],
        [ 0,  1, -1],
        [ 0,  1,  0],
        [ 0,  1,  0],
        [ 0,  1,  1],
        [ 0,  1,  2],
        [ 0,  1,  3],
        [ 0,  1,  5]]

ipysensitivityprofiler._utils.create_batches(n: int, m: int) → List[List[int]]

Create n batches containing m examples each.

Given an array x of shape (n * m, -1), this method returns a list of list in which each list are the indices of x for each batch.

Example usage:

n=3 m=5 x = np.arange(n*m,)

batches = create_batches(n, m)

for batch in batches:
print(x[batch])

This method is meant as a support function for the sensitivity profilers. It helps collect the indices associated with the data for each curve in the curve.

Args:

n: int, optional: Number of batches
n: int, optional: Number of examples per batch

Returns:

list: List of row indices corresponding to one grid permutation.

ipysensitivityprofiler._utils.make_figure(N: int, num_x_ticks: int = 3, num_y_ticks: int = 3, tick_style: dict = {'font-size': 10}, xmin: float | None = None, xmax: float | None = None, ymin: float | None = None, ymax: float | None = None) → Figure: Create initial figure for profiler trait (data will be replaced).

ipysensitivityprofiler._utils.make_grid(n_x: int, n_y: int, N: int, width: int | None = None, height: int | None = None) → GridspecLayout: Create grid layout of specified width and height.