forecasting - weewx/weewx GitHub Wiki

With the forecast extension you can display forecasts for up to 10 days in the future as well as tide predictions. Forecasts are either generated using the Zambretti method, or downloaded from the US National Weather Service (NWS), Weather Underground (WU), Open Weathermap, UK Met Office, Aeris Weather, World Weather Online, or Dark Sky. Tide predictions are generated using XTide.

The forecast extension displays forecast data in many formats, including table, strip chart, iconic bars, compact summary, and meteograph.

The extension consists of services that download/generate forecast data, and a search list extension to make forecast data available within templates. There is one service for each type of forecast, and a single search list extension to display data from any type of forecast.

The extension includes pre-configured .inc files that can be included in other templates. This provides an easy way to add a strip, table, or iconic view to other skins.

A live example is available at the MIT sailing pavilion:

http://sailing.mit.edu/weather/forecast.html

The forecasts can be display in many different formats, no matter which forecasting service provided the data:

Compact	Iconic	Iconic
Table	Strip

wget -O weewx-forecast.zip https://github.com/matthewwall/weewx-forecast/archive/master.zip

If you want forecasts from the US National Weather Service, you must determine the location identifier and forecast office identifier for your location. The forecast office identifier indicates a general region, for example BOX for the eastern part of Massachusetts. The location identifier indicates a smaller area within a forecast office region, for example MAZ014 for the city of Cambridge, Massachusetts.

First figure out your 3-letter forecast office identifier (foid, also referred to as HADS) and 6-character location identifier (lid) by visiting the NWS web site:

http://www.nws.noaa.gov/oh/hads/USGS/

Test by requesting a point forecast using a url of this form in a web browser:

http://forecast.weather.gov/product.php?site=NWS&product=PFM&format=txt&issuedby=YOUR_THREE_LETTER_FOID

Scan the output for a description of your city or county and the associated location identifier. If there is more than one location with the same location identifier, then specify the town/county line that immediately follows the location identifier.

If you want forecasts from OpenWeatherMap, obtain an API key from the OpenWeatherMap web site. Activation of an API key for Free and Startup plans takes 10 minutes. For other tariff plans it is 10 to 60 minutes.

http://openweathermap.org/appid

If you want forecasts from the UK Met Office, visit the DataPoint web site to obtain an API key.

http://metoffice.gov.uk/datapoint

If you want forecasts from Aeris, create an account at the Aeris web site then generate an API key.

http://www.aerisweather.com/account

If you want forecasts from World Weather Online, register for an account at the WWO web site then generate and API key.

https://developer.worldweatheronline.com/auth/register

If you want forecasts from Dark Sky, visit the darksky web site to obtain the API key.

https://darksky.net/dev/register

If you want tide predictions, install the xtide software.

sudo apt-get install xtide
sudo apt-get install xtide-data

Tide data for Canada, Germany, and the UK are in a separate package:

sudo apt-get install xtide-data-nonfree

Test by generating predictions for your desired location

tide -l Boston

The harmonics data are typically updated once per year. Old harmonics files will work, but the resulting tide predictions could be off. For some locations, that may mean only a few centimeters or a few minutes, but for other locations the differences could be significant.

You can use recent harmonics files with tide from 2010 or earlier. Just tell tide where to find the harmonics using the HFILE_PATH variable; there is no need to install the latest tide program.

The XTide web pages have complete details:

https://flaterco.com/xtide/index.html

1. Run the extension installer to install the forecast service and sample skin.

weectl extension install weewx-forecast.zip

2. In weewx.conf, specify required parameters for the forecast services you want to run

    [Forecast]
        [[NWS]]
            lid = MAZ014                 # specify a location identifier
            foid = BOX                   # specify a forecast office identifier
        [[WU]]
            api_key = XXXXXXXXXXXXXXXX   # specify a weather underground api_key
        [[OWM]]
            api_key = XXXXXXXXXXXXXXXX   # specify an open weathermap api_key
        [[UKMO]]
            api_key = XXXXXXXXXXXXXXXX   # specify a UK met office api_key
            location = 2337              # specify code for UK location
        [[Aeris]]
            client_id = XXXXXXXXXXXXXXXX      # specify client identifier
            client_secret = XXXXXXXXXXXXXXXX  # specify client secret key
        [[DS]]
            api_key = XXXXXXXXXXXXXXXX   # specify a dark sky api_key
        [[XTide]]
            location = Boston            # specify a location

3. Restart weewx

sudo systemctl stop weewx
sudo systemctl start weewx

The extension installer will add all of the forecast methods to the service list. However, each method requires parameters such as an API key, so unless those parameters are entered, only Zambretti will actually run.

Zambretti runs only once per day, and only in the morning. So you might have to wait until the following day to see any Zambretti output. WU and NWS run every 3-4 hours. Tide forecasts are generated once every few weeks.

The installer also installs a skin called 'forecast' that illustrates how to use raw forecast data in any template, and how to use the pre-configured displays in other templates.

Monitor the log to see what is happening. The log should include messages about each type of forecast as it starts. After the first archive interval, each forecast should download/generate, and the forecast data should be displayed in the forecast skin.

You should disable the 'forecast' skin after you have verified that the forecasts work, and you no longer need to see the examples. This is especially true if you are running weeWX on a low-end system. The 'forecast' skin generates pages that illustrate many different ways of formatting forecasts. On a production system, you will probably only want one or two forecasts, typically embedded in one of your normal reports.

There are two approaches to using forecast data in your templates: (1) include a pre-configured forecast_*.inc, and/or (2) use the $forecast variables.

Whether you use an include or the $forecast variable directly, the ForecastVariables search list extension must be installed for the skin.

The forecast extension includes a search list extension called ForecastVariables. This defines a variable called $forecast that you can use to embed fine-grained forecast information anywhere in a template, and that is used extensively in the forecast forecast_*.inc files.

To use the $forecast variable in a template, the ForecastVariables search list extension must be enabled within the skin for that template. For example, to enable ForecastVariables in the Standard skin, modify skins/Standard/skin.conf:

[CheetahGenerator]
    search_list_extensions = user.forecast.ForecastVariables
    ...

As an example, see the skin.conf in the forecast skin.

Perhaps the easiest way to put forecasts into your pages is to include a file. The forecast extension includes a few .inc files, each of which displays forecast information in a different format. Screen shots of these formats are shown below.

For example, to use the iconic display in a template, simply include the iconic file and its corresponding CSS:

<html>
  <head>
    <title>forecast</title>
    <link rel='stylesheet' type='text/css' href='forecast_iconic.css'/>
  </head>
  <body>
#include "forecast_iconic.inc"
  </body>
</html>

Optionally adjust the parameters in skin.conf (restart of weewx is not required):

[Extras]
    [[forecast_iconic_settings]]
        source = WU
        num_days = 7

Or set them in weewx.conf (restart of weewx is required):

[StdReport]
    [[forecast]]
        [[[Extras]]]
            [[[[forecast_iconic_settings]]]]
                source = WU
                num_days = 7

If you include more than once in a single template, you probably want to specify the settings before each include. This lets you have multiple forecasts in a single page. For example, this would show two iconic forecasts in a single page, one from Weather Underground and one from the US National Weather Service.

<html>
  <head>
    <title>two forecasts</title>
    <link rel='stylesheet' type='text/css' href='forecast_iconic.css'/>
  </head>
  <body>
#set global $forecast_iconic_settings = dict()
#set global $forecast_iconic_settings['source'] = 'WU'
#set global $forecast_iconic_settings['num_days'] = 10
#include "forecast_iconic.inc"

#set global $forecast_iconic_settings = dict()
#set global $forecast_iconic_settings['source'] = 'NWS'
#set global $forecast_iconic_settings['num_days'] = 7
#include "forecast_iconic.inc"
  </body>
</html>

Each of the included files has options that control the forecast display. For example, the strip can be oriented vertically or horizontally, or you might want to hide the snow forecast in tables if you live in a region where it never snows.

These are the options for the various include files (the files that end in .inc such as forecast_table.inc):

[forecast_table_settings]
    source = NWS
    num_periods = 72
    show_legend = 1
    show_hourly = 0
    show_day = 1
    show_date = 1
    show_outlook = 1
    show_temp = 1
    show_dewpoint = 0
    show_humidity = 0
    show_wind = 1
    show_tides = 1
    show_sun = 0
    show_moon = 0
    show_pop = 1
    show_precip = 1
    show_obvis = 1

[forecast_strip_settings]
    source = Aeris
    num_periods = 300
    show_temp = 1
    show_temp_min = 1
    show_temp_max = 1
    show_dewpoint = 0
    show_humidity = 0
    show_wind = 1
    show_clouds = 1
    show_pop = 1
    show_snow = 1
    show_precip = 1
    show_sun = 0
    show_moon = 0
    show_moonphase = 0
    show_tides = 0

[forecast_iconic_settings]
    source = WU
    orientation = vertical
    num_days = 7
    bar_width = 150
    show_date = 0
    show_pop = 0
    show_precip = 1
    show_obvis = 1

[forecast_compact_settings]
    source = WU
    num_days = 4
    show_wind = 1
    show_pop = 1
    show_precip = 1
    show_obvis = 1

You can insert parts of a forecast into any template using the $forecast variable. For example, you might want to display the predicted high and low temperatures next to the current temperature, or you might want to show the rain predicted each day for the next week.

Here is an example of one way to use the $forecast variable in a template.

First query the database for the forecast events:

#set $periods = $forecast.weather_periods('WU', max_events=6)

The first argument is the forecast source, such as 'WU', 'WWO', or 'NWS'. Optionally specify the maximum number of events you are interested in. If not specified, the query will return every possible event for the indicated source.

Each period contains forecast data such as temperature, sky cover, chance of precipitation, and obstructions to visibility. Each period also contains a timestamp and location.

For example, this would display the time, temperature, and sky cover for each period:

#for $period in $periods
$period.event_ts $period.temp $forecast.label('Weather', $period.clouds)<br/>
#end for

For details about how to use the $forecast variables, see the comments at the beginning of forecast.py.

The forecasts include many icons, which must be copied to any skin that will use the forecast. For example, if you want to embed the forecast in the Standard skin, first copy the icons:

cp -rp skins/forecast/icons skins/Standard

Then include the icons in the list of files that should be copied by the CopyGenerator. Append the icons directory to the copy_once parameter in the CopyGenerator configuration in skins/Standard/skin.conf:

[CopyGenerator]
    copy_once = ..., icons/*.png

If you want to change the look-and-feel of a forecast, replace the images in the icons directory. For example, you might want colorful images instead of the default monochromatic set. Use the same set of filenames and be sure to include all the different images.

The iconic forecast is a simplified view with time increasing down the page (vertical) or across the page (horizontal).

#include "forecast_iconic.inc"

The compact forecast shows a few days into the future.

#include "forecast_compact.inc"

The forecast table contains a lot of information, with time increasing into the future as you look down the table. Each day is a summary of the forecast information for that day, and can be expanded to see the forecast breakdown for the day. For some forecast sources this is hourly, for others it is 4-hourly, for others it is a mix. Use the settings to specify which columns should be displayed.

#include "forecast_table.inc"

The forecast strip contains detailed forecast data, with time increasing into the future as you scroll to the right. The period duration depends on the forecast source - some are hourly, some are a mix of hourly and 4-hourly. Use the settings to specify which rows should be displayed.

#include "forecast_strip.inc"

The seasons skin is rather modular, so it is easy to add one or more blocks of forecast information.

To add forecast information to the Seasons skin:

1. Add a widget block for the forecast by including the file forecast.inc in the index.html.tmpl file in Seasons

      <div id="widget_group">
        #include "forecast.inc"
        #include "current.inc"
        #include "sunmoon.inc"
        #include "hilo.inc"
        #include "sensors.inc"
        #include "about.inc"
        #include "radar.inc"
        #include "satellite.inc"
        #include "map.inc"
      </div>

2. Put this into the file skins/Seasons/forecast.inc. In this example, we use the compact forecast display. You could use iconic instead, if you want.

## forecast module for weewx skins
## Copyright Tom Keffer, Matthew Wall
## See LICENSE.txt for your rights
#errorCatcher Echo

<link rel='stylesheet' type='text/css' href='forecast_compact.css'/>

<div id='forecast_widget' class="widget">
  <div class="widget_title">
    Forecast
    <a class="widget_control"
      onclick="toggle_widget('forecast')">&diams;</a>
  </div>
  <div class="widget_contents">

#include "forecast_compact.inc"

  </div>
</div>

3. Add directives to the [[SeasonsReport]] section of the weeWX configuration file that tell the CheetahGenerator to use the forecast extensions, and to copy the forecast CSS and icons.

[StdReport]
    ...
    [[SeasonsReport]]
        ...
        [[[CheetahGenerator]]]
            search_list_extensions = user.forecast.ForecastVariables
        [[[CopyGenerator]]]
            copy_once = seasons.css, seasons.js, favicon.ico, font/*.woff, font/*.woff2, forecast_compact.css, icons/*

4. Copy a few files from the forecast skin into the Seasons skin

cp skins/forecast/forecast_compact.css skins/Seasons
cp skins/forecast/forecast_compact.inc skins/Seasons
cp -rp skins/forecast/icons skins/Seasons

5. Restart weeWX

To add forecast information to the Standard skin, include one of the forecast .inc files.

The display of forecast data is built in to the exfoliation skin. It should show up automatically when the forecast extension is installed. Use the forecast options in Extras to control the output in the forecast page of the exfoliation skin.

The forecasting module was distributed as a part of weewx 2.5. As of weewx 2.6 it is a separate download.

See the comments in forecast.py for complete details about this extension.