NeuroGym

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.

6
contributors
1629 commitsLast commit ≈ 1 week ago262 stars50 forks

What NeuroGym can do for you

Status: In Development. All tasks are subject to changes right now.

NeuroGym

Badges
fairnessOpenSSF Best Practices fair-software.eu
packagePyPI version
docsDocumentation RSD DOI
testsbuild sonarcloud linkspector cffconvert linting static-typing workflow scq badge workflow scc badge
running onubuntu
licensegithub license badge

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 inherits from the machine learning toolkit Gymnasium, a maintained fork of OpenAI’s Gym library. 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.

alt tag

Installation

Create and activate a virtual environment to install the current package, e.g. using conda (please refer to their site for questions about creating the environment):

conda activate # ensures you are in the base environment
conda create -n neurogym python=3.11
conda activate neurogym

Then install neurogym as follows:

git clone https://github.com/neurogym/neurogym.git
cd neurogym
pip install -e .

Psychopy installation

If you need psychopy for your project, additionally run

pip install psychopy

Tasks

Currently implemented tasks can be found here.

Wrappers

Wrappers (see list) 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 jupyter notebook we show how to train a neural network with reinforcement learning algorithms using the Stable-Baselines3 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 provides the basic structure that we recommend a task to have:

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)

Keywords
Programming language
  • Python 100%
License
Not specified
</>Source code

Participating organisations

Netherlands eScience Center

Contributors

Dani Bodor
Backup engineer
Netherlands eScience Center
Giulia Crocioni
Giulia Crocioni
Lead Engineer
Netherlands eScience Center
MMM
Manuel Molano Mazon
Author
Universitat Politècnica de Catalunya
JM
Jorge Mejias
GRY
Guangyu Robert Yang
NC
Nathan Cloos
Development team and contributor
MIT Brain and Cognitive Sciences

Related projects

ANNUBeS

Training Artificial Neural Networks to Uncover Behavioral Strategies in neuroscience

Updated 19 months ago
In progress

Related software

ANNUBeS

AN

ANNUBeS is a deep learning framework meant to generate synthetic data and train on them neural networks aimed at developing and evaluating animals' training protocols in neuroscience.

Updated 2 weeks ago
2