MHKiT WPTO Hindcast Example
Dataset Description
The high-spatial-resolution dataset (hereafter the '3-hour' dataset) currently spans the U.S. Exclusive Economic Zone (EEZ) along the West coast and around Hawaii with an unstructured grid that has ~200 m resolution in shallow water. The time step resolution for this spatial data is 3-hours and spans 32 years, 01/01/1979 - 12/31/2010.
The 'virtual buoy dataset' (hereafter the '1-hour' dataset) is also available at specific locations within the large spatial domain. These virtual buoys span the same 32-years of the spatial dataset however the time resolution is 1-hour.
Included 3-hour Variables:
Dataset variables included are indexed by latitude and longitude, and time and include: energy_period, maximum_energy_period, mean_absolute_period, mean_zero-crossing_period, omni-directional_wave_power, peak_period, significant_wave_height, water_depth, spectral_width, and directionality_coefficient.
Included 1-hour Variables:
This dataset includes all variables in the spatial dataset as well as: directional_wave_spectrum, maximum_energy_direction, mean_wave_direction, and frequency_bin_edges.
Setting up Access to WPTO Hindcast Data
To access the WPTO hindcast data, you will need to configure h5pyd for data access on HSDS.
To get your own API key, visit https://developer.nrel.gov/signup/.
Using the WPTO Hindcast MHKiT Function
In this section we will walk through an example to request hindcast data at a point using MHKiT.
1. Download WPTO Hindcast data from a single location
In this example we will request 3-hour significant wave height for 1995 at the point (44.624076,-124.280097, near the PacWave site). We will specify each of these as a variable and pass them to the wave IO hindcast function request_wpto_dataset. The data type will be a high-spatial-resolution dataset, year(s) will be 1995, latitude/longitude pairs will be for a point near PacWave, and the parameter will be significant wave height.
data_type = '3-hour'; % setting the data type to the 3-hour dataset
lat_lon = [44.624076,-124.280097];
parameter = ["significant_wave_height"];
api_key = '3K3JQbjZmWctY0xmIfSYvYgtIcM3CN0cb1Y2w9bf'; % The example API key here is for demonstration and is rate-limited per IP
Hs = request_wpto(data_type,parameter,lat_lon,year,api_key)
Hs =
significant_wave_height: [2920×1 double]
time: [2920×1 datetime]
metadata: [1×1 struct]
The resulting structure is broken down into locations. Metadata can be found within each location. Since in this example we are accessing data from only one location, there is only a single group of fields contained in the structure. The significant wave height time series and location metadata are grouped together per location.
Hs.metadata
ans =
water_depth: 77.429496765136719
latitude: 44.624298095703125
longitude: -1.242789993286133e+02
distance_to_shore: 1.562217578125000e+04
timezone: -8
jurisdiction: 'Federal'
2. Download WPTO Hindcast data from multiple locations and parameters
Multiple locations can be requested by passing a matrix of lat/lon pairs (each row should be a pair). This time we will request the 3-hour energy period at two points. We can also request multiple parameters by grouping them together in a string array. The data type and years requested remain the same as before. By looking at the shape of the returned structure, we can see that two locations are returned. Again, each row of the struct will contain the returned data and metadata corresponding to the location.
parameter = ["energy_period","significant_wave_height"];
lat_lon = [44.624076,-124.280097;43.489171,-125.152137];
Te = request_wpto(data_type, parameter, lat_lon, year, api_key)
Te = 1×2 struct
| Fields | energy_period | significant_wave_height | time | metadata |
|---|
| 1 | 2920×1 double | 2920×1 double | 2920×1 datetime | 1×1 struct |
|---|
| 2 | 2920×1 double | 2920×1 double | 2920×1 datetime | 1×1 struct |
|---|
3. Download WPTO Hindcast 1-hour data
1-hour temporal resolutions data can be requested by passing '1-hour' as the data_type. Similarly, you can request multiple locations and multiple parameters as well. The format remains the same with one exception. When requesting "directional_wave_spectrum", this will add a frequency and direction dimension to that specific parameter. An example for requesting this higher temporal data is below.
data_type = '1-hour'; % Setting the data_type to 1-hour data
parameter = ["peak_period","directional_wave_spectrum"];
lat_lon = [44.624076,-124.280097];
J = request_wpto(data_type,parameter,lat_lon,year,api_key)
J =
peak_period: [8748×1 double]
directional_wave_spectrum: [8748×29×24 double]
time: [8748×1 datetime]
frequency: [29×1 double]
direction: [24×1 double]
metadata: [1×1 struct]