MHKiT WPTO Hindcast Example

This example loads data from the WPTO hindcast data set, hosted on AWS.

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

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
year = 1995;
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 = struct with fields:
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.
ans = struct with fields:
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
12920×1 double2920×1 double2920×1 datetime1×1 struct
22920×1 double2920×1 double2920×1 datetime1×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
year = 1995;
parameter = ["peak_period","directional_wave_spectrum"];
lat_lon = [44.624076,-124.280097];
J = request_wpto(data_type,parameter,lat_lon,year,api_key)
J = struct with fields:
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]