Metadata-Version: 2.4
Name: compass_labyrinth
Version: 0.2.0
Summary: A unified computational and behavioral framework for analyzing goal-directed navigation in complex maze environments using hierarchical probabilistic models.
Author: Shreya Bangera, Patrick Honma, Luiz Tauffer
License-Expression: GPL-3.0-only
Project-URL: homepage, https://github.com/CoMPASS-Framework/CoMPASS-Labyrinth
Project-URL: repository, https://github.com/CoMPASS-Framework/CoMPASS-Labyrinth
Project-URL: documentation, https://github.com/CoMPASS-Framework/CoMPASS-Labyrinth/blob/main/README.md
Keywords: compass,navigation,behavioral-modeling,hmm,neural-analysis,eeg,decision-making
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: joblib
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: plotly
Requires-Dist: geopandas
Requires-Dist: shapely
Requires-Dist: statsmodels
Requires-Dist: xgboost
Requires-Dist: shap
Requires-Dist: hmmlearn
Requires-Dist: umap-learn
Requires-Dist: mne
Requires-Dist: pyedflib
Requires-Dist: opencv-python
Requires-Dist: openpyxl
Requires-Dist: PyYAML
Requires-Dist: movement==0.12.0
Provides-Extra: dev
Requires-Dist: jupyterlab>=4.3.5; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Provides-Extra: tests
Requires-Dist: pytest>=7.0.0; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Requires-Dist: click==8.2.1; extra == "docs"
Dynamic: license-file

# CoMPASS-Labyrinth

<p align="center">
<a href="https://codecov.io/gh/CoMPASS-Framework/CoMPASS-Labyrinth" >
 <img src="https://codecov.io/gh/CoMPASS-Framework/CoMPASS-Labyrinth/graph/badge.svg?token=J1CUXB4N0E"/>
 </a>
   <a href="https://pypi.org/project/compass-labyrinth">
    <img src="https://img.shields.io/pypi/v/compass-labyrinth?color=%231BA331&label=PyPI&logo=python&logoColor=%23F7F991%20">
  </a>
</p>

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.


<p align="center">
  <img src="media/compass_logo.png" alt="CoMPASS Logo" width="220"/>
  &nbsp;&nbsp;&nbsp;
  <img src="media/labyrinth_bout_gif.gif" alt="Labyrinth Demo" width="230"/>
  &nbsp;&nbsp;&nbsp;
  <img src="media/maze_layout.png" alt="Maze Layout" width="220"/>
</p>

<hr style="height:2px; border:none; background:linear-gradient(to right, #ccc, #333, #ccc); width:80%;">

<p align="center">
  <img src="media/compass_framework.png" alt="Framework" width="900"/>
</p>


## 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:

```bash
pip install compass-labyrinth
```

or from source for development:

```bash
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:

```bash
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

<p align="center">
  <img src="media/compass_workflow.png" alt="Workflow" width="900"/>
</p>

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](https://compass-framework.github.io/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
