gracey.py - A python interface to xmgrace

SOURCE: gracey.py

Gracey is a python interface to Grace (xmgrace), one of the classic 2-d plotting programs. Gracey is object oriented, making it easy for others to modify and adapt. All one needs to run Gracey is access to Grace and python. Gracey has many useful features which facilitate plotting from the command line, and this is what sets it apart from other python interfaces to Grace that I am familiar with. Of course, Gracey may be used to easily create complex plots from within python programs as well.

Acceptable data file formats

There are numerous acceptable formats for data files. Lines in the file having a first character of “#” are comments. Perhaps the simplest datafile would be of the following form:

# comment line
1 1
2 4
3 9
4 16

A slightly more complex example have more than one set is:

# comment line
1 1  1
2 4  8
3 9  27
4 16 64

An equivalent file to the above would be:

# comment line
1 1
2 4
3 9
4 16

1 1
2 8
3 27
4 64

The above file format is referred to as “space delimited” hereafter, and in order for gracey to work properly one must use the -s option at the command line. Reasons for this will become clear later. One may also use more complicated files such as:

# comment line
1 1  1  1
2 4  8  10
3 9  27 29
4 16 64 66

# comment
1 1
2 2
3 3
4 4

The -s option would still be needed in this case is it is still space delimited.

Executing Gracey

Gracey is called from the command line as follows (order of filename/options irrelevant):

$ gracey.py datafile [options]

or equivalently:

$ cat datafile | gracey.py [options]

or if there are N data files:

$ gracey.py datafile1 datafile2 datafileN [options]

or equivalently:

$ cat datafile1 | gracey.py datafile2 datafileN [options]

Specifying color

There are many options which require the specification of a color, such as symbols, lines, etc. In Grace, this is specified with an integer. In Gracey, one may specify an integer, or more conveniently, a full color name or an abbreviation for a color name. For example, one may specify “yellow” or simply “ye”. The abbreviation is the first two letters of the color name unless there is ambiguity. Exceptions are bu-blue and gy-grey.

Command options for formatting plot

A large number of options are available to customize the plot from the command line. These options are detailed in the chart below. The first column gives the Gracey abreviation, the second column gives the corresponding Grace keywords, and the third column is a description. Descriptions are ommitted when obvious. One does not need to worry about the Grace keywords unless you are trying to modify the code or do something more complex.

Options are specified in the command line as “Option=Value”, or for data set dependent options for N sets as “Option=[Value1,Value2,ValueN]”. This is probably best illustrated with an example, such as the type of symbols. Consider a datafile with three sets. All sets can be respresented by diamonds as follows:

$ gracey.py datafile s=dia

Or one can specify diamonds for the first set, squares for the second, and circles for the third:

$ gracey.py datafile s=[dia,sq,o]

To further this example, one could specify that all point be green:

$ gracey.py datafile s=[dia,sq,o] sc=gr

Or one could specify green for the first set, red for the second, and blue for the third:

$ gracey.py datafile s=[dia,sq,o] sc=[gr,re,bu]

If you were to give a number of arguments different than the number of sets or 1, an error is generated and Gracey informs you of the offending option:

$ gracey.py datafile s=[dia,sq,o] sc=[gr,re,bu,ye]

improper array size given for input variable sc ERROR: problem with plot… see above.

If a space delimited data file is being used, be sure to use the -s option on the command line or else the number of data sets is not properly counted and there will be problems.

Selecting data sets from a file

By default, Gracey will plot all of the data sets present in a datafile. However, this is often not desired. Particular sets from a datafile can be selected in two ways. For example, to plot the first column against the third column:

$ gracey.py -u 1:3 datafile

or equivalently:

$ gracey.py datafile::1:3

If one wants to plot the first column against the 4th and 6th column, then:

$ gracey.py -u 1:4:6 datafile

If there are multiple data files, the -u command is used for all following files:

$ gracey.py datafile1 datafile2 -u 1:3:5 datafile3 datafile4

In the above case, the 1st, 3rd, and 5th column are used from the 3rd and 4th datafile and all sets are used from the first and second data files. Similarly, one can use the double colon notation when dealing with many files and the result should be clear:

$ gracey.py datafile1 datafile2::1:3 datafile3 datafile4::1:4:5 datafile5

Operate on data set

Often, it is useful to perform mathematical operations on some or all of the data sets. This can be performed using the -op option. The notation is a bit cryptic and is best illustrated with examples. For example, one can add 5 to the y values of all data sets:

$ gracey.py -op y:+5 datafile

or one can add 5 to the y values of only the 3rd set:

$ gracey.py -op y3:+5 datafile

or one can add 5 to the y values of the 3rd through 5th sets:

$ gracey.py -op y3..5:+5 datafile

Of course, the same can be done for the x values. Also, one is obviously not limited to addition. One could also combine mutliple operations, such as multiplying by 3 and adding 2 to all y values:

$ gracey.py -op y:*3+2 datafile

Output of code

Gracey outputs the Grace batch file that it generates. Generally, one does not need to worry about this. However, this can be very useful to understand what is going on if you are confused.

Use a color gradient for line colors

Sometimes one has many data sets and it is useful to vary the line color of each set by interpolating between two colors. This is trivially done as follows:

$ gracey.py -cg datafile

Currently, Gracey will interpolate from red to green. No other scheme is presently available. However, this is trivial to change in the code if necessary (ie. see the color_grade method).

One can also use this color gradient in a filestyle mode with N files as follows:

$ gracey.py -cgfs datafile1 datafile2 datafileN

Make a primitive contour plot

One can make a primitive contour plot by having the color of the x-y data points determined by the corresponding z value. The format of the input file is three columns, with the third column being the z-value. The z-value may vary between 100 and 200, and the color will vary between red and green. This file may only have three columns, so a space delimited file should be used if multiple sets are present. If you do electronic structure calculations, this is useful for making color-bands (ie. color corresponds to orbital character):

$ gracey.py -con datafile

Automatic legend and symbol generation

Sometimes, one would like to label all the sets by which file they came from, and this is done with leg=auto. Also, sometimes one would like to have a symbol defined for each set without doing this by hand, and this is done with s=auto. The behavior is slightly different, as expected, in filestyle mode.

File style options

Very often, one would like to apply the same options for all the sets in a given file when their are mutliple files present. Of course, one could manually do this, but if each file has 20 sets and there are many files it is very cumbersome. This is easily resoloved with the filestyle option. When filestyle is specified (ie. -fs ), one only supplies a list of style parameters with a length equal to the number of files instead of the total number of sets. We will consider an example where all the set symbols in the 1st, 2nd, and 3rd file are colored red, blue, and green, respectively:

$ gracey.py -fs datafile1 datafile2 datafile3 s=dia sc=[re,bu,gr]

In this case we chose that all symbols would be diamonds.

The option for automatic symbol generation (ie. s=auto) and legend generation (ie. leg=auto) work in filestyle mode.

A typical example where one would want to use filestyle is plotting two band structures together. In this case we would like all lines of a given file to be the same color. This can easily be accomplished like this:

$ gracey.py file1 file2 -fs lc=[bl,bu]

Outputting a hard copy

At some point you will want to get a hardcopy of your plot. This can be done using one of the following options on the command line: PostScript, EPS, JPEG, PNG, SVG, null. For example, we can generate an encapsulated postscript (ie. EPS) as follows:

$ gracey.py datafile s=dia sc=re EPS

A file called Untitled.eps will be created. The same can be done for all other formats. Some of the formats may not be supported depending on how Grace was compiled on your system.

Table of gracey.py commands

gracey	xmgrace	Example
ps	page size	800,600
pr	page resize	800,600
ft	frame type
fl	frame linestyle
flw	frame linewidth
fc	frame color
fbc	frame background color
fp	frame pattern
fbp	frame background pattern
w	world
xmin	world xmin
xmax	world xmax
ymin	world ymin
ymax	world ymax
v	view
t	title
tf	title font
ts	title size
tc	title color
st	subtitle
sts	subtitle size
xa	xaxis
ax	autoscale xaxes
xl	xaxis label
xls	xaxis label char size
xlf	xaxis label font
xt	xaxis tick major
xtm	xaxis tick minor ticks
xtl	xaxis ticklabel
xtls	xaxis ticklabel char size
xtlf	xaxis ticklabel font
xtlc	xaxis ticklabel color
xtlo	xaxis ticklabel offset spec xaxis ticklabel offset
xtp	xaxis tick place
xbl	xaxis bar linewidth
ya	yaxis
ay	autoscale yaxes
yl	yaxis label
yls	yaxis label char size
ylf	yaxis label font
yt	yaxis tick major
ytm	yaxis tick minor ticks
ytl	yaxis ticklabel
ytls	yaxis ticklabel char size
ytlf	yaxis ticklabel font
ytlc	yaxis ticklabel color
ytlo	yaxis ticklabel offset spec yaxis ticklabel offset
ytp	yaxis tick place
ll	legend
llt	legend loctype
lcs	legend char size
lbf	legend box fill pattern
lbl	legend box linestyle
lvg	legend vgap
lhg	legend hgap
ys	yaxes scale
xs	xaxes scale
strz	with string string on string def
strzl	string
strc	string color
strr	string rot
strf	string font
strj	string just
strcs	string char size
strlt	string loctype
box	with box box on box def box
boxc	box color
boxlt	box loctype
boxlw	box linewidth
boxls	box linestyle
boxfc	box fill color
boxfp	box fill pattern
linel	with line line on line def line
linec	line color
linelt	line loctype
linew	line linewidth
lines	line linestyle
linea	line arrow
lineat	line arrow type
linealen	line arrow length
linealay	line arrow layout
ebs	errorbar size
ebc	errorbar color
s	symbol
ss	symbol size
sc	symbol color
sfc	symbol fill color
sfp	symbol fill pattern
sp	symbol pattern
sls	symbol linestyle
slw	symbol linewidth
sch	symbol char
schf	symbol char font
leg	legend
l	line type
ls	line linestyle
lw	line linewidth
lc	line color

Docstrings from gracey.py

Copyright (C) 2019 Marianetti Group

class gracey.plot(mode='')

this class is use to create grace plots in python

auto_leg()

this method creates a legend where each set is labeled by it’s filename and set number.

auto_symbol()

this method automatically gives a unique symbol to each set. however, there are only ten symbols defined in xmgrace so the symbols will repeat after ten sets.

candles(inp)

this method is used to make candles for stock plots. the input is: x,open,high,low,close

comment_to_legend()

takes comments from input file and makes these the legend label. comment must be of the form ‘# comment1 comment2 …’, and this must only be on the line before the set starts. this will likely be used in a space delimited file, so remeber to set space_delimited flag (ie. -s).

contour(files)

this method allows for a primitive contour map. three columns must be specified for each set with the third column being the point color. only three columns per file. mulitple sets can be given with delimiting sets by a (horizontal) space.

data(dlist, space_delimited='', pcol=[], use_comments=False)

plot a data file. dlist is either a filename as a string or a list of strings. all columns in the file will be treated as data. space_delimited determines wether or not a empty row within a file should be treated as demarcating a new set (default=False not yet totally robust). pcol allows one to plot only certain columns of files having multiple column sets.

defaults(file='')

Apply default values from the supplied file.

fat_contour(files)

this method is similar to contour, except instead of using color it uses the size of the point from the third column. You should scale your results however you need to get reasonable point sizes.

filestyle(inp='')

define set attributes for all sets in a file. for example, when plotting two files with many sets, one want all sets from each file colored the same. the method should be given an input string such as “lc=[1,2]” which means color all the lines in the first file color 1, etc (ie. for a plot made from 2 files). defaults are provided for lc,sc,sfc if nothing given. s=auto will give an automatic symbol for all sets in a given file. leg=auto will create a legend with the filename for each set within a file.

function(inp1, inp2=[])

plot a list/array from python. if only a single list is given, it should contain x,y1,y2,etc. if two lists are given, the first should be the x data and the second is y1,y2,y3,etc.

get_limits(file='')

This method determines retrieves xmgrace’s values for the bounds of the plot (ie. xmin, xmax, ymin, ymax). This is useful when you want to use these bounds for defining lines or string positions but dont want to have to always specify them. This is kind of clunky as we actually have to fire up xmgrace and then grep the values out of the output, but it works.

gracefunc(inp)

this method plots a function using grace’s built-in capabilities. all we need to do is provide the x-mesh. inp should be given as a string or list of xmin,xmax,xinc,func or simply “xmin,xmax,xinc func1 func2 etc” or even “xmin,xmax,xinc func1 xmin,xmax,xinc func2 func3 etc”. convention should be clear. if xinc is chosen to be less than zero, it is assumed to be the number of points and not the increment. enter “help” to print selected grace functions.

newsubplot()

create a new subplot

oldcandles(inp, bw=1.0, sw=0.1)

this method is used to make candles for stock plots. the input is: x,open,high,low,close

oldquickin(modparam, nset=0, use_default=True, debug='')

this method allows most grace commands with a shortcut syntax. a dictionary is used to store the shortcut names as keys, and the values are a two item list with the first item being the grace command and the second item the deafault value (optiotnal) of the grace command. in the case of commands corresonding to data set quantities (ie. line color), the value of the grace command is given as a list. this method takes in a string such as “t=plot1 xl=eV” and will look through the dictionary to find the proper grace command. any text will automatically be quoted. set quantities are specified as “s=[1,2,3]”, which correspond to a plot with three sets, and assigns symbol type one for set one, etc. one may also specify plot defaults by manually modifying the dictionary below.

operate_on_set(input)

operate on the datasets and modify the x and/or y values. x4..6:*2.5

postprocess()

this method does any postprocessing

put(inp)

send command to the grace pipe and/or append to batch variable

quickin(modparam, nset=0, use_default=True)

this method allows most grace commands with a shortcut syntax. a dictionary is used to store the shortcut names as keys, and the values are a two item list with the first item being the grace command and the second item the default value (deprecated, now use defaults method) of the grace command. in the case of commands corresonding to data set quantities (ie. line color), the value of the grace command is given as a list. this method takes in a string such as “t=plot1 xl=eV” and will look through the dictionary to find the proper grace command. any text will automatically be quoted. set quantities are specified as “s=[1,2,3]”, which correspond to a plot with three sets, and assigns symbol type one for set one, etc. one may also specify plot defaults by manually modifying the dictionary below.

save(filename='')

save the entire session as a grace file

show(device='')

if interactive mode is not being used, this can be used to call grace AFTER all of the desired commands have been enetered. also, this method will create a hardcopy if PostScript, EPS, JPEG, or PNG is specified in the constructor, even in interactive mode.