Probability Boxes#

class pba.pbox.Pbox#

A probability distribution is a mathematical function that gives the probabilities of occurrence for diﬀerent possible values of a variable. Probability boxes (p-boxes) represent interval bounds on probability distributions. The simplest kind of p-box can be expressed mathematically as

\[\mathcal{F}(x) = [\underline{F}(x),\overline{F}(x)], \ \underline{F}(x)\geq \overline{F}(x)\ \forall x \in \mathbb{R}\]

where $\underline{F}(x)$ is the function that defines the left bound of the p-box and $\overline{F}(x)$ defines the right bound of the p-box. In PBA the left and right bounds are each stored as a NumPy array containing the percent point function (the inverse of the cumulative distribution function) for steps evenly spaced values between 0 and 1. P-boxes can be defined using all the probability distributions that are available through SciPy’s statistics library,

Naturally, precise probability distributions can be defined in PBA by defining a p-box with precise inputs. This means that within probability bounds analysis probability distributions are considered a special case of a p-box with zero width. Resultantly, all methodology that applies to p-boxes can also be applied to probability distributions.

Distribution-free p-boxes can also be generated when the underlying distribution is unknown but parameters such as the mean, variance or minimum/maximum bounds are known. Such p-boxes make no assumption about the shape of the distribution and instead return bounds expressing all possible distributions that are valid given the known information. Such p-boxes can be constructed making use of Chebyshev, Markov and Cantelli inequalities from probability theory.

Attention

It is usually better to define p-boxes using distributions or non-parametric methods (see ). This constructor is provided for completeness and for the construction of p-boxes with precise inputs.

Parameters:

left – Left bound of the p-box. Can be a list, NumPy array, Interval or numeric type.
right – Right bound of the p-box. Can be a list, NumPy array, Interval or numeric type.
steps – Number of steps to discretize the p-box into. Default is None.
shape – The shap eof the distribution used to construct the p-box. The shape is defined by the p-box constructor. Default is None.
mean – Interval containing the mean of the p-box. Default is Interval(-np.inf,np.inf).
var – Interval containing the variance of the p-box. Default is Interval(-np.inf,np.inf).
interpolation – Interpolation method to use. See interpolation for more details. Default is linear.
check_moments – If True, the mean and variance of the p-box are checked and recalculated if necessary. Default is True.

Important

If steps is not specified, left and right must be arrays of the same length and steps is set at that value.

If steps is specified, both left and right are interpolated to the specified number of steps using the specified interpolation method (see interpolation_). In this case if steps is less than the length of left or right, a warning is raised and steps is set to the length of left or right.

Warning

The statistic values be specified by constructor function are also calculated automatically. If specified values differ from the calculated values, the calculated values are used and a warning is raised.

If check_moments is set to True and mean and/or var are specified, if the calculated values differ from the specified values, the calculated values are used and a warning is raised.

Error

If the left and right bounds are not increasing, a NotIncreasingError is raised. ValueError is raised if left and right are not the same length.

__init__(left: list | ndarray, right: list | ndarray | None = None, steps: int | None = None, shape: str = '', mean: Interval = Interval[-inf, inf], var: Interval = Interval[0, inf], mean_left: float | None = None, mean_right: float | None = None, var_left: float | None = None, var_right: float | None = None, interpolation: str = 'linear', check_moments: bool = True)#

add(other: Pbox | Interval | float | int, method='f', enforce_steps=True) → Pbox#: Adds other to Pbox to other using the defined dependency method

div(other, method='f')#: Divides Pbox by other using the defined dependency method

env(other)#

Computes the envelope of two Pboxes.

Arguments:

other: Another Pbox, Interval or a numeric value.

Returns:

Pbox

Error

NotImplementedError is raised if other is not a Pbox. Imputation of other needs to be done manually

get_interval(p: float) → Interval#: Returns the interval for the given probability

get_probability(val) → Interval#: Returns the interval

hi()#: Returns the right-most value in the interval

imp(other)#: Returns the imposition of self with other

interpolate(steps: int, method: str = 'linear', inplace=True) → None#

Function to interpolate a p-box to a new number of steps.

Arguments:: steps (int): Number of steps to interpolate to. method (str): Interpolation method to use. Must be one of linear, cubicspline or step. inplace (bool): If True, the p-box is interpolated in place. If False, a new p-box is returned.

Note

method = linear uses numpy.interp method = cubicspline uses scipy.interpolate.CubicSpline method = step uses a step interpolation method.

lo()#: Returns the left-most value in the interval

max(other, method='f')#

Returns a new Pbox object that represents the element-wise minimum of two Pboxes.

Arguments:

other: Another Pbox, Interval or a numeric value. method: Calculation method to determine the minimum. Can be one of ‘f’, ‘p’, ‘o’, ‘i’.

Returns:

Pbox

mean() → Interval#: Returns the mean of the pbox

median() → Interval#: Returns the median of the distribution

min(other, method='f')#

Returns a new Pbox object that represents the element-wise minimum of two Pboxes.

Arguments:

other: Another Pbox, Interval or a numeric value. method: Calculation method to determine the minimum. Can be one of ‘f’, ‘p’, ‘o’, ‘i’.

Returns:

Pbox

mul(other, method='f')#: Multiplies other and Pbox using the defined dependency method

plot(figax=None, now=True, title='', xlabel='x', ylabel='$\\Pr(x \\leq X)$', left_col='red', right_col='black', label=None, **kwargs)#

Plots the p-box

Arguments:

figax (tuple): Tuple containing a matplotlib figure and axis object. If not specified, a new figure and axis object are created. now (bool): If True, the figure is shown. If False, the figure is returned. title (str): Title of the plot. xlabel (str): Label for the x-axis. ylabel (str): Label for the y-axis. label (str): Label for the plot (for use in legend). left_col (str): Colour of the left bound of the p-box. right_col (str): Colour of the right bound of the p-box. kwargs (dict): Additional keyword arguments to pass to matplotlib.pyplot.plot.

Example:

>>> p = pba.N([-1,1],1)
>>> fig, ax = plt.subplots()
>>> p.show(figax = (fig,ax), now = True, title = 'Example', xlabel = 'x', ylabel = r'$\Pr(x \leq X)$',left_col = 'red',right_col = 'black')

pow(other: Pbox | Interval | float | int, method='f') → Pbox#: Raises a p-box to the power of other using the defined dependency method

recip()#: Calculates the reciprocal of a p-box.

Error

DivisionByZero is raised if the p-box contains 0.

show(figax=None, now=True, title='', xlabel='x', ylabel='$\\Pr(x \\leq X)$', left_col='red', right_col='black', label=None, **kwargs)#

Plots the p-box

Arguments:

figax (tuple): Tuple containing a matplotlib figure and axis object. If not specified, a new figure and axis object are created. now (bool): If True, the figure is shown. If False, the figure is returned. title (str): Title of the plot. xlabel (str): Label for the x-axis. ylabel (str): Label for the y-axis. label (str): Label for the plot (for use in legend). left_col (str): Colour of the left bound of the p-box. right_col (str): Colour of the right bound of the p-box. kwargs (dict): Additional keyword arguments to pass to matplotlib.pyplot.plot.

Example:

>>> p = pba.N([-1,1],1)
>>> fig, ax = plt.subplots()
>>> p.show(figax = (fig,ax), now = True, title = 'Example', xlabel = 'x', ylabel = r'$\Pr(x \leq X)$',left_col = 'red',right_col = 'black')

straddles(N, endpoints=True) → bool#

Checks whether a number is within the p-box’s support

Arguments:

N (float): Number to check endpoints (bool): If True, the endpoints of the p-box are included in the check.

Returns:

bool

straddles_zero(endpoints=True) → bool#: Checks whether $0$ is within the p-box

sub(other, method='f')#: Subtracts other from Pbox using the defined dependency method

summary() → str#: Returns a summary of the p-box

support() → Interval#

Returns the range of the pbox

Implementation

>>> Interval(self.lo(),self.hi())

truncate(a: Interval | float | int, b: float | int | None = None, method='f')#

Truncates a p-box to the interval [a,b], or a if b is not specified and a is an Interval.

Arguments:

a (Interval, float, int): The lower bound of the truncation interval. b (float, int): The upper bound of the truncation interval. If not specified, the upper bound of a is used. method (str): The dependency method to use. Can be one of f, p, o, i.

Implementation

>>> self.min(a).max(b)

Error

ValueError is raised if b is not specified and a is not an Interval.

unary(func, *args, **kwargs)#

Allows for unary operations to be performed on a p-box. This is acheived by applying the function to each interval in the p-box.

Arguments:: func (function): Function to apply to each interval in the p-box. args (tuple): Arguments to pass to the function. kwargs (dict): Keyword arguments to pass to the function.

Important

The function must accept an Interval object as its first argument and return an Interval object. args and kwargs are passed to the function as additional arguments.

>>> func(Interval(l,r),*args, **kwargs)

The function must return an Interval object. Behaviour may be unpredictable if the endpoints of the inputted interval do not correspond to the endpoints of the outputted p-box.