Storm Surge Alerts Feeds¶

Development Notes¶

Notes about development of ATOM/RSS feeds for storm surge alerts. Started in the process of working out the details of how to provide a feed to Port Metro Vancouver during the 2015/2016 storm surge season. Consideration is also given to the possibility of providing a wider collection of feeds in the future.

Port Metro Vancouver presently consumes Environment Canada feeds, so we use that as our pattern.

Feeds are generically referred to as RSS, but there are 2 current standards for them: ATOM and RSS-2.0. EC uses ATOM, and it seems to be somewhat more favourable technically, so that's what we'll focus on initially.

The IETF standard for ATOM is RFC 4287.

The Vancouver weather forecast web page has links to the weather forecast feed, and the weather alerts feed. Using the Firefox "View Page Source" function on the page that loads from either of those feed links lets you see the structure of the feed content.

Other useful links:

• A blog post about creating ATOM ID elements

• A blog post (linked from the above one) about using tag URIs as ATOM IDs

• The Python feedgen package documentation,

Github repository, and PyPI page.

URLs¶

The storm surge alerts feeds will be located under http://salishsea.eos.ubc.ca/storm-surge/.

The initial ATOM feed for Port Metro Vancouver (PMV) will be http://salishsea.eos.ubc.ca/storm-surge/atom/pmv.xml.

That pattern can be extended to provide other feed like:

• One containing alert messages for the entire model domain

based on Ben's narrative template developed during the Aug-2015 sprint: http://salishsea.eos.ubc.ca/storm-surge/atom/alerts.xml

• Feeds for specific locations: http://salishsea.eos.ubc.ca/storm-surge/atom/PointAtkinson.xml
• Feeds customized for other stakeholders

This URL structure also allows for the possibility of generating RSS-2.0 feeds in the future at locations like:

• http://salishsea.eos.ubc.ca/storm-surge/rss/pmv.xml
• http://salishsea.eos.ubc.ca/storm-surge/rss/alerts.xml
• http://salishsea.eos.ubc.ca/storm-surge/rss/PointAtkinson.xml
• etc.

Even though the PMV and Point Atkinson feeds are for the same geolocation and are expressions of the same model results, they are treated separately so that the PMV feed can be customized with units, threshold levels, etc. requested by that stakeholder.

Generating the PMV Feed¶

EC appears to generate a new feed each time the forecast page is updated (so, hourly, at least) rather than appeding new feed entries to an existing feed. We will adopt the same practice for the PMV feed:

• A new feed will be generated each day after the forecast and forecast2 runs
• In contrast to EC, who always have at least new current conditions to report on,

we will only generate feed entries when the Point Atkinson water level is forecast to exceed the risk and extreme risk thresholds

We'll use the feedgen package to construct the feed and its entries and store them to disk.

Instead of pretty-printing the ASCII version of the feed, the production code will save it as binary data in a file with:

fg.atom_file(os.path.join(path_to_storm_surge, 'atom', 'pmv.xml')

The only really interesting bit in the code above is the calculation of the id element for the feed. Quoting Mark Pilgrim's blog post:

There are three requirements for an Atom ID:

1. The ID must be a valid URI, as defined by RFC 2396.
2. The ID must be globally unique, across all Atom feeds, everywhere, for all time. This part is actually easier than it sounds.
3. The ID must never, ever change.

We use the tag URI technique to create our id with the EC tactic of appending the UTC feed create date/time as a string of digits:

tag:salishsea.eos.ubc.ca,2015-12-12:/storm-surge/atom/pmv/20151221020629

This tag is composed of:

• Our domain name: salishsea.eos.ubc.ca
• A comma
• The date on which this scheme was conceived: 2015-12-12
• A colon
• The path to the feed file, excluding the .xml extension: /storm-surge/atom/pmv
• The UTC date/time when the feed was created as a string of digits, prepended with a '/': /20151221020629

Generating a PMV Feed Entry¶

The feed above will be generated after every forecast and forecast2 run by the make_feeds worker between the successful completion of the make_site_page forecast publish worker and the launch of the push_to_web worker.

If the Point Atkinson water level is forecast to exceed the risk and extreme risk thresholds, the make_feeds worker will also add an entry to the feed. Apart from the calculation of the alert text for the entry, its creation looks like:

Each entry also requires a unique id. Here we use a similar algorithm to the feed id except that the date/time is local rather than UTC:

tag:salishsea.eos.ubc.ca,2015-12-20:/storm-surge/atom/pmv/20151220180702

This tag is composed of:

• Our domain name: salishsea.eos.ubc.ca
• A comma
• The date on which the entry was created: 2015-12-20
• A colon
• The path to the feed file, excluding the .xml extension: /storm-surge/atom/pmv
• The local date/time when the entry was created as a string of digits, prepended with a '/': /20151220180702

Calculation of the Alert Text for the Entry summary Element¶

The summary element of the feed entry for a forecast for which there is a water level alert condition will be something like:

STORM SURGE ADVISORY!
Extreme sea levels expected for the marine areas of Vancouver

Synopsis:
Strong winds over the northeast Pacific Ocean are expected 
to produce elevated sea levels near Vancouver early Sunday morning.
These elevated sea levels may present a flood risk to 
coastal structures and communities at high tide.

Point Atkinson
Maximum Water Level: 5.37 m above chart datum
Wind: 33.67 km/hr (18.18 knots) from the W (276°)
Time: Dec 13, 2015 07:22 [PST]

Wind speed and direction are average over the 4 hours preceding
the maximum water level to give information regarding wave setup
that may augment flood risks.

Things that need to be calculated for this message:

• The risk level: risk or extreme risk to reflect the words used in the

storm surge forecast page graphic

• Maximum water level above chart datum in metres
• Average wind speed in km/hr and knots over the 4 hours preceding the maximum water level
• Average wind direction as a compass point (e.g. SW) and a bearing in degrees that the wind is coming from
• Date and time of the maximum water level with the appropriate timezone indicated

The summary element can be either plain text for HTML. We probably need to use the latter to get formatting like above. That opens the possibility of font faces (bold, italic, ...) and inclusion of a link to the appropriate forecast page, although the rel="alternate" link element may provide that.

Most of the code that we need to calculate that text is available in the SalishSeaNowcast package, in particular, in the nowcast.figures module. There is also a Mako template that generates RST in SalishSeaNowcast/nowcast/www/templates/surgetext.mako.

The next cell mounts the /results filesystem on skookum locally. It is intended for use if when this notebook is run on a laptop or other non-Waterhole machine that has sshfs installed. Don't execute the cell if that doesn't describe your situation.

Calculating the Values to use in the Template¶

The nowcast.figures.plot_threshold_website() has code (reproduced below) that calculates:

• The maximum sea surface height in a grid_T run results file
• The time at which it occurs

During development of the nowcast.workers.make_feeds() worker the above code was refactored to:

From those results we can calculate:

• Maximum water level above chart datum in metres
• Date and time of the maximum water level with the appropriate timezone indicated

Formating the date/time would be easy if it weren't for adding the timezone name:

We also want to "humanize" the date/time into a phrase like "early Monday afternoon". There is code in the surge_warning notebook that forms the basis for a function to do that.

During development of the nowcast.workers.make_feeds() worker a slightly different version of that function that uses the same time of day descriptions as Environment Canada does in the public weather forecasts was implemented as salishsea_tools.unit_conversions.humanize_time_of_day():

Some code adapted from nowcast.figures.plot_threshold_map() provides the risk level:

The above function has been added to the stormtools module.

There is code in nowcast.figures.get_model_winds() that finds the wind component arrays at the grid point in the weather forcing dataset at the lat-lon-time point that is closest to the tide gauge site at the time of the maximum water level:

Since we regularly need to get wind component values at the weather grid points closest to tide gauge stations, we'll put the grid indices in the salishsea_tools.places.PLACES data structure.

Having done that we can use the salishsea_tools.nc_tools.uv_wind_timeseries_at_point() function to get the wind component time series:

nowcast.figures.get_maxes() above gave us i_max_ssh_wind, the index in the wind component arrays of the hour in which the maximum water level occurs.

As a result of the development refactoring we're no longer using nowcast.figures.get_maxes() to provide i_max_ssh_wind. Instead we'll just grab the code that calculates it:

We use that to calculate the average wind components in the 4 hours preceding that hour:

Conversion of the wind speed from m/s to km/hr and knots is easily accomplished with some conversion factors and functions that should be added to a module in the SalishSeaTools package:

Those conversion factors and functions are implemented in the salishsea_tools.unit_conversions module.

We need a function that converts wind bearings from the "wind to" orientation that physicists use to the "wind from" orientation that people are used to:

This function is also now implemented as salishsea_tools.unit_converstions.wind_to_from().

We also need a function that converts compass bearings to compass headings:

This function is available as salishsea_tools.unit_conversions.bearing_heading():

Rendering the Template for the summary Element¶

We'll start with a reStructuredText template based on SalishSeaNowcast/nowcast/www/templates/surgetext.mako:

Rendering the RST to HTML:

Finally, we have everything we need to generate the feed and an entry if the model is predicting a storm surge risk:

To store the feed in a file instead of rendering it to a string use:

fg.atom_file('pmv.xml')

Now the code in this notebook will be used to create a nowcast.worker module that will generate feeds and store them in the appropriate locations after every forecast and forecast2 run.