pywws.windrose
Plot a “wind rose”
usage: python -m pywws.windrose [options] data_dir temp_dir xml_file output_file
options are:
-h or --help display this help
data_dir is the root directory of the weather data
temp_dir is a workspace for temporary files e.g. /tmp
xml_file is the name of the source file that describes the plot
output_file is the name of the image file to be created e.g. 24hrs.png
Introduction
This routine plots one or more “wind roses” (see Wikipedia for a description). Like
pywws.plot almost everything is controlled by an XML
“recipe” / template file.
Before writing your own template files, it might be useful to look at some of the examples in the example_graph_templates directory. If (like I was) you are unfamiliar with XML, I suggest reading the W3 Schools XML tutorial.
XML graph file syntax
Here is the simplest useful wind rose template. It plots wind over the last 24 hours.
<?xml version="1.0" encoding="ISO-8859-1"?>
<graph>
<windrose>
<ycalc>data['wind_ave']</ycalc>
</windrose>
</graph>
In this example, the root element graph has one windrose element which contains nothing more than a ycalc element.
The complete element hierarchy is shown below.
graph
This is the root element of the graph XML file. It does not have to be called “graph”, but there must be exactly one root element.
start
This element sets the date & time of the wind roses. It is used in the
constructor of a Python datetime object. For example, to start at noon
(local time) on Christmas day 2008: <start>year=2008, month=12,
day=25, hour=12</start>. The default value is (stop - duration).
stop
This element sets the date & time of the end of the wind roses. It is
used in the constructor of a Python datetime object. For example, to
end at 10 am (local time) on new year’s day 2009: <stop>year=2009,
month=1, day=1, hour=10</stop>. The default value is (start +
duration), unless start is not defined in which case the timestamp of
the latest weather station hourly reading is used.
duration
This element sets the duration of wind roses, unless both start and
stop are defined. It is used in the constructor of a Python timedelta
object. For example, to plot one week:
<duration>weeks=1</duration>. The default value is hours=24.
layout
Controls the layout of the plots. Default is a grid that is wider than
it is tall. The layout element specifies rows and columns. For
example: <layout>4, 2</layout> will use a grid of 4 rows and 2
columns.
size
Sets the overall dimensions of the image file containing the graph.
Default is a height of 600 pixels and a width that depends on the
layout. Any size element must include both width and height. For
example: <size>800, 600</size> will produce an image 800 pixels
wide and 600 pixels high.
fileformat
Sets the image format of the file containing the plots. Default is
png. Any string recognised by your installation of gnuplot should do.
For example: <fileformat>gif</fileformat> will produce a GIF
image.
lmargin, rmargin, tmargin, bmargin
Over-rides the automatically computed left, right, top or bottom
margin. Supply any positive real number, for example
<lmargin>1.3</lmargin>. Some experimentation may be necessary to
find the best values.
title
Sets the overall title of the plots. A single line of text, for example:
<title>Today's wind direction</title>. This title appears at the
very top, outside any plot area.
New in version 15.06.0.dev1301: If the title contains any “%” characters it will be used as a
strftime style format string for the datetime of the stop value. This
allows you to include the graph’s date or time in the title, for
example: <title>Wind over 24 hours ending %H:%M (mph)</title>
windrose
A separate plot is drawn for each windrose element, but all share the same time period.
xcalc
Selects if data is included in the wind rose. The value should be a
valid Python logical expression. For example, to plot a rose for
afternoon winds only: <xcalc>data['idx'].hour >= 12</xcalc>.
This allows aggregation of afternoon wind data over several days.
Remember that data is indexed in UTC, so you need to use an expression
that takes account of your time zone. The default value is ‘True’.
ycalc
Selects the data to be plotted. Any one line Python expression that
returns a single float value can be used. At its simplest this just
selects one value from the “data” dictionary, for example:
<ycalc>data['wind_ave']</ycalc>. To convert to mph use:
<ycalc>data['wind_ave'] * 3.6 / 1.609344</ycalc>. You are unlikely
to want to use anything other than ‘wind_ave’ here.
threshold
Sets the thresholds for each colour on the rose petals. Defaults are
based on the Wikipedia example. The values should be a correctly
ordered list of real numbers, for example: <threshold>0.5, 3.5, 7.5,
12.5, 18.5, 24.5, 31.5</threshold> approximates to the Beaufort
scale, if ycalc has been set to convert windspeeds to mph.
colour
Sets the colours of the threshold petal segments. Can be any sequence of values accepted by gnuplot. Default value is a sequence of integer colour indexes, which is probably not what you want. You may need to experiment with more complicated values such as
<colour>'rgb "grey"','rgb "#0000FF"','rgb "#00A080"','rgb "#00FF00"','rgb "#A0FF00"','rgb "#FFFF00"'</colour>
yrange
Sets the upper limits of the axes. The rose shows what percentage of
the time the wind came from a particular direction. For example, if
you live somewhere with a very steady wind you might want to allow
higher percentages than normal: <yrange>91</yrange>. Auto-scaling
is also possible, using an asterisk: <yrange>*</yrange>
points
Sets the text of the compass points. The defaults are ‘N’, ‘S’, ‘E’ &
‘W’. For graphs in another language you can over-ride this, for example:
<points>'No', 'Zu', 'Oo', 'We'</points>. (The preferred way to do
this is to create a language file, see pywws.localisation.)
source
Select the weather data to be plotted. Permitted values are
<source>raw</source>, <source>hourly</source>,
<source>daily</source> and <source>monthly</source>. Default
is raw. Note that the different sources have different data
dictionaries, so this choice affects ycalc.
title
Sets the title of the plot. A single line of text, for example:
<title>Morning winds</title>. This title appears within the plot
area, above the threshold colour key.
command
New in version 16.06.0.
Execute any gnuplot command, just before the main “plot” command. This option allows advanced users to have greater control over the graph appearance. The value is any valid gnuplot command, typically beginning with the word set.
For example, <command>set grid front</command> will stop the grid
being hidden by the coloured wedges, and <command>set key outside
above right maxrows 1</command> will place the key outside the plot
area.
Detailed API
Functions
|
Classes
|
Comments or questions? Please subscribe to the pywws mailing list http://groups.google.com/group/pywws and let us know.