A collection of algorithms to autonomously identify and track mesoscale ocean eddies in sea surface height (SSH) satellite data. For immediate support email Ivy Frenger (ifrenger@geomar.de, see also https://github.com/ifrenger/OceanEddies).
An eddy identification algorithm that utilizes thresholding to detect eddies in SSH data.
There are two scripts which can be used to call eddyscan: scan_single.m
and scan_multi.m. The second script is can be used to scan many
timesteps at once. Below is an example for using scan_single.m
(assuming current directory is eddyscan):
% Find all anticyclonic eddies
ssh_slice = ncread('ssh_data.nc', 'Grid_0001');
landval = max(ssh_slice(:));
ssh_slice(ssh_slice == landval) = NaN;
lat = ncread('ssh_data.nc', 'NbLatitudes');
lon = ncread('ssh_data.nc', 'NbLongitudes');
lon(lon >= 180) = lon(lon >= 180)-360;
load('../data/quadrangle_area_by_lat.mat'); % Load areamap to compute eddies' surface areas
eddies = scan_single(ssh_slice, lat, lon, 'anticyc', 'v2', areamap);
scan_single(ssh,lat,lon,areamap,cyc,scan_type,...)
Detect all eddies for a particular timestamp.
ssh
- ssh slice with nans for land, size should be [length(lat) length(lon)]
lat
- 1D array of the latitudes of ssh gridlon
- 1D array of the longitudes of ssh gridcyc
- 'anticyc'
or 'cyclonic'
scan_type
- 'v1'
, 'v2'
, 'hybrid'
v2
and v1
scanning and will take the union of the two sets where, for common features, v2
bodies will be usedareamap
- A 2D array that refer to the area of each pixel in SSH data (should have same size as ssh), or 1D array that refer to area of each pixel for a specific lat in a regular grid (pixeld have same area for the same latitude)'minimumArea'
- minimum number of pixels for an eddy, used for validating eddies, default value is 9
'thresholdStep'
- the minimum step for thresholding, the unit is SSH's unit, default value is 0.05
'isPadding'
- whether or not to pad SSH data, should be true when scanning SSH data with the longitudes expanding the whole world dmap. Set to false if only partial SSH data is used. Default value is true'sshUnits'
- The units the SSH data is in. bottom_up_single is built to work natively on centimeter SSH data. Valid parameters are 'meters'
and 'centimeters'
. If the paramater passed in is 'meters'
, the SSH data will be multiplied by 100. No changes will be made if the paramater passed in is 'centimeters'
. The default value of 'sshUnits' is centimeters.scan_multi(ssh,lat,lon,areamap,cyc,scan_type,destdir,...)
Detect all eddies for all time steps. Results are saved to disk as specified by the destdir
paramter.
ssh
- ssh cube with nans for landlat
- A 1D array of double's that gives the latitude for a given index in ssh data , should be equal to size(ssh, 1)
lon
- A 1D array of double's that gives the longitude for a given index in ssh data, should be equal to size(ssh, 2)
dates
- A 1D array of the dates of ssh data, length should be equal to size(ssh, 3)
cyc
- 'anticyc'
or 'cyclonic'
scan_type
- 'v1'
, 'v2'
, 'hybrid'
v2
and v1
scanning and will take the union of the two sets where, for common features, v2
bodies will be useddestdir
- destination directory to save eddiesSame as scan_single
A tracking algorithm (surpassed by MHA) for eddies.
See track_lnn.m.
A tracking algorithm that maintains multiple hypothesis and does n-scan pruning. MHA can allow eddies to disappear for one timestep from the data to avoid breaking tracks.
To build MHA, run python setup.py build_ext -b mht
in mha/.
MHA can be called from within MATLAB, the command line, or python. See track_mha.m and track_mha.py for running from MATLAB or the command line respectively. Below is an example for using MHA in python:
import mht
eddies_path = '/path/to/eddyscan/out'
roots = mht.build_mht(mht.list_eddies(eddies_path, 'eddies'), do_lookahead=True)
mht.write_tracks(roots, 'cyclonic_tracks.mat', mht.list_dates(eddies_path, 'eddies'))
This eddy viewer will display eddy tracks from Eddyscan v2 together with SSH data background. It contains the following components (from left to right, top to bottom):
Currently, only a sample data set of the first 12 weeks (10/14/1992 to 12/30/1992) is uploaded on Github. Full viewer data (about 3GB) are available at http://gofc.cs.umn.edu/eddy_project/tracks_viewer_data.zip. Use prepare_viewer_data to download and unzip data.
start_track_viewer; % This script will start the viewer with sample data (first 12 weeks)