neuromorphopy

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.

CLI Installation (Recommended)

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

2. 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.