Package: pygrace
About Pygracepygracewas designed to enable the construction and use ofxmgraceprojects from Python.pygraceprovides a collection of classes that serve as editable templates for elements of a xmgrace project. The inheritance structure ofpygracemirrors the structure ofxmgrace.pygraceProjectobjects are used to construct and savexmgraceproject files (.agr).Projectfiles capture the state of axmgracesession, including the figures, settings, and current variables.A more detailed diagram of all the attributes ofpygracetemplate objects can be found athttps://github.com/uqfoundation/pygrace/blob/master/docs/diagrams/diagram.pdf, while a handy cheatsheet of the methods and attributes of eachpygracetemplate class can be found athttps://github.com/uqfoundation/pygrace/blob/master/docs/diagrams/cheatsheet.pdf. This cheatsheet can be dynamically generated through use of thewrite_cheatsheetmethod, available from theProjectclass.pygraceis in active development, so any user feedback, bug reports, comments, or suggestions are highly appreciated.  A list of issues is located athttps://github.com/uqfoundation/pygrace/issues, with a legacy list maintained athttps://github.com/pygrace/pygrace/issues.Major Featurespygraceprovides an object-oriented Python interface for the efficient construction ofxmgraceprojects (e.g. highly-customizable publication-quality single and multi-figure plots).pygraceprovides:an object-relational mapping from Python objects to axmgraceprojectan interactive Python-basedgrace>prompt forxmgracecommandsa set of high-level Python functions for drawingxmgraceGraphsCurrent ReleaseThe latest released version ofpygraceis available from:https://pypi.org/project/pygracepygraceis distributed under a 3-clause BSD license.Development VersionYou can get the latest development version with all the shiny new features at:https://github.com/uqfoundationIf you have a new contribution, please submit a pull request.Installationpygracecan be installed withpip:$ pip install pygraceIt is assumedxmgraceis already installed and on the user’s$PATH.xmgraceis available at:https://plasma-gate.weizmann.ac.il/pub/grace/src/Alternately,xmgracetypically can be installed with most package managers. For example:$ apt-get install grace # on Linux
$ brew install grace # on MacOSInstalling an Xserver from X.org (xorg,xorg-server,xquartz, or similar, depending on your operating system and package manager) is also required to open thexmgraceGUI.Requirementspygracerequires:python(orpypy),>=3.8setuptools,>=42cython,>=0.29.30numpy,>=1.0mpmath,>=0.19Additional requirements:xmgrace,>=5.1.14Basic Usagestart apygraceproject file:>>> from pygrace.project import Project
>>> plot = Project()add aGraphto theProjectinstance:>>> graph = plot.add_graph()
>>> graph.title.text = 'Hello, world!'add aDataSetto the graph:>>> data = [(0, 0), (0.5, 0.75), (1, 1)]
>>> dataset = graph.add_dataset(data)save theProjectto a xmgrace project file (.agr format):>>> plot.saveall('00_helloworld.agr')then, open the project file with xmgrace:$ xmgrace 00_helloworld.agrfind out more aboutpygraceathttp://pygrace.rtfd.ioor browse some more of the examples athttps://github.com/uqfoundation/pygrace/tree/master/examples.for example:$ python 05_colorplot.py
$ xmgrace 05_colorplot.agrand:$ python 08_latexlabels.py
$ xmgrace 08_latexlabels.agrwe can also work in an interactive xmgrace session:>>> from pygrace import grace
>>> pg = grace()use xmgrace methods directly from the Python interpreter:>>> import numpy as np
>>> x = np.arange(21) * np.pi/10
>>> pg.plot(x, np.sin(x))push variables into xmgrace and interact with the xmgrace scripting language:>>> pg.put('x', x)
>>> pg.put('y', np.cos(x))
>>> pg.eval('s0 line color 2')
>>> pg.eval('plot(x,y)')use the interactive xmgrace prompt:>>> pg.prompt()
grace interface:
vars=
     y
     x
grace> histoPlot(y)
grace> s0 fill color 3
grace> redraw()
grace> exitcheck variables in xmgrace session:>>> list(pg.who().keys())
['x', 'y']
>>> pg.who('x')
array([0.        , 0.31415927, 0.62831853, 0.9424778 , 1.25663706,
       1.57079633, 1.88495559, 2.19911486, 2.51327412, 2.82743339,
       3.14159265, 3.45575192, 3.76991118, 4.08407045, 4.39822972,
       4.71238898, 5.02654825, 5.34070751, 5.65486678, 5.96902604,
       6.28318531])get variables back into Python from xmgrace:>>> cosx = pg.get('y')use shortcuts for put, eval, and get:>>> pg.z = 0.5
>>> pg('print(z)')
0.5
>>> pg.z + cosx
array([ 1.5       ,  1.45105652,  1.30901699,  1.08778525,  0.80901699,
        0.5       ,  0.19098301, -0.08778525, -0.30901699, -0.45105652,
       -0.5       , -0.45105652, -0.30901699, -0.08778525,  0.19098301,
        0.5       ,  0.80901699,  1.08778525,  1.30901699,  1.45105652,
        1.5       ])delete variables from xmgrace:>>> pg.delete('x')
>>> pg.delete('y')save the current session to a project file, then exit:>>> pg.saveall('histoPlot.agr')
>>> pg.exit()start a new interactive xmgrace session from the saved project:>>> pg = grace(project='histoPlot.agr')More InformationProbably the best way to get started is to look at the documentation athttp://pygrace.rtfd.io. Also seepygrace.testsfor a set of scripts that
demonstrate several of the many features ofpygrace. You can run the test
suite withpython-mpygrace.tests. Also seehttps://github.com/uqfoundation/pygrace/tree/master/examplesfor examples that demonstrate the construction
ofxmgraceproject files (.agr).https://github.com/uqfoundation/pygrace/tree/master/examples/interactiveincludes examples of usingpythonto interact
with a livexmgracesession. The source code is relatively well documented,
so some questions may be resolved by inspecting the code itself.  However,
please feel free to submit a ticket on github, or ask a question on
stackoverflow (@Mike McKerns). If you would like to share how you usepygracein your work, please send an email (tommckerns at uqfoundation
dot org).CitationIf you usepygraceto do research that leads to publication, we ask that you
acknowledge use ofpygraceby citing the following in your publication:Michael McKerns, Dean Malmgren, Mike Stringer, and Daniel Stouffer,
"pygrace: Python bindings to xmgrace", 2005- ;
https://github.com/uqfoundation/pygracePlease seehttps://pygrace.github.io/for further information on an earlier version ofpygracedeveloped by Dean Malmgren, Mike Stringer, and members of the Amaral Lab, and later maintained by Daniel Stouffer and members of the Stouffer Lab. This code has been merged into the originalpygracedeveloped by Mike McKerns.