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:

   Ngl.set_values
   Ngl.get_float
   Ngl.get_integer
   Ngl.get_string
   Ngl.get_integer_array
   Ngl.get_float_array
   Ngl.get_string_array
   Ngl.get_MDfloat_array
   Ngl.get_MDinteger_array
   Ngl.change_workstation
   Ngl.destroy
   Ngl.draw

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.

Ngl.end()