gracey.py - A python interface to xmgrace ============================================== **SOURCE:** :download:`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: .. code-block:: bash # comment line 1 1 2 4 3 9 4 16 A slightly more complex example have more than one set is: .. code-block:: bash # comment line 1 1 1 2 4 8 3 9 27 4 16 64 An equivalent file to the above would be: .. code-block:: bash # 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: .. code-block:: bash # 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): .. code-block:: bash $ gracey.py datafile [options] or equivalently: .. code-block:: bash $ cat datafile | gracey.py [options] or if there are N data files: .. code-block:: bash $ gracey.py datafile1 datafile2 datafileN [options] or equivalently: .. code-block:: bash $ 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: .. code-block:: bash $ gracey.py datafile s=dia Or one can specify diamonds for the first set, squares for the second, and circles for the third: .. code-block:: bash $ gracey.py datafile s=[dia,sq,o] To further this example, one could specify that all point be green: .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ gracey.py -u 1:3 datafile or equivalently: .. code-block:: bash $ gracey.py datafile::1:3 If one wants to plot the first column against the 4th and 6th column, then: .. code-block:: bash $ gracey.py -u 1:4:6 datafile If there are multiple data files, the -u command is used for all following files: .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ gracey.py -op y:+5 datafile or one can add 5 to the y values of only the 3rd set: .. code-block:: bash $ gracey.py -op y3:+5 datafile or one can add 5 to the y values of the 3rd through 5th sets: .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ 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): .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ gracey.py file1 file2 -fs lc=[bl,bu] .. image:: Untitled.png 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: .. code-block:: bash $ 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 ----------------------------- .. automodule:: gracey :members: