Repository for visualizing and analyzing neuron meshes using fafbseg, navis, and related libraries. This package provides both a Python API and a command-line tool for rendering FlyWire neurons on brain templates.
conda create -n plot-neurons python=3.12
conda activate plot-neurons
git clone https://github.com/Nely-EPFL/plot-neurons.git
cd plot-neurons
pip install .For development with additional tools (linting, formatting, type checking):
pip install -e ".[dev]"For the fafb dataset, you need to get an API token from https://global.daf-apis.com/auth/api/v1/create_token and save it on your local machine.
You can save your API token to a local file, which is more secure than hardcoding it in scripts:
- Get your token from the link above
- Manually create a file at
~/.cloudvolume/secrets/global.daf-apis.com-cave-secret.json - Add your token to the file:
{
"token": "your_actual_token_here"
}This method ensures your token is stored securely and doesn't appear in your code.
Alternatively, you can set the token using Python (less secure as it may appear in your code):
from fafbseg import flywire
# replace with your actual token
flywire.set_chunkedgraph_secret("your_actual_token_here")The detailed instructions can be found at https://fafbseg-py.readthedocs.io/en/latest/source/tutorials/flywire_setup.html
Simple example to plot a neuron mesh from the flywire dataset:
import flybrains
import matplotlib.pyplot as plt
import navis
from fafbseg import flywire
from fafbseg.flywire import NeuronCriteria as NC
flywire.set_default_dataset("public")
meshes = flywire.get_mesh_neuron(
NC(type="MBON22"), # alternatively, use list of ids (e.g., [720575940616463477, 720575940635063135])
dataset="flat_783",
lod=3
)
meshes = navis.downsample_neuron(meshes, 20)
kwargs = {
"method": "2d",
"view": ('x', '-y'),
"rasterize": True, # change to False for vector graphics
}
fig, ax = navis.plot2d(flybrains.FLYWIRE, color=(0.7, 0.7, 0.7, 0.05), **kwargs)
navis.plot2d(meshes, color="red", ax=ax, **kwargs)
ax.axis("off")
ax.grid(False)
plt.savefig("mbon22.pdf", bbox_inches="tight", pad_inches=0, dpi=300)
The package includes several command-line tools for different tasks:
plot-neurons --neurons neurons.yamlAlternatively, you can run the script directly:
python -m plot_neurons.flywire_renderer --neurons neurons.yamlFor processing multiple YAML files with different colors (configurable for any project):
batch-yaml-render --yaml_dir /path/to/yaml/filesThis tool automatically processes all YAML files in a directory, using a configurable color registry that can be adapted for different projects.
After installation, these tools are available as console commands:
oir-to-tiff- Convert .oir files to TIFFoib-to-tiff- Convert .oib files to TIFFZstack-renderer- Create Z-stack visualizationsconfocal-imaging-pipeline- Complete automated pipeline for folder processing
See the Confocal Imaging Tools section below for detailed usage.
# Single neuron group with custom styling
plot-neurons --neurons "1234,5678,9012" --color blue --formats png,svg
# Batch YAML rendering with custom output settings
batch-yaml-render --yaml_dir ./neuron_lists/ballpushing_screen --output_dir ./renders --formats png,svg --dpi 600
# High-resolution single group rendering
plot-neurons --neurons neurons.yaml --out_prefix my_neurons --dpi 600plot-neurons:
--neurons(required): YAML file with neuron IDs or comma-separated list of IDs--color(default: "red"): Color for neuron traces--formats(default: "png"): Comma-separated list of output formats (png, svg, pdf)--out_prefix(default: "flywire_neurons"): Prefix for output files--dpi(default: 300): Resolution for output images
batch-yaml-render:
--yaml_dir(required): Directory containing YAML files with neuron IDs--output_dir(default: "."): Directory to save output files--formats(default: "png"): Comma-separated list of output formats--dpi(default: 300): Resolution for output images--list-regions: List available categories/regions with their default colors--out_prefix(default: "flywire_neurons"): Prefix for output files--dpi(default: 300): Resolution for output images
The command-line tool accepts neuron IDs in various formats:
YAML file with simple list:
- 720575940625237891
- 720575940625237892
- 720575940625237893YAML file with dictionary:
neuron_1: 720575940625237891
neuron_2: 720575940625237892
neuron_3: 720575940625237893Comma-separated list:
plot-neurons --neurons "720575940625237891,720575940625237892,720575940625237893"The batch-yaml-render tool uses a configurable color registry that can be adapted for different projects. The current default colors are optimized for brain regions:
| Region | Color | Hex Code |
|---|---|---|
| MB | Blue | #1f77b4 |
| Vision | Orange | #ff7f0e |
| LH | Green | #2ca02c |
| Neuropeptide | Red | #d62728 |
| Olfaction | Purple | #9467bd |
| MB extrinsic neurons | Brown | #8c564b |
| CX | Pink | #e377c2 |
| Others | Gray | #7f7f7f |
To see the current color registry, use:
batch-yaml-render --list-regionsNote: This color registry can be easily modified in the script for different projects by editing the get_default_color_registry() function.
# Basic single neuron group rendering
plot-neurons --neurons my_neurons.yaml
# Process all YAML files in a directory with batch rendering
batch-yaml-render --yaml_dir ./neuron_lists/ballpushing_screen
# Batch rendering with custom output settings
batch-yaml-render --yaml_dir ./neuron_lists/ballpushing_screen --output_dir ./renders --formats png,svg
# Custom styling for single group
plot-neurons --neurons "1234,5678" --color "#FF5733" --formats png,svg,pdf
# High-resolution output
plot-neurons --neurons neurons.yaml --dpi 600 --out_prefix high_res_neurons
# List available categories and their colors
batch-yaml-render --list-regions- Python API: Direct integration with your Python scripts
- Command-line tools:
plot-neurons: Single neuron group renderingbatch-yaml-render: Batch processing multiple YAML files with configurable colors
- Multiple input formats: YAML files or comma-separated neuron IDs
- Flexible output: PNG, SVG, PDF formats with configurable resolution
- Brain region color coding: Predefined colors for different brain regions
- Robust error handling: Clear error messages and validation
- Configurable rendering: Custom colors, transparency, and view angles
- Batch processing: Process entire directories of YAML files automatically
- Project adaptability: Color registry can be easily modified for different projects
- File conversion: Convert .oir and .oib files to TIFF using Bio-Formats
- Z-stack visualization: Create publication-quality maximum intensity projections and montages
- Automated pipeline: Process entire folders with one command
- Color-coded rendering: Proper GFP (green) and nc82 (magenta) channel mapping
- Batch processing: Handle multiple files automatically with organized output
- Headless operation: Suitable for batch scripts and CI environments
- Customizable rendering: Adjustable contrast, gamma, brightness, and grid layouts
- Progress tracking: Detailed logging and summary reports
- Import Errors: Ensure all dependencies are installed correctly
- API Token Issues:
- Make sure your FlyWire API token is properly configured
- Check that the token file exists at
~/.cloudvolume/secrets/global.daf-apis.com-cave-secret.json - Verify the JSON format is correct (no trailing commas, proper quotes)
- Ensure your token is still valid (regenerate if necessary)
- Network Issues: Check internet connection for FlyWire data fetching
- Invalid Neuron IDs: Verify neuron IDs are valid FlyWire identifiers
- Memory Issues: For large numbers of neurons, consider processing in smaller batches
- Bio-Formats Issues:
- Tools automatically download bftools if not found - ensure internet connectivity
- Check
~/.bftoolsdirectory if you encounter persistent download issues - Use
--diagnoseflag to check bfconvert availability
- File Format Issues:
- Ensure input files are valid .oir/.oib format
- Check file permissions and disk space for output
- TIFF Processing Issues:
- Verify TIFF files have proper Z-stack structure
- Check that channel information is correctly embedded
- For custom TIFF files, ensure they follow expected dimension ordering
- Memory Issues: Large TIFF files may require significant RAM - consider processing smaller files or upgrading system memory
- Pipeline Issues:
- Check folder permissions for both input and output directories
- Ensure sufficient disk space for converted files and renderings
- Use
--skip-conversionor--skip-renderingto isolate issues
- Check the examples directory for working code
- Review the fafbseg documentation for API details
- For confocal tools, test individual conversion/rendering steps before using the full pipeline
- Ensure you have the latest version:
pip install --upgrade plot-neurons
This repository includes comprehensive tools for converting and processing confocal microscopy images:
Convert Olympus microscopy files to TIFF format using Bio-Formats:
oir-to-tiff path/to/input.oir [path/to/output.tiff]oib-to-tiff path/to/input.oib [path/to/output.tiff]Both tools support the same options:
--tmp-dir: temporary directory for downloads/extraction (defaults to$TMPDIRor system temp)--bftools-url: custom URL to download bftools zip--bftools-cache: directory to cache downloaded bftools (default~/.bftools)--diagnose: show basic bfconvert discovery info and exit
Create publication-quality Z-stack visualizations:
Zstack-renderer input_file.tiff [options]Options:
--output-dir: output directory (default: same as input file)--step 3: step size between Z-slices for montage--cols 6: number of columns in montage grid--gamma 1.2: gamma correction for contrast--brightness 1.3: brightness multiplier--min-percentile 1: lower percentile for contrast stretching--max-percentile 99: upper percentile for contrast stretching--mip-only: create only maximum intensity projection--montage-only: create only Z-stack montage
The tool creates:
- Maximum Intensity Projection (MIP): Collapsed Z-stack showing maximum intensity
- Z-Stack Montage: Grid of individual Z-slices
- Proper color mapping: GFP=green, nc82=magenta
Process entire folders of microscopy files automatically:
confocal-imaging-pipeline /path/to/image/folder [options]What it does:
- Scans folder for
.oir,.oib, and.tifffiles - Converts
.oir/.oibfiles to TIFF using Bio-Formats - Creates Z-stack renderings for all TIFF files
- Organizes outputs in dedicated subdirectories
Pipeline Options:
--step 3: Z-slice step size for montages--cols 6: montage grid columns--gamma 1.0: gamma correction--brightness 1.0: brightness multiplier--min-percentile 0: contrast lower percentile--max-percentile 100: contrast upper percentile--skip-conversion: only render existing TIFF files--skip-rendering: only convert files
Example workflows:
# Process all files in a folder
confocal-imaging-pipeline /path/to/images/
# Custom rendering settings
confocal-imaging-pipeline /path/to/images/ --step 5 --cols 6 --gamma 1.2
# Only convert files (skip rendering)
confocal-imaging-pipeline /path/to/images/ --skip-rendering
# Only render existing TIFF files
confocal-imaging-pipeline /path/to/images/ --skip-conversionPipeline Features:
- Automatic file detection: Finds .oir, .oib, and .tiff files
- Organized output: Each file gets its own subdirectory (e.g.,
filename_rendered/) - Progress tracking: Detailed logging of conversion and rendering progress
- Error handling: Continues processing other files if one fails
- Summary reports: Shows success/failure status for all operations
All tools support these environment variables:
TMPDIR: overrides temp dirBFTTOOLS_URL: overrides default bftools URLBFTOOLS_DIR: overrides default cache dir
- All conversion tools automatically download Bio-Formats bftools if not found on PATH
- Tools are designed for headless operation in batch scripts and CI environments
- Z-stack renderer handles various TIFF formats and automatically detects dimensions
- Pipeline creates reproducible, organized outputs suitable for publication