compass-labyrinth 0.1.0

A unified computational and behavioral framework for analyzing goal-directed navigation in complex maze environments using hierarchical probabilistic models.

CoMPASS-Labyrinth

CoMPASS-Labyrinth is a unified computational and behavioral framework for analyzing goal-directed navigation in complex, ethologically valid maze environments using hierarchical probabilistic models. This project integrates behavioral modeling with neural data analysis to uncover latent cognitive states and their underlying neural dynamics during complex decision-making tasks.

       

---

Key Features

1. Naturalistic Maze Framework: A Novel Labyrinth maze paradigm that elicits spontaneous, intrinsically motivated, and untrained navigation behavior in rodents, closely mimicking real-world foraging.

2. CoMPASS: A Hierarchical Probabilistic Framework integrating local movement dynamics with goal-directed cognitive states.

3. Latent State Inference: Identification of fine-grained cognitive states that underlie navigation strategies, beyond what is captured by task performance alone.

4. Neural-Behavioral Integration: Linking probabilistically inferred behavioral states with neural oscillatory signatures, reflecting how internal cognitive processes manifest in circuit-level dynamics.

5. Translational Relevance: Sensitive detection of early cognitive deficits in models of neurodegenerative disease (e.g., App-KI mice), with broader implications for human cognition, learning, and memory.

Prerequisites

• Python 3.11 or higher
• R version 4.4.0 or lower

Installation

Option A: Using Conda

1. Clone the repository

   git clone https://github.com/CoMPASS-Framework/CoMPASS-Labyrinth.git
   cd CoMPASS-Labyrinth
   

2. Create Python environment

   conda env create -f environment.yml
   conda activate compass-labyrinth
   

   This automatically installs the package with all dependencies from pyproject.toml.

3. Initialize R environment

   Rscript init_renv.R
   

   This installs all required R packages using renv. First run may take several minutes.

Option B: Using pip with pyproject.toml

1. Clone the repository

   git clone https://github.com/CoMPASS-Framework/CoMPASS-Labyrinth.git
   cd CoMPASS-Labyrinth
   

2. Create Python virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install the package with all dependencies

   pip install -e ".[dev]"  # Includes Jupyter and development tools
   # or
   pip install -e .  # Core dependencies only
   

4. Initialize R environment

   Rscript init_renv.R
   

Notes on Dependency Management

• Python packages: Managed via pyproject.toml
• R packages: Managed via renv
• When you start R in this directory, renv will automatically activate

Usage

1. See individual README.md files within src\compass-labyrinth for detailed instructions for descriptions of individual modules and code elements.

2. See tutorials for examples of running the code and instructions for usage. The tutorials have been numbered in order of usage and contain a description on the code and how to run it.

3. Tutorials included:

• 00_dlc_processing_template : Custom processing using DLC (outside of the compass-labyrinth env)
• 01_create_project : Initialization of project and concatenating post-DLC results
• 02_task_performance : Task performance metrics
• 03_simulated_agent_modeling : Simulated Agent modeling
• 04_compass_level_1 : CoMPASS Level 1 model
• 05_compass_level_1_post_analysis : CoMPASS Level 1 post analysis
• 06_compass_level_2 : CoMPASS Level 2 model

4. Test datasets present in tests/assests
5. Go through src/compass_labyrinth/compass/level_1/README.md and src/compass_labyrinth/compass/level_2/README.md for instructions on optimal model parameters. NOTE: Please test all and input all parameters to get optimal results.

Citation

If you use this framework, please cite the below manuscript:

Decoding hidden goal-directed navigational states and their neuronal representations using a novel labyrinth paradigm and probabilistic modeling framework. bioarxiv (2025)

Patrick S Honma*, Shreya C Bangera*, Reuben R Thomas, Nicholas Kaliss, Dan Xia, Jorge J Palop

doi: https://doi.org/10.1101/2025.11.13.688348