Formulate
=========
|Build Status| |Coverage Status| |PyPI| |Scikit-HEP Project|
Easy conversions between different styles of expressions. Formulate
currently supports converting between
`ROOT <https://root.cern.ch/doc/master/classTFormula.html>`__ and
`numexpr <https://numexpr.readthedocs.io/en/latest/user_guide.html>`__
style expressions.
.. |Build Status| image:: https://github.com/scikit-hep/formulate/workflows/Python%20package/badge.svg
:target: https://github.com/scikit-hep/formulate/actions
.. |Coverage Status| image:: https://coveralls.io/repos/github/scikit-hep/formulate/badge.svg?branch=master&service=github
:target: https://coveralls.io/github/scikit-hep/formulate?branch=master
.. |PyPI| image:: https://badge.fury.io/py/formulate.svg
:target: https://pypi.python.org/pypi/formulate/
.. |Scikit-HEP Project| image:: https://scikit-hep.org/assets/images/Scikit--HEP-Project-blue.svg
:target: https://scikit-hep.org
Installation
------------
Install formulate like any other Python package:
.. code-block:: bash
pip install --user formulate
or similar (use ```sudo``, ```virtualenv``, or ```conda``` if you wish).
Usage
-----
Command line usage
""""""""""""""""""
.. code-block:: bash
$ python -m formulate --from-root '(A && B) || TMath::Sqrt(A)' --to-numexpr
(A & B) | sqrt(A)
$ python -m formulate --from-numexpr '(A & B) | sqrt(A)' --to-root
(A && B) || TMath::Sqrt(A)
$ python -m formulate --from-root '(A && B) || TMath::Sqrt(1.23) * e**1.2 + 5*pi' --variables
A
B
$ python -m formulate --from-root '(A && B) || TMath::Sqrt(1.23) * e**1.2 + 5*pi' --named-constants
E
PI
$ python -m formulate --from-root '(A && B) || TMath::Sqrt(1.23) * e**1.2 + 5*pi' --unnamed-constants
1.2
1.23
5
API
"""
The most basic usage involves calling ``from_$BACKEND`` and then ``to_$BACKEND``, for example when starting with a ROOT style expression:
.. code-block:: python
>>> import formulate
>>> momentum = formulate.from_root('TMath::Sqrt(X_PX**2 + X_PY**2 + X_PZ**2)')
>>> momentum
Expression<SQRT>(Expression<ADD>(Expression<POW>(Variable(X_PX), UnnamedConstant(2)), Expression<POW>(Variable(X_PY), UnnamedConstant(2)), Expression<POW>(Variable(X_PZ), UnnamedConstant(2))))
>>> momentum.to_numexpr()
'sqrt(((X_PX ** 2) + (X_PY ** 2) + (X_PZ ** 2)))'
>>> momentum.to_root()
'TMath::Sqrt(((X_PX ** 2) + (X_PY ** 2) + (X_PZ ** 2)))'
Similarly, when starting with a ``numexpr`` style expression:
.. code-block:: python
>>> my_selection = formulate.from_numexpr('X_PT > 5 & (Mu_NHits > 3 | Mu_PT > 10)')
>>> my_selection.to_root()
'(X_PT > 5) && ((Mu_NHits > 3) || (Mu_PT > 10))'
>>> my_selection.to_numexpr()
'(X_PT > 5) & ((Mu_NHits > 3) | (Mu_PT > 10))'
If the the type of expression isn't known in advance ``formulate`` can also auto detect it:
.. code-block:: python
>>> my_sum = formulate.from_auto('True + False')
>>> my_sum.to_root()
'true + false'
>>> my_sum.to_numexpr()
'True + False'
The ``Expression`` Object
"""""""""""""""""""""""""
When calling ``from_*`` the returned object is derived from ``formulate.ExpressionComponent``. From this object you can inspect the expression to find it's dependencies:
.. code-block:: python
>>> my_check = formulate.from_auto('(X_THETA*TMath::DegToRad() > pi/4) && D_PE > 9.2')
>>> my_check.variables
{'D_PE', 'X_THETA'}
>>> my_check.named_constants
{'DEG2RAD', 'PI'}
>>> my_check.unnamed_constants
{'4', '9.2'}
Additionally ``ExpressionComponent`` s can be combined using both operators and ``numpy`` functions:
.. code-block:: python
>>> new_selection = (momentum > 100) and (my_check or (numpy.sqrt(my_sum) < 1))
>>> new_selection.to_numexpr()
'((X_THETA * 0.017453292519943295) > (3.141592653589793 / 4)) & (D_PE > 9.2)'
As the ``==`` operator returns a new expression, it can't be used to check for equality. Instead the ``.equivalent`` method should be used:
**TODO: Implement this using** ``expression.equivalent`` **!**
Raw data
{
"_id": null,
"home_page": "https://github.com/scikit-hep/formulate",
"name": "formulate",
"maintainer": "The Scikit-HEP admins",
"docs_url": null,
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7",
"maintainer_email": "scikit-hep-admins@googlegroups.com",
"keywords": "formula,conversion,ROOT,numexpr,HEP",
"author": "Chris Burr",
"author_email": "c.b@cern.ch",
"download_url": "https://files.pythonhosted.org/packages/c5/39/7c55af7fafbdc40d09ae7e21728f95bcbb077ab28b45c511aafbf8deebec/formulate-0.1.1.tar.gz",
"platform": "Any",
"description": "Formulate\n=========\n\n|Build Status| |Coverage Status| |PyPI| |Scikit-HEP Project|\n\nEasy conversions between different styles of expressions. Formulate\ncurrently supports converting between\n`ROOT <https://root.cern.ch/doc/master/classTFormula.html>`__ and\n`numexpr <https://numexpr.readthedocs.io/en/latest/user_guide.html>`__\nstyle expressions.\n\n.. |Build Status| image:: https://github.com/scikit-hep/formulate/workflows/Python%20package/badge.svg\n :target: https://github.com/scikit-hep/formulate/actions\n.. |Coverage Status| image:: https://coveralls.io/repos/github/scikit-hep/formulate/badge.svg?branch=master&service=github\n :target: https://coveralls.io/github/scikit-hep/formulate?branch=master\n.. |PyPI| image:: https://badge.fury.io/py/formulate.svg\n :target: https://pypi.python.org/pypi/formulate/\n.. |Scikit-HEP Project| image:: https://scikit-hep.org/assets/images/Scikit--HEP-Project-blue.svg\n :target: https://scikit-hep.org\n\nInstallation\n------------\n\nInstall formulate like any other Python package:\n\n.. code-block:: bash\n\n pip install --user formulate\n\nor similar (use ```sudo``, ```virtualenv``, or ```conda``` if you wish).\n\n\nUsage\n-----\n\nCommand line usage\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\n.. code-block:: bash\n\n $ python -m formulate --from-root '(A && B) || TMath::Sqrt(A)' --to-numexpr\n (A & B) | sqrt(A)\n\n $ python -m formulate --from-numexpr '(A & B) | sqrt(A)' --to-root\n (A && B) || TMath::Sqrt(A)\n\n $ python -m formulate --from-root '(A && B) || TMath::Sqrt(1.23) * e**1.2 + 5*pi' --variables\n A\n B\n\n $ python -m formulate --from-root '(A && B) || TMath::Sqrt(1.23) * e**1.2 + 5*pi' --named-constants\n E\n PI\n\n $ python -m formulate --from-root '(A && B) || TMath::Sqrt(1.23) * e**1.2 + 5*pi' --unnamed-constants\n 1.2\n 1.23\n 5\n\nAPI\n\"\"\"\n\nThe most basic usage involves calling ``from_$BACKEND`` and then ``to_$BACKEND``, for example when starting with a ROOT style expression:\n\n.. code-block:: python\n\n >>> import formulate\n >>> momentum = formulate.from_root('TMath::Sqrt(X_PX**2 + X_PY**2 + X_PZ**2)')\n >>> momentum\n Expression<SQRT>(Expression<ADD>(Expression<POW>(Variable(X_PX), UnnamedConstant(2)), Expression<POW>(Variable(X_PY), UnnamedConstant(2)), Expression<POW>(Variable(X_PZ), UnnamedConstant(2))))\n >>> momentum.to_numexpr()\n 'sqrt(((X_PX ** 2) + (X_PY ** 2) + (X_PZ ** 2)))'\n >>> momentum.to_root()\n 'TMath::Sqrt(((X_PX ** 2) + (X_PY ** 2) + (X_PZ ** 2)))'\n\nSimilarly, when starting with a ``numexpr`` style expression:\n\n.. code-block:: python\n\n >>> my_selection = formulate.from_numexpr('X_PT > 5 & (Mu_NHits > 3 | Mu_PT > 10)')\n >>> my_selection.to_root()\n '(X_PT > 5) && ((Mu_NHits > 3) || (Mu_PT > 10))'\n >>> my_selection.to_numexpr()\n '(X_PT > 5) & ((Mu_NHits > 3) | (Mu_PT > 10))'\n\nIf the the type of expression isn't known in advance ``formulate`` can also auto detect it:\n\n.. code-block:: python\n\n >>> my_sum = formulate.from_auto('True + False')\n >>> my_sum.to_root()\n 'true + false'\n >>> my_sum.to_numexpr()\n 'True + False'\n\n\nThe ``Expression`` Object\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nWhen calling ``from_*`` the returned object is derived from ``formulate.ExpressionComponent``. From this object you can inspect the expression to find it's dependencies:\n\n.. code-block:: python\n\n >>> my_check = formulate.from_auto('(X_THETA*TMath::DegToRad() > pi/4) && D_PE > 9.2')\n >>> my_check.variables\n {'D_PE', 'X_THETA'}\n >>> my_check.named_constants\n {'DEG2RAD', 'PI'}\n >>> my_check.unnamed_constants\n {'4', '9.2'}\n\nAdditionally ``ExpressionComponent`` s can be combined using both operators and ``numpy`` functions:\n\n.. code-block:: python\n\n >>> new_selection = (momentum > 100) and (my_check or (numpy.sqrt(my_sum) < 1))\n >>> new_selection.to_numexpr()\n '((X_THETA * 0.017453292519943295) > (3.141592653589793 / 4)) & (D_PE > 9.2)'\n\nAs the ``==`` operator returns a new expression, it can't be used to check for equality. Instead the ``.equivalent`` method should be used:\n\n**TODO: Implement this using** ``expression.equivalent`` **!**\n\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Convert between different style of formulae",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/scikit-hep/formulate"
},
"split_keywords": [
"formula",
"conversion",
"root",
"numexpr",
"hep"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fadb136dfc9cff8c220d4752f47ef312d8631c2a308d63666925a978874f5d2a",
"md5": "b5ee5c4518f7865933d2d68103717835",
"sha256": "2524c3bd5072e6de3ad61701cff06c8230a38eb8bc881e6415bdd8a0c2971ed5"
},
"downloads": -1,
"filename": "formulate-0.1.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b5ee5c4518f7865933d2d68103717835",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7",
"size": 21535,
"upload_time": "2021-04-15T16:27:42",
"upload_time_iso_8601": "2021-04-15T16:27:42.051898Z",
"url": "https://files.pythonhosted.org/packages/fa/db/136dfc9cff8c220d4752f47ef312d8631c2a308d63666925a978874f5d2a/formulate-0.1.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c5397c55af7fafbdc40d09ae7e21728f95bcbb077ab28b45c511aafbf8deebec",
"md5": "b9fb5ddcbb67f8b412bafc16659660b4",
"sha256": "8ce3b7a785f40157619c2ea3a5722af323e30f3f3540d57a9317823ad1149afd"
},
"downloads": -1,
"filename": "formulate-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "b9fb5ddcbb67f8b412bafc16659660b4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7",
"size": 26443,
"upload_time": "2021-04-15T16:27:43",
"upload_time_iso_8601": "2021-04-15T16:27:43.622337Z",
"url": "https://files.pythonhosted.org/packages/c5/39/7c55af7fafbdc40d09ae7e21728f95bcbb077ab28b45c511aafbf8deebec/formulate-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-04-15 16:27:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "scikit-hep",
"github_project": "formulate",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "formulate"
}
JSON
