Maps and Areas

This document aims to show how to use Diana to create plots from Python scripts and from within the ipython notebook.

Installation

To get access to the Python modules that expose Diana's plotting features, you need to install the python-diana package from the local package repository. Either use the package manager to do this, or enter the following in a terminal:

apt-get install python-diana

Some examples can also be found in the python-diana-examples package.

Importing Modules

You can use Diana's functionality from Python by importing the bdiana and plotcommands modules from the metno package. If you are using an old version of ipython (earlier than version 1.0) then it is also useful to import the embed function from the metno.ipython_extensions module.



In [1]:

    
# Import the modules needed to use Diana.
from metno import bdiana, plotcommands
# Import an extension that lets us embed an image into a worksheet.
from metno.ipython_extensions import embed
import datetime

Initialisation and Setup

The bdiana module contains the BDiana class. This provides a convenient interface to Diana's functions and also wraps several initialisation steps into one object. To start using Diana, we simply create an instance of this class.



In [2]:

    
# Create a BDiana object - this provides a simpler interface than calling Diana functions directly.
b = bdiana.BDiana()

By default, Diana doesn't know anything about data files or other resources. The locations of data files, definitions of plot types, palettes, and other pieces of information are stored in one or more setup files. We choose one of these and use the setup method to let Diana know where to get data from.



In [3]:

    
# Load a setup file - this describes where Diana finds data files and other resources.
b.setup("/etc/diana/setup/diana.setup-COMMON")









    Out[3]:





True

The method will return True if the setup file was loaded correctly.

Creating a Plot

Diana creates plots by reading and executing a series of plot commands. To create a plot, we need to create these commands. First, we write a plot command to create a map by creating a Map object and setting some options. These are explained below.



In [4]:

    
m = plotcommands.Map()
m.setOption("map", "Gshhs-Auto")
m.setOption("backcolour", "white")
m.setOption("land", "on")
m.setOption("land.colour", "flesh")

The map option describes the map data to use. "Gshhs-Auto" is a good general map to use.
The backcolour option describes the colour to use for the plot background. Named colours or colour components can be used to specify the colour. Use "0:0:0:0" for a transparent background.
The land option determines whether the land is filled.
The land.colour describes the fill colour used.

Normally, plot commands are contained in an input file that describes what kind of output to produce, as well as other syntax to ensure that Diana understands exactly what is to be plotted. For convenience, the BDiana class provides the setPlotCommands method that lets us ignore those details. We pass the plot commands to this method to set up the plot.



In [5]:

    
b.setPlotCommands([m])
# Print the actual plot commands for clarity.
print m.text()









    



MAP map=Gshhs-Auto backcolour=white land=on land.colour=flesh

The last thing we need to do before asking Diana to plot the figure is to set the plot time. We choose the last one available from the collection we obtained earlier.



In [6]:

    
b.setPlotTime(datetime.datetime.now())









    Out[6]:





True

A return value of True indicates that the specified time was acceptable. If False was returned then the time is not available. This shouldn't happen in this example.

Now we are able to create an image for the plot we specified. This one will be 500 pixels wide and 500 pixels high.



In [7]:

    
im = b.plotImage(500, 500)

When using an ipython notebook, it is useful to be able to preview the image we obtained. The embed function does this for us.



In [8]:

    
embed(im)









    Out[8]:

Plotting a Specific Area

By default, the area plotted will be the area covered by the fields used in the plot. To plot a specific area, we need to specify an area in the list of plot commands. This is done using the Area plot command class.



In [9]:

    
a = plotcommands.Area(name = "Norge")



In [10]:

    
m2 = plotcommands.Map(map = "skredvarsling")

Now we can create the plot again using this area.



In [11]:

    
b.setPlotCommands([a, m, m2])
b.setPlotTime(datetime.datetime.now())
im = b.plotImage(500, 500)
embed(im)









    Out[11]:



In [ ]: