Skip to content

neurospatial

Python 3.10+ License: MIT Documentation

neurospatial is a Python library for spatial neuroscience. It helps scientists analyze how animals move through space and how neural activity represents it, with tools for environments, behavior, neural encoding and decoding, simulation, and visualization.

Our highest design priority is the scientist's experience: common analyses should be easy to discover, behave as a scientist reasonably expects, and produce scientifically correct, interpretable results. Clear assumptions, consistent interfaces, and useful error messages are part of that experience.

The long-term goal is a shared foundation for spatial neuroscience: define an environment once, save and share it, and use it for behavior, neural analysis, simulation and visualization, with methods that scientists can trust and compare. See the project vision for the goals and the design principles for how we evaluate changes toward them.

Key Features

  • Multiple Layout Engines: Choose from regular grids, hexagonal tessellations, masked regions, polygon-bounded areas, triangular meshes, and 1D linearized tracks
  • Automatic Bin Detection: Infer active bins from data samples with morphological operations (dilation, closing, hole filling)
  • Connectivity Graphs: Built-in NetworkX graphs with mandatory node/edge metadata for spatial queries
  • 1D Linearization: Transform complex 2D environments into 1D linearized coordinates for track-based analysis
  • Spatial Queries: Point-to-bin mapping, neighbor finding, shortest paths, geodesic distances
  • Region Support: Define and manage named regions of interest (ROIs) with immutable semantics
  • Environment Composition: Merge multiple environments with automatic bridge inference
  • Alignment Tools: Transform and map probability distributions between environments
  • Type-Safe Protocol Design: Layout engines implement protocols, not inheritance, for maximum flexibility

Quick Example

import numpy as np
from neurospatial import Environment

# Generate some 2D position data (e.g., from animal tracking)
position_data = np.array([
    [0.0, 0.0],
    [5.0, 5.0],
    [10.0, 10.0],
    [15.0, 5.0],
    [20.0, 0.0],
])

# Create an environment with 2 cm bins
env = Environment.from_samples(
    positions=position_data,
    bin_size=2.0,
    name="OpenField"
)

# Query the environment
print(f"Environment has {env.n_bins} bins")
print(f"Dimensions: {env.n_dims}D")

# Map a point to its bin
point = np.array([[10.5, 10.2]])
bin_idx = env.bin_at(point)
print(f"Point {point[0]} is in bin {bin_idx[0]}")

# Find neighbors
neighbors = env.neighbors(bins=bin_idx[0])
print(f"Bin {bin_idx[0]} has {len(neighbors)} neighbors")

Installation

Install neurospatial using pip:

pip install neurospatial

For development installation with documentation tools:

git clone https://github.com/edeno/neurospatial.git
cd neurospatial
uv sync --extra docs

See the Installation Guide for more details.

Documentation

Use Cases

neurospatial is designed for researchers working with spatial data in neuroscience:

  • Place Cell Analysis: Discretize environments for computing firing rate maps
  • Position Tracking: Convert continuous trajectories into spatial bins
  • Maze Experiments: Linearize complex track structures for 1D analysis
  • Spatial Navigation: Compute geodesic distances and shortest paths
  • Multi-Environment Studies: Align and compare spatial representations across sessions

Project Status

Status: Alpha (v0.8.0) - API may change. Contributions and feedback welcome!

Citation

If you use neurospatial in your research, please cite:

@software{neurospatial2026,
  author = {Denovellis, Eric},
  title = {neurospatial: Spatial environment discretization for neuroscience},
  year = {2026},
  url = {https://github.com/edeno/neurospatial},
  version = {0.8.0}
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

Eric Denovellis