Explore program methods, definitions, data conventions, and publications

There are a variety of data types that can be loaded.  The specific data types are described below.  See the tutorial on Direction Conventions for information of how wind and wave directions are stored and displayed.


1. Raw Wind and Wave Data


Raw data are the original wind and wave data files that are loaded.  Raw wave spectrum data come in many forms and are typically produced by instrument- or model-specific applications.  These data can be in ASCII or binary format and include various pieces of header information for identifying observation parameters such as time, location, water depth, etc.  Raw wind data are stored in a MATLAB™ *.mat file.


Specific data types supported are listed below.  Click on individual data types for specific data format detail.



Datawell Waverider data

Coastal Data Information Program (CDIP) data

Triaxys DIRSPEC data

Oceanweather Inc. hindcast data


Wavescan spectra files

Wavescan time series files

Rowe Technologies time series files

WAVEWATCH III model spectra files

SWAN model spectra files

ASL Wave Profiler data

Generic 2D

Generic 1D

Generic ASCII

NDBC real-time data (Disk file and WWW download)

NODC Historical data (Disk file and WWW download)

NetCDF-formatted data


When available, wind data can also be loaded to improve the analysis of the wave data.  There are two types of MATLAB (*.mat) wind files that can be loaded.


For wind speed and direction data, a matrix named ‘wind’ has the following data columns:

1. Year (YYYY)

2. Month (MM)

3. Day (DD)

4. Hour (hhhh)

5. Minute (mm)

6. Second (ss)

7. Wind direction (deg from North)

8. Wind speed (m/s)


In the above wind file, the column containing Second (ss) data is optional.  Thus this file can have 7 or 8 columns of data.


The second type of wind data than can be loaded is Friction Velocity (u*).  This is also a MATLAB file with the name ‘wind’.  However in this case the data are in a structure:


 wind.time – row vector of datenum times for the observations

 wind.ustar – row vector of friction velocity (m/s) values


It is anticipated that the above 2 wind file types will be merged in the future.


Custom data formatters are available by request from WaveForce Technologies


2. Processed Data

Processed data are stored in special output structure called wavedat.  Each processing module adds specific fields into this structure.  A summary of the wavedat fields associated with each processing step is given below.



Loaded Wave Data

Loading wave data in Start Up creates a new wavedat structure with the following fields:


file: (string)

Processing History

name: (string)

Data Set Name

size: (double)

Number of Records

time: [1x size double]

Observation Date and Time as MATLAB Serial Date Number

espt: {1x size cell}

Directional Wave Spectra (m2/(hz x deg)

dwAvv: {1x size cell}

1D Energy-Frequency Spectra

df: [1x nfreq double]

Array of Frequency Bin Differentials (dwfhz(n+1) – dwfhz(n))

da: (double)

Angle Bin Width (deg)

dwfhz: [1x nfreq double]

Array of Frequency Bins (Hz)

dwdeg: [1x nang double]

Array of Angle Bins (deg)

hs: [1x size double]

Significant Wave Height (m)

fp: [1x size double]

Peak Frequency (Hz)

tz: [1x size double]

Zero Crossing Period (s)

dm: [1x size double]

Mean Wave Direction (Deg From North)

thetap: [1x size double]

Peak Wave Direction (Deg From North)

sp: [1x size double]

Directional Spread (deg)

winddir: [1x size double]

Wind Direction (Deg From North)

windspeed: [1x size double]

Wind Speed (m/s)

ustar: [1x size double]

Friction Velocity (m/s) – this field is optional

type: '2D' or ‘1D’,

Specifies Directional or Non-Directional Data

lat: (double)

Latitude (decimal degrees +N/-S)

lon: (double)

Longitude (decimal degrees +E/-W)

depth: (double)

Water Depth (m)

param_rfmt: [1x1 struct]

Reformat Parameters used to Load Data Set

RecordsList {size x 1 cell}

Date and Time String for each Record


Processed Wave Data

Running the Wave Systems Module adds the following new wavedat fields:


out: [1x1 struct]

Wave Partitioning Results (See Below)

parsum: [1x240 struct]

Wave Partition Templates

windtype: (string)

Specifies Observed or Estimated Winds

param_trk: [1x1 struct]

Wave System Parameters used to Process Data Set


The fields in wavedat.out contain information on the individual wave components (spectral partitions):


time: [1xM double]

Date and Time of Partition Record as MATLAB Serial Date Number

azimuth: [1xM double]

Mean Direction (Deg from True North)

thetap [1xM double]

Peak Direction (Deg from True North)

freq: [1xM double]

Peak Frequency (Hz)

tz: [1xM double]

Zero-Crossing Period (s)

grp: [1xM double]

Wave System Number

sys: [1xM double]

Swell Event Number

totnrg: [1xM double]

Total Energy (m2)

sighight: [1xM double]

Significant Wave Height (m)

dirspread: [1xM double]

Directional Spread (deg)

par: [1xM double]

Partition Number

wforce: [1xM double]

Wave Force Ratio



*m is the total number of partitions found in all records



3. Export Data

A variety of data export options are offered, including image files, animations, and summary tables.  See the Data Export Wizard for details on custom export tables in a variety of formats.




Parameter set name


Observation year


Latitude (decimal degrees)


Longitude (decimal degrees)


Magnetic compass correction (deg)




Processing method [1=On-Board, 2=Off-Board]




Process all files [1=True, 0=False]


Index within directory of files to process


Parameter setting to use [1=True, 0=False]


Estimate winds [1=True, 0=False]


Water depth (m)


Data smoothing interval (h)


Data sub sample interval (h)


Number of output angle bins


Path to raw data


File name extension for raw data


Full path to input wind data


Input data type string


Specifies which parameter set to use for multiple saved parameter sets of the same datatype


Identify specific records of OceanWeather NetCDF files


Identify index of meaningful characters within a file name (buoyname, year, month, day, hour, minute)


Index of NDBC station from internal Wwavector list (NDBC_Wave_Station_Info.mat)


Date string for NODC data


Minimum data gap for estimating winds (h)


Wind measurement height (m)


Wind data set number


Full path to NetCDF input file


NetCDF mode [0=Disabled, 1=New file, 2=Append file]


Number of days to process from NDBC buoy




Parameter set name


Wind sea multiplier


Minimum swell wave weight (m)


Spread factor


Maximum number of swells per record


Variance threshold


Minimum number of records


Swell separation angle


Parameter setting to use [1=True, 0=False]


Spectral smoothing threshold


Trend analysis window (h)


Wind sea identifier




Wind force threshold


Friction velocity


Number of spectrum division levels for partitioning




Parameter set name


1D Wind sea fit type


1D Swell fit type


Parameter setting to use [1=True, 0=False]


2D Wind sea fit type


2D Swell fit type


Conserve wave energy flag [1=True, 0=False]


Conserve wave period flag [1=True, 0=False]


Wave period tolerance (s)


JONSWAP fit type




Parameter set name










Scatter table data normalization


Significant wave height (m) increment between wave height bins


Wave period (s) increment between wave period bins


Number of wave direction bins


Array of computed bin centers


Array of computed width between bins


Parameter setting to use [1=True, 0=False]




Select peak period or zero-crossing period




Wind speed PoT threshold type


Wind speed PoT threshold value


Wave height PoT threshold type


Wave height PoT threshold value


PoT minimum time lag (h) between successive events


Compute 95% confidence intervals [1=True, 0=False]




Number of records to keep in memory


Structure of NetCDF data fields




Parameter set name


Parameter setting to use [1=True, 0=False]


Baseline data smoothing interval (h)


Baseline data subsample interval (h)


Maximum allowable time gap for matching records (h)


Wind speed PoT threshold type


Wind speed PoT threshold value


Wave height PoT threshold type


Wave height PoT threshold value


Process and compare wave systems flag


Number of swell groups to compare


Method to delineate swells, wave height or period


Wave period (s) used to delineate swells


Full path to baseline data


Full path to evaluate data


Full path to NetCDF data


PoT minimum time lag (h) between successive events


PoT search window duration (h) to match peaks in baseline/evaluate data




Parameter set name


Parameter setting to use [1=True, 0=False]


Maximum number of output partitions


Format of export data file (ASCII, EXCEL or mat file)


Structure containing output header options


Structure containing all output data fields




Parameter set name


Import data type


Full path for *.mat data file


Parameter setting to use [1=True, 0=False]


Reformat parameters (parameters.reformat) set number to be used [Disable=-1]


Wave Systems parameters (parameters.tracking) set number to be used [Disable=-1]


Spectral Fit parameters (parameters.specfit) set number to be used [Disable=-1]


Export Wizard parameters (parameters.export) set number to be used [Disable=-1]


Sea State (parameters.seastate) parameters set number to be used [Disable=-1]


AutoWaves flag to display processing waitbars [Enable=1, Disable=0]


Full path of XWaves format .mat file to process data from [Disable=[]]


Structure containing NetCDF parameters [FieldName, nrec, NCFile, records]


Save Data to .mat Flag [Enable=1, Disable=0]


Export plots? [Enable=1, Disable=0]


Array of flags to output each available plot [Enable=1, Disable=0]


Format of export plots [.bmp, .jpg, .pdf, .png, .tif, .emf, or .fig]


Path to save plots


Automatic processing option [Enable=1, Disable=0]


Automatic processing interval (h)


Append automatic processing to existing output file? [Enable=1, Disable=0]


Full path to export wizard output file


Full path to spectral coefficient text file


Spectral coefficient text file output flag [Enable=1, Disable=0]


Single record per spectral coefficient text file [Enable=1, Disable=0]


BlueFat Table File Output Flag [Enable=1, Disable=0]


Full path for BlueFat table output file


Full path to vessel heading file for BlueFat table


Enable downloading from NDBC stations? [Enable=1, Disable=0]


Array of flags to download each available NDBC Station [Enable=1, Disable=0]


Path to save NDBC station data


Log file options. [0=log all actions, 1=log error messages only]


Windows Service Update Option


Wave height recurrence table output flag [Enable=1, Disable=0]


Full path to wave height recurrence table


Wind speed recurrence table output flag [Enable=1, Disable=0]


Full path to wind speed recurrence table


Save output data option [‘single’, ‘individual’, or ‘monthly’]


Frequency axis scaling [‘Log’ or ‘Linear’]

A variety of statistical parameters are calculated by the software and can be exported for additional use.  Here we provide the definitions of these parameters.


Metadata Fields

Date and Time

A Matlab serial date number is stored for each wave record and corresponding statistical parameter.  The serial date number represents the whole and fractional number of days from a fixed, preset date (January 0, 0000). Upon exporting, date and time is converted to a standard string format: yyyy-mm-dd HH:MM:SS.


Typically the data are assumed to be referenced to Greenwich Mean Time (GMT).  However the wavedat data structure allows inclusion of a time zone field which specifies the offset from GMT in hours.  See Data Formats for additional information.



Each data set is referenced to a specific geographic location.


Latitude is saved in decimal degrees (+N/-S)

Longitude is saved in decimal degrees (+E/-W)


Water Depth

Each data set is referenced to a specific water depth.

Water Depth (m) is saved as a positive number with mean sea level as 0.


Wind Parameters

Wind information can either be imported or estimated by the software.  Saved wind information includes speed (m/s) and direction (deg from N).

Wind data can be stored with reference to a measurement height above the ocean surface, windz (m).  Otherwise the reference height is assumed to be 10 m.


Wave Parameters

Wave statistics can be computed from the full wave spectrum, wave spectrum partitions, or from model fits to the spectrum (JONSWAP, Lognormal, etc.). In all cases the equations are the same.


Wave Spectrum

The Directional Wave Spectrum S(f,θ) provides the distribution of wave ‘energy’ or variance (m 2/(Hz*deg)) as a function of wave frequency f (Hz) and wave direction θ (deg from N).


Integration of S(f,θ) over direction yields the Frequency Spectrum



Likewise, integration of S(f,θ) over frequency yields the Direction Spectrum



With the total energy (variance) in the spectral domain given by the zeroth moment




Wave Statistics

A variety of statistical parameters are computed from the wave spectra, including the Significant Wave Height, approximated by Hmo



the Peak Wave Period



with Peak Wave Frequency fp computed from a 3-point parabolic fit to the Frequency Spectrum peak;

the Mean Wave Period (zero-crossing)



with the second moment given by



The deep-water Wavelength is calculated from the Mean Wave Period



And the deep water Phase Speed is given by



with gravitational acceleration g=9.81 m/s2.

The Peak Direction (deg from N) is the directional bin with the highest total energy (summed over frequency).


Also computed is the Mean Wave Direction



with bulk Fourier coefficients






and the Directional Spread








O'Reilly, W. C., T. H. C. Herbers, R. J. Seymour, and R. T. Guza, 1996. A comparison of directional buoy and fixed platform measurements of pacific swell. J. Atmos. Ocean. Tech. 13(1), 231-238.

Kuik, A. J., G. P. van Vledder, and L. H. Holthuijsen, 1988.  A method for the routine analysis of pitch-and-roll buoy wave data, J. Phys. Oceanogr., 18, 1020–1034.


Additional Information

Data Formats

Direction Conventions

Data Export Wizard




In general all wind and wave directions are stored in the standard meteorological “Degrees from North” convention, where angles rotate clockwise from north (0 Deg).


All plots display directions with this convention with the exception of vector plots, such as the Wave Systems Vector Plot in the Wave Systems Module. The vector plots rotate wind and wave directions 180 degrees to display them in vector form as “Degrees towards”, again with rotation clockwise from north.


The only exception to this direction convention rule is with the BlueFat table export function, which provides the option to rotate all directions relative to ship azimuth (180 = head on seas). For this feature a ship heading file must be provided by the user.


Magnetic Compass Corrections


As many conventional wave sensors collect wave direction data using a magnetic compass, correction is necessary in order to rotate the wave directions relative to True North. Most of the data formatters allow the user to input a Magnetic Compass Correction factor to facilitate this correction. This parameter is the magnetic declination, sometimes called magnetic variation, which is the angle between magnetic north and true north. The Magnetic Compass Correction should be entered as positive east of true north and negative when west. The input wave directions will be rotated by this angle to generate directions relative to True North.


The magnetic compass correction is a function of latitude and longitude and can be computed on a web page hosted by the National Geophysical Data Center:


The following data manipulations are facilitated by the Data Utilities Module.


Smooth Records

The Smooth Records option performs a weighted running average over the specified records.  The utility uses a user-specified duration (h) to select directional wave spectra records to smooth.  A weighted smooth function is generated that provides 100% weighting at the center record and 50% weighting at the tails.  All statistical parameters are then recalculated based on the smoothed spectra.


If wind and/or friction velocity data are present, the wind directions are vector-averaged and the wind speeds are scalar averaged over the smoothing window.  No taper is applied for winds.

For example, assume a 5-h smooth is applied to half-hourly records.  The sliding window will smooth all wind and wave data occurring up to 2.5-h prior and 2.5-h after each observation time.  For wave data, the +/- 2.5-h records will only contribute 50% to the averaging process.


This feature is helpful for noisy spectra, usually obtained from short time series records, and will help reduce Wave Systems processing time by eliminating spurious peaks.


SubSample File

The SubSample option reduces user data file sizes by saving only those records that occur at a user-specified time interval (h).    Records that fall in-between this interval are removed.


For example, if a 3-h data subsample interval is selected for data that is provided hourly, the first record will be saved and the second and third records will be discarded.  This pattern will repeat through the entire data set.

This feature is helpful for decreasing the size of large files, and will reduce Wave Systems processing time by providing fewer records to process.


Spectral Resolution

The Spectral Resolution utility is used to change the frequency range, frequency resolution, and directional resolution of the wave spectra in a file.  The user specifies the desired frequency range, number of frequency bins, and number of angle bins.  A two-dimensional linear interpolation is then performed on the Input spectra S(f,θ) to result in the requested frequency and direction resolution.  All statistical parameters are then recalculated based on the interpolated spectra.


This utility can greatly reduce output file sizes and save on Wave Systems processing times for large data sets.  It can also be used to smooth noisy spectra.


Append File

The Append File utility is used to append another data set to the beginning or end of the current user data set.  Files selected to append must have observation times that either precede or follow the observation times of the user data in memory.


Subset File

The Subset File utility allows the user to create a new data file from a subset of a loaded data file.  The subsetting is performed based on user-provided start and stop times.


Remove Records

The Remove Records utility allows the user to discard records from a loaded data file.  The records are removed based on user-provided start and stop times.



The Rename utility allows the user to change the name of a loaded data set.  Selecting Rename will not cause any other data to be reprocessed or lost.


Additional Information:

Data Utilities Module


Wave spectral partitioning provides an efficient approach to characterize energy levels of individual wind-sea and swell wave components in directional wave spectra. Here a ‘wave component’ is defined as a specific wind-sea or swell that can be attributed to a region of enhanced energy in the directional wave spectrum. The time evolution of a series of related wave components forms a ‘wave system’ that can be traced to a specific generation region on the ocean surface. Wave spectral partitioning methods have been applied in a variety of investigations, including the comparison of wave fields from the Labrador Sea Extreme Waves Experiment (Beal 1989), the validation of WAve Model WAM performance against ERS-1 SAR spectra (Hasselmann et al. 1994), the assimilation of wave observations into the WAM model (Voorrips et al. 1997), the analysis of wind sea growth and dissipation in the open ocean (Hanson and Phillips 1999), a study of swell evolution across the Pacific (Hanson and Phillips 2001), and an analysis of nearshore wave climatology (Scott et al. 2002).


Originally proposed by Gerling (1992), wave partitioning allows the identification and grouping of component wave systems from spatially and temporally distributed observations of directional wave spectra. A primary limitation to the Gerling approach is that only those portions of the spectrum that rise above a constant threshold are used to determine the features of particular wave component. Hasselmann et al. (1994) improved on this method by dividing the spectrum into subset domains based on an inverted catchment area approach, thus using the entire spectral region of each peak to compute wave component parameters. Hanson (1996) and Hanson and Phillips (2001) made further improvements to the technique by adding clustering routines to track the evolution of individual wave components and dispersion calculations to estimate the source time and location of resulting wave systems. Work has continued on the development of these techniques since the publication of Hanson and Phillips (2001), hereinafter referred to as HP01, to the point that we now have a fully automated, GUI-driven system employing modern image processing technology for performing a wide range of wave system analyses on time-evolving series of directional wave spectra.


For completeness, we summarize the methods here and provide detail on the improvements that have been made since HP01.


Wave Component Identification

The first step of spectral partitioning is to isolate spectral regions S(f,θ) associated with individual energy peaks. This was accomplished by HP01 with a time-consuming recursive algorithm that assigned each spectrum value to a path of steepest ascent associated with a local peak. All paths leading to the same peak were assigned to a distinct spectral partition. This step has been improved with efficient image processing routines that were designed for making watershed delineations in topographic imagery (Soille 1999, Vincent and Soille 1991). Treating the spectrum as an inverse topographic domain, an 8-point connected smoothing transform removes fine-scale noise in the spectrum. A watershed delineation transform then identifies the boundaries forming the minima between remaining spectral peaks. Spectral regions surrounded by such boundaries become individual partitions. This change in basic methodology has reduced by an order of magnitude the time required to process each record, with essentially no change in output results.


Wave Component Identification

Once the initial partitions are identified, a variety of component statistics are computed to aid with further processing. These include the 1D energy spectrum



the total energy in the 2D spectral domain



the significant wave height, approximated by Hmo



and the peak wave period



with the peak wave frequency f p computed from a 3-point parabolic fit to the 1D spectral peak. Also computed is the vector mean wave direction







and the directional spread (O’Rielly et al. 1996)







with bulk Fourier coefficients



Both full spectrum and spectral component statistics are computed using the above relationships. Integration domains are implied to be over all frequency bins and from 0 to 2π in direction. For computing statistics of a spectral component, all spectral values not falling within the partition domain are set to zero.


Wind-sea and swell combinations

The resulting wave components are sorted into wind-sea or swell. To be classified as wind-sea, a spectral peak must be forced by a component of the existing wind. A wave-age criterion is used to identify and combine the 2D wind-sea partitions. All remaining peaks are labeled as swell. Adjacent 2D swell peaks that are contiguous in frequency can be part of the same swell system and are combined under certain conditions. Two tests are made to determine if adjacent swell peaks belong to the same wave system. A swell angle threshold test requires the mean directions of adjacent peaks be separated by less than a threshold angle. A threshold value of 30 deg yielded optimum results with the Pacific Ocean data and provided a comfortable margin outside the stated +/-10-deg accuracy of the buoy directions. A second test compares the f, θ spectral distance between peaks in relation to their individual spectral spreads. Peaks are combined if the spread of either peak is large compared to the distance between the two peaks. Wave component statistics are updated after each combination is made.


Minimum Wave Height Threshold and Storage of Results

As a final step in producing consistent results with minimal noise, any wind-sea or swell component that falls below a significant wave height threshold of 0.1 m is removed from analysis and labeled as miscellaneous energy.


The partitioning results are stored in a wave component template T(f,θ) that has the same degrees of freedom and cut-off frequency as the input spectrum. Matrix values contained in the template can be one of the following:


Matrix Value



Wind Sea


Swell System ID


Miscellaneous Energy


An example of a partitioned buoy spectrum containing a wind-sea and three swell components appears in Fig 1.


Swell Tracking

Once a time series of directional wave spectra has been partitioned, a clustering algorithm is used to link common wave components together through time. This results in the generation of wave systems, which are statistically represented by time-evolving series of Hs (approximated by H mo), T p, and attributes associated with each wave component. A convenient display of these features is in the form of the wave vector history plot shown in Fig 2a. At any given time, the wave field is composed of multiple wave components that are members of a distinct evolving wave system. For example, the wave vectors at the dashed vertical line in Fig 2a correspond to the wave components identified in Fig. 1. The wave vector history shows how these particular components evolve through time. Wind-seas (black arrows) are driven by local winds. The swell events are more persistent, with systems from the North and South Pacific both typically lasting about 6 days. It is interesting to note that the two most energetic wave height events during this two-week period (Fig. 2b) are a result of the superposition of locally increased wind-seas with energetic swells from three different origins.

Note: Energy levels logarithmically scaled to the peak value


Fig. 1. Example partition results for buoy station 51028 2D spectrum on 9 November 2000 (0700 GMT). White lines denote the boundaries of each wave component as represented in the partition template T(f,θ). Note that this record contains a wind sea (0), North Pacific swell (1), South Pacific Swell (2), and a more locally generated easterly swell (3).


Fig. 2. Example results from Spectral Partitioning Module showing persistent wave system evolution during November 2000 at NDBC Station 51028. a. Wave vector history. Wave vectors represent the height (length), peak frequency (origin), and direction of travel (azimuth) of evolving wave systems (color-coded). For clarity, only wave systems persisting 10-h or longer are displayed. b. Full-spectrum significant wave height.




Beal, R. C., Ed, 1989: Directional Ocean Wave Spectra. The Johns Hopkins University Press, Baltimore, MD, 218 pp.

Gerling, T. W., 1992: Partitioning sequences and arrays of directional ocean wave spectra into component wave systems. J. Atmos. Oceanic Technol., 9, 444-458.

Hanson, J. L., 1996: Wind sea growth and swell evolution in the Gulf of Alaska. Ph.D. Dissertation, the Johns Hopkins University, 151 pp.

Hanson, J. L., and O. M. Phillips, 2001: Automated analysis of ocean surface directional wave spectra. J. Atmos. Oceanic. Technol., 18, 277-293.

Hanson, J. L., and O. M. Phillips, 1999: Wind sea growth and dissipation in the open ocean. J. Phys. Oceanogr, 29, 1633-1648.

Hasselmann, S., K. Hasselmann, and C. Bruning, 1994: Extraction of wave spectra from SAR image spectra. Dynamics and Modelling of Ocean Waves, G.J. Komen et al., Eds., Cambridge University Press, 391-401.

O’Reilly, W.C., T.H.C. Herbers, R.J. Seymour and R. T. Guza, 1996: A comparison of directional buoy and fixed platform measurements of Pacific Swell. J. Atmos. Oceanic. Technol., 13 (1), 231-238.

Scott, D., D. Resio and C. Pantoja, 2002: Swell propagation and nearshore wave climate. 7th International Workshop on Wave Hindcasting and Forecasting, Meteorological Service of Canada, 13-24.

Soille, P., 1999: Morphological Image Analysis: Principles and Applications. Springer-Verlag, 170-171.

Vincent, L., and P. Soille, 1991: Watersheds in digital spaces: An efficient algorithm based on immersion simulations. IEEE Transactions of Pattern Analysis and Machine Intelligence, 13(6), 583-598.

Voorrips, A. C., V. K. Makin and S. Hasselmann, 1997: Assimilation of wave spectra from pitch-and-roll buoys in a North Sea wave model. J. Geophys. Res. 102, 5829-5849.

Please send all questions, comments, or suggestions to: