pystra.distributions.zero_inflated.ZeroInflated#

Use it: User guide · Worked example · Theory

class ZeroInflated(name, dist, p, *, start_point=None)[source]#

Bases: Distribution

Mixture of a point mass at zero and a supplied distribution.

With probability p the value is zero; with probability 1 - p a value is drawn from dist.

Parameters:

name (str) – Name of the random variable, matching a limit-state argument.
dist (Distribution) – Distribution realized when the variable is not set to zero.
p (float) – Probability of setting the variable to zero; must satisfy 0 <= p < 1.
start_point (float | None) – Starting point for the design-point search. Defaults to the mean.

Methods

`cdf`	Evaluate the cumulative distribution function.
`cdf_gradient`	Derivatives of the CDF w.r.t.
`get_name`	Return the random-variable name.
`isf`	Inverse survival function, from the parent's upper tail.
`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`	Evaluate the probability density function.
`plot`	Plot the probability density function.
`ppf`	Evaluate the inverse cumulative distribution function.
`sample`	Draw random samples from the distribution.
`set_location`	Updating the zero-inflated distribution location parameter.
`set_scale`	Updating the zero-inflated distribution scale parameter.
`set_zero_probability`	Update the zero-inflated probability.
`sf`	Survival function; the zero atom lies on the CDF side.
`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 sensitivity_params: dict[str, float]#: No generic moment perturbation; replace the constructor inputs.

pdf(x)[source]#

Evaluate the probability density function.

Return type:: float | ndarray

cdf(x)[source]#

Evaluate the cumulative distribution function.

Return type:: float | ndarray

ppf(p)[source]#

Evaluate the inverse cumulative distribution function.

Return type:: float | ndarray

sf(x)[source]#

Survival function; the zero atom lies on the CDF side.

Return type:: float | ndarray

isf(q)[source]#

Inverse survival function, from the parent’s upper tail.

Return type:: float | ndarray

set_location(loc=0)[source]#

Updating the zero-inflated distribution location parameter.

Return type:: None

set_scale(scale=1)[source]#

Updating the zero-inflated distribution scale parameter.

Return type:: None

set_zero_probability(p)[source]#

Update the zero-inflated probability.

Return type:: None

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

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.

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

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 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