From bde65e19bb7cc8c5849456bc48c21e5a0bb558c7 Mon Sep 17 00:00:00 2001 From: Sebastian Musslick Date: Sat, 11 Nov 2023 20:51:18 +0100 Subject: [PATCH 1/3] updated README --- README.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3da8fc516..701cf5702 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,9 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ![GitHub Discussions](https://img.shields.io/github/discussions/autoresearch/autora) +BRAINSTORM Program     +BRAINSTORM Program + [AutoRA](https://pypi.org/project/autora/) (Automated Research Assistant) is an open-source framework for automating multiple stages of the empirical research process, including model discovery, experimental design, data collection, and documentation for open science. @@ -14,10 +17,25 @@ AutoRA was initially intended for accelerating research in the behavioral and br ![Autonomous Empirical Research Paradigm](https://github.com/AutoResearch/autora/raw/main/docs/img/overview.png) -## Getting Started +## Installation + + +We recommended using a `Python` environment manager like `virtualenv`. You may refer to the Development Guide on how to [set up a virtual environment](https://autoresearch.github.io/autora/contribute/setup/#create-a-virtual-environment). + +Before installing the PyPI ``autora`` package, you may [activate your environment](https://autoresearch.github.io/autora/contribute/setup/#activating-and-using-the-environment). To install the PyPI `autora` package, run the following command: + +```shell +pip install "autora" +``` + +## Documentation Check out the documentation at -[https://autoresearch.github.io/autora](https://autoresearch.github.io/autora). +[https://autoresearch.github.io/autora](https://autoresearch.github.io/autora). If you run into any issues or questions regarding the use of AutoRA, please reach out to us at the [AutoRA forum](https://github.com/orgs/AutoResearch/discussions/categories/using-autora). + +## Contributions + +We welcome contributions to the AutoRA project. Please refer to the [contributor guide](https://autoresearch.github.io/autora/contribute/) for more information. Also, feel free to ask any questions or provide any feedback regarding core contributions on the [AutoRA forum](https://github.com/orgs/AutoResearch/discussions/). ## About @@ -27,9 +45,6 @@ in collaboration with the [Center for Computation and Visualization at Brown Uni The development of this package is supported by Schmidt Science Fellows, in partnership with the Rhodes Trust, as well as the Carney BRAINSTORM program at Brown University. -BRAINSTORM Program     -BRAINSTORM Program - ## Read More From 04b07d0d1f8ca6f16707c9cfd4d376e3fd023b33 Mon Sep 17 00:00:00 2001 From: Sebastian Musslick Date: Thu, 30 Nov 2023 12:31:02 +0100 Subject: [PATCH 2/3] added minimum example --- README.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 94 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 701cf5702..1dd45c751 100644 --- a/README.md +++ b/README.md @@ -30,9 +30,102 @@ pip install "autora" ## Documentation -Check out the documentation at +Check out tutorials and documentation at [https://autoresearch.github.io/autora](https://autoresearch.github.io/autora). If you run into any issues or questions regarding the use of AutoRA, please reach out to us at the [AutoRA forum](https://github.com/orgs/AutoResearch/discussions/categories/using-autora). +## Example + +The following example demonstrates how to use AutoRA to automate the process of model discovery, experimental design, and data collection. + +The discovery problem is defined by a single independent variable $x \in [0, 2 \pi]$ and dependent variable $y$. +The experiment amounts to a simple sine wave, $y = \sin(x)$, which is the model we are trying to discover. + +Th discovery cycle iterates between the experimentalist, experiment runner, and theorist. Here, we us a "random" experimentalist, which samples novel experimental conditions for $x$ every cycle. +The experiment runner then collects data for the corresponding $y$ values. Finally, the theorist uses a [Bayesian Machine Scientist](https://autoresearch.github.io/autora/user-guide/theorists/bms/) (BMS; Guimerà et al., in Science Advances) to identify a scientific model that explains the data. + +The workflow relies on the ``StandardState`` object, which stores the current state of the discovery process, such as ``conditions``, ``experiment_data``, or ``models``. The state is passed between the experimentalist, experiment runner, and theorist. + + +```python +#################################################################################### +## Import statements +#################################################################################### + +import pandas as pd +import numpy as np +import sympy as sp + +from autora.variable import Variable, ValueType, VariableCollection + +from autora.experimentalist.random import random_pool +from autora.experiment_runner.synthetic.abstract.equation import equation_experiment +from autora.theorist.bms import BMSRegressor + +from autora.state import StandardState, on_state, estimator_on_state + +#################################################################################### +## Define initial data +#################################################################################### + +#### Define variable data #### +iv = Variable(name="x", value_range=(0, 2 * np.pi), allowed_values=np.linspace(0, 2 * np.pi, 30)) +dv = Variable(name="y", type=ValueType.REAL) +variables = VariableCollection(independent_variables=[iv],dependent_variables=[dv]) + +#### Define seed condition data #### +conditions = random_pool(variables, num_samples=10, random_state=0) + +#################################################################################### +## Define experimentalist +#################################################################################### + +experimentalist = on_state(random_pool, output=["conditions"]) + +#################################################################################### +## Define experiment runner +#################################################################################### + +sin_experiment = equation_experiment(sp.simplify('sin(x)'), variables.independent_variables, variables.dependent_variables[0]) +sin_runner = sin_experiment.experiment_runner + +experiment_runner = on_state(sin_runner, output=["experiment_data"]) + +#################################################################################### +## Define theorist +#################################################################################### + +theorist = estimator_on_state(BMSRegressor(epochs=100)) + +#################################################################################### +## Define state +#################################################################################### + +s = StandardState( + variables = variables, + conditions = conditions, + experiment_data = pd.DataFrame(columns=["x","y"]) +) + +#################################################################################### +## Cycle through the state +#################################################################################### + +print('Pre-Defined State:') +print(f"Number of datapoints collected: {len(s['experiment_data'])}") +print(f"Derived models: {s['models']}") +print('\n') + +for i in range(5): + s = experimentalist(s, num_samples=10, random_state=42) + s = experiment_runner(s, added_noise=1.0, random_state=42) + s = theorist(s) + print(f"\nCycle {i+1} Results:") + print(f"Number of datapoints collected: {len(s['experiment_data'])}") + print(f"Derived models: {s['models']}") + print('\n') +``` + + ## Contributions We welcome contributions to the AutoRA project. Please refer to the [contributor guide](https://autoresearch.github.io/autora/contribute/) for more information. Also, feel free to ask any questions or provide any feedback regarding core contributions on the [AutoRA forum](https://github.com/orgs/AutoResearch/discussions/). From 653fdf2473a80761048608b84927d944b176cdd3 Mon Sep 17 00:00:00 2001 From: Sebastian Musslick Date: Thu, 30 Nov 2023 12:31:58 +0100 Subject: [PATCH 3/3] added minimum example --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1dd45c751..48dff2159 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ AutoRA was initially intended for accelerating research in the behavioral and br ## Installation -We recommended using a `Python` environment manager like `virtualenv`. You may refer to the Development Guide on how to [set up a virtual environment](https://autoresearch.github.io/autora/contribute/setup/#create-a-virtual-environment). +We recommend using a `Python` environment manager like `virtualenv`. You may refer to the Development Guide on how to [set up a virtual environment](https://autoresearch.github.io/autora/contribute/setup/#create-a-virtual-environment). Before installing the PyPI ``autora`` package, you may [activate your environment](https://autoresearch.github.io/autora/contribute/setup/#activating-and-using-the-environment). To install the PyPI `autora` package, run the following command: