A framework for analyzing spatial decision-making by integrating multimodal data into a unified topological representation.
Requirements
- Python >=3.9
1. Clone the repository
git clone https://github.com/PBLab/NaviGraph.git2. Navigate to the project directory
cd NaviGraph3. Create and activate a virtual environment
# Create a new virtual environment
python3 -m venv venv
# Activate the virtual environment
source venv/bin/activate # On macOS/Linux
venv\Scripts\activate # On Windows4. Install dependencies
pip install -r requirements.txt- Prepare your data: Pose tracking (
.h5) via DeepLabCut, calcium imaging (zarr, optional) via MiniAn. - Configure the pipeline: Customize example (
.yaml) config file (details in next section). - Run the pipeline Execute the main script:
python run.py
Note: For testing or exploring the system mode features run the pipeline as-is to try it out on included demo data.
Pipeline behavior is controlled via a YAML config file located at configs/navigraph_config.yaml.
General Paths
project_local_data_path: Root directory for all input data (pose, video, etc.)keypoint_detection_file_path: Directory containing DeepLabCut.h5filesmap_path: Maze image for spatial alignmentoutput_directory_path: Directory where outputs (calibration, analysis, plots, etc.) are saved
Running Mode
system_running_mode: Defines the pipeline mode; options includecalibrate,test,visualize, oranalyze
Calibration
calibrator_parameters: Settings for point capture and spatial alignment
Map Settings
map_settings: Setup parameters for maze segmentation and scaling (segment length, origin, grid size, pixel-to-meter ratio)
This section must be calculated for every new experiment.
Location Settings
location_settings: Specifies body part for tracking (e.g.,Nose) and likelihood threshold for filtering
Analysis Metrics
analyze.metrics: Specifies behavioral and topological metrics to compute
Graph Display
graph: Visualization options for the maze graph, including node colors, sizes, and layout
Visualization Settings
visualization: Controls frame overlays, map drawing options, video export, and visualization behavior
To get started, copy configs/navigraph_config.yaml, update relevant paths, select the desired system_running_mode, and run the pipeline with:
python run.pyIf you use NaviGraph, please cite:
Koren Iton, A., Iton, E., Michaelson, D. M., & Blinder, P. (2025). NaviGraph: A graph-based framework for multimodal analysis of spatial decision-making. bioRxiv
Contributions, issue reports, and feature requests are welcome! Please open issues or submit pull requests.
Licensed under the MIT License. See LICENSE for more details.