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.

Option	Grace keyword	Description
ps	page size
pr	page resize
ft	frame type
fl	frame linestyle
flw	frame linewidth
fc	frame color
fbc	frame background color
fp	frame pattern
fbp	frame background pattern
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
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
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
s	symbol	Type of symbol - o,dia,*,sq,+,x,tu,td,tr,tl
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

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 

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.

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.

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.