# NeuroGym
| Badges | |
| :------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **fairness** | [](https://www.bestpractices.dev/projects/9839) [](https://fair-software.eu) |
| **package** | [](https://badge.fury.io/py/neurogym) |
| **docs** | [](https://neurogym.github.io/neurogym/latest/) [](https://research-software-directory.org/software/neurogym) [](https://doi.org/10.5281/zenodo.14508986) |
| **tests** | [](https://github.com/neurogym/neurogym/actions/workflows/build.yml) [](https://github.com/neurogym/neurogym/actions/workflows/sonarcloud.yml) [](https://github.com/neurogym/neurogym/actions/workflows/linkspector.yml) [](https://github.com/neurogym/neurogym/actions/workflows/cffconvert.yml) [](https://github.com/neurogym/neurogym/actions/workflows/linting.yml) [](https://github.com/neurogym/neurogym/actions/workflows/static-typing.yml) [](https://sonarcloud.io/dashboard?id=neurogym_neurogym) [](https://sonarcloud.io/dashboard?id=neurogym_neurogym) |
| **running on** | [](https://github.com/actions/runner-images?tab=readme-ov-file#available-images) |
| **license** | [](https://github.com/neurogym/neurogym?tab=Apache-2.0-1-ov-file) |
NeuroGym is a curated collection of neuroscience tasks with a common interface. The goal is to facilitate the training of neural network models on neuroscience tasks.
- [NeuroGym](#neurogym)
- [Installation](#installation)
- [Psychopy installation](#psychopy-installation)
- [Tasks](#tasks)
- [Wrappers](#wrappers)
- [Examples](#examples)
- [Custom tasks](#custom-tasks)
- [Acknowledgements](#acknowledgements)
NeuroGym inherits from the machine learning toolkit [Gymnasium](https://gymnasium.farama.org/), a maintained fork of [OpenAI’s Gym library](https://github.com/openai/gym). It allows a wide range of well established machine learning algorithms to be easily trained on behavioral paradigms relevant for the neuroscience community.
NeuroGym also incorporates several properties and functions (e.g. continuous-time and trial-based tasks) that are important for neuroscience applications. The toolkit also includes various modifier functions that allow easy configuration of new tasks.
Please see our extended project [documentation](https://neurogym.github.io/neurogym/latest/) for additional details.
### Installation
#### Step 1: Create a virtual environment
Create and activate a virtual environment to install the current package, e.g. using
[conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) (please refer to their
site for questions about creating the environment):
```bash
conda activate # ensures you are in the base environment
conda create -n neurogym python=3.11 -y
conda activate neurogym
```
#### Step 2: Install neurogym
Then install the latest version of `neurogym` as follows:
```bash
pip install neurogym
```
##### Step 2b: Install editable package
Alternatively, get the latest updates by cloning the repo and installing the editable version of neurogym, by replacing
step 2 above by:
```bash
git clone https://github.com/neurogym/neurogym.git
cd neurogym
pip install -e .
```
#### Step 3 (Optional): Psychopy installation
**NOTE**: psycohopy installation is currently not working
If you need psychopy for your project, additionally run
```bash
pip install psychopy
```
### Tasks
Currently implemented tasks can be found [here](https://neurogym.github.io/envs/index.html).
### Wrappers
Wrappers (see [list](https://github.com/gyyang/neurogym/blob/master/docs/wrappers.md))
are short scripts that allow introducing modifications the original tasks. For instance, the Random Dots Motion task can be transformed into a reaction time task by passing it through the _reaction_time_ wrapper. Alternatively, the _combine_ wrapper allows training an agent in two different tasks simultaneously.
### Examples
NeuroGym is compatible with most packages that use gymnasium.
In this [example](https://github.com/gyyang/neurogym/blob/master/examples/example_neurogym_rl.ipynb) jupyter notebook we show how to train a neural network with reinforcement learning algorithms using the [Stable-Baselines3](https://stable-baselines3.readthedocs.io/en/master/) toolbox.
### Custom tasks
Creating custom new tasks should be easy. You can contribute tasks using the regular gymnasium format. If your task has a trial/period structure, this [template](https://github.com/gyyang/neurogym/blob/master/examples/template.py) provides the basic structure that we recommend a task to have:
```python
from gymnasium import spaces
import neurogym as ngym
class YourTask(ngym.PeriodEnv):
metadata = {}
def __init__(self, dt=100, timing=None, extra_input_param=None):
super().__init__(dt=dt)
def new_trial(self, **kwargs):
"""
new_trial() is called when a trial ends to generate the next trial.
Here you have to set:
The trial periods: fixation, stimulus...
Optionally, you can set:
The ground truth: the correct answer for the created trial.
"""
def _step(self, action):
"""
_step receives an action and returns:
a new observation, obs
reward associated with the action, reward
a boolean variable indicating whether the experiment has terminated, terminated
See more at https://gymnasium.farama.org/tutorials/gymnasium_basics/handling_time_limits/#termination
a boolean variable indicating whether the experiment has been truncated, truncated
See more at https://gymnasium.farama.org/tutorials/gymnasium_basics/handling_time_limits/#truncation
a dictionary with extra information:
ground truth correct response, info['gt']
boolean indicating the end of the trial, info['new_trial']
"""
return obs, reward, terminated, truncated, {'new_trial': new_trial, 'gt': gt}
```
### Acknowledgements
For the authors of the package, please refer to the zenodo DOI at the top of the page.
Other contributors (listed in chronological order)
- [Marta Fradera](https://github.com/martafradera)
- [Jordi Pastor](https://github.com/pastorjordi)
- [Jeremy Forest](https://github.com/jeremyforest)
- [Ru-Yuan Zhang](https://github.com/ruyuanzhang)
Raw data
{
"_id": null,
"home_page": null,
"name": "neurogym",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "neuroscience, neural networks, supervised learning, reinforcement learning, synthetic data",
"author": null,
"author_email": "Giulia Crocioni <g.crocioni@esciencecenter.nl>, Dani Bodor <d.bodor@esciencecenter.nl>, Nathan Cloos <cloosnathan@gmail.com>, Alexander Hadjiivanov <a.hadjiivanov@esciencecenter.nl>, Guangyu Robert Yang <gyyang.neuro@gmail.com>, Jorge Mejias <j.f.mejias@uva.nl>, Manuel Molano Mazon <manuelmolanomazon@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2d/8a/fb640d640d0cbb1ca2efc9a61837a022dda281d100f3d357876a3cf0a128/neurogym-1.0.6.tar.gz",
"platform": null,
"description": "# NeuroGym\n\n| Badges | |\n| :------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **fairness** | [](https://www.bestpractices.dev/projects/9839) [](https://fair-software.eu) |\n| **package** | [](https://badge.fury.io/py/neurogym) |\n| **docs** | [](https://neurogym.github.io/neurogym/latest/) [](https://research-software-directory.org/software/neurogym) [](https://doi.org/10.5281/zenodo.14508986) |\n| **tests** | [](https://github.com/neurogym/neurogym/actions/workflows/build.yml) [](https://github.com/neurogym/neurogym/actions/workflows/sonarcloud.yml) [](https://github.com/neurogym/neurogym/actions/workflows/linkspector.yml) [](https://github.com/neurogym/neurogym/actions/workflows/cffconvert.yml) [](https://github.com/neurogym/neurogym/actions/workflows/linting.yml) [](https://github.com/neurogym/neurogym/actions/workflows/static-typing.yml) [](https://sonarcloud.io/dashboard?id=neurogym_neurogym) [](https://sonarcloud.io/dashboard?id=neurogym_neurogym) |\n| **running on** | [](https://github.com/actions/runner-images?tab=readme-ov-file#available-images) |\n| **license** | [](https://github.com/neurogym/neurogym?tab=Apache-2.0-1-ov-file) |\n\nNeuroGym is a curated collection of neuroscience tasks with a common interface. The goal is to facilitate the training of neural network models on neuroscience tasks.\n\n- [NeuroGym](#neurogym)\n - [Installation](#installation)\n - [Psychopy installation](#psychopy-installation)\n - [Tasks](#tasks)\n - [Wrappers](#wrappers)\n - [Examples](#examples)\n - [Custom tasks](#custom-tasks)\n - [Acknowledgements](#acknowledgements)\n\nNeuroGym inherits from the machine learning toolkit [Gymnasium](https://gymnasium.farama.org/), a maintained fork of [OpenAI\u2019s Gym library](https://github.com/openai/gym). It allows a wide range of well established machine learning algorithms to be easily trained on behavioral paradigms relevant for the neuroscience community.\nNeuroGym also incorporates several properties and functions (e.g. continuous-time and trial-based tasks) that are important for neuroscience applications. The toolkit also includes various modifier functions that allow easy configuration of new tasks.\n\nPlease see our extended project [documentation](https://neurogym.github.io/neurogym/latest/) for additional details.\n\n\n\n### Installation\n\n#### Step 1: Create a virtual environment\n\nCreate and activate a virtual environment to install the current package, e.g. using\n[conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) (please refer to their\nsite for questions about creating the environment):\n\n```bash\nconda activate # ensures you are in the base environment\nconda create -n neurogym python=3.11 -y\nconda activate neurogym\n```\n\n#### Step 2: Install neurogym\n\nThen install the latest version of `neurogym` as follows:\n\n```bash\npip install neurogym\n```\n\n##### Step 2b: Install editable package\n\nAlternatively, get the latest updates by cloning the repo and installing the editable version of neurogym, by replacing\nstep 2 above by:\n\n```bash\ngit clone https://github.com/neurogym/neurogym.git\ncd neurogym\npip install -e .\n```\n\n#### Step 3 (Optional): Psychopy installation\n\n**NOTE**: psycohopy installation is currently not working\n\nIf you need psychopy for your project, additionally run\n\n```bash\npip install psychopy\n```\n\n### Tasks\n\nCurrently implemented tasks can be found [here](https://neurogym.github.io/envs/index.html).\n\n### Wrappers\n\nWrappers (see [list](https://github.com/gyyang/neurogym/blob/master/docs/wrappers.md))\nare short scripts that allow introducing modifications the original tasks. For instance, the Random Dots Motion task can be transformed into a reaction time task by passing it through the _reaction_time_ wrapper. Alternatively, the _combine_ wrapper allows training an agent in two different tasks simultaneously.\n\n### Examples\n\nNeuroGym is compatible with most packages that use gymnasium.\nIn this [example](https://github.com/gyyang/neurogym/blob/master/examples/example_neurogym_rl.ipynb) jupyter notebook we show how to train a neural network with reinforcement learning algorithms using the [Stable-Baselines3](https://stable-baselines3.readthedocs.io/en/master/) toolbox.\n\n### Custom tasks\n\nCreating custom new tasks should be easy. You can contribute tasks using the regular gymnasium format. If your task has a trial/period structure, this [template](https://github.com/gyyang/neurogym/blob/master/examples/template.py) provides the basic structure that we recommend a task to have:\n\n```python\nfrom gymnasium import spaces\nimport neurogym as ngym\n\nclass YourTask(ngym.PeriodEnv):\n metadata = {}\n\n def __init__(self, dt=100, timing=None, extra_input_param=None):\n super().__init__(dt=dt)\n\n\n def new_trial(self, **kwargs):\n \"\"\"\n new_trial() is called when a trial ends to generate the next trial.\n Here you have to set:\n The trial periods: fixation, stimulus...\n Optionally, you can set:\n The ground truth: the correct answer for the created trial.\n \"\"\"\n\n def _step(self, action):\n \"\"\"\n _step receives an action and returns:\n a new observation, obs\n reward associated with the action, reward\n a boolean variable indicating whether the experiment has terminated, terminated\n See more at https://gymnasium.farama.org/tutorials/gymnasium_basics/handling_time_limits/#termination\n a boolean variable indicating whether the experiment has been truncated, truncated\n See more at https://gymnasium.farama.org/tutorials/gymnasium_basics/handling_time_limits/#truncation\n a dictionary with extra information:\n ground truth correct response, info['gt']\n boolean indicating the end of the trial, info['new_trial']\n \"\"\"\n\n return obs, reward, terminated, truncated, {'new_trial': new_trial, 'gt': gt}\n\n```\n\n### Acknowledgements\n\nFor the authors of the package, please refer to the zenodo DOI at the top of the page.\n\nOther contributors (listed in chronological order)\n\n- [Marta Fradera](https://github.com/martafradera)\n- [Jordi Pastor](https://github.com/pastorjordi)\n- [Jeremy Forest](https://github.com/jeremyforest)\n- [Ru-Yuan Zhang](https://github.com/ruyuanzhang)\n",
"bugtrack_url": null,
"license": "Apache-2.0 License",
"summary": "NeuroGym: Gymnasium-style Cognitive Neuroscience Tasks",
"version": "1.0.6",
"project_urls": {
"Changelog": "https://github.com/neurogym/neurogym/CHANGELOG.md",
"Documentation": "https://neurogym.github.io/neurogym",
"Issues": "https://github.com/neurogym/neurogym",
"Repository": "https://github.com/neurogym/neurogym"
},
"split_keywords": [
"neuroscience",
" neural networks",
" supervised learning",
" reinforcement learning",
" synthetic data"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "692820caa71f8da795101c1e1f491063cb87ae8d9da85ec178a8e51bd96a99bf",
"md5": "0526b20e52ae076ad2ec2647b0fa49a6",
"sha256": "6577ea1c1688dfa17bf95655e5f7f544664f64df67536f32882361fed2d06980"
},
"downloads": -1,
"filename": "neurogym-1.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0526b20e52ae076ad2ec2647b0fa49a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 115893,
"upload_time": "2025-01-22T10:06:38",
"upload_time_iso_8601": "2025-01-22T10:06:38.455973Z",
"url": "https://files.pythonhosted.org/packages/69/28/20caa71f8da795101c1e1f491063cb87ae8d9da85ec178a8e51bd96a99bf/neurogym-1.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2d8afb640d640d0cbb1ca2efc9a61837a022dda281d100f3d357876a3cf0a128",
"md5": "8002a6a29ca2b48b9137b3e4c3a4f459",
"sha256": "2d803f98b20398f50f8660a9b39fdb277124f287abab54a1253164fba38610f6"
},
"downloads": -1,
"filename": "neurogym-1.0.6.tar.gz",
"has_sig": false,
"md5_digest": "8002a6a29ca2b48b9137b3e4c3a4f459",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 2141467,
"upload_time": "2025-01-22T10:06:40",
"upload_time_iso_8601": "2025-01-22T10:06:40.849837Z",
"url": "https://files.pythonhosted.org/packages/2d/8a/fb640d640d0cbb1ca2efc9a61837a022dda281d100f3d357876a3cf0a128/neurogym-1.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-22 10:06:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "neurogym",
"github_project": "neurogym",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "neurogym"
}
JSON
