qplot - make plots using Python’s matplotlib package
qplot plot_string [prefix suffix [nslices]]
Qplot is a Python script which uses Python’s matplotlib package to make plots of fields in Candis files. The Candis file is expected on the standard input.
The command line argument plot_string controls the plot and in general should be quoted to guard against shell expansion. The optional arguments prefix and suffix cause the plot to be output as a file with the name prefix.suffix. If the optional argument nslices is included, then a plot will be made for each variable slice available up to the specified maximum. If nslices exists and is greater than one, the files will be named prefix001.suffix, prefix002.suffix, etc., with one file per variable slice. The suffix should be named after the file extension associated with the desired output file format, e. g., eps, ps, pdf, png, svg, etc. Others may be available and not all of these may be present, depending on the system. If only the plot string command line argument is present, qplot will display a single plot using matplotlib’s native display mechanism.
The plot_string command line argument is made up of one or more commands separated by the character "/". Each command in turn is composed of components separated by the character ",". If a "/" or "," is needed in a component it should be preceded by the character "~" so that it is not confused with a separator. A literal "~" must itself also be preceded by a "~" in order to distinguish it from its escape character role.
There are three types of commands: (1) pre-plotting commands; (2) plotting commands; and (3) plot beautification commands. Command components enclosed in square brackets are optional.
All of these commands are optional.
/size,fs/ This command sets the font size in points to be used in most text. The default for size is 12 pt.
/sx,sy,nx,ny[,lm,rm,bm,tm,hs,vs],fg/ This command defines the figure size and number of sub-plots, which are arranged as a rectangular grid of plots with nx columns and ny rows. The horizontal and vertical figure dimensions are given in inches by sx and sy. The default size is 8 by 6 inches. The optional components lm, rm, bm, tm, hs, vs give the left, right, bottom, and top margins and the horizontal and vertical spacing of subplots, all in inches. Matplotlib doesn’t feel bound to honor hs and vs strictly, and exactly where the figure ends and margin starts is a bit uncertain, so experimentation is in order. The default values of these components are 1, 1, 1, 1, 3, 3 inches respectively, and if a zero value is specified for a particular component, the default value is used. This command is only needed if multiple sub-plots are desired or if a non-standard figure size or shape is needed.
/spnum,sp/ This command sets the sub-plot number, which ranges from spnum = 1 to nx*ny. The sub-plots are with nx iterating most rapidly. When making sub-plots, the sub-plot number should be set for each sub-plot, followed by all the plotting commands and beautification commands for that sub-plot.
At least one of these commands must be issued. Line-producing commands should be called after fill and image producing commands.
/x,y,var[,cmap[,ccs]],f/ This command produces a filled contour plot with a color bar on the right side to indicate contour values. The components x and y give the Candis names of the index fields (axes) for the horizontal and vertical axes respectively, which must be consistent with the dimensions of the component var, the name of the Candis field to be plotted. The optional component cmap specifies a color map to use. The choices are 1 (jet; the default), 2 (gray; a gray scale map), 3 (summer; a summer-themed color map), and 4(spectral; a color map somewhat similar to jet). The optional component ccs (which may only be accessed if the color map is specified) provides contours to be plotted in the form min_contour:max_contour:number_of_contours.
/x,y,var[,cmap],i/ This command operates like the filled contour command except that it produces an image in which the image color is mapped to the Candis field value. The cmap specifies a color map as with the filled contour command. The output for this command is considerably larger than the corresponding output for a filled contour plot.
/x,y,var[,c[,lw[,ccs]]],c/ This command creates a conventional contour plot with components as in the filled contour plot with the following exceptions: The optional component c specifies the color of the contour lines, with values r, g, b, y, m, c, k, w indicating "red", "green", "blue", "yellow", "magenta", "cyan", "black", and "white" respectively. The optional component lw specifies the line width in points. The default color scheme for contour lines is to cycle through the above colors. A colorbar is created on the right side of the plot only in the case with no optional components specified.
/x,y,u,v,skx,sky[,scale[,c]],v/ This command plots a grid of vectors representing the two-dimensional vector field with components given by the variables u and v. The variables x and y define the axes as above. The quantities skx and sky define "thinning factors"; a value of 1 means all data are used, 2 means every other data point, 3 every third data point, etc. The optional component scale is a floating point scale factor for both axes which gives the number of axis units per vector unit. A reasonable default choice is made if this component is missing. The optional component c specifies the color of the vectors as in the contour plot. The default is black.
/x,y[,fmt[,lw[,legend]]],p/ This command makes a line or marker plot of the Candis variable y versus the variable x. The default is a line whose color changes as successive plot commands of this type are called. The optional component fmt specifies the color and type of line or point. The first character is a color as specified in the contour plot above. The optional second and possibly third characters specify a line or marker type. For instance, "-" indicates a solid line (default), "--" a dashed line, "-." a dash-dot line, "." a point marker, "o" a circle marker, "v" a triangle marker, "s" a square marker, "*" a star marker, "+" a plus marker, "x" an x marker, etc. The optional component lw specifies the line width as in the contour plot. If the optional component legend is present, it replaces the default legend. Legends are only drawn if the le command is given -- see below. The two variables must either have the same exact dimensions or one of them must be a one-dimensional field with the other having the same first dimension as that of the one-dimensional field.
/x,y[,fmt[,lw[,legend]]],x/ As for the line or marker plot except log x axis.
/x,y[,fmt[,lw[,legend]]],y/ As for the line or marker plot except log y axis.
/x,y[,fmt[,lw[,legend]]],l/ As for the line or marker plot except log x and y axes.
/xcoords,ycoords[,fmt[,lw[,legend]]],d/ This draws a polyline from the x and y coordinates xcoords and ycoords with successive x and y values separated by colons, e. g., xcoords = 1:3:5.5:8, ycoords = 7:4:-1:-5. The optional fmt and lw commands act as in the line plot above. This draws straight line segments on semilog and log-log plots as well. The default legend is null.
/x,y,len,label[,c],a/ This draws a horizontal arrow of length len at the location x,y and writes the label above it. The purpose is to provide a visual calibration of vector lengths for a previous vector plot. (Technically, the calibration is only correct for the horizontal vector components.) By default, the arrow is black, but the color c can be optionally specified as in vector plots. The location is given in plot (or sub-plot) physical coordinates and the length of the arrow is given in the same units as the length of vectors in the previous vector plot.
Plot beautification commands label axes, set axis scales, add text and titles, etc. They are all optional, but are often needed to make plots more intelligible.
/xmin,xmax,dx,ymin,ymax,dy,ax/ This command sets the x (xmin, xmax) and y (ymin, ymax) axis limits and the interval between tic marks (dx, dy).
/label,lx/, /label,ly/ These commands label the x and y axes. Text contained between dollar signs is interpreted as Latex.
/label,xloc,yloc[,c],ll/ This command writes text label on the plot at location (xloc, yloc) with the optional color defined by c, as specified for line colors in contour plots. Text contained between dollar signs is interpreted as Latex.
/title[,fs],tl/ This command places the text contained in title above the current plot. The font size of the title in points is given by the optional component fs. Text contained between dollar signs is interpreted as Latex.
/title[,fs],tu/ This command places an "uber-title" above the entire figure. Otherwise see the title command above. This command should be called after all sub-plots have been completed.
/onoff,gr/ This command draws a grid on the plot if onoff = 1 and omits the grid if onoff = 0. Off is the default.
/[location],le/ This command draws a legend identifying the variables involved in line/mark plots. It is most useful when multiple lines are drawn on a single sub-plot. The optional location argument tells qplot where to put the legend on the plot, with the possible choices being ne, n, nw, w, sw, s, se, e, c; i. e., map directions. The default is ne.
This script depends on the standard numpy and matplotlib packages of Python as well as the Candis access package pycandis written by Max Brister. This package is part of the Candis distribution.
If the order of dimensions in a variable is not what is desired for aP to change the order. plot, use the Candis filter cdforder
The Latex feature for text doesn’t work well for text rotated out of the horizontal, as with y axis labels. This is a bug in version 0.99 of matplotlib, and hopefully will go away at some point.
There are still issues with the matplotlib interpretation of numpy masked arrays in filled contour plots.
David J. Raymond, raymond@kestrel.nmt.edu.