
pywws.Plot
**********


Introduction
============

Comme Template.py celui-ci est un des modules les plus difficiles à
utiliser dans le logiciel de collecte de la station météo. Il trace un
graphe (ou un ensemble de graphes) de données météorologiques. Presque
tout le graphe est contrôlé par un fichier XML. Je me réfère à ces
fichiers en tant que modèles, mais ils ne sont pas des gabarits dans
le même sens que Template.py les utilise pour créer des fichiers
texte.

Avant d'écrire vos propres fichiers de gabarit de graphe, il pourrait
être utile d'examiner quelques exemples dans le répertoire
example_graph_templates. Si (comme moi) vous n'êtes pas familier avec
le langage XML, je vous suggère de lire le tutoriel XML du Site du
Zéro.


Syntaxe XML du fichier graphe
-----------------------------

Voici le modèle de graphe utile le plus simple. Il trace la
température extérieure pendant les 24 dernières heures.

   <?xml version="1.0" encoding="ISO-8859-1"?>
   <graph>
     <plot>
       <subplot>
         <title>Temperature (°C)</title>
         <ycalc>data['temp_out']</ycalc>
       </subplot>
     </plot>
   </graph>

Dans cet exemple, l'élément racine du graphe a un élément de tracé,
lequel a un élément graphe secondaire. L'élément graphe secondaire
contient un élément de titre et un élément ycalc. Pour tracer
davantage de données sur le même ensemble d'axes (par exemple le point
de rosée et la température), on peut ajouter plus d'éléments sous-
graphe. Pour tracer plus d'un ensemble d'axes (par exemple la vitesse
du vent qui est mesurée en unités différentes de la température) dans
le même fichier, nous pouvons ajouter plus d'éléments de graphe.

La hiérarchie complète de l'élément est illustré ci-dessous.

   graph
       plot
           subplot
               xcalc
               ycalc
               axes
               style
               colour
               title
           bmargin
           yrange
           y2range
           ytics
           y2tics
           ylabel
           ylabelangle
           y2label
           y2labelangle
           grid
           source
           boxwidth
           title
           command
       start
       stop
       duration
       layout
       size
       fileformat
       terminal
       lmargin
       rmargin
       xformat
       xlabel
       dateformat
       xtics
       title


graph
-----

C'est l'élément racine du fichier XML de graphe. Il n'a pas à être
appelé "graph ", mais il doit y avoir exactement un élément racine.


plot
----

Chaque élément graphe doit contenir au moins un élément de tracé. Un
graphe distinct est établi pour chaque élément de tracé, mais tous
partagent le même axe X.


start
-----

Cet élément règle la date et l'heure de départ de l'axe X. Il est
utilisé pour la construction d'un élément Python datetime. Par
exemple, pour démarrer le graphe à midi (heure locale), le jour de
Noel 2008: "<start>year=2008, month=12, day=25, hour=12</start>". La
valeur par défaut est (stop - duration).


stop
----

Cet élément règle la date et l'heure de fin de l'axe X. Il est utilisé
pour la construction d'un élément Python datetime. Par exemple, pour
terminer le graphe à 10h am (heure locale), le jour du Nouvel An:
"<stop>year=2009, month=1, day=1, hour=10</stop>". La valeur par
défaut est (start + duration), à moins que start ne soit pas définit
dans lequel cas l'horodate de la dernière lecture horaire de la
station météo est employée.


duration
--------

Cet élément définit l'étendue de l'axe X du graphique, à moins que
start (début) et stop (arrêt) soient tous deux définis. Il est utilisé
dans le construction d'un objet Python timedelta. Par exemple, pour
tracer une semaine: "<duration>weeks=1</duration>". La valeur par
défaut est hours=24.


layout
------

Contrôle la disposition des tracés. Par défaut sur une seule colonne.
L'élément de mise en page définit les lignes et les colonnes. Par
exemple: "<layout>4, 2</layout>" utilisera une grille de 4 lignes et 2
colonnes.


size
----

Définit les dimensions globales du fichier image contenant le graphe.
Par défaut (dans une mise en page à simple colonne) une largeur de 600
pixels et une hauteur de 200 pixels pour chaque tracé est employé,
donc la dimension d'un graphe avec quatre éléments tracés serait de
600 x 800 pixels. Tout élément de taille doit inclure à la fois la
largeur et la hauteur. Par exemple: "<size>800, 600</size>" produira
une image 800 pixels de large et 600 pixels de haut.


fileformat
----------

Définit le format du fichier d'image contenant le graphe. Par défaut
png. Toute chaîne reconnue par votre installation de gnuplot peut
convenir. Par exemple: "<fileformat>gif</fileformat>" va produire une
image GIF.


terminal
--------

Permet un contrôle complet des paramètres 'terminal' de gnuplot. Vous
pouvez utiliser cette option si vous tracez un format d'image
inhabituel. Toute chaîne reconnue par la commande 'terminal' de votre
installation gnuplot devrait faire. Par exemple: "<terminal>svg
enhanced font "arial,9" size 600,800 dynamic rounded</ terminal>". Ce
paramètre spécifie à la fois la taille et le format de fichier.


lmargin
-------

Définit la marge gauche des graphes, c'est à dire la distance entre
l'axe de gauche sur le bord gauche de la zone de l'image. Selon la
documentation de gnuplot les unités de lmargin sont des largeurs de
caractères. La valeur par défaut est de 5, ce qui devrait être OK dans
la plupart des circonstances.


rmargin
-------

Définit la marge droite des graphes, c'est à dire la distance entre
l'axe de droite à l'extrémité droite de la zone d'image. Selon la
documentation de gnuplot les unités de rmargin sont des largeurs de
caractères. La valeur par défaut est -1, ce qui spécifie le réglage
automatique.


xformat
-------

Définit le format des étiquettes de date / heure xtic. La valeur est
une chaîne de style format strftime. Par défaut elle dépend de la
durée du graphe: 24 heures ou moins est "%H%M", 24 heures sur 7 jours
est "%a% d" et 7 jours ou plus est "%Y/%m/%d".


xlabel
------

Définit l'étiquette d'axe X. La valeur est une chaîne de style format
strftime. Par défaut dépend de la durée du graphe: 24 heures ou moins
est "Time (%Z)", de 24 heures à 7 jours est «Day» et 7 jours ou plus
est «Date». Le datetime utilisé pour calculer ce départ, ce qui peut
produire des résultats inattendus lorsqu'un graphique s'étend de début
ou de fin DST.


dateformat
----------

Définit le format des étiquettes de date à chaque extrémité de l'axe
X. La valeur est une chaîne de style format strftime. Par défaut est
"%Y/%m/%d". L'étiquette de droite est uniquement affichée si elle
diffère de la gauche. Pour avoir aucune étiquette, définissez un
format vide: "<dateformat></dateformat>"


xtics
-----

Définit l'espacement des "tic" des marques sur l'axe X. La valeur est
un nombre entier d'heures. La valeur par défaut est de laisser gnuplot
définir l'intervalle approprié.


title
-----

Définit le titre du graphe. Une seule ligne de texte, par exemple:
"<title>La météo du jour</ title>". Ce titre apparaît tout en haut du
graphe, en dehors de toute zone de traçage.


subplot
-------

Chaque élément du graphe doit contenir au moins un élément graphe
secondaire. Une tracé distinct est établi pour chaque élément sous-
graphe, mais tous partagent les même axes X et Y.


bmargin
-------

Définit la marge inférieure, c'est à dire la distance entre la partie
inférieure de l'axe X et le bord du graphique (ou le graphe suivante).
La valeur par défaut est de laisser gnuplot ajuster automatiquement,
ce qui fonctionne bien la plupart du temps, mais vous pouvez ajuster
la valeur en fonction de votre installation.

La valeur autorisée est un nombre non négatif réel. Sur mon
installation 0.9 est une bonne valeur, définie comme suit: "<bmargin>
0.9</ bmargin>".


yrange
------

Définit les limites inférieure et supérieure de l'axe Y gauche. La
valeur est tout ce qui est recconnu par gnuplot, généralement une
paire de nombres. La valeur par défaut est de permettre à gnuplot de
définir les valeurs appropriées, ce qui est peu susceptible d'être ce
que vous voulez. Par exemple, pour tracer des températures typiques du
Royaume-Uni sans valeur va hors du graphe: "<yrange>-10, 30</yrange>".
Notez que les virgules sont converties en deux points, donc
"<yrange>10:30</ yrange>" serait équivalent.

Vous pouvez utiliser un astérisque pour laisser gnuplot choisir une
valeur appropriée. Par exemple, pour automatiser l'échelle de valeur
supérieure, tout en fixant la valeur inférieure à zéro, utilisez
"<yrange>0:*</yrange>".


y2range
-------

Définit les limites inférieure et supérieure de l'axe Y de droite. Le
défaut est pour l'axe Y de droite d'être la même que celle de gauche,
mais fixer une plage différente est utile en double axe de traçage.


ytics
-----

Contrôle les "tic" des marques sur l'axe Y de gauche. La valeur peut
être tout ce qui est compris par gnuplot. Par exemple, pour définir
l'espacement tic à 45 utiliser "<ytics>45</ ytics>". Des choses plus
complexes sont également possibles, par exemple étiqueter un diagramme
de direction du vent avec des points de boussole, utilisez
"<y2tics>('N' 0, 'E' 90, 'S' 180, 'W' 270, 'N' 360)</ y2tics>".


y2tics
------

Contrôle les "tic" des marques sur l'axe de droite. Le format est le
même que celui de ytics. Le comportement par défaut consiste à copier
les marques de graduation de gauche, mais sans étiquette.


ylabel
------

Ajoute une étiquette à gauche de l'axe Y. Par exemple, lors du tracé
de la température: "<ylabel>°C</ylabel>". Si vous utilisez ylabel vous
voudrez probablement ajuster lmargin.


ylabelangle
-----------

Ajuste l'angle de l'étiquette à gauche de l'axe Y, si votre version de
gnuplot le soutient. Par exemple, pour écrire l'étiquette
horizontalement: "<ylabelangle>90</ylabelangle>".


y2label
-------

Ajoute une étiquette à l'axe Y de droite. Par exemple, lors du tracé
de l'humidité: "<y2label>%</y2label>". Cela est principalement utilisé
lors du traçage de graphes à deux axes. Si vous utilisez y2label vous
voudrez probablement ajuster rmargin.


y2labelangle
------------

Ajuste l'angle de l'étiquette d'axe Y à droite, si votre version de
gnuplot le permet. Par exemple, pour écrire l'étiquette
horizontalement: "<y2labelangle>90</ y2labelangle>".


grid
----

Ajoute une grille au tracé. Dans la plupart des situations, la grille
par défaut de gnuplot est appropriée, si aucune valeur n'est
nécessaire: "<grid></grid>". Plus de contrôle est possible en
utilisant l'une des options comprises par la commande set grid de
gnuplot. Par exemple, pour avoir les lignes horizontales de la grille
uniquement: "<grid>ytics</grid>".


source
------

Sélectionne les données météorologiques à tracer. Les valeurs
autorisées sont "<source>raw</source>", "<source> hourly</ source>",
"<source>daily</source>" et "<source>monthly</source>". LA valeur par
défaut est raw. Notez que les sources différentes ont des
dictionnaires de données différents, donc ce choix affecte ycalc.


boxwidth
--------

Définit la largeur des "boîtes" utilisés lors de l'élaboration des
graphes à barres. La valeur est une expression entière pour obtenir un
nombre de secondes. Le défaut dépend de la source: brut est de 240,
horaire est de 2800 et quotidien est de 2800 * 24.


title
-----

Définit le titre du graphe. Une seule ligne de texte, par exemple:
"<title>Température (°C)</ title>". Ce titre apparaît dans la zone de
traçage, au-dessus de tous les titres sous-graphes.


command
-------

Exécute n'importe quelle commande gnuplot, juste avant la principale
commande de tracé. Cette option permet aux utilisateurs avancés
d'avoir plus de contrôle sur l'apparence du graphe. La valeur est une
commande gnuplot valide, généralement commençant par un ensemble de
mots. Par exemple: "<command>set key tmargin center horizontal width 1
noreverse enhanced autotitles box linetype -1 linewidth 1</ command>".
(Ne me demandez pas ce que cet exemple produit - Je ne suis pas un
utilisateur avancé).


xcalc
-----

Contrôle le positionnement de l'axe X du tracé des valeurs de données.
La valeur par défaut de data['idx'] est correcte pour la plupart des
données, mais il y a quelques exceptions. Par exemple, lors du tracé
des diagrammes à barres de pluies horaires, il est bon de centrer les
barres sur 30 minutes après l'heure:  "<xcalc>data
['idx'].replace(minute=30, second=0)</ xcalc>".


ycalc
-----

Sélectionne les données à tracer. Toute expression Python sur une
ligne qui retourne une valeur flottante simple peut être utilisée. Au
plus simple cela sélectionne une seule valeur du dictionnaire "data",
par exemple: "<ycalc>data['temp_out']</ycalc>" trace la température
extérieure. Des expressions plus complexes sont possibles, et
certaines fonctions d'aide sont fournies. Par exemple:
"<ycalc>dew_point(data['temp_out'], data['hum_out'])</ ycalc>" trace
le point de rosée externe, et "<ycalc>data['wind_ave'] * 3,6 /
1.609344</ ycalc>" trace la vitesse moyenne du vent en miles par
heure.

Les courbes cumulatives sont également possibles. Le résultat de
chaque calcul ycalc est stocké et mis à la disposition du calcul
suivant dans la variable last_ycalc. Ceci peut être utilisé avec toute
donnée, mais il est plus utile avec des précipitations: "<ycalc>data
['rain'] + last_ycalc</ ycalc>".


axes
----

Sélectionne contre quel axe Y les données sont tracées. Par défaut
c'est l'axe de gauche, mais l'axe de droite peut être choisie avec:
"<axes>x1y2</ axes>". Ceci peut être utilisé en conjonction avec
y2range pour tracer deux quantités indépendantes sur une courbe, par
exemple la température et de l'humidité.


style
-----

Définit le style de ligne pour le graphe. Le défaut est une ligne
continue lisse, d'épaisseur 1. Pour sélectionner un graphique à
barres, utilisez: "<style>box</ style>". Pour sélectionner des points
sans ligne de raccordement, utilisez: "<style>+</ style>" ou
"<style>x</ style>". Pour sélectionner une épaisseur de ligne à 3 (par
exemple): "<style>line 3</ style>". L'épaisseur des points peut être
réglé de la même façon. Pour un contrôle complet (pour utilisateurs
avancés) un style gnuplot complet peut être réglé ainsi:
"<style>smooth unique lc 5 lw 3</ style>".


colour
------

Définit la couleur de la ligne de sous-graphe ou des boîtes. Toute
valeur entière est acceptée. La charte des couleurs est fixée par
gnuplot. La valeur par défaut est la couleur précédente plus un.


title
-----

Définit le titre du sous-graphe. Une seule ligne de texte, par
exemple: "<title>Température (°C)</ title>". Ce titre apparaît dans la
zone de graphe, à côté d'un court segment de la couleur de la ligne
utilisée pour le sous-graphe.


API détaillé
============

Plot graphs of weather data according to an XML recipe

   usage: python RunModule.py Plot [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

-[ Fonctions ]-

+------------+--------------------------------------------------------------------------------------------+
+------------+--------------------------------------------------------------------------------------------+

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
+------------+--------------------------------------------------------------------------------------------+
+------------+--------------------------------------------------------------------------------------------+

class class pywws.Plot.BasePlotter(params, raw_data, hourly_data, daily_data, monthly_data, work_dir)

   DoPlot(input_file, output_file)

   GetChildren(node, name)

   GetValue(node, name, default)

class class pywws.Plot.Record

class class pywws.Plot.GraphPlotter(params, raw_data, hourly_data, daily_data, monthly_data, work_dir)

   GetPlotList()

   GetDefaultRows()

   GetDefaultPlotSize()

   GetPreamble()

   PlotData(plot_no, plot, source)

pywws.Plot.main(argv=None)
