virocon.contours module¶
- class virocon.contours.AndContour(model, alpha, n=None, deg_step=3, sample=None, allowed_error=0.01)[source]¶
Bases:
virocon.contours.Contour
A contour that connects points of constant AND exceedance. Such contours are described, for example, in Mazas (2019) [1]_. 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
- 1
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)[source]¶
Bases:
virocon.contours.Contour
Direct sampling contour as introduced by Huseby et al. (2013) [1]_ 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
- 1
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)[source]¶
Bases:
virocon.contours.Contour
Contour based on the highest density method.
This method was proposed by Haselsteiner et. al (2017) [1]_
- 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
References
- 1
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Bases:
virocon.contours.Contour
Contour based on the inverse first-order reliability method.
This method was proposed by Winterstein et. al (1993) [1]_
- Parameters
- coordinates¶
Coordinates of the calculated contour.
- beta¶
Reliability index.
References
- 1
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)[source]¶
Bases:
virocon.contours.Contour
Contour based on the inverse second-order reliability method.
This method was proposed by Chai and Leira (2018) [1]_
- Parameters
- coordinates¶
Coordinates of the calculated contour.
- beta¶
Reliability index.
References
- 1
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)[source]¶
Bases:
virocon.contours.Contour
A contour that connects points of constant OR exceedance. Such type of multivariate exceedance is described, for example, in Serinaldi (2015) [1]_. 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
- 1
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)[source]¶
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. In the univariate case the contour is a threshold, x1.
\(\alpha= \frac{T_s}{T_r * 365.25 * 24}\)
\(F(x_1) = P(X_1 \geq x_1)= \int_{- \infty}^{x_1} f(x) dx = 1- \alpha\)
- Returns
alpha – The probability that an environmental contour is exceeded.
- Return type
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)[source]¶
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.