Hex-maze

This repository provides a library of functions and tutorials for generating, visualizing, and analyzing hex maze configurations and optimal barrier-change sequences for the hex maze behavioral task developed by the Berke Lab at UCSF. It also includes curated databases of valid maze configurations and their associated attributes.

Installation (General use)

To simply use the functions in this repo, install the latest version of this Python package with the following command:

pip install hex-maze-neuro

Then import and use functions from the package in your Python script or Jupyter notebook:

from hexmaze import plot_hex_maze, get_hex_distance, get_optimal_paths

# Define an example maze
maze = {37, 7, 39, 41, 14, 46, 20, 23, 30}

# Set the rat's position
rat_hex = 16
rat_facing = 13

# Calculate optimal path from port 3 to the rat, with distances for each hex
rat_hex_path = get_optimal_paths(maze, start_hex=3, target_hex=rat_hex)[0]
rat_hex_path_distances = {h: get_hex_distance(maze, start_hex=rat_hex, target_hex=h) for h in rat_hex_path}

# Plot the maze with the rat's path colored by distance
plot_hex_maze(maze, show_barriers=False, show_hex_labels=False, rat=rat_hex, rat_to=rat_facing, 
              color_by=rat_hex_path_distances, colormap="Blues", vmin=-15)

# This generates the hex-maze-neuro logo plot!

Note that installing the package via pip does not make the tutorial notebooks or hex maze databases in this repo available. Follow the developer instructions to install from source to access the tutorials and databases.

Installation from source (Developer instructions)

Step 1. Fork and clone the repository

To contribute to this project, you first need to fork the repository to your own GitHub account. This creates a copy of the project where you can make changes. Do this by clicking the "Fork" button at the top-right corner of the repository page and following the instructions.

Once you have forked the repository, you need to clone it to your local machine to start working on it.

1. Open a terminal or command prompt.

2. Clone your forked repository using the following command (replacing {your-github-username} with your username):

   git clone https://github.com/{your-github-username}/Hex-maze.git
   

3. Navigate to the newly created Hex-maze directory.

   cd Hex-maze
   

Step 2. Install dependencies

1. First, make sure you are in the repo inside a terminal or command prompt (Step 3 above).

2. To install all necessary dependencies for this project, run the following command:

   pip install -r requirements.txt
   

Step 3. Start the tutorials

Navigate to the Tutorials/ folder and begin with the Getting_Started.ipynb notebook.

Tutorials/ also includes the following tutorial notebooks:

• Demos of useful hex maze functions
• Plotting hex mazes and barrier change sequences
• Comparing optimal paths between mazes for barrier shift sessions
• Searching the maze configuration database for the mazes you want
• Searching the barrier sequence database for the sequence you want
• Generating barrier sequences with custom criteria
• Modeling port values based on choices and reward outcomes

These 3 are also provided for reference:

• How the hex maze database was generated
• How the training maze database was generated
• How the probability change database was generated

Step 4: Explore and use the databases!

This repo provides the following databases of valid maze configurations and barrier change sequences for the hex maze task:

Hex Maze Databases

Database of hex maze configurations

Maze_Databases/maze_configuration_database contains 55,896 possible hex maze configurations with the following attributes:

• 9 barriers
• no unreachable hexes
• path lengths between reward ports are between 15-25 hexes
• all critical choice points are >=6 hexes away from a reward port
• there are a maximum of 3 critical choice points
• there are no straight paths >6 hexes to a reward port (including port hex)
• there are no straight paths >6 hexes in the middle of the maze

This database also provides information about each maze configuration:

• length of the optimal path(s) between each pair of reward ports
• lists of hexes defining the optimal path(s) between those reward ports
• number of choice points, and which hexes are choice points
• number of cycles (where the rat can start and end at the same hex without turning around) and lists of hexes defining those cycles
• a set of other mazes isomorphic to this maze (representing reflections and rotations of the maze)

This database is provided in both csv (.csv) and pickle (.pkl) format - csv is better to explore in excel, but pickle is preferable for loading and working with in jupyter notebooks (csv tends to load everything as a string).

This database was generated using the Generate_Hex_Maze_Database.ipynb notebook available in the Tutorials/ folder.

Database of mazes for barrier change experiments

The Barrier_Sequence_Databases/ folder contains multiple databases of barrier sequences (consecutive maze configurations that differ by the movement of a single barrier).

• barrier_sequence_database contains 3126 barrier sequences that are 4-6 mazes long, and is a good place to start.
• single_choice_point contains 3720 barrier sequences >= 3 mazes long where all mazes in the sequence have a single choice point.

The Barrier_Sequence_Database_Search.ipynb notebook in the Tutorials/ folder has more information about the other available databases, and how to search these databases for a barrier sequence that fits your criteria.

Custom databases can be generated using the Generate_Custom_Barrier_Sequence_Database.ipynb notebook available in the Tutorials/ folder.

Database of mazes for probability change experiments

Maze_Databases/probability_change_mazes contains a database of mazes good for probability change experiments. These mazes are grouped such that all mazes in a group differ by at least 10 hexes on optimal paths.

This database was generated using the Generate_Probability_Change_Database.ipynb notebook available in the Tutorials/ folder.

Database of mazes for early stages of training

Maze_Databases/training_maze_database contains a database of mazes good for training. There are 5-6 barriers and all paths are the same length (either 15 or 17 hexes).

This database was generated using the Generate_Training_Maze_Database.ipynb notebook available in the Tutorials/ folder.

Reinforcement Learning Models

src/hexmaze/rl provides reinforcement learning agents for modeling port and hex values in the hex maze task. See the rl README for full documentation.

Port value learning (outcome-based)

Learns expected reward values for each port from binary reward sequences.

• RescorlaWagner — Q-learning
• BayesianPortLearner — Beta-binomial conjugate model with credible intervals
• HiddenStatePortLearner — Bayesian belief over permutations of known reward probabilities

All port learners support maximum-likelihood fitting (.fit_rewards() and .fit_choices()), BIC model comparison, and trial-by-trial history. See the port learning README for detailed docs.

Hex value learning (trajectory-based)

Learns values over individual hexes from maze trajectories.

• HexMazeTDLearner — TD(0) + TD(1) value learning, maintains V(hex) per starting port
• HexMazeQLearner — Q-learning, learns Q(hex, action) to capture directional preferences

Both support learning from rat trajectories, self-generated simulation, configurable priors, and mid-session barrier changes. Learned values can be visualized as heatmaps on the maze with plot_hex_maze(color_by=...).

Other info

Hex maze functions

src/hexmaze provides all of the functions for hex maze related tasks, organized into core (most analysis functions), barrier_shift (maze comparisons and barrier sequence generation), utils (helpers for transforming maze representations), and plotting (all things plotting and hex centroids).

If you'd like any extra functionality, let me know (or feel free to add it and submit a PR)!

A tutorial for the most useful functions can be found at Tutorials/Hex_Maze_Functions.ipynb. For functions without tutorials, you can view the documentation running help(function_name).

License & Citation

This software is licensed under the MIT License. See LICENSE.

If you use Hex-maze-neuro in your research, please cite it as:

Crater, Stephanie (2026). Hex-maze-neuro: A Python toolkit for hex maze generation, visualization, and analysis. Zenodo. https://doi.org/10.5281/zenodo.17635391

@software{crater_hexmazeneuro_2026,
  author       = {Crater, Stephanie},
  title        = {Hex-maze-neuro: A Python toolkit for hex maze generation, visualization, and analysis},
  version      = {1.1.8},
  year         = {2026},
  month        = october,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.17635391},
  url          = {https://doi.org/10.5281/zenodo.17635391}
}