pystra.distributions.distribution.Distribution

Use it: User guide · Worked example · Theory

class Distribution(name='', dist_obj=None, mean=None, std=None, start_point=None)

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, or provide the tail functions below (see, e.g., Maximum).

Tail accuracy. Every distribution provides cdf, sf, logcdf, logsf, pdf, logpdf, ppf and isf, each accurate in its own tail. u_to_x and x_to_u evaluate the tail that the point lies in, so a probability near one is never formed: x = F^{-1}(Phi(u)) for u <= 0 and x = Fbar^{-1}(Phi(-u)) for u > 0. Beyond the smallest normal double (|u| above about 37.5) the log-probability is inverted instead, in closed form where one exists and otherwise by solving the log-CDF or log-survival function. Jacobians switch to log densities when the densities underflow. Subclasses that override cdf or ppf should override sf or isf as well; the fallbacks 1 - cdf and ppf(1 - q) lose the upper tail.

Parameters:

• name (str) – Name of the random variable. Must match a keyword argument of the limit-state function.

• dist_obj (rv_frozen | None) – A frozen SciPy distribution. When provided, mean and std are computed from the distribution automatically.

• mean (float | None) – Mean of the distribution (required if dist_obj is None).

• std (float | None) – Standard deviation (required if dist_obj is None).

• start_point (float | None) – Starting point for iterative search algorithms (defaults to the mean).

name

Name of the random variable.

Type:

str

dist_type

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

Type:

str

Methods

cdf	Cumulative distribution function.
cdf_gradient	Derivatives of the CDF w.r.t.
get_name	Return the random-variable name.
isf	Inverse survival function, accurate for small upper-tail q.
jacobian	Diagonal Jacobian of the marginal x-to-u transformation.
logcdf	Logarithm of the CDF, accurate in both tails.
logpdf	Log density, -inf where the density is zero.
logsf	Logarithm of the survival function, accurate in both tails.
pdf	Probability density function.
plot	Plot the probability density function.
ppf	Percent-point function (inverse CDF).
sample	Draw random samples from the distribution.
set_location	Update the location parameter of the underlying SciPy distribution.
set_scale	Update the scale parameter of the underlying SciPy distribution.
sf	Survival function 1 - F(x), accurate in the upper tail.
u_to_x	Transform from standard normal space to physical space.
with_parameters	Rebuild an independent marginal, replacing constructor parameters.
x_to_u	Transform from physical space to standard normal space.

property mean: float

Mean of the distribution.

property std: float

Standard deviation of the distribution.

property start_point: float

Starting point of the design-point search; the mean by default.

get_name()

Return the random-variable name.

Return type:

str

pdf(x)

Probability density function.

Parameters:

x (ArrayLike) – Value(s) in physical space.

Returns:

Density value(s).

Return type:

float | ndarray

logpdf(x)

Log density, -inf where the density is zero.

Return type:

float | ndarray

cdf(x)

Cumulative distribution function.

Parameters:

x (ArrayLike) – Value(s) in physical space.

Returns:

Probability value(s) in [0, 1].

Return type:

float | ndarray

sf(x)

Survival function 1 - F(x), accurate in the upper tail.

Return type:

float | ndarray

logcdf(x)

Logarithm of the CDF, accurate in both tails.

Below the median the logarithm of the CDF itself (or SciPy’s logcdf) is used; above it, log1p(-sf(x)) keeps the difference from zero.

Return type:

float | ndarray

logsf(x)

Logarithm of the survival function, accurate in both tails.

Return type:

float | ndarray

ppf(u)

Percent-point function (inverse CDF).

Parameters:

u (ArrayLike) – Probability value(s) in (0, 1).

Returns:

Quantile(s) in physical space.

Return type:

float | ndarray

isf(q)

Inverse survival function, accurate for small upper-tail q.

Return type:

float | ndarray

u_to_x(u)

Transform from standard normal space to physical space.

Applies the marginal Nataf mapping x = F^{-1}(Phi(u)). Above u = 3 it is evaluated as Fbar^{-1}(Phi(-u)), so the probability passed on is never rounded towards one; far into either tail the log-probability is used (see _tail_quantiles()).

Parameters:

u (ArrayLike) – Value(s) in standard normal (u) space.

Returns:

Corresponding value(s) in physical (x) space.

Return type:

float | ndarray

x_to_u(x)

Transform from physical space to standard normal space.

Applies the marginal Nataf mapping u = Phi^{-1}(F(x)), as u = -Phi^{-1}(Fbar(x)) above u = 3, with log probabilities where these underflow.

Parameters:

x (ArrayLike) – Value(s) in physical (x) space.

Returns:

Corresponding value(s) in standard normal (u) space.

Return type:

float | ndarray

jacobian(u, x)

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. The ratio is formed from log densities where either density underflows.

Parameters:

• u (ArrayLike) – Value(s) in standard normal space.

• x (ArrayLike) – 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)

Draw random samples from the distribution.

Uses inverse-transform sampling via ppf.

Parameters:

n (int) – Number of samples (default 1000).

Returns:

Array of shape (n,) with sampled values.

Return type:

ndarray

plot(ax=None, **kwargs)

Plot the probability density function.

Parameters:

• ax (Axes | None) – Axes to plot on. A new figure is created if None.

• **kwargs (Any) – Additional keyword arguments forwarded to ax.plot().

Returns:

The axes containing the plot.

Return type:

Axes

property sensitivity_params: dict[str, float]

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.

Fixed constructor settings such as bounds are separate from these sensitivity coordinates. Native reconstruction parameters can be another representation of the same law: sensitivity analysis perturbs the declared coordinates together, keeping other moments fixed.

Returns:

{param_name: current_value}

Return type:

dict

property parameters: Mapping[str, object]

Read-only snapshot of keyword arguments that rebuild this marginal.

type(dist)(**dist.parameters) reproduces its law, name and start point. Built-ins use native parameters where moment fitting could lose precision. Nested marginals and SciPy objects are independent copies, so mutating a snapshot never changes the source distribution. Custom marginals may override this property with their complete constructor mapping. Sensitivity coordinates are specified separately by sensitivity_params.

with_parameters(**changes)

Rebuild an independent marginal, replacing constructor parameters.

Parameters:

**changes (object) – Replacements for keys of parameters. Built-ins supporting moment sensitivities also accept mean and std; supplying either switches to moment construction, holding the other moment and fixed bounds/shape constant. Native coordinates and moments cannot be supplied together. The start point remains unchanged unless explicitly replaced (None selects the new mean).

Returns:

Independent instance of the same type, including nested marginals. An empty replacement reproduces the distribution.

Return type:

Self

Raises:

• TypeError – A replacement is unknown, or mixes moments and native coordinates.

• ModelError, ValueError – Constructor parameters do not define a valid distribution.

cdf_gradient(x)

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 with_parameters().

Before computing derivatives, a reconstruction sanity check verifies that with_parameters() (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 parameters).

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

Parameters:

x (ArrayLike) – Evaluation point in physical space.

Returns:

{param_name: ∂F/∂θ} for each parameter in sensitivity_params.

Return type:

dict[str, float | ndarray]

Raises:

ValueError – If the distribution cannot be faithfully reconstructed by with_parameters().

set_location(loc=0)

Update the location parameter of the underlying SciPy distribution.

After updating, mean and std are recomputed. This is available for callers that need an in-place parameter update.

Parameters:

loc (float) – New location parameter (default 0).

Raises:

ModelError – If the distribution does not wrap a SciPy frozen distribution.

Return type:

None

set_scale(scale=1)

Update the scale parameter of the underlying SciPy distribution.

After updating, mean and std are recomputed. This is available for callers that need an in-place parameter update.

Parameters:

scale (float) – New scale parameter (default 1).

Raises:

ModelError – If the distribution does not wrap a SciPy frozen distribution.

Return type:

None