Skip to content

neurospatial

Python 3.10+ License: MIT Documentation

neurospatial is a Python library for discretizing continuous N-dimensional spatial environments into bins/nodes with connectivity graphs. It provides tools for spatial analysis, particularly for neuroscience applications involving place fields, position tracking, and spatial navigation.

Whether you're analyzing animal navigation data, modeling place cells, or working with any spatial discretization problem, neurospatial gives you flexible, powerful tools to represent and analyze spatial environments.

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(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.3.0) - API may change. Contributions and feedback welcome!

Citation

If you use neurospatial in your research, please cite:

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

License

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

Contact

Eric Denovellis