pystra.distributions.beta.Beta#

Use it: User guide · Worked example · Theory

class Beta(name, mean=None, std=None, *, q=None, r=None, lower=0, upper=1, start_point=None)[source]#

Bases: Distribution

Beta distribution on a bounded interval.

Supply either mean and std or q and r. The two parameterizations cannot be combined.

Parameters:

name (str) – Name of the random variable, matching a limit-state argument.
mean (float | None) – Mean in physical space.
std (float | None) – Standard deviation in physical space.
q (float | None) – First beta shape parameter. Supply with the other native parameters instead of mean and std.
r (float | None) – Second beta shape parameter. Supply with the other native parameters instead of mean and std.
lower (float) – Lower bound of the distribution. Defaults to 0.
upper (float) – Upper bound of the distribution. Defaults to 1.
start_point (float | None) – Starting point for the design-point search. Defaults to the mean.

Methods

`beta_parameter`	Return the standard-deviation residual for beta shape fitting.
`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.

beta_parameter(q, *args)[source]#

Return the standard-deviation residual for beta shape fitting.

The optimizer supplies q; args contains lower, upper, mean and std.

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

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

get_name()#

Return the random-variable name.

Return type:: str

isf(q)#

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

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

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

logpdf(x)#

Log density, -inf where the density is zero.

Return type:: float | ndarray

logsf(x)#

Logarithm of the survival function, accurate in both tails.

Return type:: float | ndarray

property mean: float#: Mean of the distribution.

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.

pdf(x)#

Probability density function.

Parameters:: x (ArrayLike) – Value(s) in physical space.
Returns:: Density value(s).
Return type:: float | 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

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

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

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

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

sf(x)#

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

Return type:: float | ndarray

property start_point: float#: Starting point of the design-point search; the mean by default.

property std: float#: Standard deviation of the distribution.

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

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.

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