Toolbox Modules¶

The following sections contain the documentation for WDRT. Note that this documentation is also contained in the python source code. As such, documentation for any WDRT function or class can also be accessed in iPython via by calling

>>> help(<wdrt class or module>)

WDRT.fatigue module¶

This module contains tools used to calculate the fatigue load.

WDRT.fatigue.EqLoad(F, N, m)[source]¶

Calculates an equivalent fatigue load based on Miner’s Rule, using the rainflow counting method presented in, Downing & Socie, 1982, “Simple rainflow counting algorithms”

Parameters

F ((np.array)) – Force or stress history
N ((float)) – Number of lifetime cycles
m ((float)) – S-N curve slope

Returns

Feq – Equivalent force or stress

Return type

(float)

WDRT.shortTermExtreme module¶

This module contains tools for analysis of short-term (sea-state specific) extremes, as well as some usefull statistical methods.

class WDRT.shortTermExtreme.ecmDist(x, pdf=None, cdf=None)[source]¶

Bases: object

Class for extreme response distributions.

Class provides basic functionality for statistical distributions as needed for extreme value analysis. Can be initialized via either PDF or CDF.

Note: For pdf, cdf, and ppf toggle ecmDist.{function}.bounds_error to give an error or a NaN if input is outside of bounds(x).

pdf¶

Probability density function

Type: scipy.interpolate.interpolate.interp1d

cdf¶

Cumulative distribution function

Type: scipy.interpolate.interpolate.interp1d

ppf¶

Percent point function (inverse cdf)

Type: scipy.interpolate.interpolate.interp1d

getExpVal[source]¶

Expected value of distribution

Type: method

gerRthValue¶

Rth percentile value of distribution

Type: method

Class initialization function

Parameters

x (np.array) – Response variable
pdf (np.array) – Probability density function for x
cdf (np.array) – Cumulative distribution function (a.k.a. distribution function) for x

Example

To create an ecmDist object, you can use either the PDF:

>>> myDist1 = ste.ecmDist(x=my_x, pdf=my_PDF)

or the CDF:

>>> myDist2 = ste.ecmDist(x=my_x, cdf=my_CDF)

getExpVal()[source]¶

Expected value from ecmDist.

Finds expected value (mean) from distribution.

Returns: ev – Expected value (mean)
Return type: float

Example

In order to find the expected value from the distribution

>>> vExp = myDist.getExpVal()

getRthVal(r)[source]¶

Rth percentile value from ecmDist.

Finds value of cumulative distribution function for a given percentile.

Parameters: r (float) – Target percentile (0 < r < 1)
Returns: xr – Response for rth percentile
Return type: float

Example

In order to find the 95th percentile value from the distribution:

>>> v95 = myDist.getRthVal(r=0.95)

WDRT.shortTermExtreme.blockMaxima(x, t, t_st)[source]¶

Finds the block maxima of a time-series.

Parameters

x (np.array) – Independent random variable (global peaks)
t (np.array) – Time vector corresponding to x
t_st (float) – Short-term period

Returns

block_maxima – Block maxima (i.e. largest peak in each block)

Return type

np.array

WDRT.shortTermExtreme.cdf2pdf(x, cdf)[source]¶

Calculates a probability density function from the cumulative distribution function via numerical differentiation.

Parameters

x (np.array) – Response variable
cdf (np.array) – Cumulative distribution function values at x

Returns

pdf – Probability density function values at x

Return type

np.array

WDRT.shortTermExtreme.compare_methods(x, t, t_st, methods=[1, 2, 3, 4, 5], colors=['g', 'b', 'r', 'k', 'k'], lines=['-', '-', '-', '-', '--'])[source]¶

Compares the results obtained using different methods to approximate the short-term extreme distribution. The methods are: 1 - All peaks Weibull, 2 - Weibull tail fit, 3 - Peaks over threshold, 4 - Block maxima GEV, 5 - Block maxima Gumbel,

Parameters

x (np.array) – Independent random variable (global peaks)
t (np.array) – Time vector corresponding to x
t_st (float) – Short-term period
methods (list) – List of methods to be compared. Options are any combination of: 1, 2, 3, 4,and 5
colors (list) – Strings defining the color used to plot each method
lines (list) – Strings defining the lines used to plot each method

Returns

fig1 (matplotlib.pyplot figure) – Figure containing the comparison of peaks distribution.
fig2 (matplotlib.pyplot figure) – Figure containing the comparison of short-term extreme distribution
expected_value_of_short_term_extreme (dictionary) – Expected value of the short-term extreme distribution from each method

WDRT.shortTermExtreme.empiricalCdf(x, m=0)[source]¶

Returns an empirical cumulative distribution function.

Parameters

x (np.array) – Response variable
m (float) – Number of points below min(x). Use if x consists of only values above a certain minimum and CDF for entire population wanted.

Returns

x_cdf (np.array) – x locations
cdf (np.array) – CDF values at x_cdf

WDRT.shortTermExtreme.empiricalPdf(x, bins, m=0)[source]¶

Returns an empirical probability density function.

Parameters

x (np.array) – Response variable
bins (int) – Number of bins
m (float) – Number of points below min(x). Use if x consists of only values above a certain minimum and PDF for entire population wanted.

Returns

x_pdf (np.array) – Bin (x) locations
pdf (np.array) – PDF values at x_pdf

WDRT.shortTermExtreme.extremeDistribution_Weibull(x, x_e, t_x, t_st, locFlag=0)[source]¶

Approximates the short-term extreme distribution using the all peaks Weibull method.

Parameters

x (np.array) – Independent random variable (global peaks)
x_e (np.array) – Array of x values at which to evaluate the short-term extreme CDF
t_x (float) – Time length of the x array
t_st (float) – Short-term period
locFlag (boolean) – locFlag = 0: Location parameter of Weibull distribution is forced to zero locFlag = 1: Location parameter of Weibull distribution is calculated in fit

Returns

stextreme_dist (ecmDist object) – Probability distribution of the short-term extreme.
stextreme_dist (ecmDist object) – Probability distribution of the short-term extreme.
peaks_dist (scipy.stats rv_frozen) – Probability distribution of the peaks.
peaks_params (np.array length 4) – Parameters of peak’s distribution (Weibull) [shape_a, shape_c, loc, scale].

WDRT.shortTermExtreme.extremeDistribution_WeibullTailFit(x, x_e, t_x, t_st, avg=0, p0=None)[source]¶

Approximates the short-term extreme distribution using the Weibull tail fit method.

Parameters

x (np.array) – Independent random variable (global peaks)
x_e (np.array) – Array of x values at which to evaluate the short-term extreme CDF
t_x (float) – Time length of the x array
t_st (float) – Short-term period
avg (float) – The average of the time response, if this was substracted before identifying global peaks. Else it is assumed that the average is zero.
p0 (list length 2: [float, float]) – Initial guess for the Weibull parameters [shape, scale]

Returns

stextreme_dist (ecmDist object) – Probability distribution of the short-term extreme.
stextreme_dist (ecmDist object) – Probability distribution of the short-term extreme.
peaks_dist (scipy.stats rv_frozen) – Probability distribution of the peaks.
subset_shape_params (np.array length 7) – Shape parameter for each of the seven Weibull fits for the subsets of data corresponding to F>[0.65,0.7,…,0.95].
subset_scale_params (np.array length 7) – Scale parameter for each of the seven Weibull fits for the subsets of data corresponding to F>[0.65,0.7,…,0.95].
peaks_params (np.array length 4) – Parameters of peak’s distribution (Weibull) [shape_a, shape_c, loc, scale].

WDRT.shortTermExtreme.extremeDistribution_blockMaximaGEV(x, t, t_st)[source]¶

Approximates the short-term extreme distribution using the block maxima method and the Generalized Extreme Value distribution.

Parameters

x (np.array) – Independent random variable (global peaks)
t (np.array) – Time vector corresponding to x
t_st (float) – Short-term period

Returns

stextreme_dist (scipy.stats rv_frozen) – Probability distribution of the short-term extreme.
stextreme_dist (scipy.stats rv_frozen) – Probability distribution of the short-term extreme.
ste_params (np.array length 3) – Parameters of the short term extreme distribution (Generalized Extreme Value) [shape_c, loc, scale].
block_maxima (np.array) – Block maxima (i.e. largest peak in each block).

WDRT.shortTermExtreme.extremeDistribution_blockMaximaGumb(x, t, t_st)[source]¶

Approximates the short-term extreme distribution using the block maxima method and the Gumbel (right) distribution.

Parameters

x (np.array) – Independent random variable (global peaks)
t (np.array) – Time vector corresponding to x
t_st (float) – Short-term period

Returns

stextreme_dist (scipy.stats rv_frozen) – Probability distribution of the short-term extreme.
stextreme_dist (scipy.stats rv_frozen) – Probability distribution of the short-term extreme.
ste_params (np.array length 2) – Parameters of the short term extreme distribution (Gumbel_r) [loc, scale].
block_maxima (np.array) – Block maxima (i.e. largest peak in each block).

WDRT.shortTermExtreme.extremeDistribution_peaksOverThreshold(x, x_e, t_x, t_st, u)[source]¶

Approximates the short-term extreme distribution using the peaks over threshold method.

Parameters

x (np.array) – Independent random variable (global peaks)
x_e (np.array) – Array of x values at which to evaluate the short-term extreme CDF
t_x (float) – Time length of the x array
t_st (float) – Short-term period
u (float) – Threshold below which peaks (x) are ignored

Returns

stextreme_dist (ecmDist object) – Probability distribution of the short-term extreme.
stextreme_dist (ecmDist object) – Probability distribution of the short-term extreme.
peaks_dist (ecmDist object) – Probability distribution of the peaks.
peaksOverThreshold_dist (scipy.stats rv_frozen) – Probaility distribution of the peaks over threshold.
pot_params (np.array length 3) – Parameters of peak over threshold’s distribution using Generalized Pareto[shape_c, loc, scale].

WDRT.shortTermExtreme.globalPeaks(t, data)[source]¶

Finds the global peaks (maxima between consecutive zero up-crossings) of a zero-centered response time-series

Parameters

t (np.array) – Time vector
data (np.array) – Response time-series

Returns

t_peaks (np.array) – Time vector for peaks
peaks (np.array) – Peaks of the response time-series

WDRT.shortTermExtreme.goodnessOfFitPlots(data, prob_func, x_pdf, bins_pdf=20, np_return=100001, m_prob=0.0, response_name='Response', response_name_2='Peaks', response_units='Response Units')[source]¶

Creates plots showing the goodness of fit of a probability model to the actual data. The four subplots are: the probability plot, the quantile plot, the return level plot, and probability density function (PDF) plot.

Parameters

data (np.array) – Data which the probability model represents
prob_func ({scipy.stats rv_frozen} or {ecmDist object}) – Probability function that models the data.
x_pdf (np.array) – Array of x values at which to evaluate the PDF.
bins_pdf (int) – Number of bins to use for the PDF plot.
np_return (int) – Number of points to use in the return level plot.
m_prob (float) – Number of points below min(data). Use if data consists of only values above a certain minimum and goodness of fit plots for entire population wanted.

Returns

fgof – Figure containing the four goodness of fit subplots.

Return type

matplotlib.pyplot figure

WDRT.shortTermExtreme.loadtxt(filename, delimiter='ws')[source]¶

Loads data from a ASCII file. First line is header with same delimiter as data, followed by data.

Parameters

filename (str) – Filename
delimiter (str) – Data delimiter. Default ‘ws’ for whitespace, use ‘,’ for CSV files.

Returns

data –

Data as a dictionary:

keys: str: Header name for each column.
values: np.array: Column data

Return type

dictionary

WDRT.shortTermExtreme.pdf2cdf(x, pdf)[source]¶

Calculates a cumulative distribution function from the probability density function via numerical integration.

Parameters

x (np.array) – Response variable
pdf (np.array) – Probability density function values at x

Returns

cdf – Cumulative distribution function values at x

Return type

np.array

WDRT.longTermExtreme module¶

This module contains tools for analysis of long-term extremes.

class WDRT.longTermExtreme.fullLongTermSurvival(Fr, fs)[source]¶

Bases: object

Class for full sea state long-term approach

Parameters

Fr (list) – List where each element is a CCDF for a given sea state.
fs (list) – Weighting for each sea state.

WDRT.ESSC module¶

The Extreme Sea State Contour (ESSC) module contains the tools necessary to calculate environmental contours of extreme sea states for buoy data.

class WDRT.ESSC.BivariateKDE(buoy, bw, NData=100, logTransform=False, max_T=None, max_Hs=None)[source]¶

Bases: WDRT.ESSC.EA

Create a BivariateKDE EA class for a buoy object. Contours generated under this class will use a non-parametric KDE to fit the joint distribution.

Parameters

buoy (NDBCData) – ESSC.Buoy Object
bw (np.array) – Array containing KDE bandwidth for Hs and T
NData (int) – Discretization resolution used in KDE construction
logTransform (Boolean) – Logical. True if log transformation should be taken prior to KDE construction. Default value is False.
max_T (float) – Maximum T value for KDE contstruction, must include possible range of contour. Default value is 2*max(T)
max_Hs (float) – Maximum Hs value for KDE contstruction, must include possible range of contour. Default value is 2*max(Hs)

getContours(time_ss, time_r)[source]¶

WDRT Extreme Sea State non-parameteric bivariate KDE Contour function. This function calculates environmental contours of extreme sea states using a bivariate KDE to estimate the joint distribution. The contour is then calculcated directly from the joint distribution.

Parameters

time_ss (float) – Sea state duration (hours) of measurements in input.
time_r (np.array) – Desired return period (years) for calculation of environmental contour, can be a scalar or a vector.

Returns

Hs_Return (np.array) – Calculated Hs values along the contour boundary following return to original input orientation.
T_Return (np.array) – Calculated T values along the contour boundary following return to original input orientation.

Example

To obtain the contours for a NDBC buoy:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website
buoy46022 = ESSC.Buoy('46022','NDBC')
buoy46022.fetchFromWeb()

# Create Environmental Analysis object using above parameters
BivariateKDE46022 = ESSC.BivariateKDE(buoy46022, bw = [0.23,0.19], logTransform = False)

# Declare required parameters
Time_SS = 1.  # Sea state duration (hrs)
Time_r = 100  # Return periods (yrs) of interest

# KDE contour generation example
Hs_Return, T_Return = BivariateKDE46022.getContours(Time_SS, Time_r)

class WDRT.ESSC.Buoy(buoyNum, buoyType)[source]¶

Bases: object

This class creates a buoy object to store buoy data for use in the environmental assessment functions available in the ESSC module.

swdList¶

List that contains numpy arrays of the spectral wave density data, separated by year.

Type: list

freqList¶

List that contains numpy arrays that contain the frequency values for each year

Type: list

dateList¶

List that contains numpy arrays of the date values for each line of spectral data, separated by year

Type: list

Hs¶

Significant wave height.

Type: list

T¶

Energy period.

Type: list

dateNum¶

List of datetime objects.

Type: list

Parameters

buoyNum (string) – device number for desired buoy
buoyType (string) – type of buoy device, available options are ‘NDBC’ or ‘CDIP’
savePath (string) – relative path where the data read from ndbc.noaa.gov will be stored

createSubsetBuoy(trainingSize)[source]¶

Takes a given buoy and creates a subset buoy of a given length in years.

Parameters: trainingSize (int) – The size in years of the subset buoy you would like to create
Returns: # subsetBuoy – A buoy (with Hs, T, and dateList values) that is a subset of the given buoy
Return type: ESSC.Buoy object

Example

To get a corresponding subset of a buoy with a given number of years:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website buoy46022 = ESSC.Buoy(‘46022’,’NDBC’) buoy46022.fetchFromWeb()

# Create a subset of buoy 46022 consisting of the first 10 years subsetBuoy = buoy46022.createSubsetBuoy(10)

fetchFromWeb(savePath='./Data/', proxy=None)[source]¶

Calls either __fetchCDIP() or __fetchNDBC() depending on the given buoy’s type and fetches the necessary data from its respective website.

Parameters

saveType (string) – If set to to “h5”, the data will be saved in a compressed .h5 file If set to “txt”, the data will be stored in a raw .txt file Otherwise, a file will not be created NOTE: Only applies
savePath (string) – Relative path to place directory with data files.
proxy (dict) – Proxy server and port, i.e., {http”:”http://proxyserver:port”}

Example

>>> import WDRT.ESSC as ESSC
>>> buoy = ESSC.Buoy('46022','NDBC')
>>> buoy.fetchFromWeb()

loadCDIP(filePath=None)[source]¶: Loads the Hs and T values of the given site from the .nc file downloaded from http://cdip.ucsd.edu/ :param filePath: File path to the respective .nc file containing the Hs and T values :type filePath: string

loadFile(dirPath=None)[source]¶: Loads file depending on whether it’s NDBC or CDIP.

loadFromH5(fileName=None)[source]¶

Loads NDBC data previously saved in a .h5 file

Parameters: fileName (string) – Name of the .h5 file to load data from.

Example

To load data from previously downloaded files:

import WDRT.ESSC as ESSC buoy46022 = ESSC.Buoy(‘46022’,’NDBC’) buoy46022.fetchFromWeb() buoy46022.saveData() buoy46022.loadFromH5(‘NDBC46022.h5’)

loadFromTxt(dirPath=None)[source]¶

Loads NDBC data previously downloaded to a series of text files in the specified directory.

Parameters: dirPath (string) – Relative path to directory containing NDBC text files (created by NBDCdata.fetchFromWeb). If left blank, the method will search all directories for the data using the current directory as the root.

Example

To load data from previously downloaded files created using fetchFromWeb():

import WDRT.ESSC as ESSC buoy46022 = ESSC.Buoy(‘46022’,’NDBC’) buoy46022.loadFromText()

saveAsH5(fileName=None)[source]¶

Saves NDBC buoy data to h5 file after fetchFromWeb() or loadFromText(). This data can later be used to create a buoy object using the loadFromH5() function.

Parameters: fileName (string) – relevent path and filename where the .h5 file will be created and saved. If no filename, the h5 file will be named NDBC(buoyNum).h5 in location where code is running.

Example

To save data to h5 file after fetchFromWeb or loadFromText:

import WDRT.ESSC as ESSC buoy46022 = ESSC.Buoy(‘46022’,’NDBC’) buoy46022.fetchFromWeb() buoy46022.saveAsH5()

saveAsTxt(savePath='./Data/')[source]¶

Saves spectral wave density data to a .txt file in the same format as the files found on NDBC’s website.

Parameters: savePath (string) – Relative file path where the .txt files will be saved.

Example

To save data to h5 file after fetchFromWeb or loadFromText:

import WDRT.ESSC as ESSC buoy46022 = ESSC.Buoy(‘46022’,’NDBC’) buoy46022.fetchFromWeb() buoy46022.saveAsTxt()

class WDRT.ESSC.ClaytonCopula(buoy, n_size=40.0, bin_1_limit=1.0, bin_step=0.25)[source]¶

Bases: WDRT.ESSC.EA

Create a ClaytonCopula EA class for a buoy object. Contours generated under this class will use a Clayton copula.

Parameters

buoy (NDBCData) – ESSC.Buoy Object
n_size (float) – minimum bin size used for Copula contour methods
bin_1_limit (float) – maximum value of Hs for the first bin
bin_step (float) – overlap interval for each bin

getContours(time_ss, time_r, nb_steps=1000)[source]¶

WDRT Extreme Sea State Clayton Copula Contour function. This function calculates environmental contours of extreme sea states using a Clayton copula and the inverse first-order reliability method.

Parameters

time_ss (float) – Sea state duration (hours) of measurements in input.
time_r (np.array) – Desired return period (years) for calculation of environmental contour, can be a scalar or a vector.
nb_steps (float) – Discretization of the circle in the normal space used for inverse FORM calculation.

Returns

Hs_Return (np.array) – Calculated Hs values along the contour boundary following return to original input orientation.
T_Return (np.array) – Calculated T values along the contour boundary following return to original input orientation.
nb_steps (float) – Discretization of the circle in the normal space

Example

To obtain the contours for a NDBC buoy:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website
buoy46022 = ESSC.Buoy('46022','NDBC')
buoy46022.fetchFromWeb()

# Create Environtmal Analysis object using above parameters
Clayton46022 = ESSC.ClaytonCopula(buoy46022)

# Declare required parameters
Time_SS = 1.  # Sea state duration (hrs)
Time_r = 100  # Return periods (yrs) of interest
nb_steps = 1000  # Enter discretization of the circle in the normal space (optional)

# Clayton copula contour generation example
Hs_Return, T_Return = Clayton46022.getContours(Time_SS, Time_r,nb_steps)

getSamples()[source]¶: Currently not implemented in this version

class WDRT.ESSC.EA[source]¶

Bases: object

The Environmental Assessment (EA) class points to functions for various contour methods (including getContours and getSamples) and allows the user to plot results (plotData), sample along the contour (getContourPoints), calculate the wave breaking steepness curve (steepness) and/or use the bootstrap method to calculate 95% confidence bounds about the contours (bootStrap).

bootStrap(boot_size=1000, plotResults=True)[source]¶

Get 95% confidence bounds about a contour using the bootstrap method. Warning - this function is time consuming. Computation time depends on selected boot_size.

Parameters

boot_size (int (optional)) – Number of bootstrap samples that will be used to calculate 95% confidence interval. Should be large enough to calculate stable statistics. If left blank will be set to 1000.
plotResults (boolean (optional)) – Option for showing plot of bootstrap confidence bounds. If left blank will be set to True and plot will be shown.

Returns

contourmean_Hs (nparray) – Hs values for mean contour calculated as the average over all bootstrap contours.
contourmean_T (nparray) – T values for mean contour calculated as the average over all bootstrap contours.

Example

To generate 95% boostrap contours for a given contour method:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website buoy46022 = ESSC.Buoy(‘46022’,’NDBC’) buoy46022.fetchFromWeb()

# Create PCA EA object for buoy pca46022 = ESSC.PCA(buoy46022)

# Declare required parameters Time_SS = 1. # Sea state duration (hrs) Time_r = 100 # Return periods (yrs) of interest nb_steps = 1000 # Enter discretization of the circle in the normal space (optional)

# Contour generation Hs_Return, T_Return = pca46022.getContours(Time_SS, Time_r,nb_steps)

# Calculate boostrap confidence interval contourmean_Hs, contourmean_T = pca46022.bootStrap(boot_size=10)

contourIntegrator()[source]¶

Calculates the area of the contour over the two-dimensional input space of interest.

Parameters: None –
Returns: area – The area of the contour in TxHs units.
Return type: float

Example

To obtain the area of the contour:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website buoy46022 = ESSC.Buoy(‘46022’,’NDBC’) buoy46022.fetchFromWeb()

# Create PCA EA object for buoy rosen46022 = ESSC.Rosenblatt(buoy46022)

# Declare required parameters Time_SS = 1. # Sea state duration (hrs) Time_r = 100 # Return periods (yrs) of interest

# Generate contour Hs_Return, T_Return = rosen46022.getContours(Time_SS, Time_r)

# Return the area of the contour rosenArea = rosen46022.contourIntegrator()

dataContour(tStepSize=1, hsStepSize=0.5)[source]¶

Creates a contour around the ordered pairs of buoy observations. How tightly: the contour fits around the data will be determined by step size parameters. Please note that this function currently is in beta; it needs further work to be optimized for use.

Parameters

tStepSize (float) – Determines how far to search for the next point in the T direction. Smaller values will produce contours that follow the data more closely.
hsStepSize (float) – Determines how far to search for the next point in the Hs direction. Smaller values will produce contours that follow the data more closely.

Returns

dataBoundryHs (nparray) – The Hs values of the boundry observations
dataBoundryT (nparray) – The Hs values of the boundry observations

Example

To get the corresponding data contour:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website buoy46022 = ESSC.Buoy(‘46022’,’NDBC’) buoy46022.fetchFromWeb()

# Create PCA EA object for buoy rosen46022 = ESSC.Rosenblatt(buoy46022)

# Calculate the data contour dataHs, dataT = rosen46022.dataContour(tStepSize = 1, hsStepSize = .5)

getContourPoints(T_Sample)[source]¶

Get Hs points along a specified environmental contour using user-defined T values.

Parameters: T_Sample (nparray) – points for sampling along return contour
Returns: Hs_SampleCA – points sampled along return contour
Return type: nparray

Example

To calculate Hs values along the contour at specific user-defined T values:

import WDRT.ESSC as ESSC import numpy as np

# Pull spectral data from NDBC website buoy46022 = ESSC.Buoy(‘46022’,’NDBC’) buoy46022.fetchFromWeb()

# Create PCA EA object for buoy pca46022 = ESSC.PCA(buoy46022)

# Declare required parameters Time_SS = 1. # Sea state duration (hrs) Time_r = 100 # Return periods (yrs) of interest nb_steps = 1000 # Enter discretization of the circle in the normal space (optional)

# Generate contour Hs_Return, T_Return = pca46022.getContours(Time_SS, Time_r,nb_steps)

# Use getContourPoints to find specific points along the contour T_sampleCA = np.arange(12, 26, 2) Hs_sampleCA = pca46022.getContourPoints(T_sampleCA)

getContours()[source]¶: Points to the getContours function in whatever contouring method is used

getSamples()[source]¶: Points to the getSamples function in whatever contouring method is used, currently only implemented for PCA contours. Implementation for additional contour methods planned for future release.

outsidePoints()[source]¶

Determines which buoy observations are outside of a given contour.

Parameters

None –

Returns

outsideHs (nparray) – The Hs values of the observations that are outside of the contour
outsideT (nparray) – The T values of the observations that are outside of the contour

Example

To get correseponding T and Hs arrays of observations that are outside of a given contour:

import WDRT.ESSC as ESSC import numpy as np

# Pull spectral data from NDBC website buoy46022 = ESSC.Buoy(‘46022’,’NDBC’) buoy46022.fetchFromWeb()

# Create PCA EA object for buoy rosen46022 = ESSC.Rosenblatt(buoy46022)

# Declare required parameters Time_SS = 1. # Sea state duration (hrs) Time_r = 100 # Return periods (yrs) of interest

# Generate contour Hs_Return, T_Return = rosen46022.getContours(Time_SS, Time_r)

# Return the outside point Hs/T combinations outsideT, outsideHs = rosen46022.outsidePoints()

plotData()[source]¶: Display a plot of the 100-year return contour, full sea state samples and contour samples

saveContour(fileName=None)[source]¶

Saves all available contour data obtained via the EA module to a .h5 file

Parameters: fileName (string) – relevent path and filename where the .h5 file will be created and saved. If no filename, the h5 file will be named NDBC(buoyNum).h5

steepness(SteepMax, T_vals, depth=None)[source]¶

This function calculates a steepness curve to be plotted on an H vs. T diagram. First, the function calculates the wavelength based on the depth and T. The T vector can be the input data vector, or will be created below to cover the span of possible T values. The function solves the dispersion relation for water waves using the Newton-Raphson method. All outputs are solved for exactly using: \(hw^2/g = kh*tanh(khG)\)

Approximations that could be used in place of this code for deep and shallow water, as appropriate:

deep water: \(h/\lambda \geq 1/2, tanh(kh) \sim 1, \lambda = (gT^2)/(2\pi)\)

shallow water: \(h/\lambda \leq 1/20, tanh(kh) \sim kh, \lambda = \sqrt{T(gh)}\)

Parameters

SteepMax (float) – Wave breaking steepness estimate (e.g., 0.07).
T_vals (np.array) – Array of T values [sec] at which to calculate the breaking height.
depth (float) – Depth at site Note: if not inputted, the depth will tried to be grabbed from the respective buoy type’s website.

Returns

SteepH (np.array) – H values [m] that correspond to the T_mesh values creating the steepness curve.
T_steep (np.array) – T values [sec] over which the steepness curve is defined.

Example

To find limit the steepness of waves on a contour by breaking:

import numpy as np import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website buoy46022 = ESSC.Buoy(‘46022’,’NDBC’) buoy46022.fetchFromWeb()

# Create PCA EA object for buoy pca46022 = ESSC.PCA(buoy46022)

T_vals = np.arange(0.1, np.amax(buoy46022.T), 0.1) # Enter estimate of breaking steepness SteepMax = 0.07 # Reference DNV-RP-C205

# Declare required parameters depth = 391.4 # Depth at measurement point (m)

SteepH = pca46022.steepness(depth,SteepMax,T_vals)

class WDRT.ESSC.GaussianCopula(buoy, n_size=40.0, bin_1_limit=1.0, bin_step=0.25)[source]¶

Bases: WDRT.ESSC.EA

Create a GaussianCopula EA class for a buoy object. Contours generated under this class will use a Gaussian copula.

Parameters

buoy (NDBCData) – ESSC.Buoy Object
n_size (float) – minimum bin size used for Copula contour methods
bin_1_limit (float) – maximum value of Hs for the first bin
bin_step (float) – overlap interval for each bin

getContours(time_ss, time_r, nb_steps=1000)[source]¶

WDRT Extreme Sea State Gaussian Copula Contour function. This function calculates environmental contours of extreme sea states using a Gaussian copula and the inverse first-order reliability method.

Parameters

time_ss (float) – Sea state duration (hours) of measurements in input.
time_r (np.array) – Desired return period (years) for calculation of environmental contour, can be a scalar or a vector.
nb_steps (float) – Discretization of the circle in the normal space used for inverse FORM calculation.

Returns

Hs_Return (np.array) – Calculated Hs values along the contour boundary following return to original input orientation.
T_Return (np.array) – Calculated T values along the contour boundary following return to original input orientation.
nb_steps (float) – Discretization of the circle in the normal space

Example

To obtain the contours for a NDBC buoy:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website
buoy46022 = ESSC.Buoy('46022','NDBC')
buoy46022.fetchFromWeb()

# Create Environtmal Analysis object using above parameters
Gauss46022 = ESSC.GaussianCopula(buoy46022)

# Declare required parameters
Time_SS = 1.  # Sea state duration (hrs)
Time_r = 100  # Return periods (yrs) of interest
nb_steps = 1000  # Enter discretization of the circle in the normal space (optional)

# Gaussian copula contour generation example
Hs_Return, T_Return = Gauss46022.getContours(Time_SS, Time_r,nb_steps)

getSamples()[source]¶: Currently not implemented in this version.

class WDRT.ESSC.GumbelCopula(buoy, n_size=40.0, bin_1_limit=1.0, bin_step=0.25, Ndata=1000)[source]¶

Bases: WDRT.ESSC.EA

Create a GumbelCopula EA class for a buoy object. Contours generated under this class will use a Gumbel copula.

Parameters

buoy (NDBCData) – ESSC.Buoy Object
n_size (float) – minimum bin size used for Copula contour methods
bin_1_limit (float) – maximum value of Hs for the first bin
bin_step (float) – overlap interval for each bin
Ndata (int) – discretization used in the Gumbel copula density estimation, must be less than the number of contour points used in getContours

getContours(time_ss, time_r, nb_steps=1000)[source]¶

WDRT Extreme Sea State Gumbel Copula Contour function This function calculates environmental contours of extreme sea states using a Gumbel copula and the inverse first-order reliability method.

Parameters

time_ss (float) – Sea state duration (hours) of measurements in input.
time_r (np.array) – Desired return period (years) for calculation of environmental contour, can be a scalar or a vector.
nb_steps (float) – Discretization of the circle in the normal space used for inverse FORM calculation.

Returns

Hs_Return (np.array) – Calculated Hs values along the contour boundary following return to original input orientation.
T_Return (np.array) – Calculated T values along the contour boundary following return to original input orientation.
nb_steps (float) – Discretization of the circle in the normal space

Example

To obtain the contours for a NDBC buoy:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website
buoy46022 = ESSC.Buoy('46022','NDBC')
buoy46022.fetchFromWeb()

# Create Environtmal Analysis object using above parameters
Gumbel46022 = ESSC.GumbelCopula(buoy46022)

# Declare required parameters
Time_SS = 1.  # Sea state duration (hrs)
Time_r = 100  # Return periods (yrs) of interest
nb_steps = 1000  # Enter discretization of the circle in the normal space (optional)

# Gumbel copula contour generation example
Hs_Return, T_Return = Gumbel46022.getContours(Time_SS,Time_r,nb_steps)

getSamples()[source]¶: Currently not implemented in this version.

class WDRT.ESSC.NonParaClaytonCopula(buoy, Ndata=1000, max_T=None, max_Hs=None)[source]¶

Bases: WDRT.ESSC.EA

Create a NonParaClaytonCopula EA class for a buoy object. Contours generated under this class will use a Clayton copula with non-parametric marginal distribution fits.

Parameters

buoy (NDBCData) – ESSC.Buoy Object
NData (int) – discretization resolution used in KDE construction
max_T (float) – Maximum T value for KDE contstruction, must include possible range of contour. Default value is 2*max(T)
max_Hs (float) – Maximum Hs value for KDE contstruction, must include possible range of contour. Default value is 2*max(Hs)

getContours(time_ss, time_r, nb_steps=1000)[source]¶

WDRT Extreme Sea State non-parameteric Clayton Copula Contour function. This function calculates environmental contours of extreme sea states using a Clayton copula with non-parametric marginal distribution fits and the inverse first-order reliability method.

Parameters

time_ss (float) – Sea state duration (hours) of measurements in input.
time_r (np.array) – Desired return period (years) for calculation of environmental contour, can be a scalar or a vector.
nb_steps (float) – Discretization of the circle in the normal space used for inverse FORM calculation.

Returns

Hs_Return (np.array) – Calculated Hs values along the contour boundary following return to original input orientation.
T_Return (np.array) – Calculated T values along the contour boundary following return to original input orientation.
nb_steps (float) – Discretization of the circle in the normal space

Example

To obtain the contours for a NDBC buoy:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website
buoy46022 = ESSC.Buoy('46022','NDBC')
buoy46022.fetchFromWeb()

# Create Environtmal Analysis object using above parameters
NonParaClayton46022 = ESSC.NonParaClaytonCopula(buoy46022)

# Declare required parameters
Time_SS = 1.  # Sea state duration (hrs)
Time_r = 100  # Return periods (yrs) of interest
nb_steps = 1000  # Enter discretization of the circle in the normal space (optional)

# Non-Parametric Clayton copula contour generation example
Hs_Return, T_Return = NonParaClayton46022.getContours(Time_SS, Time_r,nb_steps)

getSamples()[source]¶: Currently not implemented in this version.

class WDRT.ESSC.NonParaGaussianCopula(buoy, Ndata=1000, max_T=None, max_Hs=None)[source]¶

Bases: WDRT.ESSC.EA

Create a NonParaGaussianCopula EA class for a buoy object. Contours generated under this class will use a Gaussian copula with non-parametric marginal distribution fits.

Parameters

buoy (NDBCData) – ESSC.Buoy Object
NData (int) – discretization resolution used in KDE construction
max_T (float) – Maximum T value for KDE contstruction, must include possible range of contour. Default value is 2*max(T)
max_Hs (float) – Maximum Hs value for KDE contstruction, must include possible range of contour. Default value is 2*max(Hs)

getContours(time_ss, time_r, nb_steps=1000)[source]¶

WDRT Extreme Sea State Gaussian Copula Contour function. This function calculates environmental contours of extreme sea states using a Gaussian copula with non-parametric marginal distribution fits and the inverse first-order reliability method.

Parameters

time_ss (float) – Sea state duration (hours) of measurements in input.
time_r (np.array) – Desired return period (years) for calculation of environmental contour, can be a scalar or a vector.
nb_steps (float) – Discretization of the circle in the normal space used for inverse FORM calculation.

Returns

Hs_Return (np.array) – Calculated Hs values along the contour boundary following return to original input orientation.
T_Return (np.array) – Calculated T values along the contour boundary following return to original input orientation.
nb_steps (float) – Discretization of the circle in the normal space

Example

To obtain the contours for a NDBC buoy:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website
buoy46022 = ESSC.Buoy('46022','NDBC')
buoy46022.fetchFromWeb()

# Create Environtmal Analysis object using above parameters
NonParaGauss46022 = ESSC.NonParaGaussianCopula(buoy46022)

# Declare required parameters
Time_SS = 1.  # Sea state duration (hrs)
Time_r = 100  # Return periods (yrs) of interest
nb_steps = 1000  # Enter discretization of the circle in the normal space (optional)

# Non-Parametric Gaussian copula contour generation example
Hs_Return, T_Return = NonParaGauss46022.getContours(Time_SS, Time_r,nb_steps)

getSamples()[source]¶: Currently not implemented in this version.

class WDRT.ESSC.NonParaGumbelCopula(buoy, Ndata=1000, max_T=None, max_Hs=None)[source]¶

Bases: WDRT.ESSC.EA

Create a NonParaGumbelCopula EA class for a buoy object. Contours generated under this class will use a Gumbel copula with non-parametric marginal distribution fits.

Parameters

buoy (NDBCData) – ESSC.Buoy Object
NData (int) – discretization resolution used in KDE construction
max_T (float) – Maximum T value for KDE contstruction, must include possible range of contour. Default value is 2*max(T)
max_Hs (float) – Maximum Hs value for KDE contstruction, must include possible range of contour. Default value is 2*max(Hs)

getContours(time_ss, time_r, nb_steps=1000)[source]¶

WDRT Extreme Sea State non-parameteric Gumbel Copula Contour function. This function calculates environmental contours of extreme sea states using a Gumbel copula with non-parametric marginal distribution fits and the inverse first-order reliability method.

Parameters

time_ss (float) – Sea state duration (hours) of measurements in input.
time_r (np.array) – Desired return period (years) for calculation of environmental contour, can be a scalar or a vector.
nb_steps (float) – Discretization of the circle in the normal space used for inverse FORM calculation.

Returns

Hs_Return (np.array) – Calculated Hs values along the contour boundary following return to original input orientation.
T_Return (np.array) – Calculated T values along the contour boundary following return to original input orientation.
nb_steps (float) – Discretization of the circle in the normal space

Example

To obtain the contours for a NDBC buoy:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website
buoy46022 = ESSC.Buoy('46022','NDBC')
buoy46022.fetchFromWeb()

# Create Environtmal Analysis object using above parameters
NonParaGumbel46022 = ESSC.NonParaGumbelCopula(buoy46022)

# Declare required parameters
Time_SS = 1.  # Sea state duration (hrs)
Time_r = 100  # Return periods (yrs) of interest
nb_steps = 1000  # Enter discretization of the circle in the normal space (optional)

# Non-Parametric Gumbel copula contour generation example
Hs_Return, T_Return = NonParaGumbel46022.getContours(Time_SS, Time_r,nb_steps)

getSamples()[source]¶: Currently not implemented in this version.

class WDRT.ESSC.PCA(buoy, size_bin=250.0)[source]¶

Bases: WDRT.ESSC.EA

Create a PCA EA class for a buoy object. Contours generated under this class will use principal component analysis (PCA) with improved distribution fitting (Eckert et. al 2015) and the I-FORM.

Parameters

size_bin (float) – chosen bin size
buoy (NDBCData) – ESSC.Buoy Object

getContours(time_ss, time_r, nb_steps=1000)[source]¶

WDRT Extreme Sea State PCA Contour function This function calculates environmental contours of extreme sea states using principal component analysis and the inverse first-order reliability method.

Parameters

time_ss (float) – Sea state duration (hours) of measurements in input.
time_r (np.array) – Desired return period (years) for calculation of environmental contour, can be a scalar or a vector.
nb_steps (int) – Discretization of the circle in the normal space used for inverse FORM calculation.

Returns

Hs_Return (np.array) – Calculated Hs values along the contour boundary following return to original input orientation.
T_Return (np.array) – Calculated T values along the contour boundary following return to original input orientation.
nb_steps (float) – Discretization of the circle in the normal space

Example

To obtain the contours for a NDBC buoy:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website
buoy46022 = ESSC.Buoy('46022','NDBC')
buoy46022.fetchFromWeb()

# Create PCA EA object for buoy
pca46022 = ESSC.PCA(buoy46022)

# Declare required parameters
Time_SS = 1.  # Sea state duration (hrs)
Time_r = 100  # Return periods (yrs) of interest
nb_steps = 1000  # Enter discretization of the circle in the normal space (optional)

# Contour generation example
Hs_Return, T_Return = pca46022.getContours(Time_SS, Time_r,nb_steps)

getSamples(num_contour_points, contour_returns, random_seed=None)[source]¶

WDRT Extreme Sea State Contour Sampling function. This function calculates samples of Hs and T using the EA function to sample between contours of user-defined return periods.

Parameters

num_contour_points (int) – Number of sample points to be calculated per contour interval.
contour_returns (np.array) – Vector of return periods that define the contour intervals in which samples will be taken. Values must be greater than zero and must be in increasing order.
random_seed (int (optional)) – Random seed for sample generation, required for sample repeatability. If left blank, a seed will automatically be generated.

Returns

Hs_Samples (np.array) – Vector of Hs values for each sample point.
Te_Samples (np.array) – Vector of Te values for each sample point.
Weight_points (np.array) – Vector of probabilistic weights for each sampling point to be used in risk calculations.

Example

To get weighted samples from a set of contours:

import numpy as np
import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website
buoy46022 = ESSC.Buoy('46022','NDBC')
buoy46022.fetchFromWeb()

# Create PCA EA object for buoy
pca46022 = ESSC.PCA(buoy46022)

# Declare required parameters
Time_SS = 1.  # Sea state duration (hrs)
Time_r = 100  # Return periods (yrs) of interest
num_contour_points = 10 # Number of points to be sampled for each contour interval
contour_returns = np.array([0.001, 0.01, 0.05, 0.1, 0.5, 1, 5, 10, 50, 100])

# Calculate contour to save required variables to PCA EA object
pca46022.getContours(Time_SS, Time_r,nb_steps)

# Probabilities defining sampling contour bounds.
random_seed = 2  # Random seed for sample generation

# Get samples for a full sea state long term analysis
Hs_sampleFSS, T_sampleFSS, Weight_sampleFSS = pca46022.getSamples(num_contour_points,
                                             contour_returns, random_seed)

plotSampleData()[source]¶: Display a plot of the 100-year return contour, full sea state samples and contour samples

class WDRT.ESSC.Rosenblatt(buoy, n_size=50.0, bin_1_limit=0.5, bin_step=0.25)[source]¶

Bases: WDRT.ESSC.EA

Create a Rosenblatt EA class for a buoy object. Contours generated under this class will use a Rosenblatt transformation and the I-FORM.

Parameters

buoy (NDBCData) – ESSC.Buoy Object
n_size (float) – minimum bin size used for Copula contour methods
bin_1_limit (float) – maximum value of Hs for the first bin
bin_step (float) – overlap interval for each bin

getContours(time_ss, time_r, nb_steps=1000)[source]¶

WDRT Extreme Sea State Rosenblatt Copula Contour function. This function calculates environmental contours of extreme sea states using a Rosenblatt transformation and the inverse first-order reliability method.

Parameters

time_ss (float) – Sea state duration (hours) of measurements in input.
time_r (np.array) – Desired return period (years) for calculation of environmental contour, can be a scalar or a vector.
nb_steps (float) – Discretization of the circle in the normal space used for inverse FORM calculation.

Returns

Hs_Return (np.array) – Calculated Hs values along the contour boundary following return to original input orientation.
T_Return (np.array) – Calculated T values along the contour boundary following return to original input orientation.
nb_steps (float) – Discretization of the circle in the normal space

Example

To obtain the contours for a NDBC buoy:

import WDRT.ESSC as ESSC

# Pull spectral data from NDBC website
buoy46022 = ESSC.Buoy('46022','NDBC')
buoy46022.fetchFromWeb()

# Create Environtmal Analysis object using above parameters
Rosen46022 = ESSC.Rosenblatt(buoy46022)

# Declare required parameters
Time_SS = 1.  # Sea state duration (hrs)
Time_r = 100  # Return periods (yrs) of interest
nb_steps = 1000  # Enter discretization of the circle in the normal space (optional)

# Rosenblatt contour generation example
Hs_Return, T_Return = Rosen46022.getContours(Time_SS, Time_r,nb_steps)

getSamples()[source]¶: Currently not implemented in this version

WDRT.MLER module¶

To improve the model efficiency and reduce required computational time or wave tank testing time, the shipping and offshore industry often perform their mid- and high-fidelity simulations and experimental wave tank tests using an equivalent design wave profile generated from (linear) low-fidelity model solutions. The MLER module was developed based on the most likely extreme response method, which uses the linear RAO of the device and the spectrum for the sea state of interest to produce a focused wave profile that gives the largest response. This approach does not require an input time series for the device. Because it uses linear theory, the underlying assumption is that the higher-order effects are small in comparison to the linear effects.