Statistics#

This module contains all statistics related functionality.

The most important class in this module is Stochast. It defines the stochastic properties of a stochastic variable, which is part of a project (which is the main entry point for performing a reliability, uncertainty or sensitivity analysis).

class ConditionalValue(id=None)[source]#

Bases: FrozenObject

Defines the stochast properties at a certain value of a Stochast.conditional_source, which is used when a stochast is Stochast.conditional

Several conditional values form a list, which is used to derive stochast properties in case of a conditional stochast. The values in this conditional value are used for interpolation to retrieve the stochast properties at a certain value assigned to the Stochast.conditional_source of a stochast.

property deviation: float#

Optional standard deviation value of the conditional value

When retrieved, the value set by the user is returned and nan if not set. When set, other properties in this conditional value are modified in such a way that the set value and mean are maintained. The same distribution type is assumed as the parent stochast

property location: float#: Defines the location of the conditional value

property maximum: float#: Defines the maximum of the conditional value

property mean: float#

Optional mean value of the conditional value

When retrieved, the value set by the user is returned and nan if not set. When set, other properties in this conditional value are modified in such a way that the set value and deviation are maintained. The same distribution type is assumed as the parent stochast

property minimum: float#: Defines the minimum of the conditional value

property observations: int#: Defines the number of observations of the conditional value

property scale: float#: Defines the scale of the conditional value

property shape: float#: Defines the shape of the conditional value

property shape_b: float#: Defines the additional shape of the conditional value

property shift: float#: Defines the shift of the conditional value

property shift_b: float#: Defines the additional shift of the conditional value

property x: float#: The x-value for which the stochast properties in this conditional value apply

class ConstantParameterType(value)[source]#

Bases: Enum

Enumeration which defines which stochast parameter should remain unchanged when the stochast properties are updated

deviation = 'deviation'#

variation = 'variation'#

class ContributingStochast(id=None)[source]#

Bases: FrozenObject

Stochast contributing to a stochast with distribution type composite

create(variable)[source]#

Creates a contributing stochast

Parameters:

probability (float.) – Fraction of the contributing stochast
variable (Stochast.) – Stochast definition of the contributing stochast

property probability: float#

Fraction how much this contributing stochast contributes to the parent stochast.

The contributing stochast contributes for a certain fraction (probability) to a parent stochast. All probability values must add up to 1.

property variable: Stochast#: Stochast definition of the contributing stochast

class CopulaCorrelation(id=None)[source]#

Bases: FrozenObject

Copulas correlation for stochastic variables

The correlation values are retrieved or set with an indexer, with variables as arguments.

```mermaid classDiagram

class Stochast{
+distribution : DistributionType +”defining properties” : float

} class CopulaCorrelation{

+variables : list[Stochast]

} class SelfCorrelationMatrix{

+variables : list[Stochast]

} Stochast “*” <– CopulaCorrelation Stochast “*” <– SelfCorrelationMatrix

```

property variables: list[Stochast]#: List of variables for which correlations are defined. The variables are retrieved automatically when this correlation class is part of a project.

class CopulaType(value)[source]#

Bases: Enum

Enumeration which defines the type of copula correlation

clayton = 'clayton'#

diagonal_band = 'diagonal_band'#

frank = 'frank'#

gaussian = 'gaussian'#

classmethod get_index(type)[source]#

gumbel = 'gumbel'#

class CorrelationMatrix(id=None)[source]#

Bases: FrozenObject

Correlation matrix for stochastic variables

The correlation is defined as the Pearson correlation value. The correlation value must be between -1 and 1 (inclusive).

By default, the correlation is 0 between different stochasts and 1 between the same stochasts. The correlation matrix is symmetric, which is maintained automatically.

The correlation values are retrieved or set with an indexer, with variables as arguments.

```mermaid classDiagram

class Stochast{
+distribution : DistributionType +”defining properties” : float

} class CorrelationMatrix{

+variables : list[Stochast]

} class SelfCorrelationMatrix{

+variables : list[Stochast]

} Stochast “*” <– CorrelationMatrix Stochast “*” <– SelfCorrelationMatrix

```

property variables: list[Stochast]#: List of variables for which correlations are defined. The variables are retrieved automatically when this correlation matrix is part of a project.

class CorrelationType(value)[source]#

Bases: Enum

Enumeration which defines the type of correlation

copulas = 'copulas'#

gaussian = 'gaussian'#

classmethod get_index(type)[source]#

class DiscreteValue(id=None)[source]#

Bases: FrozenObject

Defines a discrete value of a stochast in case of a discrete distribution

property amount: float#: The number of occurrences or PMF (probability mass function) corresponding with the x-value of this discrete value The amounts do not have to be normalized over all discrete values of a stochast

create(amount)[source]#

Creates a discrete value with an x-value and amount

Parameters:

x (float) – The x-value to which the discrete value applies
amount (float) – The amount corresponding with the x-value

property x: float#: X-value for which this discrete value is defined

class DistributionType(value)[source]#

Bases: Enum

Enumeration which defines the probability distribution type

bernoulli = 'bernoulli'#

beta = 'beta'#

cdf_curve = 'cdf_curve'#

composite = 'composite'#

conditional_weibull = 'conditional_weibull'#

deterministic = 'deterministic'#

discrete = 'discrete'#

exponential = 'exponential'#

frechet = 'frechet'#

gamma = 'gamma'#

generalized_extreme_value = 'generalized_extreme_value'#

generalized_pareto = 'generalized_pareto'#

gumbel = 'gumbel'#

histogram = 'histogram'#

log_normal = 'log_normal'#

normal = 'normal'#

pareto = 'pareto'#

poisson = 'poisson'#

qualitative = 'qualitative'#

rayleigh = 'rayleigh'#

rayleigh_n = 'rayleigh_n'#

standard_normal = 'standard_normal'#

student_t = 'student_t'#

trapezoidal = 'trapezoidal'#

triangular = 'triangular'#

uniform = 'uniform'#

weibull = 'weibull'#

class FragilityValue(id=None)[source]#

Bases: FrozenObject

Defines a point in a CDF curve of a Stochast in case of a cdf_curve distribution

create(reliability_index)[source]#

Creates a discrete value with an x-value and amount

Parameters:

x (float) – The x-value to which the fragility value applies
reliability_index (float) – The reliability index corresponding with the x-value

property design_point: DesignPoint#: Design point corresponding with this fragility value

property probability_of_failure: float#: Probability of failure corresponding with the reliability index in this fragility value

property probability_of_non_failure: float#: Probability of non-failure corresponding with the reliability index in this fragility value

property reliability_index: float#: Reliablity index corresponding with the x-value of this fragility value

property return_period: float#: Return period corresponding with the reliability index in this fragility value

property x: float#: X-value for which this fragility value is defined

class HistogramValue(id=None)[source]#

Bases: FrozenObject

Defines a histogram value (or bin) of a Stochast in case of a histogram distribution

A histogram value is defined by a lower bound and upper bound and contains an amount, which is the number of occurrences between these boundaries (the height of the bin). The difference between the lower and upper bound (the width of the bin) may vary between the histogram values of a stochast and can even be zero.

When the histogram values are the result of an operation (fit of the stochast or an uncertainty analysis), all histogram values have the same width for clarity for the user and understandability of a plot.

When the minimum or maximum values appear multiple times in the fit set, they are regarded as non-exceedable minimum and maximum values and histogram value boundaries do not exceed these values. Instead, a boundary histogram value is added with width zero.

property amount: float#: The number of occurrences or PMF (probability mass function) corresponding with the histogram value The amounts do not have to be normalized over all histogram values of a stochast

create(upper_bound, amount)[source]#

Creates a discrete value with an x-value and amount

Parameters:

lower_bound (float) – The lower bound of the histogram value
upper_bound (float) – The upper_bound of the histogram value
amount (float) – The amount of the histogram value

property lower_bound: float#: The lower bound of the histogram value

property upper_bound: float#: The upper bound of the histogram value

class ProbabilityValue(id=None)[source]#

Bases: FrozenObject

Contains a probability in several interchangeable definitions

property probability_of_failure: float#: The probability as a probability, i.e. a value between 0 and 1

property probability_of_non_failure: float#: The probability as a probability of non-failure

property reliability_index: float#: The probability as a reliability index (u-space)

property return_period: float#: The probability as a return period

class Scenario(id=None)[source]#

Bases: FrozenObject

Defines the contribution of a design point, when it is combined with other design point points in an exclusive way

A scenario corresponds with a probabilistic_library.reliability.DesignPoint. They will be combined by an probabilistic_library.project.ExcludingCombineProject.

property name: str#: Defines the name of a scenario

property probability: float#: Defines the fraction of the design point. The fractions of all scenarios to be combined must add up to 1.

class SelfCorrelationMatrix[source]#

Bases: FrozenObject

Defines the correlation values of a stochast with another stochast, both corresponding with the same parameter.

This is used for upscaling in a probabilistic_library.project.LengthEffectProject, which is used when a design point is applicable for a certain section of a system (e.g. a section of 50 m in a trajectory of 500 m). When upscaling the design point to the system, it is combined with itself. But stochasts do not have full correlation with stochasts of another section. The self correlation matrix defines these correlations.

The correlation values are retrieved or set with an indexer, with a variable as argument

class StandardNormal[source]#

Bases: FrozenObject

Provides conversions between probabilities (p,q), reliability (u) and return time (t)

get_p_from_u()[source]#

Gets p (probability of non-exceedence) from u

Return type:: float
Parameters:: u (float)

get_q_from_u()[source]#

Gets q (probability of exceedence) from u

Return type:: float
Parameters:: u (float)

get_t_from_u()[source]#

Gets return time from u

Return type:: float
Parameters:: u (float)

get_u_from_p()[source]#

Gets u from p (probability of non-exceedence)

Return type:: float
Parameters:: p (float)

get_u_from_q()[source]#

Gets u from q (probability of exceedence)

Return type:: float
Parameters:: q (float)

get_u_from_t()[source]#

Gets u from return time

Return type:: float
Parameters:: t (float)

class Stochast(id=None)[source]#

Bases: FrozenObject

Contains the definition of a stochastic variable

The stochastic variable is defined by the following properties: distribution, location, scale, shape, shape_b, shift, shift_b, minimum, maximum, observations, truncated and inverted. Depending on the distribution, a selection of these properties is used. To find out which properties are used by a distribution, print the variable, which only prints the properties in use. For some distributions, the list of histogram_values, discrete_values or fragility_values is used. Composite stochasts are supported, where a stochast consists of several other stochasts, each with a certain fraction.

A number of characteristics can be derived. They can also be set and then stochast properties are updated. These characteristics are: mean, (standard) deviation, variation (coefficient) and design_value. The design_value needs the input values design_factor and design_quantile to be calculated. The following characteristic features needing an x-value are available: get_cdf, get_pdf, get_u_at_x, get_x_at_u and get_quantile.

The stochast properties can be estimated by providing a number of values from which the properties will be fitted. The methods fit and fit_prior enable this feature. The goodness of fit can be retrieved by get_ks_test.

Conditional stochasts are supported. The stochast properties depend on the value (or realization in a probabilistic analysis) of another stochast, indicated by conditional_source. A table conditional_values is used to define the stochast properties for a certain value of the source stochast.

A stochast can function as an array in a probabilistic analysis. The stochast will function as a number of uncorrelated stochastic variables. To define an array, use is_array and array_size.

Printing and plotting are supported with methods print, plot, get_plot, get_series and get_special_values. Validation is supported by is_valid and validate.

property array_size: int#: Size of the array when this stochast is an array (defined by is_array)

property array_variables: list[Stochast]#

Optional list of stochasts which are used when this stochast is an array

If not filled, this stochast definition is used for each member in the array. If filled, the items in this list are used in the array, where the first item in this list corresponds with the first array stochast, the second list item to the second array stochast, etc. When this list is exhausted, this stochast definition is used for the remaining array stochasts.

can_fit_prior()[source]#

Tells whether a fit with prior can be performed.

Return type:: bool

property conditional: bool#

Indicates whether the stochast is conditional, which means that the defining stochast properties depend on the value of the conditional_source

Within a probabilistic analysis, all stochastic variables get realizations, which means that a value is assigned to them. The value assigned to the conditional_source is used to look up the defining properties of this stochast. Therefore the list conditional_values is used, where these values are defined for some values of the conditional_source

property conditional_source: Stochast#: The source stochast if this stochast is conditional

property conditional_values: list[ConditionalValue]#

The list of conditional values if this stochast is conditional

In a probabilistic analysis, the defining properties of are derived from this list. By interpolation against the value assigned to the conditional_source the defining properties are determined. No extrapolation takes place, but the values belonging to the most extreme conditional_source values are used.

property contributing_stochasts: list[ContributingStochast]#: List of contributing stochasts, defines a stochast of distribution type composite

copy_from(source)[source]#

Copies the stochast properties from a source stochast.

Parameters:: source (Stochast|str) – The stochast to copy the properties from

property design_factor: float#: Defines the factor, which is used to calculate the design_value

property design_quantile: float#: Defines the quantile, which is used to calculate the design_value

property design_value: float#: The design value, which is a representable calculation value based on the stochastic definition. When set, defining properties are adapted while keeping the variation property value unchanged

property deviation: float#: Standard deviation of the stochast. When set, defining properties are modified in such a way that the set value and mean are maintained

property discrete_values: list[DiscreteValue]#: List of discrete values, defines a stochast of distribution type discrete

property distribution: DistributionType#

Distribution type of the stochast

When the distribution type is changed, an effort will be made to maintain the mean and deviation. When the distribution type is changed initially, before other properties have been set, this does not take place.

fit(values, shift=nan)[source]#

Fits the stochast parameters from a list of values. Validates first whether the fit can be performed, if not an error message is printed and no fit is performed.

Parameters:

values (list[float].) – The list of values from which is fitted
shift (float, optional.) – If set, the shift value is not fitted, but taken from this value

fit_prior(prior, values, shift=nan)[source]#

Fits the stochast parameters from a list of values. Validates first whether the fit can be performed, if not an error message is printed and no fit is performed.

Parameters:

values (list[float].) – The list of values from which is fitted
prior (Stochast | str.) – Prior stochast, Bayesian updating is used to perform fitting with prior
shift (float, optional.) – If set, the shift value is not fitted, but taken from this value

property fragility_values: list[FragilityValue]#: List of fragility values, defines a stochast of distribution type cdf_curve

get_cdf(x)[source]#

Gets the CDF value of the stochast

Parameters:: x (float.) – X-value for which the CDF is requested
Return type:: float

get_ks_test(values)[source]#

Generates the Kolmogorov-Smirnov statistic, which indicates the goodness of fit. A value of 1 indicates a perfect fit, a value of 0 indicates the worst possible fit.

Parameters:: values (list[float]) – The list of values to compare this stochast against
Return type:: float

get_pdf(x)[source]#

Gets the PDF or PMF value of the stochast

Parameters:: x (float) – X-value for which the PDF or PMF is requested
Return type:: float

get_plot(xmin=None, xmax=None)[source]#

Gets the plot object of this stochast

Parameters:

xmin (float, optional) – The minimum x value (default is None, a proper minimum value will be used)
xmax (float, optional) – The maximum x value (default is None, a proper maximum value will be used)

Return type:

get_quantile(quantile)[source]#

Gets the value belonging to a given quantile

Parameters:: quantile (float.) – Quantile for which the x-value is requested, must be between 0 and 1 (exclusive)
Return type:: float

get_series(xmin=None, xmax=None, number_of_points=None)[source]#

Gets a list of x values which is useful for plotting.

The list of x values will be generated between a minimum and maximum with equal distance. The distance is based on the number points. The minimum and maximum are included always. The list of values will be extended with x-values to plot discontinuity points properly.

Parameters:

xmin (float, optional) – The minimum x value (default is None, a proper minimum value will be used)
xmax (float, optional) – The maximum x value (default is None, a proper maximum value will be used)
number_of_points (int, optional) – The number of points to be generated (default is None)

Return type:

list[float]

get_special_values()[source]#

Gets a list of special x-values, which is useful for plotting

Return type:: list[float]

get_u_from_x(x)[source]#

Gets the u-value at a given x-value of the stochast

Parameters:: x (float.) – X-value for which the u-value is requested
Return type:: float

get_x_from_u(u)[source]#

Gets the x-value at a given u-value of the stochast

Parameters:: u (float) – U-value for which the x-value is requested
Return type:: float

get_x_from_u_and_source(u, x)[source]#

Gets the x-value at a given u-value of a conditional stochast

Parameters:

u (float.) – U-value for which the x-value is requested
x (float.) – The conditional value on which the distribution of this conditional stochast is based

Return type:

float

Returns:

Requested x-value

property histogram_values: list[HistogramValue]#: List of histogram values, defines a stochast of distribution type histogram

property inverted: bool#: Indicates whether the stochast is inverted, i.e. mirrored in the shift

property is_array: bool#: Indicates whether this stochast should be used as a list of stochasts in a probabilistic analysis

is_valid()[source]#

Indicates whether the stochast is valid

Return type:: bool

property location: float#: Location parameter of the stochast (one of the defining properties)

property maximum: float#: Maximum value of the stochast (one of the defining properties)

property mean: float#: Mean value of the stochast. When set, defining properties are modified in such a way that the set value and deviation are maintained

property minimum: float#: Minimum value of the stochast (one of the defining properties)

property name: str#: The name of the stochast The name is set automatically when the stochast is provided by a model

property observations: int#: Number of observations of the stochast (one of the defining properties)

plot(xmin=None, xmax=None)[source]#

Shows a plot of this stochast

Parameters:

xmin (float, optional) – The minimum x value (default is None, a proper minimum value will be used)
xmax (float, optional) – The maximum x value (default is None, a proper maximum value will be used)

print(decimals=4)[source]#

Prints this stochast Only properties in use will be printed

Parameters:: decimals (int, optional) – The number of decimals to apply

property rate: float#: Rate parameter of the stochast, derived from scale

property scale: float#: Scale parameter of the stochast (one of the defining properties)

property shape: float#: Shape parameter of the stochast (one of the defining properties)

property shape_b: float#: Additional shape parameter of the stochast (one of the defining properties)

property shift: float#: Shift parameter of the stochast (one of the defining properties)

property shift_b: float#: Additional shift parameter of the stochast (one of the defining properties)

property truncated: bool#: Indicates whether the stochast is truncated. The truncation takes place at the minimum and maximum value

validate()[source]#: Prints the validation of this stochast

property variation: float#: Variation coefficient of the stochast. When set, defining properties are modified in such a way that the set value and mean are maintained