diff --git a/docs/Variable.ipynb b/docs/Variable.ipynb new file mode 100644 index 00000000..15e0bf18 --- /dev/null +++ b/docs/Variable.ipynb @@ -0,0 +1,327 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "6f464ab4d943192c", + "metadata": {}, + "source": [ + "# `autora.variable`: `Variable` and `VariableCollection`\n", + "\n", + "`autora.variable.Variable` represents an experimental variable: \n", + "- an independent variable, or\n", + "- dependent variable.\n", + "\n", + "They can be initialized as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c2bfbd97b0a14547", + "metadata": {}, + "outputs": [], + "source": [ + "from autora.variable import Variable\n", + "\n", + "x1 = Variable(\n", + " name=\"x1\",\n", + ")\n", + "x2 = Variable(\n", + " name=\"x2\",\n", + ")\n", + "y = Variable(\n", + " name=\"y\",\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "3d195cbb145dcd58", + "metadata": {}, + "source": [ + "A group of `Variables` representing the domain of an experiment is a `autora.variable.VariableCollection`. \n", + "\n", + "They can be initialized as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8f1dce3b50b7984c", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "VariableCollection(independent_variables=[Variable(name='x1', value_range=None, allowed_values=None, units='', type=, variable_label='', rescale=1, is_covariate=False), Variable(name='x2', value_range=None, allowed_values=None, units='', type=, variable_label='', rescale=1, is_covariate=False)], dependent_variables=[Variable(name='y', value_range=None, allowed_values=None, units='', type=, variable_label='', rescale=1, is_covariate=False)], covariates=[])" + ] + }, + "execution_count": null, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from autora.variable import VariableCollection\n", + "\n", + "VariableCollection(\n", + " independent_variables=[x1, x2],\n", + " dependent_variables=[y]\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "80e85b4c6997a5fe", + "metadata": {}, + "source": [ + "For the full list of arguments, see the documentation in the `autora.variable` submodule.\n", + "\n", + "Some functions included in AutoRA use specific values stored on the Variable objects. For instance, the \n", + "`autora.experimentalist.grid.pool` uses the `allowed_values` field to create a grid of conditions:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6eb32ff49345119e", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
x1x2
0-111
1-112
2-113
3-211
4-212
5-213
6-311
7-312
8-313
\n", + "
" + ], + "text/plain": [ + " x1 x2\n", + "0 -1 11\n", + "1 -1 12\n", + "2 -1 13\n", + "3 -2 11\n", + "4 -2 12\n", + "5 -2 13\n", + "6 -3 11\n", + "7 -3 12\n", + "8 -3 13" + ] + }, + "execution_count": null, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from autora.experimentalist.grid import grid_pool\n", + "\n", + "grid_pool(\n", + " VariableCollection(independent_variables=[\n", + " Variable(name=\"x1\", allowed_values=[-1, -2, -3]),\n", + " Variable(name=\"x2\", allowed_values=[11, 12, 13])\n", + " ])\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "6f3f12554ba12ad", + "metadata": {}, + "source": [ + "The `autora.experimentalist.random.pool` uses the `value_range` field to sample conditions:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f890f05dd5c601ab", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
x1x2
00.456338101.527294
11.008636101.297280
20.319617101.962166
3-1.753273101.859696
4-1.933420101.201565
\n", + "
" + ], + "text/plain": [ + " x1 x2\n", + "0 0.456338 101.527294\n", + "1 1.008636 101.297280\n", + "2 0.319617 101.962166\n", + "3 -1.753273 101.859696\n", + "4 -1.933420 101.201565" + ] + }, + "execution_count": null, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from autora.experimentalist.random import random_pool\n", + "\n", + "random_pool(\n", + " VariableCollection(independent_variables=[\n", + " Variable(name=\"x1\", value_range=(-3, 3)),\n", + " Variable(name=\"x2\", value_range=(101, 102))\n", + " ]), \n", + " random_state=180\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "f4ab2b25903f40a7", + "metadata": {}, + "source": [ + "The `autora.state.estimator_from_state` function uses the `names` of the variables to pass the correct columns to a \n", + "scikit-learn compatible estimator for curve fitting." + ] + }, + { + "cell_type": "markdown", + "id": "3f4d28f5979fe9cb", + "metadata": {}, + "source": [ + "Check the documentation for any functions you are using to determine whether you need to include specific metadata." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 2 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython2" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}