pystra.distributions.shifted_lognormal.ShiftedLognormal#

Use it: User guide · Worked example · Theory

class ShiftedLognormal(name, mean, std, lower, *, start_point=None)[source]#

Bases: Lognormal

Shifted lognormal distribution.

If X is lognormal, Y = X + lower has this distribution. The supplied mean and standard deviation describe Y.

Parameters:

name (str) – Name of the random variable, matching a limit-state argument.
mean (float) – Mean in physical space.
std (float) – Standard deviation in physical space.
lower (float) – Lower bound of the distribution.
start_point (float | None) – Starting point for the design-point search. Defaults to the mean.

Methods

`cdf`	Evaluate the cumulative distribution function.
`cdf_gradient`	Analytical derivatives of the Lognormal 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`	Log CDF.
`logpdf`	Log density.
`logsf`	Log survival function.
`pdf`	Evaluate the probability density function.
`plot`	Plot the probability density function.
`ppf`	Percent-point function (inverse CDF).
`sample`	Draw random samples from the distribution.
`set_location`	Set the physical mean to loc and update the underlying normal parameters.
`set_lower`	Updating the distribution lower parameter.
`set_scale`	Set the physical standard deviation to scale and update normal parameters.
`sf`	Survival function.
`u_to_x`	Transform standard normal coordinates to physical values.
`with_parameters`	Rebuild an independent marginal, replacing constructor parameters.
`x_to_u`	Transform physical values to standard normal coordinates.

set_lower(lower=0)[source]#

Updating the distribution lower parameter. For Lognormal, even though we have a SciPy object, it’s not being used in the functions above for performance, so we need to update params directly.

Return type:: None

cdf(x)#

Evaluate the cumulative distribution function.

Return type:: float | ndarray

cdf_gradient(x)#

Analytical derivatives of the Lognormal CDF w.r.t. μ and σ.

The CDF is F(x) = Φ((ln x - λ) / ζ) where ζ = sqrt(ln(1 + (σ/μ)²)) and λ = ln(μ) - ζ²/2.

The chain rule gives:

\[\frac{\partial F}{\partial \theta} = \frac{\varphi(z)}{\zeta} \left(-\frac{\partial\lambda}{\partial\theta} - z\,\frac{\partial\zeta}{\partial\theta}\right)\]

where z = (ln x - λ) / ζ.

Return type:: dict[str, float | ndarray]

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

Log CDF.

Return type:: float | ndarray

logpdf(x)#

Log density.

Return type:: float | ndarray

logsf(x)#

Log survival function.

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

Evaluate the probability density function.

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

Set the physical mean to loc and update the underlying normal parameters.

Return type:: None

set_scale(scale=1)#

Set the physical standard deviation to scale and update normal parameters.

Return type:: None

sf(x)#

Survival function.

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 standard normal coordinates to physical values.

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 physical values to standard normal coordinates.

Return type:: float | ndarray