stormtracks API

Contents

Running

stormtracks.download – Download Necessary Data

stormtracks.download.download_full_c20(year)

Downloads each ensemble member’s values for prmsl, u and v

stormtracks.download.download_full_c20_range(start_year, end_year)

Downloads each ensemble member’s values for prmsl, u and v in a given range

stormtracks.download.download_ibtracs()

Downloads all IBTrACS data

Downloads compressed tarball from FTP site to settings.DATA_DIR. Decompresses it to settings.DATA_DIR/ibtracs

stormtracks.download.download_mean_c20(year)

Downloads mean values for prmsl, u and v

stormtracks.download.download_mean_c20_range(start_year, end_year)

Downloads mean values for prmsl, u and v in a given range

stormtracks.run_stormtracks – Run the Project

stormtracks.run_stormtracks.main(num_ensemble_members=56)

Entry point into local running of code

Runs through complete analysis, saves results using a results_manager.

Parameters:num_ensemble_members – how many ensemble members to analyse
Returns:results_manager that has complete set of results.

Main Modules

stormtracks.c20data – C20 Reanalysis Data

class stormtracks.c20data.C20Data(start_year, smoothing=False, upscaling=False, verbose=True)

Class used for accessing data from C20 Reanalysis project.

This acts as a wrapper around netCDF4.Datasets and makes it easy to view data. Typically it exposes the psl, vort, and vort4 fields for one ensemble member. (vort4 is calculated using a 4th order vorticity calculation.) It will load these fields, along with corresponding maxima (vorticity) and minima (pressure) each time a new date is set for an object.

Parameters:
  • start_year – Year from which to take data
  • smoothing – Apply smoothing to data fields
  • upscaling – Upscale data using cubic splines
  • verbose – Prints lots of output
close_datasets()

Closes all open datasets

cvorticity(u, v)

Calculates the (2nd order) vorticity by calling into a c function

cvorticity4(u, v)

Calculates the (4th order) vorticity by calling into a c function

Algorithm was taken from Walsh’s code

first_date(ensemble_member=0, ensemble_mode='member')

Sets date to the first date of the year (i.e. Jan the 1st)

fourth_order_vorticity(u, v)

Calculates the (4th order) vorticity using python

Algorithm was taken from Walsh’s code

load_datasets(year)

Loads datasets for a given year

If self.ensemble == True it will load the datasets with each ensemble member. Otherwise it will load the ensemble means datasets.

next_date(ensemble_member=0, ensemble_mode='member')

Moves date on by one timestep (6hr)

prev_date(ensemble_member=0, ensemble_mode='member')

Moves date back by one timestep (6hr)

set_date(date, ensemble_member=0, ensemble_mode='member')

Sets date and loads all data for that date

Will have no effect if there is no difference in date or ensemble_member.

Parameters:
  • date – date to load
  • ensemble_member – ensemble member to load
  • ensemble_mode – whether to load an individual member or take an average
Returns:

date if successful, otherwise None

set_year(year)

Sets a year and loads the relevant dataset

vorticity(u, v)

Calculates the (2nd order) vorticity using python

class stormtracks.c20data.GlobalEnsembleMember(c20data, ensemble_member=0)

Wrapper around a C20Data object

holds state of which ensemble member is currently being analysed

set_date(date)

Sets the date, does nothing if it is the same as the stored date

set_year(year)

Change the year of the stored C20Data object

stormtracks.ibtracsdata – IBTrACS Data

class stormtracks.ibtracsdata.IbStormtrack(year, name)

Holds info about an IBTrACS best track

class stormtracks.ibtracsdata.IbtracsData(data_dir=None, verbose=True)

Class used for accessing IBTrACS data

Wraps the underlying NetCDF4 files and extracts the infromation required from them.

Parameters:
  • data_dir – directory where IBTrACS NetCDF4 files are held
  • verbose – whether to pring lots of output
load_ibtracks_year(year, basin='NA')

Loads a given year’s worth of data

Parameters:
  • year – year to load
  • basin – which basins to load (‘all’ for all of them)
Returns:

list of loaded best tracks

load_wilma_katrina()

Loads only best tracks corresponding to Wilma and Katrina (2005)

stormtracks.tracking – Tracking of Features

class stormtracks.tracking.VortMax(date, pos, vort)

Holds key info (date, position, vorticity value) about a vorticity maximum.

To serialize this class (or any that contain objects of this class) you must make sure next_vortmax/prev_vortmax are None.

Parameters:
  • date – date of vortmax
  • pos – position (2 element tuple)
  • vort – vorticity value
add_next(vortmax)

Used to make doubly linked list of vortmaxes

class stormtracks.tracking.VortMaxTrack(start_vortmax)

Stores a collection of VortMax objects in a list and adds them to a dict that is accessible through a date for easy access.

class stormtracks.tracking.VortmaxFinder(gdata)

Finds all vortmaxes for a given ensemble member

Parameters:gdata – GlobalEnsembleMember to use
find_vort_maxima(start_date, end_date, use_upscaled=False)

Runs over the date range looking for all vorticity maxima

class stormtracks.tracking.VortmaxKalmanFilterTracker(Q_mult=0.001, R_mult=0.1)

Uses a Kalman Filter to try to track vorticity maxima

The main idea is to use the innovation parameter from the Kalman Filter estimation process as a measure of how likely it is that a vorticity maxima in a subsequent timestep belongs to the same track as a vorticity maxima in the current timestep

track_vort_maxima(vortmax_time_series)

Uses a generated list of vortmaxes to track them from one timestep to another

Parameters:vortmax_time_series – dict of vortmaxes
Returns:self.vort_tracks_by_date (OrderedDict)
class stormtracks.tracking.VortmaxNearestNeighbourTracker

Simple nearest neighbour tracker

Assumes that the two nearest points from one timestep to another belong to the same track.

track_vort_maxima(vortmax_time_series)

Uses a generated list of vortmaxes to track them from one timestep to another

Parameters:vortmax_time_series – dict of vortmaxes
Returns:self.vort_tracks_by_date (OrderedDict)

stormtracks.tracking – Matching of Tracks

class stormtracks.match.Match(best_track, vort_track)

Represents one match between a best track and a vorticity track

av_dist()

Returns the average distance between the best and vorticity tracks

stormtracks.match.combined_match(best_tracks, all_matches)

Uses all best tracks and matches to combine all matches for each best track

Parameters:
  • best_tracks – list of best tracks
  • all_matches – all matches to search through
Returns:

dict of combined_matches (key: best track, value: list of matches)

stormtracks.match.match(vort_tracks_by_date, best_tracks)

Takes all vorticity tracks and best tracks and matches them up

Uses CUM_DIST_CUTOFF to decide whether the two tracks are too far apart

Parameters:
  • vort_tracks_by_date – dict with dates as keys and lists of vort tracks as values
  • best_tracks – list of best tracks
Returns:

OrderedDict of Match objects * key: (best_track, vortmax) tuple * value: Match object

stormtracks.results – Store and Access Results

class stormtracks.results.StormtracksResult(dct)

Utility class that is easier to use than a dict

Parameters:dct – dict used to populate this class’ fields
class stormtracks.results.StormtracksResultsManager

Manager class that is responsible for loading and saving all results

Load/saves to settings.OUTPUT_DIR. Saves each result based on its year/ensemble_member (using that as a directory/filename structure). Saves each result as a name in a dictionary that then gets serialized to disk.

add_result(year, ensemble_member, name, result)

Adds a given result based on year, ensemble_member and a user chosen name

delete(year=2005, ensemble_member=0)

Deletes a specific result from disk

get_result(year, ensemble_member)

Gets a set of results based on year, ensemble_member

list_ensemble_members(year)

List all results saved for a particular year

list_years()

List all saved years

load(year=2005, ensemble_member=0)

Loads results from disk

print_list_years()

Print all saved results

save()

Saves all results that have been added so far

Utilities

stormtracks.utils.utils.dist(p1, p2)

Returns the cartesian distance between two points

stormtracks.utils.utils.find_extrema(array)

Takes an array and finds its local extrema.

Returns an array with 0s for not an extrema, 1s for maxs and -1 for mins and a list of the indices of all maximums and minimums

N.B. this function is much faster than the above.

stormtracks.utils.utils.find_extrema_slow(array, print_warning=True)

Takes an array and finds its local extrema.

Returns an array with 0s for not an extrema, 1s for maxs and -1 for mins and a list of the indices of all maximums and minimums

stormtracks.utils.utils.geo_dist(p1, p2)

Returns the geodesic distance between two points

stormtracks.utils.utils.pairwise(iterable)

s -> (s0,s1), (s1,s2), (s2, s3), ...

stormtracks.utils.utils.raster_voronoi(extrema, maximums, minimums)

Takes a 2D array and points of max/mins, and returns a 2D array with the voronoi sections filled with different values

stormtracks.utils.utils.upscale_field(lons, lats, field, x_scale=2, y_scale=2, is_degrees=True)

Takes a field defined on a sphere using lons/lats and returns an upscaled version, using cubic spline interpolation.

class stormtracks.utils.kalman.KalmanFilter(F, H)

Implementation of static Kalman Filter

Assumes a static model and observation operator.

Parameters:
  • F – model to use to update x (np.matrix)
  • H – observation operator (np.matrix)
estimate(x_init, P_init, z, Q, R)

Perform predict then update

Parameters:
  • Q – covariance matrix for uncertainty in model
  • R – covariance matrix for uncertainty in observation
Returns:

best estimate for x, P

predict(x_init, P_init, Q)

Predict where x, P will be based on model

update(x, P, z, R)

Update x, P based on new observation

class stormtracks.utils.kalman.Linear2DKalman

Linear 2D version of KalmanFilter

class stormtracks.utils.kalman.RTSSmoother(F, H)

Implementation of Rauch-Tung-Striebel smoother

process_data(zs, x, P, Q, R)
Parameters:
  • zs – measurements
  • x – initial state
  • P – initial covariance matrix
  • Q – process uncertainty covariance matrix
  • R – measurement uncertainty covariance matrix
Returns:

self.xs: all smoothed x values, self.Ps: all smoothed P values