pystra.distributions.distribution.Distribution#

class Distribution(name='', dist_obj=None, mean=None, stdv=None, startpoint=None)[source]#

Bases: object

Base class for all probability distributions used in reliability analysis.

Subclasses typically construct a scipy.stats frozen distribution object (dist_obj) and pass it to this base class, which then delegates pdf, cdf, ppf, and the Nataf-space transformations (x_to_u, u_to_x, jacobian) to it.

Subclasses that do not wrap a SciPy distribution must override the transformation and Jacobian methods directly (see, e.g., ZeroInflated).

Parameters:

name (str) – Name of the random variable. Must match a keyword argument of the limit state function.
dist_obj (scipy.stats.rv_frozen, optional) – A frozen SciPy distribution. When provided, mean and stdv are computed from the distribution automatically.
mean (float, optional) – Mean of the distribution (required if dist_obj is None).
stdv (float, optional) – Standard deviation (required if dist_obj is None).
startpoint (float, optional) – Starting point for iterative search algorithms (defaults to the mean).

name#

Name of the random variable.

Type:: str

mean#

Mean of the distribution.

Type:: float

stdv#

Standard deviation of the distribution.

Type:: float

startpoint#

Starting point for search algorithms.

Type:: float

dist_type#

Human-readable label set by each subclass (e.g. "Normal").

Type:: str

Methods

`cdf`	Cumulative distribution function.
`dF_dtheta`	Derivatives of the CDF w.r.t.
`getMean`
`getName`
`getStartPoint`
`getStdv`
`jacobian`	Diagonal Jacobian of the marginal x-to-u transformation.
`pdf`	Probability density function.
`plot`	Plot the probability density function.
`ppf`	Percent-point function (inverse CDF).
`sample`	Draw random samples from the distribution.
`setStartPoint`
`set_location`	Update the location parameter of the underlying SciPy distribution.
`set_scale`	Update the scale parameter of the underlying SciPy distribution.
`u_to_x`	Transform from standard normal space to physical space.
`x_to_u`	Transform from physical space to standard normal space.

pdf(x)[source]#

Probability density function.

Parameters:: x (float or array_like) – Value(s) in physical space.
Returns:: Density value(s).
Return type:: float or ndarray

cdf(x)[source]#

Cumulative distribution function.

Parameters:: x (float or array_like) – Value(s) in physical space.
Returns:: Probability value(s) in [0, 1].
Return type:: float or ndarray

ppf(u)[source]#

Percent-point function (inverse CDF).

Parameters:: u (float or array_like) – Probability value(s) in (0, 1).
Returns:: Quantile(s) in physical space.
Return type:: float or ndarray

u_to_x(u)[source]#

Transform from standard normal space to physical space.

Applies the marginal Nataf mapping: x = F^{-1}(Phi(u)).

Parameters:: u (float) – Value in standard normal (u) space.
Returns:: Corresponding value in physical (x) space.
Return type:: float

x_to_u(x)[source]#

Transform from physical space to standard normal space.

Applies the marginal Nataf mapping: u = Phi^{-1}(F(x)).

Parameters:: x (float) – Value in physical (x) space.
Returns:: Corresponding value in standard normal (u) space.
Return type:: float

jacobian(u, x)[source]#

Diagonal Jacobian of the marginal x-to-u transformation.

Returns a diagonal matrix J where the diagonal entry is f_X(x) / phi(u) (Lemaire, eq. 4.9). This is assembled into the full Jacobian by the Transformation class.

Parameters:

u (float or array_like) – Value(s) in standard normal space.
x (float or array_like) – Corresponding value(s) in physical space.

Returns:

Diagonal Jacobian matrix of shape (n, n) where n is the length of the input arrays.

Return type:

ndarray

sample(n=1000)[source]#

Draw random samples from the distribution.

Uses inverse-transform sampling via ppf.

Parameters:: n (int, optional) – Number of samples (default 1000).
Returns:: Array of shape (n,) with sampled values.
Return type:: ndarray

plot(ax=None, **kwargs)[source]#

Plot the probability density function.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to plot on. A new figure is created if None.
**kwargs – Additional keyword arguments forwarded to ax.plot().

Returns:

The axes containing the plot.

Return type:

matplotlib.axes.Axes

property sensitivity_params#

Distribution parameters for which sensitivities are computed.

Returns a dict {param_name: current_value} listing every parameter with respect to which \(\partial\beta/\partial\theta\) should be evaluated.

The default implementation returns {"mean": μ, "std": σ}, which is appropriate for most distributions. Distributions with additional parameters of interest (e.g. the GEV shape parameter) should override this property to include them.

Parameters listed in _ctor_kwargs but not in sensitivity_params are held fixed during sensitivity analysis — they are only used by _make_copy() to faithfully reconstruct the distribution.

Returns:: {param_name: current_value}
Return type:: dict

dF_dtheta(x)[source]#

Derivatives of the CDF w.r.t. each sensitivity parameter.

Returns ∂F_X(x)/∂θ for every parameter listed by sensitivity_params. The base-class implementation uses central finite differences on the CDF via _make_copy().

Before computing derivatives, a reconstruction sanity check verifies that _make_copy() (with no overrides) reproduces the current distribution. This catches both constructor failures (e.g. composite distributions) and silent mismatches (e.g. distributions whose extra constructor arguments are not stored in _ctor_kwargs).

Subclasses may override this with analytical expressions for better accuracy and performance (see Normal and Lognormal).

Parameters:: x (float) – Evaluation point in physical space.
Returns:: {param_name: ∂F/∂θ} for each parameter in sensitivity_params.
Return type:: dict
Raises:: ValueError – If the distribution cannot be faithfully reconstructed by _make_copy().

set_location(loc=0)[source]#

Update the location parameter of the underlying SciPy distribution.

After updating, mean and stdv are recomputed. This is used by the sensitivity analysis to perturb distribution parameters.

Parameters:: loc (float, optional) – New location parameter (default 0).
Raises:: Exception – If the distribution does not wrap a SciPy frozen distribution.

set_scale(scale=1)[source]#

Update the scale parameter of the underlying SciPy distribution.

After updating, mean and stdv are recomputed. This is used by the sensitivity analysis to perturb distribution parameters.

Parameters:: scale (float, optional) – New scale parameter (default 1).
Raises:: Exception – If the distribution does not wrap a SciPy frozen distribution.