Wave Module

The wave module contains a set of functions to calculate quantities of interest for wave energy converters (WEC).

The wave module uses wave elevation time series data and spectra data.

Wave elevation time series data is stored as a pandas DataFrame indexed by time. Time can be specified in datetime or in seconds. The column names describe the type of data in each column (for example, data from multiple sensors).
Spectra data is stored as a pandas DataFrame and may be indexed by frequency in Hz or datetime. The resource and graphic modules expects spectra indexed by frequency. Timeseries spectra may be passed to these functions using after ausing the pandas method transpose.

IO

The io submodule contains the following functions to request, load, and manipulate National Data Buoy Center (NDBC) data, WPTO Hindcast <https://registry.opendata.aws/wpto-pds-us-wave/>`_data, and `CDiP data. The io module also has functions to load and manipulate WEC-Sim and SWAN model data.

`read_file`	Reads a NDBC wave buoy data file (from https://www.ndbc.noaa.gov).
`available_data`	For a given parameter this will return a DataFrame of years, station IDs and file names that contain that parameter data.
`request_data`	Requests data by filenames and returns a dictionary of DataFrames for each filename passed.
`to_datetime_index`	Converts the NDBC date and time information reported in separate columns into a DateTime index and removed the NDBC date & time columns.
`dates_to_datetime`	Takes a DataFrame and converts the NDBC date columns
`parameter_units`	Returns an ordered dictionary of NDBC parameters with unit values.
`get_buoy_metadata`	Fetches and parses the metadata of a National Data Buoy Center (NDBC) station from https://www.ndbc.noaa.gov.
`read_output`	Loads the wecSim response class once 'output' has been saved to a .mat structure.
`read_table`	Reads in SWAN table format output
`read_block`	Reads in SWAN block output with headers and creates a dictionary of DataFrames for each SWAN output variable in the output file.
`dictionary_of_block_to_table`	Converts a dictionary of structured 2D grid SWAN block format x (columns),y (index) to SWAN table format x (column),y (column), values (column) DataFrame.
`block_to_table`	Converts structured 2D grid SWAN block format x (columns), y (index) to SWAN table format x (column),y (column), values (column) DataFrame.
`request_wpto_point_data`	Returns data from the WPTO wave hindcast hosted on AWS at the specified latitude and longitude point(s), or the closest available point(s).
`request_wpto_directional_spectrum`	Returns directional spectra data from the WPTO wave hindcast hosted on AWS at the specified latitude and longitude point(s), or the closest available point(s).
`request_netCDF`	Returns historic or realtime data from CDIP THREDDS server
`request_parse_workflow`	Parses a passed CDIP netCDF file or requests a station number from http://cdip.ucsd.edu/) and parses.
`get_netcdf_variables`	Iterates over and extracts variables from CDIP bouy data.

CDiP Data

mhkit.wave.io.cdip.request_netCDF(station_number, data_type)[source]

Returns historic or realtime data from CDIP THREDDS server

Parameters

station_number (string) – CDIP station number of interest
data_type (string) – ‘historic’ or ‘realtime’

Returns

nc (netCDF Object) – netCDF data for the given station number and data type

mhkit.wave.io.cdip.request_parse_workflow(nc=None, station_number=None, parameters=None, years=None, start_date=None, end_date=None, data_type='historic', all_2D_variables=False)[source]

Parses a passed CDIP netCDF file or requests a station number from http://cdip.ucsd.edu/) and parses. This function can return specific parameters is passed. Years may be non-consecutive e.g. [2001, 2010]. Time may be sliced by dates (start_date or end date in YYYY-MM-DD). data_type defaults to historic but may also be set to ‘realtime’. By default 2D variables are not parsed if all 2D varaibles are needed. See the MHKiT CDiP example Jupyter notbook for information on available parameters.

Parameters

nc (netCDF Object) – netCDF data for the given station number and data type. Can be the output of request_netCDF
station_number (string) – Station number of CDIP wave buoy
parameters (string or list of stings) – Parameters to return. If None will return all varaibles except 2D-variables.
years (int or list of int) – Year date, e.g. 2001 or [2001, 2010]
start_date (string) – Start date in YYYY-MM-DD, e.g. ‘2012-04-01’
end_date (string) – End date in YYYY-MM-DD, e.g. ‘2012-04-30’
data_type (string) – Either ‘historic’ or ‘realtime’
all_2D_variables (boolean) – Will return all 2D data. Enabling this will add significant processing time. If all 2D variables are not needed it is recomended to pass 2D parameters of interest using the ‘parameters’ keyword and leave this set to False. Default False.

Returns

data (dictionary) –

‘vars1D’: DataFrame: 1D variables indexed by time
’metadata’: dictionary: Anything not of length time
’vars2D’: dictionary of DataFrames, optional: If 2D-vars are passed in the ‘parameters key’ or if run with all_2D_variables=True, then this key will appear with a dictonary of DataFrames of 2D variables.

mhkit.wave.io.cdip.get_netcdf_variables(nc, start_date=None, end_date=None, parameters=None, all_2D_variables=False)[source]

Iterates over and extracts variables from CDIP bouy data. See the MHKiT CDiP example Jupyter notbook for information on available parameters.

Parameters

nc (netCDF Object) – netCDF data for the given station number and data type
start_stamp (float) – Data of interest start in seconds since epoch
end_stamp (float) – Data of interest end in seconds since epoch
parameters (string or list of stings) – Parameters to return. If None will return all varaibles except 2D-variables. Default None.
all_2D_variables (boolean) – Will return all 2D data. Enabling this will add significant processing time. If all 2D variables are not needed it is recomended to pass 2D parameters of interest using the ‘parameters’ keyword and leave this set to False. Default False.

Returns

results (dictionary) –

‘vars1D’: DataFrame: 1D variables indexed by time
’metadata’: dictionary: Anything not of length time
’vars2D’: dictionary of DataFrames, optional: If 2D-vars are passed in the ‘parameters key’ or if run with all_2D_variables=True, then this key will appear with a dictonary of DataFrames of 2D variables.

NDBC Data

mhkit.wave.io.ndbc.read_file(file_name, missing_values=['MM', 9999, 999, 99])[source]

Reads a NDBC wave buoy data file (from https://www.ndbc.noaa.gov).

Realtime and historical data files can be loaded with this function.

Note: With realtime data, missing data is denoted by “MM”. With historical data, missing data is denoted using a variable number of # 9’s, depending on the data type (for example: 9999.0 999.0 99.0). ‘N/A’ is automatically converted to missing data.

Data values are converted to float/int when possible. Column names are also converted to float/int when possible (this is useful when column names are frequency).

Parameters

file_name (string) – Name of NDBC wave buoy data file
missing_value (list of values) – List of values that denote missing data

Returns

data (pandas DataFrame) – Data indexed by datetime with columns named according to header row
metadata (dict or None) – Dictionary with {column name: units} key value pairs when the NDBC file contains unit information, otherwise None is returned

mhkit.wave.io.ndbc.available_data(parameter, buoy_number=None, proxy=None)[source]

For a given parameter this will return a DataFrame of years, station IDs and file names that contain that parameter data.

Parameters

parameter (string) – ‘swden’: ‘Raw Spectral Wave Current Year Historical Data’ ‘swdir’: ‘Spectral Wave Current Year Historical Data (alpha1)’ ‘swdir2’: ‘Spectral Wave Current Year Historical Data (alpha1)’ ‘swr1’: ‘Spectral Wave Current Year Historical Data (r1)’ ‘swr2’: ‘Spectral Wave Current Year Historical Data (r2)’ ‘stdmet’: ‘Standard Meteorological Current Year Historical Data’ ‘cwind’ : ‘Continuous Winds Current Year Historical Data’
buoy_number (string (optional)) – Buoy Number. 5-character alpha-numeric station identifier
proxy (dict) – Proxy dict passed to python requests, (e.g. proxy_dict= {“http”: ‘http:wwwproxy.yourProxy:80/’})

Returns

available_data (DataFrame) – DataFrame with station ID, years, and NDBC file names.

mhkit.wave.io.ndbc.request_data(parameter, filenames, proxy=None)[source]

Requests data by filenames and returns a dictionary of DataFrames for each filename passed. If filenames for a single buoy are passed then the yearly DataFrames in the returned dictionary (ndbc_data) are indexed by year (e.g. ndbc_data[‘2014’]). If multiple buoy ids are passed then the returned dictionary is indexed by buoy id and year (e.g. ndbc_data[‘46022’][‘2014’]).

Parameters

parameter (string) – ‘swden’ : ‘Raw Spectral Wave Current Year Historical Data’ ‘swdir’: ‘Spectral wave data (alpha1)’ ‘swdir2’: ‘Spectral wave data (alpha2)’ ‘swr1’: ‘Spectral wave data (r1)’ ‘swr2’: ‘Spectral wave data (r2)’ ‘stdmet’: ‘Standard Meteorological Current Year Historical Data’ ‘cwind’ : ‘Continuous Winds Current Year Historical Data’
filenames (pandas Series or DataFrame) – Data filenames on https://www.ndbc.noaa.gov/data/historical/{parameter}/
proxy (dict) – Proxy dict passed to python requests, (e.g. proxy_dict= {“http”: ‘http:wwwproxy.yourProxy:80/’})

Returns

ndbc_data (dict) – Dictionary of DataFrames indexed by buoy and year.

mhkit.wave.io.ndbc.to_datetime_index(parameter, ndbc_data)[source]

Converts the NDBC date and time information reported in separate columns into a DateTime index and removed the NDBC date & time columns.

Parameters

parameter (string) – ‘swden’: ‘Raw Spectral Wave Current Year Historical Data’ ‘swdir’: ‘Spectral wave data (alpha1)’ ‘swdir2’: ‘Spectral wave data (alpha2)’ ‘swr1’: ‘Spectral wave data (r1)’ ‘swr2’: ‘Spectral wave data (r2)’ ‘stdmet’: ‘Standard Meteorological Current Year Historical Data’ ‘cwind’: ‘Continuous Winds Current Year Historical Data’
ndbc_data (DataFrame) – NDBC data in dataframe with date and time columns to be converted

Returns

df_datetime (DataFrame) – Dataframe with NDBC date columns removed, and datetime index

mhkit.wave.io.ndbc.dates_to_datetime(data, return_date_cols=False, return_as_dataframe=False)[source]

Takes a DataFrame and converts the NDBC date columns: (e.g. “#YY MM DD hh mm”) to datetime. Returns a DataFrame with the removed NDBC date columns a new [‘date’] columns with DateTime Format.

Parameters

data (DataFrame) – Dataframe with headers (e.g. [‘YY’, ‘MM’, ‘DD’, ‘hh’, {‘mm’}])
return_date_col (Bool (optional)) – Default False. When true will return list of NDBC date columns
return_as_dataFrame (bool) – Results returned as a DataFrame (useful for MHKiT-MATLAB)

Returns

date (Series) – Series with NDBC dates dropped and new [‘date’] column in DateTime format
ndbc_date_cols (list (optional)) – List of the DataFrame columns headers for dates as provided by NDBC

mhkit.wave.io.ndbc.parameter_units(parameter='')[source]

Returns an ordered dictionary of NDBC parameters with unit values. If no parameter is passed then an ordered dictionary of all NDBC parameterz specified unites is returned. If a parameter is specified then only the units associated with that parameter are returned. Note that many NDBC paramters report multiple measurements and in that case the returned dictionary will contain the NDBC measurement name and associated unit for all the measurements associated with the specified parameter. Optional parameter values are given below. All units are based on https://www.ndbc.noaa.gov/measdes.shtml.

Parameters: parameter (string (optional)) – ‘adcp’: ‘Acoustic Doppler Current Profiler Current Year Historical Data’ ‘cwind’: ‘Continuous Winds Current Year Historical Data’ ‘dart’: ‘Water Column Height (DART) Current Year Historical Data’ ‘derived2’: ‘Derived Met Values’ ‘ocean’ : ‘Oceanographic Current Year Historical Data’ ‘rain’ : ‘Hourly Rain Current Year Historical Data’ ‘rain10’: ‘10-Minute Rain Current Year Historical Data’ ‘rain24’: ‘24-Hour Rain Current Year Historical Data’ ‘realtime2’: ‘Detailed Wave Summary (Realtime .spec data files only)’ ‘srad’: ‘Solar Radiation Current Year Historical Data’ ‘stdmet’: ‘Standard Meteorological Current Year Historical Data’ ‘supl’: ‘Supplemental Measurements Current Year Historical Data’ ‘swden’: ‘Raw Spectral Wave Current Year Historical Data’ ‘swdir’: ‘Spectral Wave Current Year Historical Data (alpha1)’ ‘swdir2’: ‘Spectral Wave Current Year Historical Data (alpha2)’ ‘swr1’: ‘Spectral Wave Current Year Historical Data (r1)’ ‘swr2’: ‘Spectral Wave Current Year Historical Data (r2)’
Returns: units (dict) – Dictionary of parameter units

mhkit.wave.io.ndbc.request_directional_data(buoy, year)[source]

Request the directional spectrum data and return an xarray.Dataset containing all 5 variables. The NDBC historical data is organized into files based on buoy number, year, and parameter. For a given buoy number and year, the five files—corresponding to the 5 parameters NDBC uses to describe directional wave spectrum—are fetched and processed.

Parameters

buoy (string) – Buoy Number. Five character alpha-numeric station identifier.
year (int) – Four digit year.

Returns

ndbc_data (xr.Dataset) – Dataset containing the five parameter data indexed by frequency and date.

mhkit.wave.io.ndbc.create_spread_function(data, directions)[source]

Create the spread function from the 4 relevant NDBC parameter data. Return as an xarray.DataArray indexed by frequency and wave direction.

Parameters

data (xr.Dataset) – Dataset containing the four NDBC parameter data indexed by frequency.
directions (np.ndarray) – One-dimensional array of wave directions in degrees.

Returns

spread (xr.DataArray) – DataArray containing the spread function values indexed by frequency and wave direction.

mhkit.wave.io.ndbc.create_directional_spectrum(data, directions)[source]

Create the spectrum from the 5 relevant NDBC parameter data. Return as an xarray.DataArray indexed by frequency and wave direction.

Parameters

data (xr.Dataset) – Dataset containing the five NDBC parameter data indexed by frequency.
directions (np.ndarray) – One-dimensional array of wave directions in degrees.

Returns

spectrum (xr.DataArray) – DataArray containing the spectrum values indexed by frequency and wave direction.

mhkit.wave.io.ndbc.get_buoy_metadata(station_number: str)[source]

Fetches and parses the metadata of a National Data Buoy Center (NDBC) station from https://www.ndbc.noaa.gov.

Extracts information such as provider, buoy type, latitude, longitude, and other metadata from the station’s webpage.

Parameters: station_number (string) – The station number (ID) of the NDBC buoy
Returns: data (dict) – A dictionary containing metadata of the buoy with keys representing the information type and values containing the corresponding data

SWAN Data

mhkit.wave.io.swan.read_table(swan_file)[source]

Reads in SWAN table format output

Parameters

swan_file (str) – filename to import

Returns

swan_data (DataFrame) – Dataframe of swan output
metaDict (Dictionary) – Dictionary of metaData

mhkit.wave.io.swan.read_block(swan_file)[source]

Reads in SWAN block output with headers and creates a dictionary of DataFrames for each SWAN output variable in the output file.

Parameters

swan_file (str) – swan block file to import

Returns

data (Dictionary) – Dictionary of DataFrame of swan output variables
metaDict (Dictionary) – Dictionary of metaData dependent on file type

mhkit.wave.io.swan.dictionary_of_block_to_table(dictionary_of_DataFrames, names=None)[source]

Converts a dictionary of structured 2D grid SWAN block format x (columns),y (index) to SWAN table format x (column),y (column), values (column) DataFrame.

Parameters

dictionary_of_DataFrames (Dictionary) – Dictionary of DataFrames in with columns as X indicie and Y as index.
names (List (Optional)) – Name of data column in returned table. Default=Dictionary.keys()

Returns

swanTables (DataFrame) – DataFrame with columns x,y,values where values = Dictionary.keys() or names

mhkit.wave.io.swan.block_to_table(data, name='values')[source]

Converts structured 2D grid SWAN block format x (columns), y (index) to SWAN table format x (column),y (column), values (column) DataFrame.

Parameters

data (DataFrame) – DataFrame in with columns as X indicie and Y as index.
name (string (Optional)) – Name of data column in returned table. Default=’values’

Returns

table (DataFrame) – DataFrame with columns x,y,values

WEC-Sim Data

mhkit.wave.io.wecsim.read_output(file_name)[source]

Loads the wecSim response class once ‘output’ has been saved to a .mat structure.

NOTE: Python is unable to import MATLAB objects. MATLAB must be used to save the wecSim object as a structure.

Parameters: file_name (string) – Name of wecSim output file saved as a .mat structure
Returns: ws_output (dict) – Dictionary of pandas DataFrames, indexed by time (s)

WPTO Hindcast Data

This module provides functions to access and process WPTO wave hindcast data hosted on AWS at specified latitude and longitude points or the closest available points. It includes functions to retrieve data for predefined regions, request point data for various parameters, and request directional spectrum data.

Functions:

region_selection(lat_lon): Returns the name of the predefined region for given latitude and longitude coordinates.
request_wpto_point_data(data_type, parameter, lat_lon, years, tree=None, unscale=True, str_decode=True, hsds=True): Returns data from the WPTO wave hindcast hosted on AWS at the specified latitude and longitude point(s) for the requested data type, parameter, and years.
request_wpto_directional_spectrum(lat_lon, year, tree=None, unscale=True, str_decode=True, hsds=True): Returns directional spectra data from the WPTO wave hindcast hosted on AWS at the specified latitude and longitude point(s) for the given year.

Dependencies:

sys
time.sleep
pandas
xarray
numpy
rex.MultiYearWaveX, rex.WaveX

mhkit.wave.io.hindcast.hindcast.region_selection(lat_lon)[source]

Returns the name of the predefined region in which the given coordinates reside. Can be used to check if the passed lat/lon pair is within the WPTO hindcast dataset.

Parameters: lat_lon (list or tuple) – Latitude and longitude coordinates as floats or integers
Returns: region (string) – Name of predefined region for given coordinates

mhkit.wave.io.hindcast.hindcast.request_wpto_point_data(data_type, parameter, lat_lon, years, tree=None, unscale=True, str_decode=True, hsds=True, path=None, as_xarray=False)[source]

Returns data from the WPTO wave hindcast hosted on AWS at the specified latitude and longitude point(s), or the closest available point(s). Visit https://registry.opendata.aws/wpto-pds-us-wave/ for more information about the dataset and available locations and years.

Note: To access the WPTO hindcast data, you will need to configure h5pyd for data access on HSDS. Please see the WPTO_hindcast_example notebook for more information.

Parameters

data_type (string) – Data set type of interest Options: ‘3-hour’ ‘1-hour’
parameter (string or list of strings) –
Dataset parameter to be downloaded 3-hour dataset options: ‘directionality_coefficient’,

’energy_period’, ‘maximum_energy_direction’ ‘mean_absolute_period’, ‘mean_zero-crossing_period’, ‘omni-directional_wave_power’, ‘peak_period’ ‘significant_wave_height’, ‘spectral_width’, ‘water_depth’

1-hour dataset options: ‘directionality_coefficient’,
’energy_period’, ‘maximum_energy_direction’ ‘mean_absolute_period’, ‘mean_zero-crossing_period’, ‘omni-directional_wave_power’, ‘peak_period’, ‘significant_wave_height’, ‘spectral_width’, ‘water_depth’, ‘maximim_energy_direction’, ‘mean_wave_direction’, ‘frequency_bin_edges’
lat_lon (tuple or list of tuples) – Latitude longitude pairs at which to extract data
years (list) – Year(s) to be accessed. The years 1979-2010 available. Examples: [1996] or [2004,2006,2007]
tree (str | cKDTree (optional)) – cKDTree or path to .pkl file containing pre-computed tree of lat, lon coordinates, default = None
unscale (bool (optional)) – Boolean flag to automatically unscale variables on extraction Default = True
str_decode (bool (optional)) – Boolean flag to decode the bytestring meta data into normal strings. Setting this to False will speed up the meta data read. Default = True
hsds (bool (optional)) – Boolean flag to use h5pyd to handle .h5 ‘files’ hosted on AWS behind HSDS. Setting to False will indicate to look for files on local machine, not AWS. Default = True
path (string (optional)) – Optionally override with a custom .h5 filepath. Useful when setting hsds=False.
as_xarray (bool (optional)) – Boolean flag to return data as an xarray Dataset. Default = False

Returns

data (DataFrame) – Data indexed by datetime with columns named for parameter and cooresponding metadata index
meta (DataFrame) – Location metadata for the requested data location

mhkit.wave.io.hindcast.hindcast.request_wpto_directional_spectrum(lat_lon, year, tree=None, unscale=True, str_decode=True, hsds=True, path=None)[source]

Returns directional spectra data from the WPTO wave hindcast hosted on AWS at the specified latitude and longitude point(s), or the closest available point(s). The data is returned as an xarray Dataset with keys indexed by a graphical identifier (gid). gid`s are integers which represent a lat, long on which data is stored. Requesting an array of `lat_lons will return a dataset with multiple gids representing the data closest to each requested lat, lon.

Visit https://registry.opendata.aws/wpto-pds-us-wave/ for more information about the dataset and available locations and years.

Note: To access the WPTO hindcast data, you will need to configure h5pyd for data access on HSDS. Please see the WPTO_hindcast_example notebook for more information.

Parameters

lat_lon (tuple or list of tuples) – Latitude longitude pairs at which to extract data
year (string) – Year to be accessed. The years 1979-2010 available. Only one year can be requested at a time.
tree (str | cKDTree (optional)) – cKDTree or path to .pkl file containing pre-computed tree of lat, lon coordinates, default = None
unscale (bool (optional)) – Boolean flag to automatically unscale variables on extraction Default = True
str_decode (bool (optional)) – Boolean flag to decode the bytestring meta data into normal strings. Setting this to False will speed up the meta data read. Default = True
hsds (bool (optional)) – Boolean flag to use h5pyd to handle .h5 ‘files’ hosted on AWS behind HSDS. Setting to False will indicate to look for files on local machine, not AWS. Default = True
path (string (optional)) – Optionally override with a custom .h5 filepath. Useful when setting hsds=False

Returns

data (xarray) – Coordinates as datetime, frequency, and direction for data at specified location(s)
meta (DataFrame) – Location metadata for the requested data location

WIND Toolkit Data

mhkit.wave.io.hindcast.wind_toolkit.region_selection(lat_lon, preferred_region='')[source]

Returns the name of the predefined region in which the given coordinates reside. Can be used to check if the passed lat/lon pair is within the WIND Toolkit hindcast dataset.

Parameters

lat_lon (tuple) – Latitude and longitude coordinates as floats or integers
preferred_region (string (optional)) – Latitude and longitude coordinates as floats or integers

Returns

region (string) – Name of predefined region for given coordinates

mhkit.wave.io.hindcast.wind_toolkit.plot_region(region, lat_lon=None, ax=None)[source]

Visualizes the area that a given region covers. Can help users understand the extent of a region since they are not all rectangular.

Parameters

region (string) – Name of predefined region in the WIND Toolkit Options: ‘Offshore_CA’,’Hawaii’,’Mid_Atlantic’,’NW_Pacific’
lat_lon (couple (optional)) – Latitude and longitude pair to plot on top of the chosen region. Useful to inform accurate latitude-longitude selection for data analysis.
ax (matplotlib axes object (optional)) – Axes for plotting. If None, then a new figure is created.

Returns

ax (matplotlib pyplot axes)

mhkit.wave.io.hindcast.wind_toolkit.elevation_to_string(parameter, elevations)[source]

Takes in a parameter (e.g. ‘windspeed’) and elevations (e.g. [20, 40, 120]) and returns the formatted strings that are input to WIND Toolkit (e.g. windspeed_10m). Does not check parameter against the elevation levels. This is done in request_wtk_point_data.

Parameters

parameter (string) – Name of the WIND toolkit parameter. Options: ‘windspeed’, ‘winddirection’, ‘temperature’, ‘pressure’
elevations (list) – List of elevations (float). Values can range from approxiamtely 20 to 200 in increments of 20, depending on the parameter in question. See Documentation for request_wtk_point_data for the full list of available parameters.

Returns

parameter_list (list) – Formatted List of WIND Toolkit parameter strings

mhkit.wave.io.hindcast.wind_toolkit.request_wtk_point_data(time_interval, parameter, lat_lon, years, preferred_region='', tree=None, unscale=True, str_decode=True, hsds=True)[source]

Returns data from the WIND Toolkit offshore wind hindcast hosted on AWS at the specified latitude and longitude point(s), or the closest available point(s). Visit https://registry.opendata.aws/nrel-pds-wtk/ for more information about the dataset and available locations and years.

Calls with multiple parameters must have the same time interval. Calls with multiple locations must use the same region (use the plot_region function).

Note: To access the WIND Toolkit hindcast data, you will need to configure h5pyd for data access on HSDS. Please see the WTK_hindcast_example notebook for more information.

Parameters

time_interval (string) – Data set type of interest Options: ‘1-hour’ ‘5-minute’
parameter (string or list of strings) –
Dataset parameter to be downloaded. Other parameters may be available. This list is limited to those available at both 5-minute and 1-hour time intervals for all regions. Options:

’precipitationrate_0m’, ‘inversemoninobukhovlength_2m’, ‘relativehumidity_2m’, ‘surface_sea_temperature’, ‘pressure_0m’, ‘pressure_100m’, ‘pressure_200m’, ‘temperature_10m’, ‘temperature_20m’, ‘temperature_40m’, ‘temperature_60m’, ‘temperature_80m’, ‘temperature_100m’, ‘temperature_120m’, ‘temperature_140m’, ‘temperature_160m’, ‘temperature_180m’, ‘temperature_200m’, ‘winddirection_10m’, ‘winddirection_20m’, ‘winddirection_40m’, ‘winddirection_60m’, ‘winddirection_80m’, ‘winddirection_100m’, ‘winddirection_120m’, ‘winddirection_140m’, ‘winddirection_160m’, ‘winddirection_180m’, ‘winddirection_200m’, ‘windspeed_10m’, ‘windspeed_20m’, ‘windspeed_40m’, ‘windspeed_60m’, ‘windspeed_80m’, ‘windspeed_100m’, ‘windspeed_120m’, ‘windspeed_140m’, ‘windspeed_160m’, ‘windspeed_180m’, ‘windspeed_200m’
lat_lon (tuple or list of tuples) – Latitude longitude pairs at which to extract data. Use plot_region() or region_selection() to see the corresponding region for a given location.
years (list) – Year(s) to be accessed. The years 2000-2019 available (up to 2020 for Mid-Atlantic). Examples: [2015] or [2004,2006,2007]
preferred_region (string (optional)) – Region that the lat_lon belongs to (‘Offshore_CA’ or ‘NW_Pacific’). Required when a lat_lon point falls in both the Offshore California and NW Pacific regions. Overlap region defined by latitude = (41.213, 42.642) and longitude = (-129.090, -121.672). Default = ‘’
tree (str | cKDTree (optional)) – cKDTree or path to .pkl file containing pre-computed tree of lat, lon coordinates, default = None
unscale (bool (optional)) – Boolean flag to automatically unscale variables on extraction Default = True
str_decode (bool (optional)) – Boolean flag to decode the bytestring meta data into normal strings. Setting this to False will speed up the meta data read. Default = True
hsds (bool (optional)) – Boolean flag to use h5pyd to handle .h5 ‘files’ hosted on AWS behind HSDS. Setting to False will indicate to look for files on local machine, not AWS. Default = True

Returns

data (DataFrame) – Data indexed by datetime with columns named for parameter and cooresponding metadata index
meta (DataFrame) – Location metadata for the requested data location

Resource

The resource submodule contains functions compute wave energy spectra and metrics.

The following functions can be used to compute wave energy spectra:

`elevation_spectrum`	Calculates the wave energy spectrum from wave elevation time-series
`pierson_moskowitz_spectrum`	Calculates Pierson-Moskowitz Spectrum from IEC TS 62600-2 ED2 Annex C.2 (2019)
`jonswap_spectrum`	Calculates JONSWAP Spectrum from IEC TS 62600-2 ED2 Annex C.2 (2019)

The following functions can be used to compute wave metrics from spectra:

`surface_elevation`	Calculates wave elevation time-series from spectrum
`frequency_moment`	Calculates the Nth frequency moment of the spectrum
`significant_wave_height`	Calculates wave height from spectra
`average_zero_crossing_period`	Calculates wave average zero crossing period from spectra
`average_crest_period`	Calculates wave average crest period from spectra
`average_wave_period`	Calculates mean wave period from spectra
`peak_period`	Calculates wave peak period from spectra
`energy_period`	Calculates wave energy period from spectra
`spectral_bandwidth`	Calculates bandwidth from spectra
`spectral_width`	Calculates wave spectral width from spectra
`energy_flux`	Calculates the omnidirectional wave energy flux of the spectra
`energy_period_to_peak_period`	Convert from spectral energy period (Te) to peak period (Tp) using ITTC approximation for JONSWAP Spectrum.
`wave_celerity`	Calculates wave celerity (group velocity)
`wave_number`	Calculates wave number
`depth_regime`	Calculates the depth regime based on wavelength and height Deep water: h/l > ratio This function exists so sinh in wave celerity doesn't blow up to infinity.
`wave_length`	Calculates wave length from wave number To compute: 2*pi/wavenumber

mhkit.wave.resource.elevation_spectrum(eta, sample_rate, nnft, window='hann', detrend=True, noverlap=None)[source]

Calculates the wave energy spectrum from wave elevation time-series

Parameters

eta (pandas DataFrame) – Wave surface elevation [m] indexed by time [datetime or s]
sample_rate (float) – Data frequency [Hz]
nnft (integer) – Number of bins in the Fast Fourier Transform
window (string (optional)) – Signal window type. ‘hann’ is used by default given the broadband nature of waves. See scipy.signal.get_window for more options.
detrend (bool (optional)) – Specifies if a linear trend is removed from the data before calculating the wave energy spectrum. Data is detrended by default.
noverlap (int, optional) – Number of points to overlap between segments. If None, noverlap = nperseg / 2. Defaults to None.

Returns

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]

mhkit.wave.resource.pierson_moskowitz_spectrum(f, Tp, Hs)[source]

Calculates Pierson-Moskowitz Spectrum from IEC TS 62600-2 ED2 Annex C.2 (2019)

Parameters

f (numpy array) – Frequency [Hz]
Tp (float/int) – Peak period [s]
Hs (float/int) – Significant wave height [m]

Returns

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed frequency [Hz]

mhkit.wave.resource.jonswap_spectrum(f, Tp, Hs, gamma=None)[source]

Calculates JONSWAP Spectrum from IEC TS 62600-2 ED2 Annex C.2 (2019)

Parameters

f (numpy array) – Frequency [Hz]
Tp (float/int) – Peak period [s]
Hs (float/int) – Significant wave height [m]
gamma (float (optional)) – Gamma

Returns

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed frequency [Hz]

mhkit.wave.resource.surface_elevation(S, time_index, seed=None, frequency_bins=None, phases=None, method='ifft')[source]

Calculates wave elevation time-series from spectrum

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
time_index (numpy array) – Time used to create the wave elevation time-series [s], for example, time = np.arange(0,100,0.01)
seed (int (optional)) – Random seed
frequency_bins (numpy array or pandas DataFrame (optional)) – Bin widths for frequency of S. Required for unevenly sized bins
phases (numpy array or pandas DataFrame (optional)) – Explicit phases for frequency components (overrides seed) for example, phases = np.random.rand(len(S)) * 2 * np.pi
method (str (optional)) – Method used to calculate the surface elevation. ‘ifft’ (Inverse Fast Fourier Transform) used by default if the given frequency_bins==None. ‘sum_of_sines’ explicitly sums each frequency component and used by default if frequency_bins are provided. The ‘ifft’ method is significantly faster.

Returns

eta (pandas DataFrame) – Wave surface elevation [m] indexed by time [s]

mhkit.wave.resource.frequency_moment(S, N, frequency_bins=None)[source]

Calculates the Nth frequency moment of the spectrum

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
N (int) – Moment (0 for 0th, 1 for 1st ….)
frequency_bins (numpy array or pandas Series (optional)) – Bin widths for frequency of S. Required for unevenly sized bins

Returns

m (pandas DataFrame) – Nth Frequency Moment indexed by S.columns

mhkit.wave.resource.significant_wave_height(S, frequency_bins=None)[source]

Calculates wave height from spectra

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
frequency_bins (numpy array or pandas Series (optional)) – Bin widths for frequency of S. Required for unevenly sized bins

Returns

Hm0 (pandas DataFrame) – Significant wave height [m] index by S.columns

mhkit.wave.resource.average_zero_crossing_period(S, frequency_bins=None)[source]

Calculates wave average zero crossing period from spectra

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
frequency_bins (numpy array or pandas Series (optional)) – Bin widths for frequency of S. Required for unevenly sized bins

Returns

Tz (pandas DataFrame) – Average zero crossing period [s] indexed by S.columns

mhkit.wave.resource.average_crest_period(S, frequency_bins=None)[source]

Calculates wave average crest period from spectra

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
frequency_bins (numpy array or pandas Series (optional)) – Bin widths for frequency of S. Required for unevenly sized bins

Returns

Tavg (pandas DataFrame) – Average wave period [s] indexed by S.columns

mhkit.wave.resource.average_wave_period(S, frequency_bins=None)[source]

Calculates mean wave period from spectra

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
frequency_bins (numpy array or pandas Series (optional)) – Bin widths for frequency of S. Required for unevenly sized bins

Returns

Tm (pandas DataFrame) – Mean wave period [s] indexed by S.columns

mhkit.wave.resource.peak_period(S)[source]

Calculates wave peak period from spectra

Parameters: S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
Returns: Tp (pandas DataFrame) – Wave peak period [s] indexed by S.columns

mhkit.wave.resource.energy_period(S, frequency_bins=None)[source]

Calculates wave energy period from spectra

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
frequency_bins (numpy array or pandas Series (optional)) – Bin widths for frequency of S. Required for unevenly sized bins

Returns

Te (pandas DataFrame) – Wave energy period [s] indexed by S.columns

mhkit.wave.resource.spectral_bandwidth(S, frequency_bins=None)[source]

Calculates bandwidth from spectra

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
frequency_bins (numpy array or pandas Series (optional)) – Bin widths for frequency of S. Required for unevenly sized bins

Returns

e (pandas DataFrame) – Spectral bandwidth [s] indexed by S.columns

mhkit.wave.resource.spectral_width(S, frequency_bins=None)[source]

Calculates wave spectral width from spectra

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
frequency_bins (numpy array or pandas Series (optional)) – Bin widths for frequency of S. Required for unevenly sized bins

Returns

v (pandas DataFrame) – Spectral width [m] indexed by S.columns

mhkit.wave.resource.energy_flux(S, h, deep=False, rho=1025, g=9.80665, ratio=2)[source]

Calculates the omnidirectional wave energy flux of the spectra

Parameters

S (pandas DataFrame or Series) – Spectral density [m^2/Hz] indexed by frequency [Hz]
h (float) – Water depth [m]
deep (bool (optional)) – If True use the deep water approximation. Default False. When False a depth check is run to check for shallow water. The ratio of the shallow water regime can be changed using the ratio keyword.
rho (float (optional)) – Water Density [kg/m^3]. Default = 1025 kg/m^3
g (float (optional)) – Gravitational acceleration [m/s^2]. Default = 9.80665 m/s^2
ratio (float or int (optional)) – Only applied if depth=False. If h/l > ratio, water depth will be set to deep. Default ratio = 2.

Returns

J (pandas DataFrame) – Omni-directional wave energy flux [W/m] indexed by S.columns

mhkit.wave.resource.energy_period_to_peak_period(Te, gamma)[source]

Convert from spectral energy period (Te) to peak period (Tp) using ITTC approximation for JONSWAP Spectrum.

Approximation is given in “The Specialist Committee on Waves, Final Report and Recommendations to the 23rd ITTC”, Proceedings of the 23rd ITTC - Volume 2, Table A4.

Parameters

Te (float or array) – Spectral energy period [s]
gamma (float or int) – Peak enhancement factor for JONSWAP spectrum

Returns

Tp (float or array) – Spectral peak period [s]

mhkit.wave.resource.wave_celerity(k, h, g=9.80665, depth_check=False, ratio=2)[source]

Calculates wave celerity (group velocity)

Parameters

k (pandas DataFrame or Series) – Wave number [1/m] indexed by frequency [Hz]
h (float) – Water depth [m]
g (float (optional)) – Gravitational acceleration [m/s^2]. Default 9.80665 m/s.
depth_check (bool (optional)) – If True check depth regime. Default False.
ratio (float or int (optional)) – Only applied if depth_check=True. If h/l > ratio, water depth will be set to deep. Default ratio = 2

Returns

Cg (pandas DataFrame) – Water celerity [m/s] indexed by frequency [Hz]

mhkit.wave.resource.wave_length(k)[source]

Calculates wave length from wave number To compute: 2*pi/wavenumber

Parameters: k (pandas Dataframe) – Wave number [1/m] indexed by frequency
Returns: l (float or array) – Wave length [m] indexed by frequency

mhkit.wave.resource.wave_number(f, h, rho=1025, g=9.80665)[source]

Calculates wave number

To compute wave number from angular frequency (w), convert w to f before using this function (f = w/2*pi)

Parameters

f (numpy array) – Frequency [Hz]
h (float) – Water depth [m]
rho (float (optional)) – Water density [kg/m^3]
g (float (optional)) – Gravitational acceleration [m/s^2]

Returns

k (pandas DataFrame) – Wave number [1/m] indexed by frequency [Hz]

mhkit.wave.resource.depth_regime(l, h, ratio=2)[source]

Calculates the depth regime based on wavelength and height Deep water: h/l > ratio This function exists so sinh in wave celerity doesn’t blow up to infinity.

P.K. Kundu, I.M. Cohen (2000) suggest h/l >> 1 for deep water (pg 209) Same citation as above, they also suggest for 3% accuracy, h/l > 0.28 (pg 210) However, since this function allows multiple wavelengths, higher ratio numbers are more accurate across varying wavelengths.

Parameters

l (array-like) – wavelength [m]
h (float or int) – water column depth [m]
ratio (float or int (optional)) – if h/l > ratio, water depth will be set to deep. Default ratio = 2

Returns

depth_reg (boolean or boolean array) – Boolean True if deep water, False otherwise

Performance

The performance submodule contains functions to compute capture length, statistics, performance matrices, and mean annual energy production.

`capture_length`	Calculates the capture length (often called capture width).
`statistics`	Calculates statistics, including count, mean, standard deviation (std), min, percentiles (25%, 50%, 75%), and max.
`capture_length_matrix`	Generates a capture length matrix for a given statistic
`wave_energy_flux_matrix`	Generates a wave energy flux matrix for a given statistic
`power_matrix`	Generates a power matrix from a capture length matrix and wave energy flux matrix
`mean_annual_energy_production_timeseries`	Calculates mean annual energy production (MAEP) from time-series
`mean_annual_energy_production_matrix`	Calculates mean annual energy production (MAEP) from matrix data along with data frequency in each bin

mhkit.wave.performance.capture_length(P, J)[source]

Calculates the capture length (often called capture width).

Parameters

P (numpy array or pandas Series) – Power [W]
J (numpy array or pandas Series) – Omnidirectional wave energy flux [W/m]

Returns

L (numpy array or pandas Series) – Capture length [m]

mhkit.wave.performance.statistics(X)[source]

Calculates statistics, including count, mean, standard deviation (std), min, percentiles (25%, 50%, 75%), and max.

Note that std uses a degree of freedom of 1 in accordance with IEC/TS 62600-100.

Parameters: X (numpy array or pandas Series) – Data
Returns: stats (pandas Series) – Statistics

mhkit.wave.performance.capture_length_matrix(Hm0, Te, L, statistic, Hm0_bins, Te_bins)[source]

Generates a capture length matrix for a given statistic

Note that IEC/TS 62600-100 requires capture length matrices for the mean, std, count, min, and max.

Parameters

Hm0 (numpy array or pandas Series) – Significant wave height from spectra [m]
Te (numpy array or pandas Series) – Energy period from spectra [s]
L (numpy array or pandas Series) – Capture length [m]
statistic (string) – Statistic for each bin, options include: ‘mean’, ‘std’, ‘median’, ‘count’, ‘sum’, ‘min’, ‘max’, and ‘frequency’. Note that ‘std’ uses a degree of freedom of 1 in accordance with IEC/TS 62600-100.
Hm0_bins (numpy array) – Bin centers for Hm0 [m]
Te_bins (numpy array) – Bin centers for Te [s]

Returns

LM (pandas DataFrames) – Capture length matrix with index equal to Hm0_bins and columns equal to Te_bins

mhkit.wave.performance.wave_energy_flux_matrix(Hm0, Te, J, statistic, Hm0_bins, Te_bins)[source]

Generates a wave energy flux matrix for a given statistic

Parameters

Hm0 (numpy array or pandas Series) – Significant wave height from spectra [m]
Te (numpy array or pandas Series) – Energy period from spectra [s]
J (numpy array or pandas Series) – Wave energy flux from spectra [W/m]
statistic (string) – Statistic for each bin, options include: ‘mean’, ‘std’, ‘median’, ‘count’, ‘sum’, ‘min’, ‘max’, and ‘frequency’. Note that ‘std’ uses a degree of freedom of 1 in accordance of IEC/TS 62600-100.
Hm0_bins (numpy array) – Bin centers for Hm0 [m]
Te_bins (numpy array) – Bin centers for Te [s]

Returns

JM (pandas DataFrames) – Wave energy flux matrix with index equal to Hm0_bins and columns equal to Te_bins

mhkit.wave.performance.power_matrix(LM, JM)[source]

Generates a power matrix from a capture length matrix and wave energy flux matrix

Parameters

LM (pandas DataFrame) – Capture length matrix
JM (pandas DataFrame) – Wave energy flux matrix

Returns

PM (pandas DataFrames) – Power matrix

mhkit.wave.performance.mean_annual_energy_production_timeseries(L, J)[source]

Calculates mean annual energy production (MAEP) from time-series

Parameters

L (numpy array or pandas Series) – Capture length
J (numpy array or pandas Series) – Wave energy flux

Returns

maep (float) – Mean annual energy production

mhkit.wave.performance.mean_annual_energy_production_matrix(LM, JM, frequency)[source]

Calculates mean annual energy production (MAEP) from matrix data along with data frequency in each bin

Parameters

LM (pandas DataFrame) – Capture length
JM (pandas DataFrame) – Wave energy flux
frequency (pandas DataFrame) – Data frequency for each bin

Returns

maep (float) – Mean annual energy production

mhkit.wave.performance.power_performance_workflow(S, h, P, statistic, frequency_bins=None, deep=False, rho=1205, g=9.80665, ratio=2, show_values=False, savepath='')[source]

High-level function to compute power performance quantities of interest following IEC TS 62600-100 for given wave spectra.

Parameters

S (pandas DataFrame or Series) – Spectral density [m^2/Hz] indexed by frequency [Hz]
h (float) – Water depth [m]
P (numpy array or pandas Series) – Power [W]
statistic (string or list of strings) – Statistics for plotting capture length matrices, options include: “mean”, “std”, “median”, “count”, “sum”, “min”, “max”, and “frequency”. Note that “std” uses a degree of freedom of 1 in accordance with IEC/TS 62600-100. To output capture length matrices for multiple binning parameters, define as a list of strings: statistic = [“”, “”, “”]
frequency_bins (numpy array or pandas Series (optional)) – Bin widths for frequency of S. Required for unevenly sized bins
deep (bool (optional)) – If True use the deep water approximation. Default False. When False a depth check is run to check for shallow water. The ratio of the shallow water regime can be changed using the ratio keyword.
rho (float (optional)) – Water density [kg/m^3]. Default = 1025 kg/m^3
g (float (optional)) – Gravitational acceleration [m/s^2]. Default = 9.80665 m/s^2
ratio (float or int (optional)) – Only applied if depth=False. If h/l > ratio, water depth will be set to deep. Default ratio = 2.
show_values (bool (optional)) – Show values on the scatter diagram. Default = False.
savepath (string (optional)) – Path to save figure. Terminate with ‘’. Default=””.

Returns

LM (xarray dataset) – Capture length matrices
maep_matrix (float) – Mean annual energy production

Graphics

The graphics submodule contains functions to plot wave data and related metrics.

`plot_spectrum`	Plots wave amplitude spectrum versus omega
`plot_elevation_timeseries`	Plot wave surface elevation time-series
`plot_matrix`	Plots values in the matrix as a scatter diagram
`plot_chakrabarti`	Plots, in the style of Chakrabarti (2005), relative importance of viscous, inertia, and diffraction phemonena Chakrabarti, Subrata.
`plot_environmental_contour`	Plots an overlay of the x1 and x2 variables to the calculate environmental contours.
`plot_compendium`	Create subplots showing: Significant Wave Height (Hs), Peak Period (Tp), and Direction (Dp) using OPeNDAP service from CDIP THREDDS Server.
`plot_boxplot`	Create plot of monthly-averaged boxes of Significant Wave Height (Hs) data.
`plot_avg_annual_energy_matrix`	Creates an average annual energy matrix with frequency of occurance.
`monthly_cumulative_distribution`	Creates a cumulative distribution of energy flux as described in IEC TS 62600-101.

mhkit.wave.graphics.plot_spectrum(S, ax=None)[source]

Plots wave amplitude spectrum versus omega

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed frequency [Hz]
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure is created.

Returns

ax (matplotlib pyplot axes)

mhkit.wave.graphics.plot_elevation_timeseries(eta, ax=None)[source]

Plot wave surface elevation time-series

Parameters

eta (pandas DataFrame) – Wave surface elevation [m] indexed by time [datetime or s]
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure is created.

Returns

ax (matplotlib pyplot axes)

mhkit.wave.graphics.plot_matrix(M, xlabel='Te', ylabel='Hm0', zlabel=None, show_values=True, ax=None)[source]

Plots values in the matrix as a scatter diagram

Parameters

M (pandas DataFrame) – Matrix with numeric labels for x and y axis, and numeric entries. An example would be the average capture length matrix generated by mhkit.device.wave, or something similar.
xlabel (string (optional)) – Title of the x-axis
ylabel (string (optional)) – Title of the y-axis
zlabel (string (optional)) – Colorbar label
show_values (bool (optional)) – Show values on the scatter diagram
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure is created.

Returns

ax (matplotlib pyplot axes)

mhkit.wave.graphics.plot_chakrabarti(H, lambda_w, D, ax=None)[source]

Plots, in the style of Chakrabarti (2005), relative importance of viscous, inertia, and diffraction phemonena Chakrabarti, Subrata. Handbook of Offshore Engineering (2-volume set). Elsevier, 2005.

Examples:

Using floats

>>> plt.figure()
>>> D = 5
>>> H = 8
>>> lambda_w = 200
>>> wave.graphics.plot_chakrabarti(H, lambda_w, D)

Using numpy array

>>> plt.figure()
>>> D = np.linspace(5,15,5)
>>> H = 8*np.ones_like(D)
>>> lambda_w = 200*np.ones_like(D)
>>> wave.graphics.plot_chakrabarti(H, lambda_w, D)

Using pandas DataFrame

>>> plt.figure()
>>> D = np.linspace(5,15,5)
>>> H = 8*np.ones_like(D)
>>> lambda_w = 200*np.ones_like(D)
>>> df = pd.DataFrame([H.flatten(),lambda_w.flatten(),D.flatten()], index=['H','lambda_w','D']).transpose()
>>> wave.graphics.plot_chakrabarti(df.H, df.lambda_w, df.D)

Parameters

H (float or numpy array or pandas Series) – Wave height [m]
lambda_w (float or numpy array or pandas Series) – Wave length [m]
D (float or numpy array or pandas Series) – Characteristic length [m]
ax (matplotlib axes object (optional)) – Axes for plotting. If None, then a new figure is created.

Returns

ax (matplotlib pyplot axes)

mhkit.wave.graphics.plot_environmental_contour(x1, x2, x1_contour, x2_contour, **kwargs)[source]

Plots an overlay of the x1 and x2 variables to the calculate environmental contours.

Parameters

x1 (numpy array) – x-axis data
x2 (numpy array) – x-axis data
x1_contour (numpy array or list) – Calculated x1 contour values
x2_contour (numpy array or list) – Calculated x2 contour values
**kwargs (optional) –

x_label: string (optional)
x-axis label. Default None.

y_label: string (optional)
y-axis label. Default None.

data_label: string (optional)
Legend label for x1, x2 data (e.g. ‘Buoy 46022’). Default None.

contour_label: string or list of strings (optional)
Legend label for x1_contour, x2_contour countor data (e.g. ‘100-year contour’). Default None.

axmatplotlib axes object (optional)
Axes for plotting. If None, then a new figure is created. Default None.

markers: string
string or list of strings to use as marker types

Returns

ax (matplotlib pyplot axes)

mhkit.wave.graphics.plot_avg_annual_energy_matrix(Hm0, Te, J, time_index=None, Hm0_bin_size=None, Te_bin_size=None, Hm0_edges=None, Te_edges=None)[source]

Creates an average annual energy matrix with frequency of occurance.

Parameters

Hm0 (array-like) – Significant wave height
Te (array-like) – Energy period
J (array-like) – Energy flux
time_index (DateTime Index) – time to index by. Optional default None. If None Passed parameters must be series indexed by Datetime.
Hm0_bin_size (float, int) – Creates edges of bin using this discrtization. Optional default None. If not passed must pass Hm0_edges.
Te_bin_size (float, int) – Creates edges of bin using this discrtization. Optional default None. If not passed must pass Te_edges.
Hm0_edges (array-like) – Defines the Hm0 bin edges to use. Optional default None.
Te_edges (array-like) – Defines the Te bin edges to use. Optional default None.

Returns

fig (Figure) – Average annual energy table plot

mhkit.wave.graphics.monthly_cumulative_distribution(J)[source]

Creates a cumulative distribution of energy flux as described in IEC TS 62600-101.

Parameters: J (Series) – Energy Flux with DateTime index
Returns: ax (axes) – Figure of monthly cumulative distribution

mhkit.wave.graphics.plot_compendium(Hs, Tp, Dp, buoy_title=None, ax=None)[source]

Create subplots showing: Significant Wave Height (Hs), Peak Period (Tp), and Direction (Dp) using OPeNDAP service from CDIP THREDDS Server.

See http://cdip.ucsd.edu/themes/cdip?pb=1&bl=cdip?pb=1&d2=p70&u3=s:100:st:1:v:compendium:dt:201204 for example Compendium plot.

Developed based on: http://cdip.ucsd.edu/themes/media/docs/documents/html_pages/compendium.html

Parameters

Hs (pandas Series) – significant wave height
Tp (pandas Series) – significant wave height
Dp (pandas Series) – significant wave height
buoy_title (string (optional)) – Buoy title from the CDIP THREDDS Server
ax (matplotlib axes object (optional)) – Axes for plotting. If None, then a new figure is created.

Returns

ax (matplotlib pyplot axes)

mhkit.wave.graphics.plot_boxplot(Hs, buoy_title=None)[source]

Create plot of monthly-averaged boxes of Significant Wave Height (Hs) data.

Developed based on:: http://cdip.ucsd.edu/themes/media/docs/documents/html_pages/annualHs_plot.html

Parameters

data (pandas DataFrame) – Spectral density [m^2/Hz] indexed frequency [Hz]
buoy_title (string (optional)) – Buoy title from the CDIP THREDDS Server
ax (matplotlib axes object (optional)) – Axes for plotting. If None, then a new figure is created.

Returns

ax (matplotlib pyplot axes)

mhkit.wave.graphics.plot_directional_spectrum(spectrum, min=None, fill=True, nlevels=11, name='Elevation Variance', units='m^2')[source]

Create a contour polar plot of a directional spectrum.

Parameters

spectrum (xarray.DataArray) – Spectral data indexed frequency [Hz] and wave direction [deg].
min (float (optional)) – Minimum value to plot.
fill (bool) – Whether to use contourf (filled) instead of contour (lines).
nlevels (int) – Number of contour levels to plot.
name (str) – Name of the (integral) spectrum variable.
units (str) – Units of the (integral) spectrum variable.

Returns

ax (matplotlib pyplot axes)

Contours

Contains functions for calculating environmental contours of extreme seastates

`environmental_contours`	Returns a Dictionary of x1 and x2 components for each contour method passed.
`PCA_contour`	Calculates environmental contours of extreme sea states using the improved joint probability distributions with the inverse first-order reliability method (I-FORM) probability for the desired return period (return_period).
`samples_full_seastate`	Sample a sea state between contours of specified return periods.
`samples_contour`	Get Hs points along a specified environmental contour using user-defined T values.

mhkit.wave.contours.environmental_contours(x1, x2, sea_state_duration, return_period, method, **kwargs)[source]

Returns a Dictionary of x1 and x2 components for each contour method passed. A method may be one of the following: Principal Component Analysis, Gaussian, Gumbel, Clayton, Rosenblatt, nonparametric Gaussian, nonparametric Clayton, nonparametric Gumbel, bivariate KDE, log bivariate KDE

Parameters

x1 (array) – Component 1 data
x2 (array) – Component 2 data
sea_state_duration (int or float) – x1 and x2 averaging period in seconds
return_period (int, float) – Return period of interest in years
method (string or list) – Copula method to apply. Options include [‘PCA’,’gaussian’, ‘gumbel’, ‘clayton’, ‘rosenblatt’, ‘nonparametric_gaussian’, ‘nonparametric_clayton’, ‘nonparametric_gumbel’, ‘bivariate_KDE’ ‘bivariate_KDE_log’]
**kwargs –

min_bin_count: int
Passed to _copula_parameters to sets the minimum number of bins allowed. Default = 40.

initial_bin_max_val: int, float
Passed to _copula_parameters to set the max value of the first bin. Default = 1.

bin_val_size: int, float
Passed to _copula_parameters to set the size of each bin after the initial bin. Default 0.25.

nb_steps: int
Discretization of the circle in the normal space is used for copula component calculation. Default nb_steps=1000.

bandwidth:
Must specify bandwidth for bivariate KDE method. Default = None.

Ndata_bivariate_KDE: int
Must specify bivariate KDE method. Defines the contoured space from which samples are taken. Default = 100.

max_x1: float
Defines the max value of x1 to discretize the KDE space

max_x2: float
Defines the max value of x2 to discretize the KDE space

PCA: dict
If provided, the principal component analysis (PCA) on x1, x2 is skipped. The PCA will be the same for a given x1, x2 therefore this step may be skipped if multiple calls to environmental contours are made for the same x1, x2 pair. The PCA dict may be obtained by setting return_fit=True when calling the PCA method.

return_fit: boolean
Will return fitting parameters used for each method passed. Default False.

Returns

copulas (Dictionary) – Dictionary of x1 and x2 copula components for each copula method

mhkit.wave.contours.PCA_contour(x1, x2, fit, kwargs)[source]

Calculates environmental contours of extreme sea states using the improved joint probability distributions with the inverse first-order reliability method (I-FORM) probability for the desired return period (return_period). Given the return_period of interest, a circle of iso-probability is created in the principal component analysis (PCA) joint probability (x1, x2) reference frame. Using the joint probability value, the cumulative distribution function (CDF) of the marginal distribution is used to find the quantile of each component. Finally, using the improved PCA methodology, the component 2 contour lines are calculated from component 1 using the relationships defined in Eckert-Gallup et. al. 2016.

Eckert-Gallup, A. C., Sallaberry, C. J., Dallman, A. R., & Neary, V. S. (2016). Application of principal component analysis (PCA) and improved joint probability distributions to the inverse first-order reliability method (I-FORM) for predicting extreme sea states. Ocean Engineering, 112, 307-319.

Parameters

x1 (numpy array) – Component 1 data
x2 (numpy array) – Component 2 data
fit (dict) – Dictionary of the iso-probability results. May additionally contain the principal component analysis (PCA) on x1, x2 The PCA will be the same for a given x1, x2 therefore this step may be skipped if multiple calls to environmental contours are made for the same x1, x2 pair. The PCA dict may be obtained by setting return_fit=True when calling the PCA method.
kwargs (optional) –

bin_sizeint
Data points in each bin for the PCA fit. Default bin_size=250.

nb_stepsint
Discretization of the circle in the normal space used for I-FORM calculation. Default nb_steps=1000.

return_fit: boolean
Default False, if True will return the PCA fit dictionary

Returns

x1_contour (numpy array) – Calculated x1 values along the contour boundary following return to original input orientation.
x2_contour (numpy array) – Calculated x2 values along the contour boundary following return to original input orientation.
fit (dict (optional)) – principal component analysis dictionary Keys: —– ‘principal_axes’: sign corrected PCA axes ‘shift’ : The shift applied to x2 ‘x1_fit’ : gaussian fit of x1 data ‘mu_param’ : fit to _mu_fcn ‘sigma_param’ : fit to _sig_fits

mhkit.wave.contours.samples_full_seastate(x1, x2, points_per_interval, return_periods, sea_state_duration, method='PCA', bin_size=250)[source]

Sample a sea state between contours of specified return periods.

This function is used for the full sea state approach for the extreme load. See Coe et al. 2018 for more details. It was originally part of WDRT.

Coe, R. G., Michelen, C., Eckert-Gallup, A., & Sallaberry, C. (2018). Full long-term design response analysis of a wave energy converter. Renewable Energy, 116, 356-366.

Parameters

x1 (np.array) – Component 1 data
x2 (np.array) – Component 2 data
points_per_interval (int) – Number of sample points to be calculated per contour interval.
return_periods (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.
sea_state_duration (int or float) – x1 and x2 sample rate (seconds)
method (string or list) – Copula method to apply. Currently only ‘PCA’ is implemented.
bin_size (int) – Number of data points in each bin

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.

mhkit.wave.contours.samples_contour(t_samples, t_contour, hs_contour)[source]

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

Parameters

t_samples (np.array) – Points for sampling along return contour
t_contour (np.array) – T values along contour
hs_contour (np.array) – Hs values along contour

Returns

hs_samples (nparray) – points sampled along return contour