Skip to content

aind-vr-foraging#

CI PyPI - Version License ruff uv

A repository for the VR Foraging task.

📋 General instructions#

This repository follows the project structure laid out in the Aind.Behavior.Services repository.

🔧 Prerequisites#

Pre-requisites for running the project can be found here.

🚀 Deployment#

For convenience, once third-party dependencies are installed, Bonsai and python virtual environments can be bootstrapped by running:

./scripts/deploy.ps1

from the root of the repository.

⚙️ Generating settings files#

The VR Foraging tasks is instantiated by a set of three settings files that strictly follow a DSL schema. These files are:

  • task.json
  • rig.json
  • session.json

Examples on how to generate these files can be found in the ./Examples directory of the repository. Once generated, these are the the only required inputs to run the Bonsai workflow in ./src/main.bonsai.

The workflow can thus be executed using the Bonsai CLI:

"./.bonsai/bonsai.exe" "./src/main.bonsai" -p SessionPath=<path-to-session.json> -p RigPath=<path-to-rig.json> -p TaskPath=<path-to-task.json>

However, for a better experiment management user experience, it is recommended to use the provided experiment launcher below.

🔄 Regenerating schemas#

To regenerate all schemas (task logic, rig, and curricula), run the following from the repository root:

uv run scripts/regenerate.py

This runs both vr-foraging regenerate and the curricula schema generation in sequence.

🧪 Tests#

This repository includes both Python and .NET tests.

Run Python tests:

uv run pytest

Run .NET extension tests:

dotnet test ./tests/Extensions.Tests/Extensions.Tests.csproj

The .NET test project references ./src/Extensions.csproj directly and targets net480.

[> ] CLI tools#

The platform exposes a few CLI tools to facilitate various tasks. Tools are available via:

uv run vr-foraging <subcommand>

for a list of all sub commands available:

uv run vr-foraging -h

You may need to install optional dependencies depending on the sub-commands you run.

🎮 Experiment launcher (CLABE)#

To manage experiments and input files, this repository contains a collection of launcher scripts that can be used to run the VR Foraging task. These are located inside ./scripts and can be run using the clabe tool:

uv run clabe run `./scripts/<script-name>.py`

Additional arguments can be passed to the script as needed:

uv run clabe -h

or via a ./local/clabe.yml file. (An example can be found in ./Examples/clabe.yml)

🔍 Primary data quality-control#

Once an experiment is collected, the primary data quality-control script can be run to check the data for issues. This script can be launcher using:

uv run vr-foraging data-qc <path-to-data-dir>

🌉 Mapping to aind-data-schema#

Once an experiment is collected, data can be mapped to aind-data-schema using the data-mapper sub-command:

uv run vr-foraging data-mapper

📖 Curricula#

The VrForaging platform supports a curricula structure that allows for the organization and management of different learning paths and experiences. The implementation relies on the a common definition of "curriculum" progression provided by aind-behavior-curriculum.

Curricula are expected to be defined in aind_behavior_vr_foraging_curricula package.