Plot ids

All of the Ngl graphics routines return an object of class PlotIds that contains the integer ids of the various Ngl plotting objects created by the plotting function. Also returned is an integer base id that represents the object that contains all of the other plot objects. The base id is always the same as one of the plot objects in the returned object.

Specifically, the object returned from a plotting function is an instance of a Python class PlotIds; this class is defined in the Ngl module. Such an object has attributes:

attribute description
base base plot id
contour contour plot id
vector vector plot id
streamline streamline plot id
map map plot id
xy xy plot id
xydspec xy data plot id
text text plot id
primitive primitive plot id (lines, polygons, markers, etc.)
cafield coordinate array plot id
sffield scalar field plot id (data for contour plots, etc.)
vffield vector field plot id

Each of the attributes of a PlotIds object described above is a Python list (or None if it is not relevant). Each element of a list that is a value of a PlotIds attribute is an integer plot identifier for a specific Ngl plot object, such as a vector plot or a contour plot. Usually the list will contain a single identifier, but, for example, if you are creating a lot of polygons, each ploygon will have its own integer id.

For example, if you use Ngl.contour to draw a contour plot, the PlotIds object returned will contain integer ids for three objects: the base object, the contour plot object, and the data (scalar field) object. In this case, the contour object and the base object are the same. Each of the integer plot ids in this case are single elements of a Python list.

In the case of Ngl.contour_map, integer ids are created for four objects: the base object, the map plot object (which is the same as the base object), the contour object, and the scalar field object.

Some of the non-plotting Ngl functions take a PlotIds object as an argument and in most cases you can just pass this along as the appropriate function argument without thinking. In some cases, however, you may need to extract certain ids from the PlotIds object before calling the non-plotting Ngl functions. For example, if after a call to Ngl.contour_map, you want to change a resource for the contour plot, you will need the plot id for that object to pass to an Ngl.set_values call. See the example below.

The non-plotting Ngl functions that have a plot identifier as an argument are:

The plot id you pass to these functions can be either an integer, a Python list, or a PlotIds object. If an integer, then it is assumed to be a plot id of a specific Ngl plot object (like a contour plot, or a map plot); if it is a Python list, then the first element of the list is used for the plot id of a specific Ngl plot object; if it is a PlotIds object, then the first element of the base attribute is used.

Here is a simple example of how to use the PlotIds object returned from a Ngl.contour_map call to change a resource (cnFillOn) of the contour plot:

import numpy                        # import NumPy.
import Ngl                          # import Ngl functions.
import Nio                          # import netCDF reader

data_dir = Ngl.ncargpath("data")                            #  open a netCDF
cdf_file = Nio.open_file(data_dir + "/cdf/941110_P.cdf","r")   #  file for reading.

psl = cdf_file.variables["Psl"]     # pressure variable.

wks = Ngl.open_wks("x11","id_test",None)  

resources = Ngl.Resources()             # establish data boundaries.
resources.sfXCStartV = -180.        # minimum longitude.
resources.sfXCEndV   =  180.        # maximum longitude.
resources.sfYCStartV =  -90.        # minimum latitude.
resources.sfYCEndV   =   90.        # maximum latitude.

map = Ngl.contour_map(wks,psl,resources)   # draw a contour over a map.

for attr in dir(map):               # print out the map attributes and values.
  print "map." + attr + " = " + str(getattr(map,attr))

del resources                          # start with a new resource list.
resources = Ngl.Resources()
resources.cnFillOn = True              # turn contour fill on
Ngl.set_values(map.contour,resources)  # with a set_values call.
resources.sfXCStartV = -180.           # re-establish data boundaries
resources.sfXCEndV   =  180.
resources.sfYCStartV =  -90.
resources.sfYCEndV   =   90.

map = Ngl.contour_map(wks,psl,resources)   # draw filled contours.