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 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/>`_.
@@ -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