5.7.1 Plotting with the SPA

The SPA provides a basic interface to the powerful NCAR Graphics plotting package. A set of high-level interfaces to NCAR Graphics are provided with the SPA distribution, including scalar and vector plotting routines and a tropical cyclone track mapping algorithm that uses best track data from a variety of sources. Each of the calls to the NCAR Graphics interface routines has numerous optional arguments, only a few of which will be described here. Use the spainfo utility to get version-specific interfacing information for each of the subprograms described here. The default operation of each of these subprograms is to produce an NCAR metafile viewable with the idt program (provided with the NCAR Graphics package). The ctrans program (also provided with NCAR Graphics) can be used to convert the metafile to a printable PostScript file.

Each of the primary plotting interfaces described in the following paragraphs has a set of optional arguments for controlling the superposition of fields and the advancement of the plotter. In each case, setting initialize=.true. (the default) results in the generation of a background map (generally only done once for each plot); setting advance=.true. (the default) causes the plotter to advance after laying down the requested field (set advance=.false. for superposition); and setting shutdown=.true. (the default) closes the active NCAR Graphics process. An example is provided below in which these arguments are used to produce a plot containing multiple fields.

The drawPlot (function) interface is used for producing plots of scalar fields. After use-associating the NCAR_Utilities module, a call to drawPlot can be made directly to produce a metafile containing a plot of the desired field. Numerous optional arguments are available to help the user tune the plot to exact requirements (for example, generating a colour-filled plot rather than contour lines). Note that several optional configuration file flavours can be provided to the drawPlot subprogram to ease the generation of multiple plots with different configurations. For a complete description of the drawPlot arguments, use the spainfo utility.

The drawVectors (function) interface is used for producing plots of a vector field. As described above, this subprogram can be invoked any time after the NCAR Graphics module is associated and produces a standard metafile. Both wind barbs and arrows can be generated and configured using this interface. As for the scalar plotting interface, either a configuration file or a series of optional arguments can be used to describe the nature of the vectors to be plotted.

The drawText (function) interface allows the user to add text to the map or page. Note that the coord optional argument allows the user to distinguish between map and viewport interpretation of the given positional coordinates.

The drawLine (function) interface allows the user to add a line (or set of connected lines) to the map or page. Note that the coord optional argument allows the user to distinguish between map and viewport interpretation of the given positional coordinates. Also, lines can be forced to lie along latitude/longitude circles rather than appearing as straight on the plotted projection.

The drawCentered (function) interface allows the user to generate storm-centered plots in cylindrical coordinates. In this case, the centre argument defines the coordinates of the point to which the pole of the globe is rotated. The result is a polar steregraphic (cylindrical coordinate) grid centred on the location of interest, usually the centre of a system. Because the calculations used to compute the range rings on the rotated polar grid are contained in NCAR Graphics, the computational function ncarCentered, which produces the gridded cylindrical coordinate data, is also a part of the NCAR Graphics API.

The drawTracks (function) interface allows the user to overlay tracking information on scalar and vector plots. The datafile named in the input argument list (use spainfo for details) should be of the form generated by the trackinfo utility provided with this package (see for a complete description).

The drawTrajectory (function) interface allows the user to generate backwards and forwards parcel trajectories. As described above, this subprogram can be invoked any time afer the NCAR Graphics module (NCAR_Utilities) has been use associated and produces a standard metafile. The trajectory can be colour coded for pressure levels (the default) or for a user-defined field as provided by the optional argument. Numerous options for highly-accurate sub-trajectory computations and start/end plotting symbols are avialable through optional arguments. Note that all gridded fields are provided as four dimensional arrays. The fourth dimensions is time, so all data should be read into the data array before drawTrajectory is called. This means that drawTrajectory is one of the very few SPA utilities that must be called from outside the main time loop of the driving program.

This example code segment shows the set of calls required to produce a colour-filled contour plot with vector (barb) overlays. A limited optional argument list is provided to each plotting subprogram and is by no means exhaustive for each.

          GKSerror = drawPlot(theta,dim,                &
                mapBounds=(/-90.,-180.,90.,180./),      &
                projection='CE',                        &
                centre=(/0.,0./),                       &
                fillColours=.true.,                     &
                colourMap=.false.,                      &
                initialize=.true.,                      &
                shutdown=.false.,                       &
                advance=.false.)
           GKSerror = drawVectors(u,v,dim,              &
                vectorRGB=(/1.,1.,0./),                 &
                mapBounds=(/-90.,-180.,90.,180./),      &
                projection='CE',                        &
                centre=(/0.,0./),                       &
                colourMap=.false.,                      &
                initialize=.false.,                     &
                advance=.true., shutdown=.true.)

The ncarInit and ncarEnd (functions) are low-level interfaces not usually called directly by the user. They are, however, used heavily by the drawing interfaces described above. Direct calls to these subprograms are, however, particularly useful if PostScript files are to be generated instead of metafiles (for example, if a large number of plots are to be produced by a single program). For a complete description of these interfaces, use the spainfo utility.

To produce direct PostScript output, the following would have to be added above the plotting calls in the example above.

           GKSerror = ncarInit(device='ps',             &
                orientation='portrait',                 &
                outFileName='testPlot.ps')

And the following would have be added after the end of the segment in the plotting example.

           GKSerror = ncarEnd(GKSerror)

This would ensure the correct startup and shutdown of the NCAR Graphics processes required to generate the requested PostScript file (in this case rather unimaginatively called testPlot.ps).