diff --git a/README.md b/README.md index 0aa9296b8..840d1c2fe 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Check out tutorials and documentation at ## Example -The following example demonstrates how to use AutoRA to automate the process of model discovery, experimental design, and data collection. +The following basic 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. @@ -127,6 +127,7 @@ for i in range(5): print('\n') ``` +If you are curious about how to apply AutoRA to real-world discovery problems, you can find use case examples of AutoRA in the [Use Case Tutorials](https://autoresearch.github.io/autora/examples/) section of the documentation. ## Contributions @@ -134,11 +135,9 @@ We welcome contributions to the AutoRA project. Please refer to the [contributor ## About -This project is in active development by -the [Autonomous Empirical Research Group](http://empiricalresearch.ai), -in collaboration with the [Center for Computation and Visualization at Brown University](https://ccv.brown.edu). +This project is in active development by the [Autonomous Empirical Research Group](https://musslick.github.io/AER_website/Research.html). -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. +The development of this package was supported by [Schmidt Science Fellows](https://schmidtsciencefellows.org/), in partnership with the Rhodes Trust, as well as the [Carney BRAINSTORM program](https://ccbs.carney.brown.edu/brainstorm) at Brown University. The development of auxiliary packages for AutoRA, such as `autodoc`, is supported by [Schmidt Sciences, LLC. and the Virtual Institute for Scientific Software (VISS)](https://www.schmidtsciences.org/viss/). The AutoRA package was developed using computational resources and services at the [Center for Computation and Visualization at Brown University](https://ccv.brown.edu). ## Read More diff --git a/docs/contribute/index.md b/docs/contribute/index.md index cf87ace06..c55431c3e 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -15,14 +15,14 @@ Child packages are generally maintained by individual contributors. The parent p *core* packages, is maintained by the [Autonomous Empirical Research Group](https://musslick.github.io/AER_website/Team.html), as well as external contributors. -![image](../img/package_overview.png) +![image](../img/contributor_model.png) [`autora`](https://github.com/autoresearch/autora) is the parent package which end users are expected to install. The parent depends on core packages, such as [`autora-core`](https://github.com/autoresearch/autora-core) and [`autora-synthetic`](https://github.com/autoresearch/autora-synthetic). It also includes vetted modules (child packages) as optional dependencies which users can choose to install. -You may contribute to any of the core packages or develop your own module as a stand-alone package (see below). +You may contribute to any of the core packages or develop your own module as a stand-alone child package (see below). ## Style Guide diff --git a/docs/img/contributor_model.png b/docs/img/contributor_model.png new file mode 100644 index 000000000..d8d1d4957 Binary files /dev/null and b/docs/img/contributor_model.png differ diff --git a/docs/img/package_overview.png b/docs/img/package_overview.png deleted file mode 100644 index a6054a485..000000000 Binary files a/docs/img/package_overview.png and /dev/null differ diff --git a/docs/img/state_logic.png b/docs/img/state_logic.png new file mode 100644 index 000000000..1bf3c627a Binary files /dev/null and b/docs/img/state_logic.png differ diff --git a/docs/img/state_wrapper.png b/docs/img/state_wrapper.png new file mode 100644 index 000000000..f036246ff Binary files /dev/null and b/docs/img/state_wrapper.png differ diff --git a/docs/index.md b/docs/index.md index 101a34493..f01806fd3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -67,6 +67,6 @@ Once you are familiar with the basics, you can explore the [Use Case Tutorials]( This project is in active development by the [Autonomous Empirical Research Group](https://musslick.github.io/AER_website/Research.html). -The development of this package was supported by Schmidt Science Fellows, in partnership with the Rhodes Trust, as well as the [Carney BRAINSTORM program](https://ccbs.carney.brown.edu/brainstorm) at Brown University. The development of auxiliary packages for AutoRA, such as `autodoc`, is supported by [Schmidt Sciences, LLC. and the Virtual Institute for Scientific Software (VISS)](https://www.schmidtsciences.org/viss/). The AutoRA package was developed using computational resources and services at the [Center for Computation and Visualization at Brown University](https://ccv.brown.edu). +The development of this package was supported by [Schmidt Science Fellows](https://schmidtsciencefellows.org/), in partnership with the Rhodes Trust, as well as the [Carney BRAINSTORM program](https://ccbs.carney.brown.edu/brainstorm) at Brown University. The development of auxiliary packages for AutoRA, such as `autodoc`, is supported by [Schmidt Sciences, LLC. and the Virtual Institute for Scientific Software (VISS)](https://www.schmidtsciences.org/viss/). The AutoRA package was developed using computational resources and services at the [Center for Computation and Visualization at Brown University](https://ccv.brown.edu). diff --git a/docs/installation.md b/docs/installation.md index a160bd9df..b166a461e 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -49,9 +49,9 @@ In using AutoRA, it is helpful to be aware of its structure, which is described ``autora`` is organized into one "parent" and many "child" packages. -![image](img/package_overview.png) +![image](img/contributor_model.png) -The ``autora`` "parent" package depends on core packages, such as [`autora-core`](https://github.com/autoresearch/autora-core), [`autora-workflow`](https://github.com/autoresearch/autora-workflow), and [`autora-synthetic`](https://github.com/autoresearch/autora-synthetic), which are automatically installed with ``autora``. +The ``autora`` "parent" package depends on core packages, such as [`autora-core`](https://github.com/autoresearch/autora-core) and [`autora-synthetic`](https://github.com/autoresearch/autora-synthetic), which are automatically installed with ``autora``. However, the ``autora`` ecosystem also includes vetted modules (child packages) as **optional dependencies** which users can choose to install. Below, we provide a list of all optional dependencies that are currently vetted by the ``autora`` core team. @@ -62,7 +62,7 @@ To install any (combination) of optional dependencies, users should run the rele pip install -U "autora[desired-dependency]" ``` -For example, to install one of the [Theorists](theorist/index.md), such as the Bayesian Machine Scientist (BMS), a user should run: +For example, to install one of the [Theorists](theorist/index.md), such as the Bayesian Machine Scientist (BMS) from the package `autora-theorist-bms`, a user should run: ```shell pip install -U "autora[theorist-bms]" diff --git a/docs/terminology.md b/docs/terminology.md index f64ac068c..f2a338ebb 100644 --- a/docs/terminology.md +++ b/docs/terminology.md @@ -2,19 +2,21 @@ The following table includes naming conventions used throughout AutoRA. -| Term | Description | Relevant Modules | -|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------| -| State | Object representing data from an experiment, like the conditions, observed experiment data and models. The State also includes rules on how to update those data if new data are provided using the "Delta mechanism". | Core | -| Delta | An object with new data that can be added to a State, returning a new State which includes the new data. | Core | -| StandardState | An optional default State that has the following fields: variables, conditions, experiment_data, models. | Core | -| Variables | A State field that holds experimental variables, which are defined according to name, type, units, allowed values, and range. | Experimentalists, Experiment Runners, Theorists | -| VariableCollection | Immutable metadata about dependent variables, independent variables, and covariates. | Experimentalists, Experiment Runners, Theorists | -| Conditions | A State field that defines what observations should be collected according to a specific combination of values of the independent variables | Experimentalists, Experiment Runners, Theorists | -| Experiment Data | A State field that holds specified conditions as well as the corresponding observations. | Experiment Runners, Theorists | -| Model | A State field that holds the the collection of best fit equations produced by theorists. | Theorists, Experimentalists | -| Components | The functions that can act on the State (e.g., experimentalists, experiment runners, theorists). | Experimentalists, Experiment Runners, Theorists | -| Experimentalist | A component that outputs new conditions, which are intended to yield novel observations. | Experimentalists | -| Theorist | A component that takes in the full collection of conditions and observations and outputs models that link the two. | Theorists | -| Experiment Runner | A component that takes in conditions and collects corresponding observations. | Experiment Runners | -| Wrapper | Special functions that make the components of AutoRA able to operate on State objects. | Experimentalists, Experiment Runners, Theorists | -| Workflow | A collection of tools that enable closed-loop empirical research with the AutoRA framework. | Experimentalists, Experiment Runners, Theorists | +| Term | Description | Relevant Modules | +|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------| +| State | Object representing data from an experiment, like the conditions, observed experiment data and models. The State also includes rules on how to update those data if new data are provided using the "Delta mechanism". | Core | +| Delta | An object with new data that can be added to a State, returning a new State which includes the new data. | Core | +| StandardState | An optional default State that has the following fields: ``variables``, ``conditions``, ``experiment_data``, ``models``. | Core | +| Variables | A State field (``state.variables``) that holds experimental variables, which are defined according to name, type, units, allowed values, and range. | Experimentalists, Experiment Runners, Theorists | +| Independent Variable | An experimental variable that the researcher intends to manipulate or change to observe its effect. A parameteriation of independent variables is called a *condition*. | Experimentalists, Experiment Runners, Theorists | +| Dependent Variable | An experimental variable that that is measured or observed in response to changes in the independent variable. Values of independent variables are referred to as *observations* and are part of the *experimental data*. | Experimentalists, Experiment Runners, Theorists | +| VariableCollection | Immutable metadata about dependent variables, independent variables, and covariates. | Experimentalists, Experiment Runners, Theorists | +| Conditions | A State field (``state.conditions``) that defines what observations should be collected according to a specific combination of values of the independent variables | Experimentalists, Experiment Runners, Theorists | +| Experiment Data | A State field (``state.experiment_data``) that holds specified conditions as well as the corresponding observations. | Experiment Runners, Theorists | +| Model | A State field (``state.models``) that holds the the collection of best fit models produced by theorists. | Theorists, Experimentalists | +| Components | The functions that can act on the State (e.g., experimentalists, experiment runners, theorists). | Experimentalists, Experiment Runners, Theorists | +| Experimentalist | A component that outputs new conditions, which are intended to yield novel observations. | Experimentalists | +| Theorist | A component that takes in the full collection of conditions and observations and outputs models that link the two. | Theorists | +| Experiment Runner | A component that takes in conditions and collects corresponding observations. | Experiment Runners | +| Wrapper | Special functions that make the components of AutoRA able to operate on State objects. | Experimentalists, Experiment Runners, Theorists | +| Workflow | A collection of tools that enable closed-loop empirical research with the AutoRA framework. | Experimentalists, Experiment Runners, Theorists | diff --git a/docs/tutorials/basic/Tutorial III Functional Workflow.ipynb b/docs/tutorials/basic/Tutorial III Functional Workflow.ipynb index ce875ce13..9758f7c73 100644 --- a/docs/tutorials/basic/Tutorial III Functional Workflow.ipynb +++ b/docs/tutorials/basic/Tutorial III Functional Workflow.ipynb @@ -103,6 +103,8 @@ "Using the functions and objects in `autora.state`, we can build flexible pipelines and cycles which operate on state\n", "objects. State objects represent data from an experiment, like the conditions, observed experiment data and models. The State also includes rules on how to update those data if new data are provided using the \"Delta mechanism\". This state can be acted upon by experimentalists, experiment runners, and theorists. \n", "\n", + "\"State\n", + "\n", "In tutorial I, we had experimentalists define new conditions, experiment runners collect new observations, and theorists model the data. To do this, we used the output of one as the input of the other, such as: \n", "\n", "`conditions = experimentalist(...)` $\\rightarrow$
\n", @@ -261,6 +263,8 @@ "- `on_state()` for experiment runners and experimentalists\n", "- `estimator_on_state()` for theorists (specifically, scikit-learn estimators)\n", "\n", + "\"State\n", + "\n", "The first argument for each wrapper should be your corresponding function (i.e., the experiment runner, the experimentalist, and the theorist). The `on_state` wrapper takes a second argument, `output`, to determine where in the state the component is acting on. For the experimentalist this will be `output=[\"conditions\"]`, and for the experiment runner this will be `output=[\"experiment_data\"]`.\n", "\n", "Once the components are wrapped, their functionality changes to act on the state, meaning that they now expect a state as the first input and will return a modified version of that state."