Merge pull request #27 from AutoResearch/add-standard-operators-and_functions

chore/docs: add documentation on metrics/refactor package

Author: Younes Strittmatter

docs/index.md

@@ -1,45 +1,17 @@
 # Equation Tree
 
-The Equation Tree package is an equation toolbox with symbolic regression in mind. It represents
-expressions as incomplete binary trees and has various features tailored towards testing symbolic
-regression algorithms or training models. The most notable features are:
+The Equation Tree package is an equation toolbox with symbolic regression in mind. It represents expressions as an incomplete binary [equation tree](user-guide/equation-formats.md) and has various features tailored towards testing symbolic regression algorithms or training models. The most notable features are:
 
-- Equation sampling (including priors)
-- Feature Extraction from equation distributions
-- Distance metrics between equations
+- [**Equation Sampling**](user-guide/equation-sampling.md)
+- Calculating [Distance Metrics](user-guide/distance-metrics.md) between equations
 
-
-## Equation Sampling
-
-![Equation Tree](img/equation-sampler.gif)
-
-In our sampling method, the equation structure and the equation content are sampled in two steps:
-- (1) First, we sample the *structure* of the equation
-- (2) Second, we sample the *content* of the equation
-
-The sampling can be customized to obtain a desired equation distribution. For example, to mimic the distribution in specific scientific fields. This is customization is implemented in form of priors for operators, functions, features, and structures. We can also use conditional priors conditioned on the parent node. 
-
-## Feature Extraction
-
-Given an equation, our package can extract features like number of constants, and variables, and various equation complexity measurements (For example, number of nodes and tree depth.)
-
-For a list of equations, our package is capable to easily access frequencies for operators, functions, features, and structures. These frequencies can in turn be used to sample new equations that mimic the original list in these aspects.
-
-## Distance Metrics
-
-For benchmarking or training, the Equation Tree package features a list of distance metrics between equations:
-
-- **Prediction distance.** Prediction distance between function values as proposed byLa Cava et al. (2021):
-- **Symbolic solution.** Another metric proposed by La Cava et al. (2021) is called symbolic solution, designed to capture SR models that differ from the true model by a constant or scalar. In our application, we define the symbolic constant difference as:
-- **Normalized edit distance.** In addition to the metrics above, Matsubara et al. (2022) propose a normalized edit distance for the trees. For a pair of two trees, edit distance computes the minimum cost to transform one to another with a sequence of operations, each of which either 1) inserts, 2) deletes, or 3) renames a node. 
+It also encompasses a variety of [additional features](user-guide/additional-features.md). For example, to obtain information about existing equation list that can, in turn, be used in our sampling method.
 
 ## Relevant Publication
 
-For reference and informations about the evaluation of our package, read our Neuroips 2023 paper:
-
-Marinescu*, I., Strittmatter*, Y, Williams, C, Musslick, S. "Expression Sampler as a Dynamic Benchmark for Symbolic Regression." In *NeurIPS 2023 AI for Science Workshop*. (2023), [Read the publication](https://openreview.net/forum?id=i3PecpoiPG). [*equal contribution]
-
+For reference and information about the evaluation of our package, read our NeuroIPS 2023 [paper](https://openreview.net/forum?id=i3PecpoiPG):
 
+Marinescu\*, I., Strittmatter\*, Y, Williams, C, Musslick, S. "Expression Sampler as a Dynamic Benchmark for Symbolic Regression." In *NeurIPS 2023 AI for Science Workshop*. (2023), . [*equal contribution]
 
 ## About
 
@@ -51,10 +23,6 @@ PI: <a href="https://smusslick.com/">Sebastian Musslick</a>. This research progr
 Schmidt Science Fellows, in partnership with the Rhodes Trust, as well as the Carney BRAINSTORM
 program at Brown University.
 
-## References
-
-La Cava, W. G., Orzechowski, P., Burlacu, B., de França, F. O., Virgolin, M., Jin, Y., Kommenda, M., & Moore, J. H. "Contemporary Symbolic Regression Methods and their Relative Performance." In *CoRR* (2021), Available at: [https://arxiv.org/abs/2107.14351](https://arxiv.org/abs/2107.14351)
 
-Matsubara, Y., Chiba, N., Igarashi, R., & Ushiku, Y. "Rethinking symbolic regression datasets and benchmarks for scientific discovery." In *arXiv preprint arXiv:2206.10540*. (2022), Available at: [https://arxiv.org/abs/2206.10540](https://arxiv.org/abs/2206.10540)
 
 

docs/quickstart.md

@@ -4,12 +4,11 @@ You will need:
 
 - `python` 3.8 or greater: [https://www.python.org/downloads/](https://www.python.org/downloads/)
 
-
+The package is available as pypi package:
 ```shell
-pip install -U equation-tree
+pip install equation-tree
 ```
 
-
 Check your installation by running:
 ```shell
 python -c "from equation_tree import EquationTree"

docs/Basic Usage.ipynb docs/tutorials/Basic Usage.ipynbdocs/Basic Usage.ipynb renamed to docs/tutorials/Basic Usage.ipynb

@@ -8,11 +8,13 @@
    },
    "source": [
     "# Basic Usage\n",
-    "Here, we demonstrate core functionalities of the Equation Tree:\n",
+    "\n",
+    "Content:\n",
     "- Basic Functionality for sampling and processing equations\n",
     "- Advanced settings for sampling equations\n",
     "\n",
-    "## Installation"
+    "## Installation\n",
+    "The Equation Tree package is available on [pyPI](https://pypi.org/project/equation-tree/):"
    ]
   },
   {
@@ -33,7 +35,7 @@
     "\n",
     "### Sampling With Default Settings\n",
     "First, we need to import the functionality.\n",
-    "Here we also set a seed to ensure reproducible results."
+    "Here, we also set a seed to ensure reproducible results."
    ],
    "metadata": {
     "collapsed": false
@@ -232,7 +234,7 @@
     "\n",
     "### Evaluating Equations\n",
     "\n",
-    "After instantiating equations, we can evaluate them arbitrary input:"
+    "After instantiating equations, we can evaluate them on arbitrary input:"
    ],
    "metadata": {
     "collapsed": false
@@ -279,7 +281,7 @@
     "\n",
     "### Input Dimensions\n",
     "\n",
-    "We can manipulate the space on witch the equation is defined. For example, if we want equations that are defined on 2-dimensions, we can write:"
+    "We can manipulate the space on witch the equations are defined. For example, if we want equations that are defined on 2-dimensions, we can write:"
    ],
    "metadata": {
     "collapsed": false
@@ -310,11 +312,11 @@
   {
    "cell_type": "markdown",
    "source": [
-    "*Note, not all the equations have exactly 2 input variable. Some of them have only one. This is since equations with only one input variable are still defined on 2 (or more dimensions)*\n",
+    "*Note, not all the equations have exactly two input variable. Some of them have only one. This is since equations with one input variable are still defined on two (or more) dimensions.*\n",
     "\n",
     "### Equation Complexity\n",
     "\n",
-    "We can also manipulate the equation complexity (as number of nodes)"
+    "We can also manipulate the equation complexity (for example, as tree depth):"
    ],
    "metadata": {
     "collapsed": false
@@ -344,6 +346,39 @@
     "collapsed": false
    }
   },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Instead of an exact depth, we can also sample all equations up to a specified depth:"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "equations_simple = sample(n=5, max_depth=3)\n",
+    "equations_complex = sample(n=5, max_depth=8)"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "print('*** simple equations ***\\n', equations_simple, '\\n')\n",
+    "print('*** complex equations ***\\n', equations_complex)"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
   {
    "cell_type": "markdown",
    "source": [