-----------------------------------
pygrace: Python bindings to xmgrace
-----------------------------------
About Pygrace
=============
``pygrace`` was designed to enable the construction and use of ``xmgrace`` projects from Python. ``pygrace`` provides a collection of classes that serve as editable templates for elements of a xmgrace project. The inheritance structure of ``pygrace`` mirrors the structure of ``xmgrace``.
``pygrace`` ``Project`` objects are used to construct and save ``xmgrace`` project files (.agr). ``Project`` files capture the state of a ``xmgrace`` session, including the figures, settings, and current variables.
.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/crow_diagram.png
:alt: pygrace project
A more detailed diagram of all the attributes of ``pygrace`` template objects can be found at https://github.com/uqfoundation/pygrace/blob/master/docs/diagrams/diagram.pdf, while a handy cheatsheet of the methods and attributes of each ``pygrace`` template class can be found at https://github.com/uqfoundation/pygrace/blob/master/docs/diagrams/cheatsheet.pdf. This cheatsheet can be dynamically generated through use of the ``write_cheatsheet`` method, available from the ``Project`` class.
``pygrace`` is in active development, so any user feedback, bug reports, comments, or suggestions are highly appreciated. A list of issues is located at https://github.com/uqfoundation/pygrace/issues, with a legacy list maintained at https://github.com/pygrace/pygrace/issues.
Major Features
==============
``pygrace`` provides an object-oriented Python interface for the efficient construction of ``xmgrace`` projects (e.g. highly-customizable publication-quality single and multi-figure plots). ``pygrace`` provides:
- an object-relational mapping from Python objects to a ``xmgrace`` project
- an interactive Python-based ``grace>`` prompt for ``xmgrace`` commands
- a set of high-level Python functions for drawing ``xmgrace`` ``Graphs``
Current Release
===============
The latest released version of ``pygrace`` is available from:
https://pypi.org/project/pygrace
``pygrace`` is distributed under a 3-clause BSD license.
Development Version
===================
You can get the latest development version with all the shiny new features at:
https://github.com/uqfoundation
If you have a new contribution, please submit a pull request.
Installation
============
``pygrace`` can be installed with ``pip``::
$ pip install pygrace
It is assumed ``xmgrace`` is already installed and on the user's ``$PATH``. ``xmgrace`` is available at:
https://plasma-gate.weizmann.ac.il/pub/grace/src/
Alternately, ``xmgrace`` typically can be installed with most package managers. For example::
$ apt-get install grace # on Linux
$ brew install grace # on MacOS
Installing an Xserver from X.org (``xorg``, ``xorg-server``, ``xquartz``, or similar, depending on your operating system and package manager) is also required to open the ``xmgrace`` GUI.
Requirements
============
``pygrace`` requires:
- ``python`` (or ``pypy``), **>=3.8**
- ``setuptools``, **>=42**
- ``cython``, **>=0.29.30**
- ``numpy``, **>=1.0**
- ``mpmath``, **>=0.19**
Additional requirements:
- ``xmgrace``, **>=5.1.14**
Basic Usage
===========
start a ``pygrace`` project file::
>>> from pygrace.project import Project
>>> plot = Project()
add a ``Graph`` to the ``Project`` instance::
>>> graph = plot.add_graph()
>>> graph.title.text = 'Hello, world!'
add a ``DataSet`` to the graph::
>>> data = [(0, 0), (0.5, 0.75), (1, 1)]
>>> dataset = graph.add_dataset(data)
save the ``Project`` to a xmgrace project file (.agr format)::
>>> plot.saveall('00_helloworld.agr')
then, open the project file with xmgrace::
$ xmgrace 00_helloworld.agr
.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/00_helloworld.png
:alt: 00_helloworld
find out more about ``pygrace`` at http://pygrace.rtfd.io or browse some more of the examples at https://github.com/uqfoundation/pygrace/tree/master/examples.
for example::
$ python 05_colorplot.py
$ xmgrace 05_colorplot.agr
.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/05_colorplot.png
:alt: 05_colorplot
and::
$ python 08_latexlabels.py
$ xmgrace 08_latexlabels.agr
.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/08_latexlabels.png
:alt: 08_latexlabels
we 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))
.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/sin.png
:alt: sin
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)')
.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/cos.png
:alt: cos
use the interactive xmgrace prompt::
>>> pg.prompt()
grace interface:
vars=
y
x
grace> histoPlot(y)
grace> s0 fill color 3
grace> redraw()
grace> exit
.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/histoPlot.png
:alt: histoPlot
check 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 Information
================
Probably the best way to get started is to look at the documentation at
http://pygrace.rtfd.io. Also see ``pygrace.tests`` for a set of scripts that
demonstrate several of the many features of ``pygrace``. You can run the test
suite with ``python -m pygrace.tests``. Also see https://github.com/uqfoundation/pygrace/tree/master/examples for examples that demonstrate the construction
of ``xmgrace`` project files (.agr). https://github.com/uqfoundation/pygrace/tree/master/examples/interactive includes examples of using ``python`` to interact
with a live ``xmgrace`` session. 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 use
``pygrace`` in your work, please send an email (to **mmckerns at uqfoundation
dot org**).
Citation
========
If you use ``pygrace`` to do research that leads to publication, we ask that you
acknowledge use of ``pygrace`` by 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/pygrace
Please see https://pygrace.github.io/ for further information on an earlier version of ``pygrace`` developed 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 original ``pygrace`` developed by Mike McKerns.
Raw data
{
"_id": null,
"home_page": "https://github.com/uqfoundation/pygrace",
"name": "pygrace",
"maintainer": "Mike McKerns",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "mmckerns@uqfoundation.org",
"keywords": "",
"author": "Mike McKerns",
"author_email": "mmckerns@uqfoundation.org",
"download_url": "https://files.pythonhosted.org/packages/7c/26/d77c423318cb11ef48c62473380c5c98baeec26b52968acca8b5b70623a3/pygrace-1.4.tar.gz",
"platform": "Linux",
"description": "-----------------------------------\npygrace: Python bindings to xmgrace\n-----------------------------------\n\nAbout Pygrace\n=============\n\n``pygrace`` was designed to enable the construction and use of ``xmgrace`` projects from Python. ``pygrace`` provides a collection of classes that serve as editable templates for elements of a xmgrace project. The inheritance structure of ``pygrace`` mirrors the structure of ``xmgrace``.\n\n``pygrace`` ``Project`` objects are used to construct and save ``xmgrace`` project files (.agr). ``Project`` files capture the state of a ``xmgrace`` session, including the figures, settings, and current variables.\n\n.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/crow_diagram.png\n :alt: pygrace project\n\nA more detailed diagram of all the attributes of ``pygrace`` template objects can be found at https://github.com/uqfoundation/pygrace/blob/master/docs/diagrams/diagram.pdf, while a handy cheatsheet of the methods and attributes of each ``pygrace`` template class can be found at https://github.com/uqfoundation/pygrace/blob/master/docs/diagrams/cheatsheet.pdf. This cheatsheet can be dynamically generated through use of the ``write_cheatsheet`` method, available from the ``Project`` class.\n\n``pygrace`` is in active development, so any user feedback, bug reports, comments, or suggestions are highly appreciated. A list of issues is located at https://github.com/uqfoundation/pygrace/issues, with a legacy list maintained at https://github.com/pygrace/pygrace/issues.\n\n\nMajor Features\n==============\n\n``pygrace`` provides an object-oriented Python interface for the efficient construction of ``xmgrace`` projects (e.g. highly-customizable publication-quality single and multi-figure plots). ``pygrace`` provides:\n\n - an object-relational mapping from Python objects to a ``xmgrace`` project\n - an interactive Python-based ``grace>`` prompt for ``xmgrace`` commands\n - a set of high-level Python functions for drawing ``xmgrace`` ``Graphs``\n\nCurrent Release\n===============\n\nThe latest released version of ``pygrace`` is available from:\n\n https://pypi.org/project/pygrace\n\n``pygrace`` is distributed under a 3-clause BSD license.\n\nDevelopment Version\n===================\n\nYou can get the latest development version with all the shiny new features at:\n\n https://github.com/uqfoundation\n\nIf you have a new contribution, please submit a pull request.\n\n\nInstallation\n============\n\n``pygrace`` can be installed with ``pip``::\n\n $ pip install pygrace\n\nIt is assumed ``xmgrace`` is already installed and on the user's ``$PATH``. ``xmgrace`` is available at:\n\n https://plasma-gate.weizmann.ac.il/pub/grace/src/\n\nAlternately, ``xmgrace`` typically can be installed with most package managers. For example::\n\n $ apt-get install grace # on Linux\n $ brew install grace # on MacOS\n\nInstalling an Xserver from X.org (``xorg``, ``xorg-server``, ``xquartz``, or similar, depending on your operating system and package manager) is also required to open the ``xmgrace`` GUI.\n\n\nRequirements\n============\n\n``pygrace`` requires:\n\n - ``python`` (or ``pypy``), **>=3.8**\n - ``setuptools``, **>=42**\n - ``cython``, **>=0.29.30**\n - ``numpy``, **>=1.0**\n - ``mpmath``, **>=0.19**\n\nAdditional requirements:\n\n - ``xmgrace``, **>=5.1.14**\n\n\nBasic Usage\n===========\n\nstart a ``pygrace`` project file::\n\n >>> from pygrace.project import Project\n >>> plot = Project()\n\nadd a ``Graph`` to the ``Project`` instance::\n\n >>> graph = plot.add_graph()\n >>> graph.title.text = 'Hello, world!'\n\nadd a ``DataSet`` to the graph::\n\n >>> data = [(0, 0), (0.5, 0.75), (1, 1)]\n >>> dataset = graph.add_dataset(data)\n\nsave the ``Project`` to a xmgrace project file (.agr format)::\n\n >>> plot.saveall('00_helloworld.agr')\n\nthen, open the project file with xmgrace::\n\n $ xmgrace 00_helloworld.agr\n\n.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/00_helloworld.png\n :alt: 00_helloworld\n\nfind out more about ``pygrace`` at http://pygrace.rtfd.io or browse some more of the examples at https://github.com/uqfoundation/pygrace/tree/master/examples.\n\nfor example::\n\n $ python 05_colorplot.py\n $ xmgrace 05_colorplot.agr\n\n.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/05_colorplot.png\n :alt: 05_colorplot\n\nand::\n\n $ python 08_latexlabels.py\n $ xmgrace 08_latexlabels.agr\n\n.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/08_latexlabels.png\n :alt: 08_latexlabels\n\n\nwe can also work in an interactive xmgrace session::\n\n >>> from pygrace import grace\n >>> pg = grace()\n\nuse xmgrace methods directly from the Python interpreter::\n\n >>> import numpy as np\n >>> x = np.arange(21) * np.pi/10\n >>> pg.plot(x, np.sin(x))\n\n.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/sin.png\n :alt: sin\n\npush variables into xmgrace and interact with the xmgrace scripting language::\n\n >>> pg.put('x', x)\n >>> pg.put('y', np.cos(x))\n >>> pg.eval('s0 line color 2')\n >>> pg.eval('plot(x,y)')\n\n.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/cos.png\n :alt: cos\n\nuse the interactive xmgrace prompt::\n\n >>> pg.prompt()\n grace interface:\n vars=\n y\n x\n grace> histoPlot(y)\n grace> s0 fill color 3\n grace> redraw()\n grace> exit\n\n.. image:: https://github.com/uqfoundation/pygrace/raw/master/docs/source/_static/histoPlot.png\n :alt: histoPlot\n\ncheck variables in xmgrace session::\n\n >>> list(pg.who().keys())\n ['x', 'y']\n >>> pg.who('x')\n array([0. , 0.31415927, 0.62831853, 0.9424778 , 1.25663706,\n 1.57079633, 1.88495559, 2.19911486, 2.51327412, 2.82743339,\n 3.14159265, 3.45575192, 3.76991118, 4.08407045, 4.39822972,\n 4.71238898, 5.02654825, 5.34070751, 5.65486678, 5.96902604,\n 6.28318531])\n\nget variables back into Python from xmgrace::\n\n >>> cosx = pg.get('y')\n\nuse shortcuts for put, eval, and get::\n\n >>> pg.z = 0.5\n >>> pg('print(z)')\n 0.5\n >>> pg.z + cosx\n array([ 1.5 , 1.45105652, 1.30901699, 1.08778525, 0.80901699,\n 0.5 , 0.19098301, -0.08778525, -0.30901699, -0.45105652,\n -0.5 , -0.45105652, -0.30901699, -0.08778525, 0.19098301,\n 0.5 , 0.80901699, 1.08778525, 1.30901699, 1.45105652,\n 1.5 ])\n\ndelete variables from xmgrace::\n\n >>> pg.delete('x')\n >>> pg.delete('y')\n\nsave the current session to a project file, then exit::\n\n >>> pg.saveall('histoPlot.agr')\n >>> pg.exit()\n\nstart a new interactive xmgrace session from the saved project::\n\n >>> pg = grace(project='histoPlot.agr')\n\n\nMore Information\n================\n\nProbably the best way to get started is to look at the documentation at\nhttp://pygrace.rtfd.io. Also see ``pygrace.tests`` for a set of scripts that\ndemonstrate several of the many features of ``pygrace``. You can run the test\nsuite with ``python -m pygrace.tests``. Also see https://github.com/uqfoundation/pygrace/tree/master/examples for examples that demonstrate the construction\nof ``xmgrace`` project files (.agr). https://github.com/uqfoundation/pygrace/tree/master/examples/interactive includes examples of using ``python`` to interact\nwith a live ``xmgrace`` session. The source code is relatively well documented,\nso some questions may be resolved by inspecting the code itself. However,\nplease feel free to submit a ticket on github, or ask a question on\nstackoverflow (**@Mike McKerns**). If you would like to share how you use\n``pygrace`` in your work, please send an email (to **mmckerns at uqfoundation\ndot org**).\n\n\nCitation \n========\n\nIf you use ``pygrace`` to do research that leads to publication, we ask that you\nacknowledge use of ``pygrace`` by citing the following in your publication::\n\n Michael McKerns, Dean Malmgren, Mike Stringer, and Daniel Stouffer,\n \"pygrace: Python bindings to xmgrace\", 2005- ;\n https://github.com/uqfoundation/pygrace\n\nPlease see https://pygrace.github.io/ for further information on an earlier version of ``pygrace`` developed 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 original ``pygrace`` developed by Mike McKerns.\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Python bindings to xmgrace",
"version": "1.4",
"project_urls": {
"Bug Tracker": "https://github.com/uqfoundation/pygrace/issues",
"Documentation": "http://pygrace.rtfd.io",
"Download": "https://pypi.org/project/pygrace/#files",
"Homepage": "https://github.com/uqfoundation/pygrace",
"Source Code": "https://github.com/uqfoundation/pygrace"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9f155a45f423c38d4025e608f231288b5ce94fa38e83cbdb2553536d6d6716c6",
"md5": "8b9ab43eb32b46f12a7744ede383dbad",
"sha256": "24d660f6f05ec1ea436a7c25612d87d4688039bc94908a29cff4d4e122fc8c11"
},
"downloads": -1,
"filename": "pygrace-1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b9ab43eb32b46f12a7744ede383dbad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 238721,
"upload_time": "2024-01-28T19:37:06",
"upload_time_iso_8601": "2024-01-28T19:37:06.843529Z",
"url": "https://files.pythonhosted.org/packages/9f/15/5a45f423c38d4025e608f231288b5ce94fa38e83cbdb2553536d6d6716c6/pygrace-1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7c26d77c423318cb11ef48c62473380c5c98baeec26b52968acca8b5b70623a3",
"md5": "ca9d499b14686248e3e4a94daf932a64",
"sha256": "8d196acbf81627d6ffb7694455fe65a593ebfbc44609163399369e7291e2c749"
},
"downloads": -1,
"filename": "pygrace-1.4.tar.gz",
"has_sig": false,
"md5_digest": "ca9d499b14686248e3e4a94daf932a64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 529017,
"upload_time": "2024-01-28T19:37:09",
"upload_time_iso_8601": "2024-01-28T19:37:09.248159Z",
"url": "https://files.pythonhosted.org/packages/7c/26/d77c423318cb11ef48c62473380c5c98baeec26b52968acca8b5b70623a3/pygrace-1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-28 19:37:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "uqfoundation",
"github_project": "pygrace",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"tox": true,
"lcname": "pygrace"
}
JSON
