{ "info": { "author": "Jaeyeong Yang", "author_email": "jaeyeong.yang1125@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Intended Audience :: Science/Research", "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3 :: Only" ], "description": "# ADOpy \n\n[![PyPI](https://img.shields.io/pypi/v/adopy.svg?color=green)](https://pypi.org/project/adopy/)\n[![Project Status: Active \u2013 The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n[![Travis CI](https://travis-ci.org/adopy/adopy.svg?branch=master)](https://travis-ci.org/adopy/adopy)\n[![CodeCov](https://codecov.io/gh/adopy/adopy/branch/master/graph/badge.svg?token=jFnJgnVV1k)](https://codecov.io/gh/adopy/adopy)\n\n**ADOpy** is a Python implementation of Adaptive Design Optimization (ADO; Myung, Cavagnaro, & Pitt, 2013), which computes optimal designs dynamically in an experiment. Its modular structure permit easy integration into existing experimentation code.\n\nADOpy supports Python 3.5 or above and relies on NumPy, SciPy, and Pandas.\n\n### Features\n\n- **Grid-based computation of optimal designs using only three classes**: `adopy.Task`, `adopy.Model`, and `adopy.Engine`.\n- **Easily customizable for your own tasks and models**\n- **Pre-implemented Task and Model classes including**:\n - Psychometric function estimation for 2AFC tasks (`adopy.tasks.psi`)\n - Delay discounting task (`adopy.tasks.ddt`)\n - Choice under risk and ambiguity task (`adopy.tasks.cra`)\n- **Example code for experiments using PsychoPy** ([link][example-code])\n\n[example-code]: https://github.com/adopy/adopy/tree/master/examples\n\n### Resources\n\n- [**Getting started**](https://adopy.org/getting-started.html)\n- [**Documentation**](https://adopy.org)\n- [**Bug reports**](https://github.com/adopy/adopy/issues)\n\n## (not so) Quick-start guide ##\n\n### Step 0. Install ADOpy on the terminal\n\n```bash\n# Install the stable version from PyPI\npip install adopy\n\n# Or install the developmental version from GitHub\ngit clone https://github.com/adopy/adopy.git\ncd adopy\ngit checkout develop\npip install .\n```\n\n### Step 1. Define a task using `adopy.Task`\n\nAssume that a user want to use ADOpy for an *arbitrary* task with two design\nvariables (`x1` and `x2`) where participants can make a binary choice on each\ntrial. Then, the task can be defined with `adopy.Task` as described below:\n\n```python\nfrom adopy import Task\n\ntask = Task(name='My New Experiment', # Name of the task (optional)\n designs = ['x1', 'x2'], # Labels of design variables\n responses = [0, 1]) # Possible responses\n```\n\n### Step 2. Define a model using `adopy.Model`\n\nTo predict partipants' choices, here we assume a logistic regression model\nthat calculates the probability to make a positive response using three model\nparameters (`b0`, `b1`, and `b2`):\n\n\n\nHow to compute the probabilty `p` should be defined as a function:\n\n```python\nimport numpy as np\n\ndef calculate_prob(x1, x2, b0, b1, b2):\n \"\"\"A function to compute the probability of a positive response.\"\"\"\n logit = b0 + x1 * b1 + x1 * b2\n p_obs = 1. / (1 + np.exp(-logit))\n return p_obs\n```\n\nUsing the information and the function, the model can be defined with\n`adopy.Model`:\n\n```python\nfrom adopy import Model\n\nmodel = Model(name='My Logistic Model', # Name of the model (optional)\n params=['b0', 'b1', 'b2'], # Labels of model parameters\n func=calculate_prob) # A probability function\n```\n\n### Step 3. Define grids for design variables and model parameters\n\nSince ADOpy uses grid search to search the design space and parameter space,\nyou must define a grid for design variables and model parameters.\nThe grid can be defined using the labels (of design variables or model\nparameters) as its key and an array of the corresponding grid points\nas its value.\n\n```python\nimport numpy as np\n\ngrid_design = {\n 'x1': np.linspace(0, 50, 100), # 100 grid points within [0, 50]\n 'x2': np.linspace(-20, 30, 100), # 100 grid points within [-20, 30]\n}\n\ngrid_param = {\n 'b0': np.linspace(-5, 5, 100), # 100 grid points within [-5, 5]\n 'b1': np.linspace(-5, 5, 100), # 100 grid points within [-5, 5]\n 'b2': np.linspace(-5, 5, 100), # 100 grid points within [-5, 5]\n}\n```\n\n### Step 4. Initialize an engine using `adopy.Engine`\n\nUsing the objects created so far, an engine should be initialized using\n`adopy.Engine`. It contains built-in functions to compute an optimal design\nusing ADO.\n\n```python\nfrom adopy import Engine\n\nengine = Engine(model=model, # a Model object\n task=task, # a Task object\n grid_design=grid_design, # a grid for design variables\n grid_param=grid_param) # a grid for model parameters\n```\n\n### Step 5. Compute a design using the engine\n\n```python\n# Compute an optimal design using ADO\ndesign = engine.get_design()\ndesign = engine.get_design('optimal')\n\n# Compute a randomly chosen design, as is typically done in non-ADO experiments\ndesign = engine.get_design('random')\n```\n\n### Step 6. Collect an observation in your experiment\n\n```python\n# Get a response from a participant using your own code\nresponse = ...\n```\n\n### Step 7. Update the engine with the observation\n\n```python\n# Update the engine with the design and the corresponding response\nengine.update(design, response)\n```\n\n### Step 8. Repeat Step 5 through Step 7 until the experiment is over\n\n```python\nNUM_TRIAL = 100 # number of trials\n\nfor trial in range(NUM_TRIAL):\n # Compute an optimal design for the current trial\n design = engine.get_design('optimal')\n\n # Get a response using the optimal design\n response = ... # Using users' own codes\n\n # Update the engine\n engine.update(design, response)\n```\n\n## Citation\nIf you use ADOpy, please cite this package along with the specific version.\nIt greatly encourages contributors to continue supporting ADOpy.\n\n> Yang, J., Ahn, W.-Y., Pitt., M. A., & Myung, J. I. (2019).\n> *ADOpy: A Python Package for Adaptive Design Optimization*.\n> Retrieved from https://adopy.org\n\n## References\n- Myung, J. I., Cavagnaro, D. R., and Pitt, M. A. (2013).\n A tutorial on adaptive design optimization.\n *Journal of Mathematical Psychology, 57*, 53\u201367.\n\n\n\n", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://adopy.org/", "keywords": "", "license": "GPL-3", "maintainer": "", "maintainer_email": "", "name": "adopy", "package_url": "https://pypi.org/project/adopy/", "platform": "", "project_url": "https://pypi.org/project/adopy/", "project_urls": { "Homepage": "https://adopy.org/" }, "release_url": "https://pypi.org/project/adopy/0.3.1/", "requires_dist": [ "numpy", "pandas", "scipy" ], "requires_python": ">=3.5", "summary": "Adaptive Design Optimization on Experimental Tasks", "version": "0.3.1" }, "last_serial": 5477548, "releases": { "0.3.1": [ { "comment_text": "", "digests": { "md5": "adf4955c81b0b4f9903b51a83e7d7420", "sha256": "61245caaa773a477402409cac29edb1e742dc783c59aa3dacf4e9c65ef17eda7" }, "downloads": -1, "filename": "adopy-0.3.1-py3-none-any.whl", "has_sig": false, "md5_digest": "adf4955c81b0b4f9903b51a83e7d7420", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.5", "size": 33572, "upload_time": "2019-07-02T17:03:15", "url": "https://files.pythonhosted.org/packages/2c/a8/fdfca3b4ede0c99006a480da2bfefe352142bafbdd72c120caf9278d9081/adopy-0.3.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "c6681852acbcc64fd36830a438327679", "sha256": "dfe4097008da1ab3291c8dc2fb78a99f1c6a23df534ca8fb9af47bfee9a57eed" }, "downloads": -1, "filename": "adopy-0.3.1.tar.gz", "has_sig": false, "md5_digest": "c6681852acbcc64fd36830a438327679", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.5", "size": 875646, "upload_time": "2019-07-02T17:03:33", "url": "https://files.pythonhosted.org/packages/e4/69/f6d0475aa62609bab8dd8fbe0844a77eb056dccc083c88fb7f4c7619a4ea/adopy-0.3.1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "adf4955c81b0b4f9903b51a83e7d7420", "sha256": "61245caaa773a477402409cac29edb1e742dc783c59aa3dacf4e9c65ef17eda7" }, "downloads": -1, "filename": "adopy-0.3.1-py3-none-any.whl", "has_sig": false, "md5_digest": "adf4955c81b0b4f9903b51a83e7d7420", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.5", "size": 33572, "upload_time": "2019-07-02T17:03:15", "url": "https://files.pythonhosted.org/packages/2c/a8/fdfca3b4ede0c99006a480da2bfefe352142bafbdd72c120caf9278d9081/adopy-0.3.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "c6681852acbcc64fd36830a438327679", "sha256": "dfe4097008da1ab3291c8dc2fb78a99f1c6a23df534ca8fb9af47bfee9a57eed" }, "downloads": -1, "filename": "adopy-0.3.1.tar.gz", "has_sig": false, "md5_digest": "c6681852acbcc64fd36830a438327679", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.5", "size": 875646, "upload_time": "2019-07-02T17:03:33", "url": "https://files.pythonhosted.org/packages/e4/69/f6d0475aa62609bab8dd8fbe0844a77eb056dccc083c88fb7f4c7619a4ea/adopy-0.3.1.tar.gz" } ] }