Skip to content

neuromorphopy

License Documentation PyPI

Neuromorphopy logo

neuromorphopy is a lightweight, standalone Python CLI tool and library for efficiently searching and downloading neuron morphologies from the NeuroMorpho.org archives.

Features

  • Efficient Downloads: Uses asynchronous I/O (httpx + asyncio) for fast, concurrent downloads.
  • Flexible Querying: Search using simple YAML or JSON configuration files.
  • Metadata Management: Automatically cleans and saves neuron metadata to CSV.
  • Smart Validation: Validates search queries against the API schema before execution.
  • Robust: Handles legacy SSL requirements of the NeuroMorpho API automatically.

Installation

neuromorphopy requires Python 3.11 or later.

The best way to install the tool for command-line use is with uv:

# Install the latest release
uv tool install neuromorphopy

# Or install the latest development version from GitHub
uv tool install git+https://github.com/kpeez/neuromorphopy.git

Development Installation

To work on the codebase or run from source:

  1. Clone the repository:
git clone https://github.com/kpeez/neuromorphopy.git
cd neuromorphopy
  1. Sync dependencies:
uv sync
# OR using just
just install

Usage

1. Create a Query File

Define your search criteria in a query.yaml (or .json) file:

filters:
  species: ["mouse", "rat"]
  brain_region: ["neocortex"]
  cell_type: ["pyramidal"]
sort:
  field: "brain_region"
  order: "ascending"

2. Run Commands

Use the neuromorpho command to explore, preview, and download.

Explore Fields: See what fields and values are available for filtering.

# List all filterable fields
neuromorpho fields

# List valid values for a specific field
neuromorpho fields species

Preview Download: Check how many neurons match your query without downloading files.

neuromorpho preview query.yaml

Download Data: Download the SWC morphology files and metadata.

# Download to default ./neurons directory
neuromorpho download query.yaml

# Download to a specific directory with higher concurrency
neuromorpho download query.yaml --output-dir ./data --concurrent 50

# Group downloaded files by species and brain region
neuromorpho download query.yaml --group-by species,brain_region

Documentation

For more detailed usage, see our documentation.