|
| 1 | +# NEURD Reference |
| 2 | + |
| 3 | +**GitHub:** https://github.com/reimerlab/NEURD |
| 4 | +**Paper:** [Nature 2025](https://www.nature.com/articles/s41586-025-08660-5) |
| 5 | +**Stars:** 22 | **Language:** Python (Jupyter Notebook heavy) |
| 6 | +**Docs:** https://reimerlab.github.io/NEURD/ |
| 7 | + |
| 8 | +A mesh decomposition framework for **automated proofreading** and **morphological analysis** of neuronal EM reconstructions. Decomposes neuron meshes into branches/limbs, detects errors via graph-based filters, and produces corrected skeletons with compartment labels. |
| 9 | + |
| 10 | +## Core Idea |
| 11 | + |
| 12 | +Takes a segmented neuron mesh → decomposes into a hierarchical graph (soma → limbs → branches) → applies graph filters to detect merge/split errors → outputs a proofread skeleton with axon/dendrite/soma labels. |
| 13 | + |
| 14 | +Unlike voxel-based approaches (our waterz pipeline), NEURD operates on **meshes** — it processes the output of a segmentation pipeline, not raw affinities. It's a **downstream consumer** of segmentations like ours. |
| 15 | + |
| 16 | +## Architecture |
| 17 | + |
| 18 | +``` |
| 19 | +Neuron Mesh (from segmentation) |
| 20 | + → Soma extraction (mesh clustering) |
| 21 | + → Limb decomposition (connected components after soma removal) |
| 22 | + → Branch decomposition (skeleton-guided mesh splitting via CGAL) |
| 23 | + → Concept network (hierarchical graph: Neuron > Limb > Branch) |
| 24 | + → Graph filters (error detection on branch graph) |
| 25 | + → Proofreading (split/merge suggestions) |
| 26 | + → Compartment labeling (axon/dendrite/soma/AIS) |
| 27 | + → Morphological features (width, spine density, boutons, etc.) |
| 28 | +``` |
| 29 | + |
| 30 | +## Key Modules |
| 31 | + |
| 32 | +| Module | Purpose | |
| 33 | +|--------|---------| |
| 34 | +| `neuron.py` | Core `Neuron` class — hierarchical data structure (soma/limb/branch) | |
| 35 | +| `neuron_pipeline_utils.py` | Full pipeline: mesh → decomposition → proofreading → classification | |
| 36 | +| `preprocess_neuron.py` | Mesh decomposition into limbs and branches | |
| 37 | +| `error_detection.py` | Low-level error detection (double-back, width jumps, skeleton angles) | |
| 38 | +| `graph_error_detector.py` | Graph filter framework for structured error detection | |
| 39 | +| `graph_filters.py` | Specific filter implementations (upstream pair matching, degree checks) | |
| 40 | +| `proofreading_utils.py` | Split/merge suggestion generation and application | |
| 41 | +| `axon_utils.py` | Axon identification and tracing | |
| 42 | +| `apical_utils.py` | Apical dendrite detection | |
| 43 | +| `spine_utils.py` | Dendritic spine detection on mesh branches | |
| 44 | +| `synapse_utils.py` | Synapse association with branches | |
| 45 | +| `cell_type_utils.py` | Excitatory/inhibitory classification | |
| 46 | +| `gnn_cell_typing_utils.py` | GNN-based cell type classification | |
| 47 | +| `connectome_utils.py` | Connectivity matrix construction and analysis | |
| 48 | +| `proximity_utils.py` | Inter-neuron proximity detection | |
| 49 | +| `width_utils.py` | Branch width measurement from mesh | |
| 50 | +| `soma_extraction_utils.py` | Soma mesh extraction | |
| 51 | +| `soma_splitting_utils.py` | Multi-soma neuron splitting | |
| 52 | +| `vdi_default.py` | Volume Data Interface — abstract data access layer | |
| 53 | +| `vdi_microns.py` | MICrONS dataset interface | |
| 54 | +| `vdi_h01.py` | H01 (human cortex) dataset interface | |
| 55 | + |
| 56 | +## Error Detection Approach |
| 57 | + |
| 58 | +NEURD detects errors via **graph filters** on the branch decomposition graph: |
| 59 | + |
| 60 | +### Merge Error Detection |
| 61 | +- **High-degree branching**: Nodes with degree > 3 in skeleton graph → check if branches are compatible (skeleton angle, width continuity, synapse density) |
| 62 | +- **Width jump detection**: Sudden width changes along a path suggest a merge of different neurites |
| 63 | +- **Double-back detection**: Branch that reverses direction suggests it belongs to a different neuron |
| 64 | +- **Axon-on-dendrite**: Thin axonal branch attached to thick dendrite → likely false merge |
| 65 | + |
| 66 | +### Split Error Detection |
| 67 | +- Not the primary focus of NEURD — it assumes the segmentation is over-merged rather than over-split |
| 68 | +- Relies on upstream proofreading tools (e.g., PyChunkedGraph) for split correction |
| 69 | + |
| 70 | +### Filter Pipeline |
| 71 | +```python |
| 72 | +# Pseudocode from graph_error_detector.py |
| 73 | +for each high-degree node in skeleton graph: |
| 74 | + 1. Check distance from soma (skip if too close) |
| 75 | + 2. Filter short endpoints (< min_skeletal_length) |
| 76 | + 3. For each upstream-downstream pair: |
| 77 | + a. Compare skeleton angles (alignment) |
| 78 | + b. Compare widths (continuity) |
| 79 | + c. Compare synapse densities |
| 80 | + d. Score match quality |
| 81 | + 4. If best match score < threshold → flag as merge error |
| 82 | + 5. Generate split suggestion (which branches to detach) |
| 83 | +``` |
| 84 | + |
| 85 | +## Data Structure: Neuron Object |
| 86 | + |
| 87 | +``` |
| 88 | +Neuron |
| 89 | +├── soma (mesh, center, radius) |
| 90 | +├── limbs[] (one per connected component after soma removal) |
| 91 | +│ ├── branches[] (skeleton-guided mesh segments) |
| 92 | +│ │ ├── skeleton (3D coordinates) |
| 93 | +│ │ ├── mesh (trimesh object) |
| 94 | +│ │ ├── width_array (per-skeleton-node width) |
| 95 | +│ │ ├── synapses[] (associated synapses) |
| 96 | +│ │ ├── spines[] (detected spines) |
| 97 | +│ │ └── labels (axon/dendrite/etc.) |
| 98 | +│ └── concept_network (networkx graph of branch connectivity) |
| 99 | +└── neuron_graph (full skeleton graph) |
| 100 | +``` |
| 101 | + |
| 102 | +## Dependencies |
| 103 | + |
| 104 | +**Core:** numpy, scipy, networkx, trimesh, meshparty, pykdtree, pymeshfix, scikit-learn, matplotlib |
| 105 | +**Data access:** datajoint, datasci-stdlib-tools, neuron_morphology_tools |
| 106 | +**ML (optional):** torch, torch_geometric (for GNN cell typing) |
| 107 | +**Mesh processing:** CGAL (via Docker — C++ mesh segmentation/skeletonization) |
| 108 | + |
| 109 | +## Relevance to PyTC Decoding |
| 110 | + |
| 111 | +NEURD operates **downstream** of our segmentation pipeline — it takes a segmented neuron mesh and proofreads it. Key connections: |
| 112 | + |
| 113 | +### What NEURD does that we don't |
| 114 | +1. **Mesh-based error detection**: Uses 3D mesh geometry (width, angles, surface area) rather than voxel-based affinity |
| 115 | +2. **Structured decomposition**: Soma → limb → branch hierarchy enables local reasoning about errors |
| 116 | +3. **Morphology-aware proofreading**: Width continuity, synapse density, and skeleton angle are strong signals for merge detection |
| 117 | +4. **Multi-soma splitting**: Can detect and split neurons that were falsely merged at the soma level |
| 118 | + |
| 119 | +### Ideas to port to PyTC (voxel-level) |
| 120 | +1. **Width-based merge detection**: NEURD's width-jump filter could be adapted for voxel-based segments — compute skeleton width (via EDT) and flag segments with discontinuous width profiles |
| 121 | +2. **Skeleton angle matching**: For our Stage 3 (skeleton split/re-merge), NEURD's upstream-downstream angle comparison is a proven criterion |
| 122 | +3. **Graph filter framework**: The `graph_error_detector.py` pattern (parameterized filters applied to a neuron graph) could structure our branch_merge stages |
| 123 | +4. **Multi-soma detection**: Before waterz agglomeration, detect soma regions and prevent cross-soma merges (similar to zwatershed's `somaBFS`) |
| 124 | + |
| 125 | +### What we do that NEURD doesn't |
| 126 | +1. **Voxel-level affinity-based segmentation**: NEURD assumes meshes are already available |
| 127 | +2. **Training + inference pipeline**: NEURD is pure post-processing |
| 128 | +3. **Affinity-based merge evidence**: We use raw model predictions; NEURD uses geometry only |
| 129 | + |
| 130 | +## Tutorials |
| 131 | + |
| 132 | +| Tutorial | Description | |
| 133 | +|----------|-------------| |
| 134 | +| Auto Proofreading Pipeline | Full pipeline: mesh → decomposition → proofread | |
| 135 | +| Neuron Features | Hierarchical data access, feature extraction | |
| 136 | +| Proximities | Inter-neuron contact analysis | |
| 137 | +| GNN Cell Typing | Graph neural network cell classification | |
| 138 | +| VDI Override | Custom dataset integration | |
| 139 | +| Spine Detection | Dendritic spine detection on mesh branches | |
0 commit comments