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

Installation

You can install CoMPASS-Labyrinth directly with pip:

pip install compass-labyrinth

or from source for development:

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

# Core dependencies only
pip install -e .

# Or with development tools
pip install -e ".[dev]"

# Or with documentation tools
pip install -e ".[docs]"

# Or install all optional dependencies
pip install -e ".[dev,tests,docs]"

You can also use Conda to manage your environment:

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

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.

Documentation

Documentation and package details can be found here: CoMPASS-Labyrinth

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