virocon.contours module

Classes for environmental contours.

class virocon.contours.AndContour(model, alpha, n=None, deg_step=3, sample=None, allowed_error=0.01)

Bases: Contour

A contour that connects points of constant AND exceedance. Such contours are described, for example, in Mazas (2019) [7]. This implementation uses Monte Carlo simulation and only works for 2D models.

Parameters:

• model (MultivariateModel) – The model to be used to calculate the contour.

• alpha (float) – The exceedance probability. The probability that an observation falls outside the environmental contour.

• n (int, optional) – Number of data points that shall be Monte Carlo simulated. Defaults to None, which calculates n based on alpha: n = int(100 / alpha).

• deg_step (float, optional) – Directional step in degrees. Defaults to 5.

• sample (2-dimensional ndarray, optional) – Monte Carlo simulated environmental states. Array is of shape (n, d) with d being the number of variables and n being the number of observations.

• allowed_error (float, optional) – Required precision for the alpha value. For example 0.1 means that the algorithm searches along the path until the probability of exceedance at the current point p_e satisfies | p_e - alpha | / alpha < 0.1. Defaults to 0.01.

coordinates

Coordinates of the calculated contour. Shape: (number of points, number of dimensions).

Type:

ndarray

References

[7]

Mazas, F. (2019). Extreme events: a framework for assessing natural hazards. Natural Hazards. https://doi.org/10.1007/s11069-019-03581-9

class virocon.contours.DirectSamplingContour(model, alpha, n=None, deg_step=5, sample=None)

Bases: Contour

Direct sampling contour as introduced by Huseby et al. (2013) [6] The provided direct sampling contour method only works for 2D models.

Parameters:

• model (MultivariateModel) – The model to be used to calculate the contour.

• alpha (float) – The exceedance probability. The probability that an observation falls outside the environmental contour.

• n (int, optional) – Number of data points that shall be Monte Carlo simulated. Defaults to None, which calculates n based on alpha: n = int(100 / alpha).

• deg_step (float, optional) – Directional step in degrees. Defaults to 5.

• sample (2-dimensional ndarray, optional) – Monte Carlo simulated environmental states. Array is of shape (n, d) with d being the number of variables and n being the number of observations.

coordinates

Coordinates of the calculated contour. Shape: (number of points, number of dimensions).

Type:

ndarray

References

[6]

Huseby, A.B.; Vanem, E.; Natvig, B. (2013) A new approach to environmental contours for ocean engineering applications based on direct Monte Carlo simulations, Ocean Engineering, Volume 60. DOI: doi.org/10.1016/j.oceaneng.2012.12.034

class virocon.contours.HighestDensityContour(model, alpha, limits=None, deltas=None)

Bases: Contour

Contour based on the highest density method.

This method was proposed by Haselsteiner et. al (2017) [5]

Parameters:

• model (MultivariateModel) – The model to be used to calculate the contour.

• alpha (float) – The exceedance probability. The probability that an observation falls outside the environmental contour.

• limits (list of tuples, optional) – The limits of the grid to use for calculation. One 2-element tuple for each dimension of the model, containing the minimum and maximum for that dimension. (min, max). If not given, reasonable values are choosen using the models marginal_icdf as upper limit and 0 as lower limit.

• deltas (float or list of float, optional) – The step size of the grid to use for calculation. If a single float is supplied it is used for all dimensions. If a list is supplied there has to be one entry for each dimension of the model. Defaults to 0.25% of the range defined by limits.

coordinates

Coordinates of the calculated contour. Shape: (number of points, number of dimensions).

Type:

ndarray

cell_center_coordinates

Points at which the grid is evaluated. A list with one entry for each dimension, each entry is an array with the cell centers for that dimension.

Type:

list of array

fm

Minimum probability density of the enclosed region / constant probability density along the contour.

Type:

float

References

[5]

Haselsteiner, A.F.; Ohlendorf, J.H.; Wosniok, W.; Thoben, K.D. (2017) Deriving environmental contours from highest density regions, Coastal Engineering, Volume 123. DOI: 10.1016/j.coastaleng.2017.03.002.

cell_averaged_joint_pdf(coords)

Calculates the cell averaged joint probabilty density function.

Multiplies the cell averaged probability densities of all distributions.

Parameters:

coords (list of array) – List with one coordinate array for each dimension.

Returns:

fbar – Joint cell averaged probability density function evaluated at coords. Cell averaged probability density function evaluated at coords. n dimensional array, where n is the number of dimensions of the model used for calculation.

Return type:

array

cell_averaged_pdf(dist_idx, coords)

Calculates the cell averaged probabilty density function of a single distribution.

Calculates the pdf by approximating it with the finite differential quotient of the cumulative distributions function, evaluated at the grid cells borders. i.e. \(f(x) \approx \frac{F(x+ 0.5\Delta x) - F(x- 0.5\Delta x) }{\Delta x}\)

Parameters:

• dist_idx (int) – The index of the distribution to calcululate the pdf for.

• coords (list of array) – List with one coordinate array for each dimension.

Returns:

fbar – Cell averaged probability density function evaluated at coords. n dimensional array, where n is the number of dimensions of the model used for calculation. All dimensions but, the dist_idx and the cond_idx dimensions are of length 1. The dist_idx and cond_idx dimensions are of length equal to the length of coords.

Return type:

array

static cumsum_biggest_until(array, limit)

Find biggest elements to sum to reach limit.

Sorts array, and calculates the cumulative sum. Returns a boolean array with the same shape as array indicating the fields summed to reach limit, as well as the last value added.

Parameters:

• array (ndarray) – Array of arbitrary shape with all values >= 0.

• limit (float) – Value to sum up to.

Returns:

• summed_fields (ndarray, dtype=Bool) – Boolean array of shape like array with True if element was used in summation.

• last_summed (float) – Element that was added last to the sum.

Raises:

ValueError – If array contains nan.

Notes

A RuntimeWarning is raised if the limit cannot be reached by summing all values.

class virocon.contours.IFORMContour(model, alpha, n_points=180)

Bases: Contour

Contour based on the inverse first-order reliability method.

This method was proposed by Winterstein et. al (1993) [3]

Parameters:

• model (MultivariateModel | TransformedModel) – The model to be used to calculate the contour.

• alpha (float) – The exceedance probability. The probability that an observation falls outside the environmental contour.

• n_points (int, optional) – Number of points on the contour. Defaults to 180.

coordinates

Coordinates of the calculated contour.

beta

Reliability index.

sphere_points

Points of the sphere in U space [3] .

References

[3] (1,2)

Winterstein, S.R.; Ude, T.C.; Cornell, C.A.; Bjerager, P.; Haver, S. (1993) Environmental parameters for extreme response: Inverse FORM with omission factors. ICOSSAR 93, Innsbruck, Austria.

class virocon.contours.ISORMContour(model, alpha, n_points=180)

Bases: Contour

Contour based on the inverse second-order reliability method.

This method was proposed by Chai and Leira (2018) [4]

Parameters:

• model (MultivariateModel) – The model to be used to calculate the contour.

• alpha (float) – The exceedance probability. The probability that an observation falls outside the environmental contour.

• n_points (int, optional) – Number of points on the contour. Defaults to 180.

coordinates

Coordinates of the calculated contour.

beta

Reliability index.

sphere_points

Points of the sphere in U space [4] .

References

[4] (1,2)

Chai, W.; Leira, B.J. (2018) Environmental contours based on inverse SORM. Marine Structures Volume 60, pp. 34-51. DOI: 10.1016/j.marstruc.2018.03.007 .

class virocon.contours.OrContour(model, alpha, n=None, deg_step=3, sample=None, allowed_error=0.01, lowest_theta=10, highest_theta=80)

Bases: Contour

A contour that connects points of constant OR exceedance. Such type of multivariate exceedance is described, for example, in Serinaldi (2015) [8]. This implementation uses Monte Carlo simulation and only works for 2D models.

Parameters:

• model (MultivariateModel) – The model to be used to calculate the contour.

• alpha (float) – The exceedance probability. The probability that an observation falls outside the environmental contour.

• n (int, optional) – Number of data points that shall be Monte Carlo simulated. Defaults to None, which calculates n based on alpha: n = int(100 / alpha).

• deg_step (float, optional) – Directional step in degrees. Defaults to 5.

• sample (2-dimensional ndarray, optional) – Monte Carlo simulated environmental states. Array is of shape (n, d) with d being the number of variables and n being the number of observations.

• allowed_error (float, optional) – Required precision for the alpha value. For example 0.1 means that the algorithm searches along the path until the probability of exceedance at the current point p_e satisfies | p_e - alpha | / alpha < 0.1. Defaults to 0.01.

• lowest_theta (float, optional) – Lowest angle considered in the calculation of the contour. Given in deg. Defaults to 10.

• highest_theta (float, otptional) – Highest angle considered in the calculation of the contour. Given in deg. Defaults to 80.

coordinates

Coordinates of the calculated contour. Shape: (number of points, number of dimensions).

Type:

ndarray

References

[8]

Serinaldi, F. (2015). Dismissing return periods! Stochastic Environmental Research and Risk Assessment, 29(4), 1179–1189. https://doi.org/10.1007/s00477-014-0916-1

virocon.contours.calculate_alpha(state_duration, return_period)

Calculates the probability that an environmental contour is exceeded (exceedance probability).

The exceedance probability, α, corresponds to a certain recurrence or return period, T, which describes the average time period between two consecutive environmental states that exceed the contour . Note that exceedance can be defined in various ways for environmental contours (Mackay and Haselsteiner, 2021) [1]

Parameters:

• state_duration (float) – Time period for which an environmental state is measured, expressed in hours \((T_s)\).

• return_period (float) – Describes the average time period between two consecutive environmental states that exceed a contour.

Returns:

alpha – The probability that an environmental contour is exceeded.

Return type:

float

References

[1]

Mackay, E., & Haselsteiner, A. F. (2021). Marginal and total exceedance probabilities of environmental contours. Marine Structures, 75. https://doi.org/10.1016/j.marstruc.2020.102863

virocon.contours.save_contour_coordinates(contour, file_path, semantics=None)

Saves the coordinates of the calculated contour. Saves a .txt file to the given path.

Parameters:

• contour (Contour) – The contour with the coordinates to save.

• file_path (string) – Indicates the path, where the contour coordinates are saved.

• semantics (dictionary) – The description of the model. semantics has the keys ‘names’, ‘symbols’ and ‘units’. Each value is a list of strings. For each dimension of the model the strings describe the name, symbol or unit of that dimension, respectively. This information is used as the header of the created file. Defaults to a dict with general descriptions.