aind-behavior-vr-foraging 0.6.0__tar.gz

aind_behavior_vr_foraging-0.6.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: aind-behavior-vr-foraging
+Version: 0.6.0
+Summary: A library that defines AIND data schema for the Aind Behavior VR Foraging experiment.
+Author: Bruno Cruz
+Author-email: Bruno Cruz <bruno.cruz@alleninstitute.org>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Dist: aind-behavior-services>=0.12,<0.13
+Requires-Dist: pydantic-settings
+Requires-Dist: contraqctor<0.6.0 ; extra == 'data'
+Requires-Dist: aind-clabe[aind-services]>=0.8.0,<0.9.0 ; extra == 'launcher'
+Requires-Dist: aind-data-schema>=2 ; extra == 'launcher'
+Requires-Dist: aind-behavior-vr-foraging[data] ; extra == 'launcher'
+Requires-Python: >=3.11
+Project-URL: Changelog, https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging/releases
+Project-URL: Documentation, https://allenneuraldynamics.github.io/Aind.Behavior.VrForaging/
+Project-URL: Issues, https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging/issues
+Project-URL: Repository, https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging/
+Provides-Extra: data
+Provides-Extra: launcher
+Description-Content-Type: text/markdown
+
+# aind-vr-foraging
+
+![CI](https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging/actions/workflows/vr-foraging-cicd.yml/badge.svg)
+[![PyPI - Version](https://img.shields.io/pypi/v/aind-behavior-vr-foraging)](https://pypi.org/project/aind-behavior-vr-foraging/)
+[![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
+[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+
+A repository for the VR Foraging task.
+
+---
+
+## 📋 General instructions
+
+This repository follows the project structure laid out in the [Aind.Behavior.Services repository](https://github.com/AllenNeuralDynamics/Aind.Behavior.Services).
+
+---
+
+## 🔧 Prerequisites
+
+[Pre-requisites for running the project can be found here](https://allenneuraldynamics.github.io/Aind.Behavior.Services/articles/requirements.html).
+
+---
+
+## 🚀 Deployment
+
+For convenience, once third-party dependencies are installed, `Bonsai` and `python` virtual environments can be bootstrapped by running:
+
+```powershell
+./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_logic.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](https://bonsai-rx.org/docs/articles/cli.html):
+
+```powershell
+"./bonsai/bonsai.exe" "./src/main.bonsai" -p SessionPath=<path-to-session.json> -p RigPath=<path-to-rig.json> -p TaskLogicPath=<path-to-task_logic.json>
+```
+
+However, for a better experiment management user experience, it is recommended to use the provided experiment launcher below.
+
+## [> ] CLI tools
+
+The platform exposes a few CLI tools to facilitate various tasks. Tools are available via:
+
+```powershell
+uv run vr-foraging <subcommand>
+```
+
+for a list of all sub commands available:
+
+```powershell
+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 launcher script that can be used to run the VR Foraging task. This script is located at `./src/aind_behavior_vr_foraging/launcher.py`. It can be run from the command line as follows:
+
+```powershell
+uv run vr-foraging clabe
+```
+
+Additional arguments can be passed to the script as needed:
+
+```powershell
+uv run vr-foraging clabe -h
+```
+
+or via a `./local/clabe.yml` file. (An example can be found in `./Examples/clabe.yml`)
+
+In order to run the launcher script, optional dependencies should be installed via:
+
+Additional custom launcher scripts can be created and used as needed.
+
+## 🔍 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:
+
+```powershell
+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:
+
+```powershell
+uv run vr-foraging data-mapper
+```
+
+## 🔄 Regenerating schemas
+
+DSL schemas can be modified in `./src/aind_behavior_vr_foraging/rig.py` (or `(...)/task_logic`.py`).
+
+Once modified, changes to the DSL must be propagated to `json-schema` and `csharp` API. This can be done by running:
+
+```powershell
+uv run vr-foraging regenerate
+```
+
+## 📖 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`](https://github.com/AllenNeuralDynamics/aind-behavior-curriculum).
+
+Curricula are expected to be defined in `src/aind_behavior_vr_foraging/curricula/` by adding individual submodules that follow the structure of [`https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging.Curricula`](https://allenneuraldynamics.github.io/Aind.Behavior.VrForaging.Curricula/). Updates to the curriculum will therefore require, by design, explicitly updating the submodule reference via a reviewed pull request.

aind_behavior_vr_foraging-0.6.0/README.md

@@ -0,0 +1,119 @@
+# aind-vr-foraging
+
+![CI](https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging/actions/workflows/vr-foraging-cicd.yml/badge.svg)
+[![PyPI - Version](https://img.shields.io/pypi/v/aind-behavior-vr-foraging)](https://pypi.org/project/aind-behavior-vr-foraging/)
+[![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
+[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+
+A repository for the VR Foraging task.
+
+---
+
+## 📋 General instructions
+
+This repository follows the project structure laid out in the [Aind.Behavior.Services repository](https://github.com/AllenNeuralDynamics/Aind.Behavior.Services).
+
+---
+
+## 🔧 Prerequisites
+
+[Pre-requisites for running the project can be found here](https://allenneuraldynamics.github.io/Aind.Behavior.Services/articles/requirements.html).
+
+---
+
+## 🚀 Deployment
+
+For convenience, once third-party dependencies are installed, `Bonsai` and `python` virtual environments can be bootstrapped by running:
+
+```powershell
+./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_logic.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](https://bonsai-rx.org/docs/articles/cli.html):
+
+```powershell
+"./bonsai/bonsai.exe" "./src/main.bonsai" -p SessionPath=<path-to-session.json> -p RigPath=<path-to-rig.json> -p TaskLogicPath=<path-to-task_logic.json>
+```
+
+However, for a better experiment management user experience, it is recommended to use the provided experiment launcher below.
+
+## [> ] CLI tools
+
+The platform exposes a few CLI tools to facilitate various tasks. Tools are available via:
+
+```powershell
+uv run vr-foraging <subcommand>
+```
+
+for a list of all sub commands available:
+
+```powershell
+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 launcher script that can be used to run the VR Foraging task. This script is located at `./src/aind_behavior_vr_foraging/launcher.py`. It can be run from the command line as follows:
+
+```powershell
+uv run vr-foraging clabe
+```
+
+Additional arguments can be passed to the script as needed:
+
+```powershell
+uv run vr-foraging clabe -h
+```
+
+or via a `./local/clabe.yml` file. (An example can be found in `./Examples/clabe.yml`)
+
+In order to run the launcher script, optional dependencies should be installed via:
+
+Additional custom launcher scripts can be created and used as needed.
+
+## 🔍 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:
+
+```powershell
+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:
+
+```powershell
+uv run vr-foraging data-mapper
+```
+
+## 🔄 Regenerating schemas
+
+DSL schemas can be modified in `./src/aind_behavior_vr_foraging/rig.py` (or `(...)/task_logic`.py`).
+
+Once modified, changes to the DSL must be propagated to `json-schema` and `csharp` API. This can be done by running:
+
+```powershell
+uv run vr-foraging regenerate
+```
+
+## 📖 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`](https://github.com/AllenNeuralDynamics/aind-behavior-curriculum).
+
+Curricula are expected to be defined in `src/aind_behavior_vr_foraging/curricula/` by adding individual submodules that follow the structure of [`https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging.Curricula`](https://allenneuraldynamics.github.io/Aind.Behavior.VrForaging.Curricula/). Updates to the curriculum will therefore require, by design, explicitly updating the submodule reference via a reviewed pull request.

aind_behavior_vr_foraging-0.6.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["uv_build>=0.8.22"]
+build-backend = "uv_build"
+
+[project]
+name = "aind-behavior-vr-foraging"
+description = "A library that defines AIND data schema for the Aind Behavior VR Foraging experiment."
+authors = [ {name = "Bruno Cruz", email = "bruno.cruz@alleninstitute.org"}]
+license = "MIT"
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Operating System :: Microsoft :: Windows",
+]
+version = "0.6.0"
+readme = {file = "README.md", content-type = "text/markdown"}
+
+dependencies = [
+  "aind_behavior_services>=0.12, <0.13",
+  "pydantic-settings"
+]
+
+[project.urls]
+Documentation = "https://allenneuraldynamics.github.io/Aind.Behavior.VrForaging/"
+Repository = "https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging/"
+Issues = "https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging/issues"
+Changelog = "https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging/releases"
+
+[project.optional-dependencies]
+
+data = ["contraqctor<0.6.0"]
+
+launcher = [
+    "aind-clabe[aind-services] >= 0.8.0 ,<0.9.0",
+    "aind-data-schema>=2",
+    "aind_behavior_vr_foraging[data]",
+    ]
+
+[dependency-groups]
+
+dev = [
+    "aind_behavior_vr_foraging[launcher]",
+    "aind_behavior_vr_foraging[data]",
+    "ruff",
+    "codespell"
+]
+
+docs = [
+    'Sphinx',
+    'furo',
+    'sphinx-jinja',
+    'autodoc_pydantic[erdantic]',
+    'myst_parser',
+    'sphinx-jsonschema',
+    "aind_behavior_vr_foraging[data]",  # Necessary for the data contract rendering
+]
+
+[project.scripts]
+vr-foraging = "aind_behavior_vr_foraging.cli:main"
+
+[tool.ruff]
+line-length = 120
+target-version = 'py311'
+
+[tool.ruff.lint]
+extend-select = ['Q', 'RUF100', 'C90', 'I']
+extend-ignore = []
+mccabe = { max-complexity = 14 }
+pydocstyle = { convention = 'google' }
+
+[tool.codespell]
+skip = '.git,*.pdf,*.svg,./bonsai,*.bonsai,./docs/_build,uv.lock,*Generated.cs'
+ignore-words-list = 'nd'
+
+[tool.uv]
+default-groups = ['dev']
+required-version = '>=0.8.4'

aind_behavior_vr_foraging-0.6.0/src/aind_behavior_vr_foraging/__init__.py

@@ -0,0 +1,30 @@
+import re
+from importlib.metadata import PackageNotFoundError, version
+
+
+def pep440_to_semver(ver: str) -> str:
+    """
+    Convert a PEP 440 version to a SemVer-compatible string.
+
+    Examples:
+        1.2.3rc2   -> 1.2.3-rc2
+        1.2.3a1    -> 1.2.3-a1
+        1.2.3b1    -> 1.2.3-b1
+        1.2.3.dev4 -> 1.2.3-dev4
+        1.2.3.post1 -> 1.2.3+post1
+    """
+    # pre-release: a, b, rc -> -aN, -bN, -rcN
+    ver = re.sub(r"(?<=\d)(a|b|rc)(\d+)", r"-\1\2", ver)
+    # dev release: .devN -> -devN
+    ver = re.sub(r"\.dev(\d+)", r"-dev\1", ver)
+    # post release: .postN -> +postN
+    ver = re.sub(r"\.post(\d+)", r"+post\1", ver)
+    return ver
+
+
+try:
+    __version__ = version(__name__)
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__semver__ = pep440_to_semver(__version__)

aind_behavior_vr_foraging-0.6.0/src/aind_behavior_vr_foraging/cli.py

@@ -0,0 +1,48 @@
+import typing as t
+
+from pydantic import Field, RootModel
+from pydantic_settings import BaseSettings, CliApp, CliSubCommand
+
+from aind_behavior_vr_foraging import __semver__, regenerate
+from aind_behavior_vr_foraging.data_mappers import DataMapperCli
+from aind_behavior_vr_foraging.data_qc import DataQcCli
+from aind_behavior_vr_foraging.launcher import ClabeCli
+
+
+class VersionCli(RootModel):
+    root: t.Any
+
+    def cli_cmd(self) -> None:
+        print(__semver__)
+
+
+class DslRegenerateCli(RootModel):
+    root: t.Any
+
+    def cli_cmd(self) -> None:
+        regenerate.main()
+
+
+class VrForagingCli(BaseSettings, cli_prog_name="vr-foraging", cli_kebab_case=True):
+    data_mapper: CliSubCommand[DataMapperCli] = Field(description="Generate metadata for aind-data-schema.")
+    data_qc: CliSubCommand[DataQcCli] = Field(description="Run data quality checks.")
+    version: CliSubCommand[VersionCli] = Field(
+        description="Print the version of the vr-foraging package.",
+    )
+    regenerate: CliSubCommand[DslRegenerateCli] = Field(
+        description="Regenerate the vr-foraging dsl dependencies.",
+    )
+    clabe: CliSubCommand[ClabeCli] = Field(
+        description="Run the Clabe CLI.",
+    )
+
+    def cli_cmd(self):
+        return CliApp().run_subcommand(self)
+
+
+def main():
+    CliApp().run(VrForagingCli)
+
+
+if __name__ == "__main__":
+    main()

aind_behavior_vr_foraging-0.6.0/src/aind_behavior_vr_foraging/data_contract/__init__.py

@@ -0,0 +1,49 @@
+import os
+import typing as t
+from functools import partial
+from pathlib import Path
+
+import contraqctor
+import semver
+
+from aind_behavior_vr_foraging import __semver__
+
+
+def _dataset_lookup_helper(version: str) -> t.Callable[[Path], contraqctor.contract.Dataset]:
+    parsed_version = semver.Version.parse(version)
+    # Ignore release candidate suffix for version comparison
+    parsed_version = semver.Version(parsed_version.major, parsed_version.minor, parsed_version.patch)
+    if semver.Version.parse("0.4.0") <= parsed_version < semver.Version.parse("0.5.0"):
+        from .v0_4_0 import dataset as _dataset
+    elif semver.Version.parse("0.5.0") <= parsed_version < semver.Version.parse("0.6.0"):
+        from .v0_5_0 import dataset as _dataset
+    elif parsed_version >= semver.Version.parse("0.6.0"):
+        from .v0_6_0 import dataset as _dataset
+    else:
+        raise ValueError(f"Unsupported version: {version}")
+    return partial(_dataset, version=version)
+
+
+def dataset(path: os.PathLike, version: str = __semver__) -> contraqctor.contract.Dataset:
+    """
+    Loads the dataset for the Aind VR Foraging project from a specified version.
+
+    Args:
+        path (os.PathLike): The path to the dataset root directory.
+        version (str): The version of the dataset to load. By default, it uses the package version.
+
+    Returns:
+        contraqctor.contract.Dataset: The loaded dataset.
+    """
+    dataset_constructor = _dataset_lookup_helper(version)
+    return dataset_constructor(Path(path))
+
+
+def render_dataset(version: str = __semver__) -> str:
+    """Renders the dataset as a tree-like structure for visualization."""
+    from contraqctor.contract.utils import print_data_stream_tree_html
+
+    dataset_constructor = _dataset_lookup_helper(version)
+    return print_data_stream_tree_html(
+        dataset_constructor(Path("<RootPath>")), show_missing_indicator=False, show_type=True
+    )