fnprior 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fnprior-0.5.0/LICENSE +9 -0
- fnprior-0.5.0/PKG-INFO +296 -0
- fnprior-0.5.0/README.rst +250 -0
- fnprior-0.5.0/fnprior/__init__.py +25 -0
- fnprior-0.5.0/fnprior/back_off.py +284 -0
- fnprior-0.5.0/fnprior/data/FeynmanEquations.csv +131 -0
- fnprior-0.5.0/fnprior/data/PhysicsEquations.csv +162 -0
- fnprior-0.5.0/fnprior/esr_prior.py +596 -0
- fnprior-0.5.0/fnprior/good_turing.py +98 -0
- fnprior-0.5.0/fnprior/kneser_ney.py +240 -0
- fnprior-0.5.0/fnprior/prior.py +362 -0
- fnprior-0.5.0/fnprior/process_equations.py +448 -0
- fnprior-0.5.0/fnprior/tree_parser.py +698 -0
- fnprior-0.5.0/fnprior.egg-info/PKG-INFO +296 -0
- fnprior-0.5.0/fnprior.egg-info/SOURCES.txt +20 -0
- fnprior-0.5.0/fnprior.egg-info/dependency_links.txt +1 -0
- fnprior-0.5.0/fnprior.egg-info/requires.txt +13 -0
- fnprior-0.5.0/fnprior.egg-info/top_level.txt +2 -0
- fnprior-0.5.0/katz/__init__.py +41 -0
- fnprior-0.5.0/setup.cfg +4 -0
- fnprior-0.5.0/setup.py +52 -0
- fnprior-0.5.0/tests/test_fnprior.py +1929 -0
fnprior-0.5.0/LICENSE
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023-2026 Deaglan J. Bartlett and Harry Desmond
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
6
|
+
|
|
7
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
fnprior-0.5.0/PKG-INFO
ADDED
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fnprior
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: Priors on functions for symbolic regression from n-gram language models
|
|
5
|
+
Home-page: https://github.com/DeaglanBartlett/fnprior
|
|
6
|
+
Author: Deaglan Bartlett, Harry Desmond
|
|
7
|
+
Author-email: deaglan.bartlett@physics.ox.ac.uk
|
|
8
|
+
License: MIT
|
|
9
|
+
Project-URL: Documentation, https://fnprior.readthedocs.io
|
|
10
|
+
Project-URL: Changelog, https://github.com/DeaglanBartlett/fnprior/blob/main/CHANGELOG.rst
|
|
11
|
+
Project-URL: Paper, https://arxiv.org/abs/2304.06333
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
19
|
+
Requires-Python: >=3.9
|
|
20
|
+
Description-Content-Type: text/x-rst
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: numpy
|
|
23
|
+
Requires-Dist: scipy
|
|
24
|
+
Requires-Dist: sympy>=1.14
|
|
25
|
+
Requires-Dist: matplotlib
|
|
26
|
+
Requires-Dist: pandas
|
|
27
|
+
Provides-Extra: esr
|
|
28
|
+
Requires-Dist: mpi4py; extra == "esr"
|
|
29
|
+
Provides-Extra: docs
|
|
30
|
+
Requires-Dist: sphinx>=5.0; extra == "docs"
|
|
31
|
+
Requires-Dist: sphinx-rtd-theme; extra == "docs"
|
|
32
|
+
Requires-Dist: myst-parser; extra == "docs"
|
|
33
|
+
Dynamic: author
|
|
34
|
+
Dynamic: author-email
|
|
35
|
+
Dynamic: classifier
|
|
36
|
+
Dynamic: description
|
|
37
|
+
Dynamic: description-content-type
|
|
38
|
+
Dynamic: home-page
|
|
39
|
+
Dynamic: license
|
|
40
|
+
Dynamic: license-file
|
|
41
|
+
Dynamic: project-url
|
|
42
|
+
Dynamic: provides-extra
|
|
43
|
+
Dynamic: requires-dist
|
|
44
|
+
Dynamic: requires-python
|
|
45
|
+
Dynamic: summary
|
|
46
|
+
|
|
47
|
+
fnprior
|
|
48
|
+
-------
|
|
49
|
+
|
|
50
|
+
:fnprior: Priors on functions for symbolic regression from n-gram language models
|
|
51
|
+
:Authors: Deaglan J. Bartlett, Harry Desmond
|
|
52
|
+
:Homepage: https://github.com/DeaglanBartlett/fnprior
|
|
53
|
+
:Documentation: https://fnprior.readthedocs.io
|
|
54
|
+
|
|
55
|
+
.. image:: https://readthedocs.org/projects/fnprior/badge/?version=latest
|
|
56
|
+
:target: https://fnprior.readthedocs.io/en/latest/?badge=latest
|
|
57
|
+
:alt: Documentation Status
|
|
58
|
+
|
|
59
|
+
.. image:: https://img.shields.io/pypi/v/fnprior.svg
|
|
60
|
+
:target: https://pypi.org/project/fnprior/
|
|
61
|
+
:alt: PyPI version
|
|
62
|
+
|
|
63
|
+
.. image:: https://img.shields.io/badge/cs.LG-arXiv%32304.06333-B31B1B.svg
|
|
64
|
+
:target: https://arxiv.org/abs/2304.06333
|
|
65
|
+
|
|
66
|
+
.. image:: https://github.com/DeaglanBartlett/fnprior/actions/workflows/build.yml/badge.svg
|
|
67
|
+
:target: https://github.com/DeaglanBartlett/fnprior/actions/workflows/build.yml
|
|
68
|
+
:alt: Build Status
|
|
69
|
+
|
|
70
|
+
.. image:: https://img.shields.io/codecov/c/github/DeaglanBartlett/fnprior
|
|
71
|
+
:target: https://app.codecov.io/gh/DeaglanBartlett/fnprior
|
|
72
|
+
:alt: Coverage
|
|
73
|
+
|
|
74
|
+
.. note::
|
|
75
|
+
|
|
76
|
+
**fnprior was called katz before version 0.5.0.** The package was renamed because it now
|
|
77
|
+
offers more than the Katz back-off model, and because the name ``katz`` on PyPI belongs to
|
|
78
|
+
an unrelated package: ``pip install katz`` does not install this code. Code that imports
|
|
79
|
+
``katz`` keeps working until version 0.8.0, with a ``FutureWarning``; replace ``katz`` by
|
|
80
|
+
``fnprior`` in the imports (e.g. ``from fnprior.prior import FunctionPrior``).
|
|
81
|
+
|
|
82
|
+
.. important::
|
|
83
|
+
|
|
84
|
+
Since version 0.4.0 the default model is Kneser-Ney smoothing (``smoothing='kn'``) with an
|
|
85
|
+
explicit start-of-tree context for the root (``root_context=True``). **Priors computed before
|
|
86
|
+
version 0.2.0**, including those of `Bartlett, Desmond & Ferreira (2023)
|
|
87
|
+
<https://arxiv.org/abs/2304.06333>`_ and the applications of the prior, **used version 0.1.0
|
|
88
|
+
or earlier**, whose Katz model differs from that of later versions in the context of a right
|
|
89
|
+
child, so that no setting of this version reproduces them (see version 0.3.0 in the `changelog <https://github.com/DeaglanBartlett/fnprior/blob/main/CHANGELOG.rst>`__).
|
|
90
|
+
To reproduce them, install the version used for them, e.g.
|
|
91
|
+
``pip install git+https://github.com/DeaglanBartlett/fnprior.git@v0.1.0``.
|
|
92
|
+
``smoothing='katz', root_context=False, normalise=False`` gives the Katz model of version
|
|
93
|
+
0.2.1.
|
|
94
|
+
|
|
95
|
+
About
|
|
96
|
+
=====
|
|
97
|
+
|
|
98
|
+
Symbolic regression algorithms attempt to find analytic expressions which accurately
|
|
99
|
+
fit a given data set. In many cases, one wants these to be interpretable and thus one
|
|
100
|
+
tries to find the simplest possible expression which can accurately fit the data.
|
|
101
|
+
Even if an expression is simple, if one is seeking a physical law, one may discard
|
|
102
|
+
an expression because it does not look like the kind of expression one would expect in this context.
|
|
103
|
+
To automate this process, we produce a prior on functions based on an n-gram language
|
|
104
|
+
model of the operators in a function's tree: by studying a corpus of previously used
|
|
105
|
+
equations in a given field, the model returns a probability for each function based on the
|
|
106
|
+
order of operators appearing in the function. The conditional probabilities are smoothed
|
|
107
|
+
with interpolated Kneser-Ney by default, or with the Katz back-off model of the original
|
|
108
|
+
paper.
|
|
109
|
+
|
|
110
|
+
Installation
|
|
111
|
+
=============
|
|
112
|
+
|
|
113
|
+
fnprior is installed from PyPI with
|
|
114
|
+
|
|
115
|
+
.. code:: bash
|
|
116
|
+
|
|
117
|
+
pip install fnprior
|
|
118
|
+
|
|
119
|
+
The prior itself needs only NumPy, SciPy, pandas and SymPy: equations are converted to trees by
|
|
120
|
+
``fnprior.tree_parser``, which reproduces the parser of the
|
|
121
|
+
`ESR Package <https://github.com/DeaglanBartlett/ESR>`_, so the prior can be used with any symbolic
|
|
122
|
+
regression method. SymPy 1.14 or later is required: older versions parse a few corpus equations
|
|
123
|
+
differently (a numeric factor is taken out of a square root), which changes the prior by up to a
|
|
124
|
+
few nats for some functions.
|
|
125
|
+
|
|
126
|
+
ESR and ``mpi4py`` are needed only to score ESR function libraries with ``fnprior.esr_prior`` and
|
|
127
|
+
to run the ESR tests. ESR is not on PyPI, so install it from GitHub; ``pip install fnprior[esr]``
|
|
128
|
+
installs ``mpi4py``. To install both from source in a new virtual environment, run
|
|
129
|
+
|
|
130
|
+
.. code:: bash
|
|
131
|
+
|
|
132
|
+
python3 -m venv fnprior_env
|
|
133
|
+
source fnprior_env/bin/activate
|
|
134
|
+
git clone https://github.com/DeaglanBartlett/ESR.git
|
|
135
|
+
pip install -e ESR
|
|
136
|
+
git clone https://github.com/DeaglanBartlett/fnprior.git
|
|
137
|
+
pip install -e "fnprior[esr]"
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
Example
|
|
141
|
+
========
|
|
142
|
+
|
|
143
|
+
To generate a prior with ``n = 2`` from the equations of the AI Feynman database
|
|
144
|
+
(`Udrescu & Tegmark 2020 <https://arxiv.org/abs/1905.11481>`_), which are included in fnprior
|
|
145
|
+
(``data_path`` gives the path of an included corpus), and evaluate it on some trial functions,
|
|
146
|
+
run the code below. The standardised equations are written to ``NewFeynman.csv``.
|
|
147
|
+
Here ``n`` is the number of symbols from which each symbol is predicted, so ``n = 2`` gives a
|
|
148
|
+
3-gram model (in general, ``n`` gives an (n+1)-gram model):
|
|
149
|
+
|
|
150
|
+
.. code-block:: python
|
|
151
|
+
|
|
152
|
+
from fnprior import data_path
|
|
153
|
+
from fnprior.prior import FunctionPrior
|
|
154
|
+
|
|
155
|
+
n = 2
|
|
156
|
+
basis_functions = [["a", "x"],
|
|
157
|
+
["sqrt", "exp", "log", "sin", "cos", "arcsin", "tanh"],
|
|
158
|
+
["+", "-", "*", "/", "pow"]]
|
|
159
|
+
|
|
160
|
+
kp = FunctionPrior(n, basis_functions, data_path('FeynmanEquations.csv'), 'NewFeynman.csv')
|
|
161
|
+
|
|
162
|
+
for eq in ['x0**2', 'sin(x0) + sin(x1)', 'sin(sin(x0+x1))']:
|
|
163
|
+
p = kp.logprior(eq)
|
|
164
|
+
print(eq, p)
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
Smoothing and representation options
|
|
168
|
+
------------------------------------
|
|
169
|
+
|
|
170
|
+
By default (``smoothing='kn'``) the conditional probabilities are estimated with
|
|
171
|
+
interpolated Kneser-Ney smoothing, with a single absolute discount ``D = 0.8`` at all
|
|
172
|
+
orders. This assigns a non-zero probability to every operator of the basis set in every
|
|
173
|
+
context and is less sensitive to the choice of ``n`` than the Katz model. The default
|
|
174
|
+
discount was chosen on the physics corpus, so for other corpora tune the discounts by
|
|
175
|
+
cross-validation with ``tune_discounts()``. They can also be set with
|
|
176
|
+
``smoothing_kwargs={'discounts': D}``, or estimated with the Chen-Goodman formulae
|
|
177
|
+
(``smoothing_kwargs={'discounts': 'mkn'}``, not recommended for corpora of fewer than
|
|
178
|
+
~100 equations). ``tune_discounts(method='count')`` tunes separate discounts for n-grams seen
|
|
179
|
+
once and n-grams seen more than once (modified Kneser-Ney), which improves on a single tuned
|
|
180
|
+
discount by ~0.1 nats per equation for ``n >= 4``. ``smoothing='katz'`` gives the Katz
|
|
181
|
+
back-off model of `Bartlett et al. (2023) <https://arxiv.org/abs/2304.06333>`__, with conditional probabilities normalised by
|
|
182
|
+
default (``normalise=True``); ``smoothing='katz', root_context=False, normalise=False``
|
|
183
|
+
gives the Katz model of version 0.2.1 (see version 0.3.0 in the `changelog <https://github.com/DeaglanBartlett/fnprior/blob/main/CHANGELOG.rst>`__).
|
|
184
|
+
|
|
185
|
+
The root and the nodes near it are conditioned on an explicit start-of-tree context
|
|
186
|
+
(``root_context=True``, the default). This gives the largest improvement in held-out tests,
|
|
187
|
+
but makes single-leaf functions considerably less probable, since no corpus equation is a
|
|
188
|
+
bare leaf; ``root_context=False`` restores the original representation, in which the root
|
|
189
|
+
is predicted from the distribution of all first children. ``code_constants=True`` codes constants
|
|
190
|
+
and parameters as ``a`` rather than as variables (by default they are treated like
|
|
191
|
+
variables, as physical constants are in the corpus, so e.g. ``pow(x0, a0)`` and
|
|
192
|
+
``pow(a0, x0)`` have the same prior).
|
|
193
|
+
|
|
194
|
+
.. code-block:: python
|
|
195
|
+
|
|
196
|
+
# the physics corpus also needs arccos; this is the basis of ESR's core_maths library
|
|
197
|
+
basis_functions = [["a", "x"],
|
|
198
|
+
["sqrt", "exp", "log", "sin", "cos", "arcsin", "arccos", "tanh", "inv"],
|
|
199
|
+
["+", "-", "*", "/", "pow"]]
|
|
200
|
+
kp = FunctionPrior(3, basis_functions, data_path('PhysicsEquations.csv'), 'NewPhysics.csv',
|
|
201
|
+
input_delimiter=';')
|
|
202
|
+
kp.tune_discounts()
|
|
203
|
+
print(kp.logprior('sin(x0) + sin(x1)'))
|
|
204
|
+
|
|
205
|
+
``KatzPrior``, the name of this class before version 0.4.0, is kept as an alias of
|
|
206
|
+
``FunctionPrior`` for backwards compatibility. ``fnprior.esr_prior.compute_logprior``, which scores
|
|
207
|
+
an ESR function library, names its output files after the prior configuration (e.g.
|
|
208
|
+
``kn_codelen_3_5.txt``, ``kn_D0.6_codelen_3_5.txt``, ``kn_tuned_codelen_3_5.txt``,
|
|
209
|
+
``katz_noroot_unnorm_codelen_2_5.txt``) and writes a JSON manifest of the configuration and
|
|
210
|
+
corpus beside them; existing files are reused only if the manifest matches. With
|
|
211
|
+
``tune_discounts`` it tunes the discounts on the corpus before scoring and records the tuned
|
|
212
|
+
values in the manifest:
|
|
213
|
+
|
|
214
|
+
.. code-block:: python
|
|
215
|
+
|
|
216
|
+
from fnprior.esr_prior import compute_logprior, get_logconst
|
|
217
|
+
|
|
218
|
+
dirname = 'ESR/esr/function_library/core_maths'
|
|
219
|
+
get_logconst(5, dirname) # constant terms of the codelength, needed first
|
|
220
|
+
compute_logprior(5, 3, basis_functions, dirname,
|
|
221
|
+
data_path('PhysicsEquations.csv'), 'NewPhysics.csv',
|
|
222
|
+
input_delimiter=';', tune_discounts='single')
|
|
223
|
+
|
|
224
|
+
Changes
|
|
225
|
+
=======
|
|
226
|
+
|
|
227
|
+
The changes in each version, including how to reproduce priors computed with earlier
|
|
228
|
+
versions, are listed in the `changelog <https://github.com/DeaglanBartlett/fnprior/blob/main/CHANGELOG.rst>`__.
|
|
229
|
+
|
|
230
|
+
Licence and Citation
|
|
231
|
+
====================
|
|
232
|
+
|
|
233
|
+
Users are required to cite the `paper <https://arxiv.org/abs/2304.06333>`__:
|
|
234
|
+
|
|
235
|
+
.. code:: bibtex
|
|
236
|
+
|
|
237
|
+
@ARTICLE{2023arXiv2304.06333,
|
|
238
|
+
author = {{Bartlett}, D.~J. and {Desmond}, H. and {Ferreira}, P.~G.},
|
|
239
|
+
title = "{Priors for symbolic regression}",
|
|
240
|
+
journal = {arXiv e-prints},
|
|
241
|
+
keywords = {Computer Science - Machine Learning},
|
|
242
|
+
year = 2023,
|
|
243
|
+
month = apr,
|
|
244
|
+
eid = {arXiv:2304.06333},
|
|
245
|
+
pages = {arXiv:2304.06333},
|
|
246
|
+
archivePrefix = {arXiv},
|
|
247
|
+
eprint = {2304.06333},
|
|
248
|
+
primaryClass = {cs.LG},
|
|
249
|
+
url = {https://arxiv.org/abs/2304.06333},
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
Since fnprior uses code that originated in the ESR package,
|
|
254
|
+
users are required to cite the ESR `paper <https://arxiv.org/abs/2211.11461>`__,
|
|
255
|
+
for which the following BibTeX can be used:
|
|
256
|
+
|
|
257
|
+
.. code:: bibtex
|
|
258
|
+
|
|
259
|
+
@ARTICLE{2022arXiv2211.11461,
|
|
260
|
+
author = {{Bartlett}, D.~J. and {Desmond}, H. and {Ferreira}, P.~G.},
|
|
261
|
+
title = "{Exhaustive Symbolic Regression}",
|
|
262
|
+
journal = {arXiv e-prints},
|
|
263
|
+
keywords = {Astrophysics - Cosmology and Nongalactic Astrophysics},
|
|
264
|
+
year = 2022,
|
|
265
|
+
month = nov,
|
|
266
|
+
eid = {arXiv:2211.11461},
|
|
267
|
+
pages = {arXiv:2211.11461},
|
|
268
|
+
archivePrefix = {arXiv},
|
|
269
|
+
eprint = {2211.11461},
|
|
270
|
+
primaryClass = {astro-ph.CO},
|
|
271
|
+
url = {https://arxiv.org/abs/2211.11461},
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
The software is available under the MIT licence:
|
|
275
|
+
|
|
276
|
+
Copyright (c) 2023-2026 Deaglan J. Bartlett and Harry Desmond
|
|
277
|
+
|
|
278
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
279
|
+
|
|
280
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
281
|
+
|
|
282
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
283
|
+
|
|
284
|
+
Contributors
|
|
285
|
+
============
|
|
286
|
+
|
|
287
|
+
Below is a list of contributors to this repository.
|
|
288
|
+
|
|
289
|
+
* `Deaglan Bartlett <https://github.com/DeaglanBartlett>`_
|
|
290
|
+
* `Harry Desmond <https://github.com/harrydesmond>`_
|
|
291
|
+
|
|
292
|
+
Documentation
|
|
293
|
+
=============
|
|
294
|
+
|
|
295
|
+
The documentation for this project can be found
|
|
296
|
+
`at this link <https://fnprior.readthedocs.io/>`_.
|
fnprior-0.5.0/README.rst
ADDED
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
fnprior
|
|
2
|
+
-------
|
|
3
|
+
|
|
4
|
+
:fnprior: Priors on functions for symbolic regression from n-gram language models
|
|
5
|
+
:Authors: Deaglan J. Bartlett, Harry Desmond
|
|
6
|
+
:Homepage: https://github.com/DeaglanBartlett/fnprior
|
|
7
|
+
:Documentation: https://fnprior.readthedocs.io
|
|
8
|
+
|
|
9
|
+
.. image:: https://readthedocs.org/projects/fnprior/badge/?version=latest
|
|
10
|
+
:target: https://fnprior.readthedocs.io/en/latest/?badge=latest
|
|
11
|
+
:alt: Documentation Status
|
|
12
|
+
|
|
13
|
+
.. image:: https://img.shields.io/pypi/v/fnprior.svg
|
|
14
|
+
:target: https://pypi.org/project/fnprior/
|
|
15
|
+
:alt: PyPI version
|
|
16
|
+
|
|
17
|
+
.. image:: https://img.shields.io/badge/cs.LG-arXiv%32304.06333-B31B1B.svg
|
|
18
|
+
:target: https://arxiv.org/abs/2304.06333
|
|
19
|
+
|
|
20
|
+
.. image:: https://github.com/DeaglanBartlett/fnprior/actions/workflows/build.yml/badge.svg
|
|
21
|
+
:target: https://github.com/DeaglanBartlett/fnprior/actions/workflows/build.yml
|
|
22
|
+
:alt: Build Status
|
|
23
|
+
|
|
24
|
+
.. image:: https://img.shields.io/codecov/c/github/DeaglanBartlett/fnprior
|
|
25
|
+
:target: https://app.codecov.io/gh/DeaglanBartlett/fnprior
|
|
26
|
+
:alt: Coverage
|
|
27
|
+
|
|
28
|
+
.. note::
|
|
29
|
+
|
|
30
|
+
**fnprior was called katz before version 0.5.0.** The package was renamed because it now
|
|
31
|
+
offers more than the Katz back-off model, and because the name ``katz`` on PyPI belongs to
|
|
32
|
+
an unrelated package: ``pip install katz`` does not install this code. Code that imports
|
|
33
|
+
``katz`` keeps working until version 0.8.0, with a ``FutureWarning``; replace ``katz`` by
|
|
34
|
+
``fnprior`` in the imports (e.g. ``from fnprior.prior import FunctionPrior``).
|
|
35
|
+
|
|
36
|
+
.. important::
|
|
37
|
+
|
|
38
|
+
Since version 0.4.0 the default model is Kneser-Ney smoothing (``smoothing='kn'``) with an
|
|
39
|
+
explicit start-of-tree context for the root (``root_context=True``). **Priors computed before
|
|
40
|
+
version 0.2.0**, including those of `Bartlett, Desmond & Ferreira (2023)
|
|
41
|
+
<https://arxiv.org/abs/2304.06333>`_ and the applications of the prior, **used version 0.1.0
|
|
42
|
+
or earlier**, whose Katz model differs from that of later versions in the context of a right
|
|
43
|
+
child, so that no setting of this version reproduces them (see version 0.3.0 in the `changelog <https://github.com/DeaglanBartlett/fnprior/blob/main/CHANGELOG.rst>`__).
|
|
44
|
+
To reproduce them, install the version used for them, e.g.
|
|
45
|
+
``pip install git+https://github.com/DeaglanBartlett/fnprior.git@v0.1.0``.
|
|
46
|
+
``smoothing='katz', root_context=False, normalise=False`` gives the Katz model of version
|
|
47
|
+
0.2.1.
|
|
48
|
+
|
|
49
|
+
About
|
|
50
|
+
=====
|
|
51
|
+
|
|
52
|
+
Symbolic regression algorithms attempt to find analytic expressions which accurately
|
|
53
|
+
fit a given data set. In many cases, one wants these to be interpretable and thus one
|
|
54
|
+
tries to find the simplest possible expression which can accurately fit the data.
|
|
55
|
+
Even if an expression is simple, if one is seeking a physical law, one may discard
|
|
56
|
+
an expression because it does not look like the kind of expression one would expect in this context.
|
|
57
|
+
To automate this process, we produce a prior on functions based on an n-gram language
|
|
58
|
+
model of the operators in a function's tree: by studying a corpus of previously used
|
|
59
|
+
equations in a given field, the model returns a probability for each function based on the
|
|
60
|
+
order of operators appearing in the function. The conditional probabilities are smoothed
|
|
61
|
+
with interpolated Kneser-Ney by default, or with the Katz back-off model of the original
|
|
62
|
+
paper.
|
|
63
|
+
|
|
64
|
+
Installation
|
|
65
|
+
=============
|
|
66
|
+
|
|
67
|
+
fnprior is installed from PyPI with
|
|
68
|
+
|
|
69
|
+
.. code:: bash
|
|
70
|
+
|
|
71
|
+
pip install fnprior
|
|
72
|
+
|
|
73
|
+
The prior itself needs only NumPy, SciPy, pandas and SymPy: equations are converted to trees by
|
|
74
|
+
``fnprior.tree_parser``, which reproduces the parser of the
|
|
75
|
+
`ESR Package <https://github.com/DeaglanBartlett/ESR>`_, so the prior can be used with any symbolic
|
|
76
|
+
regression method. SymPy 1.14 or later is required: older versions parse a few corpus equations
|
|
77
|
+
differently (a numeric factor is taken out of a square root), which changes the prior by up to a
|
|
78
|
+
few nats for some functions.
|
|
79
|
+
|
|
80
|
+
ESR and ``mpi4py`` are needed only to score ESR function libraries with ``fnprior.esr_prior`` and
|
|
81
|
+
to run the ESR tests. ESR is not on PyPI, so install it from GitHub; ``pip install fnprior[esr]``
|
|
82
|
+
installs ``mpi4py``. To install both from source in a new virtual environment, run
|
|
83
|
+
|
|
84
|
+
.. code:: bash
|
|
85
|
+
|
|
86
|
+
python3 -m venv fnprior_env
|
|
87
|
+
source fnprior_env/bin/activate
|
|
88
|
+
git clone https://github.com/DeaglanBartlett/ESR.git
|
|
89
|
+
pip install -e ESR
|
|
90
|
+
git clone https://github.com/DeaglanBartlett/fnprior.git
|
|
91
|
+
pip install -e "fnprior[esr]"
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
Example
|
|
95
|
+
========
|
|
96
|
+
|
|
97
|
+
To generate a prior with ``n = 2`` from the equations of the AI Feynman database
|
|
98
|
+
(`Udrescu & Tegmark 2020 <https://arxiv.org/abs/1905.11481>`_), which are included in fnprior
|
|
99
|
+
(``data_path`` gives the path of an included corpus), and evaluate it on some trial functions,
|
|
100
|
+
run the code below. The standardised equations are written to ``NewFeynman.csv``.
|
|
101
|
+
Here ``n`` is the number of symbols from which each symbol is predicted, so ``n = 2`` gives a
|
|
102
|
+
3-gram model (in general, ``n`` gives an (n+1)-gram model):
|
|
103
|
+
|
|
104
|
+
.. code-block:: python
|
|
105
|
+
|
|
106
|
+
from fnprior import data_path
|
|
107
|
+
from fnprior.prior import FunctionPrior
|
|
108
|
+
|
|
109
|
+
n = 2
|
|
110
|
+
basis_functions = [["a", "x"],
|
|
111
|
+
["sqrt", "exp", "log", "sin", "cos", "arcsin", "tanh"],
|
|
112
|
+
["+", "-", "*", "/", "pow"]]
|
|
113
|
+
|
|
114
|
+
kp = FunctionPrior(n, basis_functions, data_path('FeynmanEquations.csv'), 'NewFeynman.csv')
|
|
115
|
+
|
|
116
|
+
for eq in ['x0**2', 'sin(x0) + sin(x1)', 'sin(sin(x0+x1))']:
|
|
117
|
+
p = kp.logprior(eq)
|
|
118
|
+
print(eq, p)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
Smoothing and representation options
|
|
122
|
+
------------------------------------
|
|
123
|
+
|
|
124
|
+
By default (``smoothing='kn'``) the conditional probabilities are estimated with
|
|
125
|
+
interpolated Kneser-Ney smoothing, with a single absolute discount ``D = 0.8`` at all
|
|
126
|
+
orders. This assigns a non-zero probability to every operator of the basis set in every
|
|
127
|
+
context and is less sensitive to the choice of ``n`` than the Katz model. The default
|
|
128
|
+
discount was chosen on the physics corpus, so for other corpora tune the discounts by
|
|
129
|
+
cross-validation with ``tune_discounts()``. They can also be set with
|
|
130
|
+
``smoothing_kwargs={'discounts': D}``, or estimated with the Chen-Goodman formulae
|
|
131
|
+
(``smoothing_kwargs={'discounts': 'mkn'}``, not recommended for corpora of fewer than
|
|
132
|
+
~100 equations). ``tune_discounts(method='count')`` tunes separate discounts for n-grams seen
|
|
133
|
+
once and n-grams seen more than once (modified Kneser-Ney), which improves on a single tuned
|
|
134
|
+
discount by ~0.1 nats per equation for ``n >= 4``. ``smoothing='katz'`` gives the Katz
|
|
135
|
+
back-off model of `Bartlett et al. (2023) <https://arxiv.org/abs/2304.06333>`__, with conditional probabilities normalised by
|
|
136
|
+
default (``normalise=True``); ``smoothing='katz', root_context=False, normalise=False``
|
|
137
|
+
gives the Katz model of version 0.2.1 (see version 0.3.0 in the `changelog <https://github.com/DeaglanBartlett/fnprior/blob/main/CHANGELOG.rst>`__).
|
|
138
|
+
|
|
139
|
+
The root and the nodes near it are conditioned on an explicit start-of-tree context
|
|
140
|
+
(``root_context=True``, the default). This gives the largest improvement in held-out tests,
|
|
141
|
+
but makes single-leaf functions considerably less probable, since no corpus equation is a
|
|
142
|
+
bare leaf; ``root_context=False`` restores the original representation, in which the root
|
|
143
|
+
is predicted from the distribution of all first children. ``code_constants=True`` codes constants
|
|
144
|
+
and parameters as ``a`` rather than as variables (by default they are treated like
|
|
145
|
+
variables, as physical constants are in the corpus, so e.g. ``pow(x0, a0)`` and
|
|
146
|
+
``pow(a0, x0)`` have the same prior).
|
|
147
|
+
|
|
148
|
+
.. code-block:: python
|
|
149
|
+
|
|
150
|
+
# the physics corpus also needs arccos; this is the basis of ESR's core_maths library
|
|
151
|
+
basis_functions = [["a", "x"],
|
|
152
|
+
["sqrt", "exp", "log", "sin", "cos", "arcsin", "arccos", "tanh", "inv"],
|
|
153
|
+
["+", "-", "*", "/", "pow"]]
|
|
154
|
+
kp = FunctionPrior(3, basis_functions, data_path('PhysicsEquations.csv'), 'NewPhysics.csv',
|
|
155
|
+
input_delimiter=';')
|
|
156
|
+
kp.tune_discounts()
|
|
157
|
+
print(kp.logprior('sin(x0) + sin(x1)'))
|
|
158
|
+
|
|
159
|
+
``KatzPrior``, the name of this class before version 0.4.0, is kept as an alias of
|
|
160
|
+
``FunctionPrior`` for backwards compatibility. ``fnprior.esr_prior.compute_logprior``, which scores
|
|
161
|
+
an ESR function library, names its output files after the prior configuration (e.g.
|
|
162
|
+
``kn_codelen_3_5.txt``, ``kn_D0.6_codelen_3_5.txt``, ``kn_tuned_codelen_3_5.txt``,
|
|
163
|
+
``katz_noroot_unnorm_codelen_2_5.txt``) and writes a JSON manifest of the configuration and
|
|
164
|
+
corpus beside them; existing files are reused only if the manifest matches. With
|
|
165
|
+
``tune_discounts`` it tunes the discounts on the corpus before scoring and records the tuned
|
|
166
|
+
values in the manifest:
|
|
167
|
+
|
|
168
|
+
.. code-block:: python
|
|
169
|
+
|
|
170
|
+
from fnprior.esr_prior import compute_logprior, get_logconst
|
|
171
|
+
|
|
172
|
+
dirname = 'ESR/esr/function_library/core_maths'
|
|
173
|
+
get_logconst(5, dirname) # constant terms of the codelength, needed first
|
|
174
|
+
compute_logprior(5, 3, basis_functions, dirname,
|
|
175
|
+
data_path('PhysicsEquations.csv'), 'NewPhysics.csv',
|
|
176
|
+
input_delimiter=';', tune_discounts='single')
|
|
177
|
+
|
|
178
|
+
Changes
|
|
179
|
+
=======
|
|
180
|
+
|
|
181
|
+
The changes in each version, including how to reproduce priors computed with earlier
|
|
182
|
+
versions, are listed in the `changelog <https://github.com/DeaglanBartlett/fnprior/blob/main/CHANGELOG.rst>`__.
|
|
183
|
+
|
|
184
|
+
Licence and Citation
|
|
185
|
+
====================
|
|
186
|
+
|
|
187
|
+
Users are required to cite the `paper <https://arxiv.org/abs/2304.06333>`__:
|
|
188
|
+
|
|
189
|
+
.. code:: bibtex
|
|
190
|
+
|
|
191
|
+
@ARTICLE{2023arXiv2304.06333,
|
|
192
|
+
author = {{Bartlett}, D.~J. and {Desmond}, H. and {Ferreira}, P.~G.},
|
|
193
|
+
title = "{Priors for symbolic regression}",
|
|
194
|
+
journal = {arXiv e-prints},
|
|
195
|
+
keywords = {Computer Science - Machine Learning},
|
|
196
|
+
year = 2023,
|
|
197
|
+
month = apr,
|
|
198
|
+
eid = {arXiv:2304.06333},
|
|
199
|
+
pages = {arXiv:2304.06333},
|
|
200
|
+
archivePrefix = {arXiv},
|
|
201
|
+
eprint = {2304.06333},
|
|
202
|
+
primaryClass = {cs.LG},
|
|
203
|
+
url = {https://arxiv.org/abs/2304.06333},
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
Since fnprior uses code that originated in the ESR package,
|
|
208
|
+
users are required to cite the ESR `paper <https://arxiv.org/abs/2211.11461>`__,
|
|
209
|
+
for which the following BibTeX can be used:
|
|
210
|
+
|
|
211
|
+
.. code:: bibtex
|
|
212
|
+
|
|
213
|
+
@ARTICLE{2022arXiv2211.11461,
|
|
214
|
+
author = {{Bartlett}, D.~J. and {Desmond}, H. and {Ferreira}, P.~G.},
|
|
215
|
+
title = "{Exhaustive Symbolic Regression}",
|
|
216
|
+
journal = {arXiv e-prints},
|
|
217
|
+
keywords = {Astrophysics - Cosmology and Nongalactic Astrophysics},
|
|
218
|
+
year = 2022,
|
|
219
|
+
month = nov,
|
|
220
|
+
eid = {arXiv:2211.11461},
|
|
221
|
+
pages = {arXiv:2211.11461},
|
|
222
|
+
archivePrefix = {arXiv},
|
|
223
|
+
eprint = {2211.11461},
|
|
224
|
+
primaryClass = {astro-ph.CO},
|
|
225
|
+
url = {https://arxiv.org/abs/2211.11461},
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
The software is available under the MIT licence:
|
|
229
|
+
|
|
230
|
+
Copyright (c) 2023-2026 Deaglan J. Bartlett and Harry Desmond
|
|
231
|
+
|
|
232
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
233
|
+
|
|
234
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
235
|
+
|
|
236
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
237
|
+
|
|
238
|
+
Contributors
|
|
239
|
+
============
|
|
240
|
+
|
|
241
|
+
Below is a list of contributors to this repository.
|
|
242
|
+
|
|
243
|
+
* `Deaglan Bartlett <https://github.com/DeaglanBartlett>`_
|
|
244
|
+
* `Harry Desmond <https://github.com/harrydesmond>`_
|
|
245
|
+
|
|
246
|
+
Documentation
|
|
247
|
+
=============
|
|
248
|
+
|
|
249
|
+
The documentation for this project can be found
|
|
250
|
+
`at this link <https://fnprior.readthedocs.io/>`_.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""fnprior: priors on functions for symbolic regression from n-gram language models of
|
|
2
|
+
their expression trees (called katz before version 0.5.0)"""
|
|
3
|
+
|
|
4
|
+
import os
|
|
5
|
+
|
|
6
|
+
_DATA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "data")
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def data_path(name):
|
|
10
|
+
"""Path of a corpus file included in the package
|
|
11
|
+
|
|
12
|
+
Args:
|
|
13
|
+
:name (str): File name: 'PhysicsEquations.csv' (the physics corpus, delimiter ';')
|
|
14
|
+
or 'FeynmanEquations.csv' (the AI Feynman equations, delimiter ',')
|
|
15
|
+
|
|
16
|
+
Returns:
|
|
17
|
+
:path (str): The path of the file
|
|
18
|
+
"""
|
|
19
|
+
path = os.path.join(_DATA_DIR, name)
|
|
20
|
+
if not os.path.isfile(path):
|
|
21
|
+
available = ", ".join(sorted(os.listdir(_DATA_DIR)))
|
|
22
|
+
raise FileNotFoundError(
|
|
23
|
+
f"No corpus file {name!r} in fnprior; the files are: {available}"
|
|
24
|
+
)
|
|
25
|
+
return path
|