diff --git a/docs/contribute/index.md b/docs/contribute/index.md index acaf8f8a2..94f173d4d 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -9,8 +9,7 @@ project structure, along with pointers to more detailed contribution guides for [AutoRA forum](https://github.com/orgs/AutoResearch/discussions). We look forward to hearing from you! - -## Project structure +## Project Structure Contributions to AutoRA are organized into one "parent" and many "child" packages. Child packages are generally maintained by individual contributors. The parent package, along with some other @@ -28,7 +27,7 @@ to install. You may contribute to any of the core packages or develop your own module as a stand-alone package (see below). -## Module contributions +## Module Contributions Modules include theorists, experimentalists, experiment runners, or other functionalities not covered by the core packages. All modules are child packages and can become optional dependencies of the `autora` parent package. Modules packages are @@ -42,7 +41,7 @@ for inclusion in `autora`, see [the module contributor guide](modules/index.md). Feel free to post questions and feedback regarding module contributions on the [AutoRA forum](https://github.com/orgs/AutoResearch/discussions/categories/module-contributions). -## Core contributions +## Core Contributions The following packages are considered core packages, and are actively maintained by the [Autonomous Empirical Research Group](https://musslick.github.io/AER_website/Team.html): diff --git a/docs/contribute/modules/experiment-runner.md b/docs/contribute/modules/experiment-runner.md index 2a9bda28e..9db4ae2cf 100644 --- a/docs/contribute/modules/experiment-runner.md +++ b/docs/contribute/modules/experiment-runner.md @@ -8,7 +8,7 @@ To contribute a *synthetic experiment runner* follow the [core](../core.md) cont Contributions may be complete experiment runners, which are functions that return observations, or tools that help automate experiments. Examples of such tools that are already implemented include a [recruitment manager](https://autoresearch.github.io/autora/user-guide/experiment-runners/recruitment-managers/prolific/) for recruiting participants on [Prolific](https://www.prolific.co/) and an [experimentation manager](https://autoresearch.github.io/autora/user-guide/experiment-runners/experimentation-managers/firebase/) for executing online experiments with [Firebase](https://firebase.google.com/). -## Repository setup +## Repository Setup For non-synthetic experiment runners, we recommend using the [cookiecutter template](https://github.com/AutoResearch/autora-template-cookiecutter) to set up a repository for your experiment runner. Alternatively, you can use the @@ -26,7 +26,7 @@ Make sure to select the `experiment runner` option when prompted. If you want to To implement a complete experiment runner, be sure to define a function that returns observations. To get an idea for tools that help automate experiments, see the [list of tools](https://autoresearch.github.io/autora/experiment-runner/) that are already implemented. -## Next steps: testing, documentation, publishing +## Next Steps: Testing, Documentation, Publishing For more information on how to test, document, and publish your experiment runner, please refer to the [general guideline for module contributions](index.md) . diff --git a/docs/contribute/modules/experimentalist.md b/docs/contribute/modules/experimentalist.md index 39ef351f3..fe3221317 100644 --- a/docs/contribute/modules/experimentalist.md +++ b/docs/contribute/modules/experimentalist.md @@ -12,7 +12,7 @@ Experimentalists can be implemented as *poolers* or as *samplers*. a subset of conditions from the pool to be used in the next experiment. - **Samplers** directly return a subset of experimental conditions from a pool of candidate experimental conditions that already exist. -## Repository setup +## Repository Setup We recommend using the [cookiecutter template](https://github.com/AutoResearch/autora-template-cookiecutter) to set up a repository for your experimentalist. Alternatively, you can use the @@ -35,7 +35,7 @@ a numpy array, iterator variable or other data format. We generally **recommend using 2-dimensional numpy arrays as outputs** in which each row represents a set of experimental conditions. The columns of the array correspond to the independent variables. -### Implementing poolers +### Implementing Poolers Once you've created your repository, you can implement your experimentalist pooler by editing the `init.py` file in ``src/autora/experimentalist/pooler/name_of_your_experimentalist/``. @@ -82,7 +82,7 @@ def grid_pool(ivs: List[IV]): ``` -### Implementing samplers +### Implementing Samplers Once you've created your repository, you can implement your experimentalist sampler by editing the `init.py` file in ``src/autora/experimentalist/sampler/name_of_your_experimentalist/``. @@ -121,7 +121,7 @@ random_sample(conditions: Union[Iterable, Sequence], n: int = 1): ``` -## Next steps: testing, documentation, publishing +## Next Steps: Testing, Documentation, Publishing For more information on how to test, document, and publish your experimentalist, please refer to the [general guideline for module contributions](index.md) . diff --git a/docs/contribute/modules/index.md b/docs/contribute/modules/index.md index cfa5afbd7..d6b13a796 100644 --- a/docs/contribute/modules/index.md +++ b/docs/contribute/modules/index.md @@ -18,11 +18,11 @@ They are based on either this guide. -## Implementing your module +## Implement Your Module After setting up your repository and linking it to your GitHub account, you can start implementing your module. -### Step 1: implement your code +### Implement Your Code You may implement your code in the ``init.py`` located in the respective feature folder in ``src/autora``. @@ -35,7 +35,7 @@ If the feature you seek to implement does not fit in any of these categories, th you can create folders for new categories. If you are unsure how to proceed, you are always welcome to ask for help in the [AutoRA forum](https://github.com/orgs/AutoResearch/discussions/categories/module-contributions). -### Step 2 (optional): add tests +### Add Tests (Optional) It is highly encouraged to add unit tests to ensure your code is working as intended. These can be [doctests](https://docs.python.org/3/library/doctest.html) or test cases in `tests/test_your_contribution_name.py`. For example, if you are implementing a sampler experimentalist, you may rename and modify the @@ -45,7 +45,7 @@ For example, if you are implementing a sampler experimentalist, you may rename a [autora](https://github.com/AutoResearch/autora) package. However, regardless of whether you choose to implement tests, you will still be able to install your package separately, in addition to `autora`.* -### Step 3 (optional): add documentation +### Add Documentation (Optional) It is highly encouraged that you add documentation of your package in `docs/index.md`. You can also add new or delete unnecessary pages in the `docs` folder. However you structure your documentation, be sure that structure is reflected in the `mkdocs.yml` file. @@ -58,7 +58,7 @@ the `docs/quickstart.md` file. [autora](https://github.com/AutoResearch/autora) package. However, regardless of whether you choose to write documentation, you will still be able to install your package separately, in addition to `autora`.* -### Step 4: add dependencies +### Add Dependencies In the `pyproject.toml` file, add the new dependencies under `dependencies`. @@ -67,7 +67,7 @@ Install the added dependencies pip install -e ".[dev]" ``` -## Publishing your module +## Publish Your Module There are several ways to publish your package, depending on how you set up your repository. @@ -79,7 +79,7 @@ github.com, then you can use Github Actions to automatically publish your packag Once you've published your module, you should take some time to celebrate and announce your contribution in the [AutoRA forum](https://github.com/orgs/AutoResearch/discussions/categories/module-announcements). -## Incorporating your module into the `autora` parent package +## Incorporate Your Module Into The AutoRA Parent Package Once your package is working and published, you can **make a pull request** on [`autora`](https://github.com/autoresearch/autora) to have it vetted and added to the "parent" package. Note, if you are not a member of the AutoResearch organization on GitHub, you will need to create a fork of the repository for the parent package and submit your pull request via that fork. If you are a member, you can create a pull request from a branch created directly from the parent package repository. Steps for creating a new branch to add your module are specified below. The following demonstrates how to add a package published under `autora-theorist-example` in PyPI in the GitHub @@ -97,7 +97,7 @@ repository `example-contributor/contributor-theorist` The following demonstrates how to add a package published under autora-theorist-example in PyPI in the GitHub repository example-contributor/contributor-theorist -### Install the "parent" package in development mode +### Install The Parent Package In Development Mode Install this in an environment using your chosen package manager. In this example, we use pip and virtualenv. @@ -128,11 +128,11 @@ mkdocs serve ... then viewing the documentation using the link in your terminal. -### Create a new branch of the parent package +### Create A New Branch Of The Parent Package Once you've successfully installed the parent package in development mode, you can begin the process of adding your contribution by creating a new branch off of the `main` branch. You should name your branch according to the name of your contribution. In the example we're using here, the branch would be called `feat/contributor-theorist`. After creating your branch, you can start making the modifications specified below. -### Add the package as optional dependency +### Add The Package As An Optional Dependency In the `pyorject.toml` file add an optional dependency for the package in the `[project.optional-dependencies]` section: @@ -160,7 +160,7 @@ pip install -U -e ".[dev]" ... and check that your package is still importable and works as expected. -### Import documentation from the package repository +### Import Documentation From The Package Repository Import the documentation in the `mkdocs.yml` file: ```yml @@ -200,7 +200,7 @@ mkdocs serve ... then view the documentation using the link in your terminal. Check that your new documentation is included in the right place and renders correctly. -## Updating your module +## Updating Your Module !!! warning Please note, that packages need to be vetted each time they are updated. diff --git a/docs/contribute/modules/theorist.md b/docs/contribute/modules/theorist.md index d35c5866c..af850b525 100644 --- a/docs/contribute/modules/theorist.md +++ b/docs/contribute/modules/theorist.md @@ -11,7 +11,7 @@ a more complex neural network, or other models which All theorists are implemented as `sklearn` regressors. They are fitted based on experimental conditions and respective observations, and can be used to predict observations for new experimental conditions. -## Repository setup +## Repository Setup We recommend using the [cookiecutter template](https://github.com/AutoResearch/autora-template-cookiecutter) to set up a repository for your theorist. Alternatively, you use the @@ -67,7 +67,7 @@ class ExampleRegressor(BaseEstimator): return self.polynomial(conditions) ``` -## Next steps: testing, documentation, publishing +## Next Steps: Testing, Documentation, Publishing For more information on how to test, document, and publish your theorist, please refer to the [general guideline for module contributions](index.md) . diff --git a/docs/contribute/pre-commit-hooks.md b/docs/contribute/pre-commit-hooks.md index ce814731d..4e8827f1e 100644 --- a/docs/contribute/pre-commit-hooks.md +++ b/docs/contribute/pre-commit-hooks.md @@ -11,7 +11,7 @@ We use pre-commit hooks to: The hooks and their settings are specified in the `.pre-commit-config.yaml` in each repository. -## Handling pre-commit hook errors +## Handling Pre-Commit Hook Errors If your `git commit` fails because of the pre-commit hook, then you should: diff --git a/docs/contribute/setup.md b/docs/contribute/setup.md index f3157c03c..a87126d1c 100644 --- a/docs/contribute/setup.md +++ b/docs/contribute/setup.md @@ -26,9 +26,9 @@ The following sections describe how to install and configure the recommended set - **macOS**: Joe Kissell. [*Take Control of the Mac Command Line with Terminal, 3rd Edition*](https://bruknow.library.brown.edu/permalink/01BU_INST/528fgv/cdi_safari_books_v2_9781947282513). Take Control Books, 2022. Chapters *Read Me First* through *Bring the Command Line Into The Real World*. - **Linux**: William E. Shotts. [*The Linux Command Line: a Complete Introduction. 2nd edition.*](https://bruknow.library.brown.edu/permalink/01BU_INST/9mvq88/alma991043239704906966). No Starch Press, 2019. Parts *I: Learning the Shell* and *II: Configuration and the Environment*. -## Development setup +## Development Setup -### Clone the repository +### Clone The Repository The easiest way to clone the repo is to go to [the repository page on GitHub](https://github.com/AutoResearch/autora) and click the "<> Code" button and follow the prompts. @@ -39,7 +39,7 @@ and click the "<> Code" button and follow the prompts. - the [GitHub Desktop Application](https://desktop.github.com) on macOS or Windows, or - the [GitHub command line utility](https://cli.github.com) on Linux. -### Install `python` +### Install `Python` !!! success All contributions to the AutoRA core packages should work under **python 3.8**, so we recommend using that version @@ -67,7 +67,7 @@ Python 3.11.3 (main, Apr 7 2023, 20:13:31) [Clang 14.0.0 (clang-1400.0.29.202)] Type "help", "copyright", "credits" or "license" for more information. ``` -#### Create a virtual environment +#### Create A Virtual Environment !!! success We recommend setting up your development environment using a manager like `venv`, which creates isolated python @@ -92,7 +92,7 @@ Activate it by running source ".venv/bin/activate" ``` -#### Install dependencies +#### Install Dependencies Upgrade pip: ```shell @@ -110,7 +110,7 @@ Your IDE may have special support for python environments. For IDE-specific setu - [VSCode Documentation](https://code.visualstudio.com/docs/python/environments) -### Activating and using the environment +### Activating And Using The Environment To run interactive commands, you can activate the virtualenv environment. From the `` directory, run: @@ -169,7 +169,7 @@ OK ``` -### Running code non-interactively +### Running Code Non-Interactively You can run python programs without activating the environment, by using `/path/to/python run {command}`. For example, to run unittests tests, execute: @@ -189,7 +189,7 @@ Ran 1 test in 0.000s OK ``` -### Pre-commit hooks +### Pre-Commit Hooks If you wish to commit to the repository, you should install and activate `pre-commit` as follows. ```shell diff --git a/docs/index.md b/docs/index.md index 20db63a08..8afdbfad5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,7 +29,7 @@ AutoRA consists of different modules that can be used independently or in combin - [**Workflow logic**](user-guide/workflow) for defining interactions between different components of the research process - Interfaces for automated documentation of the research process -## Usages +## Uses AutoRA can be used for a variety of research purposes in empirical sciences, such as psychology, neuroscience, economics, physics, or materials science. Usages, as illustrated in the following tutorials, include: diff --git a/docs/online-experiments/firebase.md b/docs/online-experiments/firebase.md index 1f227eda3..d08d3baa5 100644 --- a/docs/online-experiments/firebase.md +++ b/docs/online-experiments/firebase.md @@ -93,7 +93,7 @@ npm start ``` During development, the Firestore database will not be used. If you want to load conditions from the database, you need to upload them first (for example using the [AutoRA Firebase Experimentation Manager](user-guide/experiment-runners/experimentation-managers/firebase/)) and set `REACT_APP_devNoDb="False"` in the `.env` file. -### Using Prolific Ids +### Using Prolific Id's If you want to recruit participants via Prolific (for example using the [AutoRA Prolific Recruitment Manager](user-guide/experiment-runners/recruitment-managers/prolific/)), we ***highly recommend*** setting `REACT_APP_useProlificId="True"`. This will speed up the recruitment of participants. ## Build And Deploy To Firebase diff --git a/docs/tutorials/Experimentalist.ipynb b/docs/tutorials/Experimentalist.ipynb index 5a16b8dde..8a52fd628 100644 --- a/docs/tutorials/Experimentalist.ipynb +++ b/docs/tutorials/Experimentalist.ipynb @@ -9,7 +9,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Automated Experimentalist Tutorial\n", + "# Experimentalist Tutorial\n", "\n", "[Experimentalists](../experimentalist/index.md) are functions designed to return novel experimental conditions that yield scientific merit.\n", "\n", @@ -65,10 +65,11 @@ ] }, { + "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ - "## Example 1: Sampling fom a Sinus Function\n", + "## Example 1: Sampling From A Sine Function\n", "\n", "In this example, we will consider a dataset resembling the sine function. We will then fit a linear model to the data and use the falsification sampler to identify experiment conditions under which the model is predicted to perform the worst.\n", "\n", @@ -242,10 +243,11 @@ ] }, { + "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ - "## Example 2: Sampling from a Gaussian Mixture Model\n", + "## Example 2: Sampling From A Gaussian Mixture Model\n", "\n", "In this example, we will consider a dataset sampled from a Gaussian mixture model. We will fit a Gaussian mixture model to the data and use the falsification sampler to identify experiment conditions under which the model is predicted to perform the worst.\n", "\n", @@ -528,10 +530,11 @@ ] }, { + "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ - "## Example 2: Sampling from a Gaussian Mixture Model\n", + "## Example 2: Sampling From A Gaussian Mixture Model\n", "\n", "In this example, we will consider a dataset sampled from a Gaussian mixture model. We will fit a Gaussian mixture model to the data and use the falsification sampler to identify experiment conditions under which the model is predicted to perform the worst.\n", "\n", diff --git a/docs/tutorials/Theorist.ipynb b/docs/tutorials/Theorist.ipynb index 817f3f376..e038ab781 100644 --- a/docs/tutorials/Theorist.ipynb +++ b/docs/tutorials/Theorist.ipynb @@ -9,7 +9,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Automated Theorist Tutorial\n", + "# Theorist Tutorial\n", "\n", "[Theorists](../theorist/index.md) are classes designed to automate the construction of interpretable models from data. AutoRA theorists are implemented as sklearn regressors and can be used with the `fit` and `predict` methods.\n", "\n",