cryoblob¶

cryoblob is a JAX-based, JIT-compiled, scalable package for detection of amorphous blobs in low SNR cryo-EM images. It provides both traditional circular blob detection and advanced multi-method detection for complex morphologies including elongated objects and overlapping structures.

Features¶

JAX-powered: Leverages JAX for high-performance computing with automatic differentiation
GPU acceleration: Can utilize both CPUs and GPUs for processing
Multi-method detection: Advanced detection algorithms for diverse blob morphologies:
- Traditional LoG: Excellent for circular blobs
- Ridge detection: Specialized for elongated (pill-shaped) objects
- Watershed segmentation: Separates overlapping circular structures
- Hessian-based detection: Superior boundary localization
Adaptive filtering: Includes adaptive Wiener filtering and thresholding
Batch processing: Memory-optimized batch processing for large datasets
Validation: Comprehensive parameter validation using Pydantic models

Installation¶

pip install cryoblob

Quick Start¶

Basic Blob Detection¶

import cryoblob as cb

# Load an MRC file
mrc_image = cb.load_mrc("your_file.mrc")

# Traditional circular blob detection
blobs = cb.blob_list_log(mrc_image)

# Process a folder of images
results = cb.folder_blobs("path/to/folder/")

# Plot results
cb.plot_mrc(mrc_image)

Enhanced Multi-Method Detection¶

# For complex scenarios with multiple blob types
circular, elongated, overlapping = cb.enhanced_blob_detection(
    mrc_image,
    use_ridge_detection=True,    # Detect elongated objects
    use_watershed=True           # Separate overlapping blobs
)

print(f"Found {len(circular)} circular, {len(elongated)} elongated, "
      f"and {len(overlapping)} overlapping blobs")

Specialized Detection¶

from cryoblob.valid import (create_elongated_objects_pipeline,
                           create_overlapping_blobs_pipeline,
                           create_comprehensive_pipeline)

# For elongated (pill-shaped) objects
config = create_elongated_objects_pipeline()
_, elongated_blobs, _ = cb.enhanced_blob_detection(mrc_image, **config.to_enhanced_kwargs())

# For overlapping circular structures
config = create_overlapping_blobs_pipeline()
circular, _, separated_blobs = cb.enhanced_blob_detection(mrc_image, **config.to_enhanced_kwargs())

# For comprehensive analysis (all methods)
config = create_comprehensive_pipeline()
all_results = cb.enhanced_blob_detection(mrc_image, **config.to_enhanced_kwargs())

Detection Methods¶

Blob Type	Method	Best For	Key Function
Circular	LoG	Standard round particles	`blob_list_log()`
Elongated	Ridge Detection	Pill-shaped, rod-like objects	`ridge_detection()`
Overlapping	Watershed	Touching circular structures	`watershed_segmentation()`
Mixed/Complex	Enhanced Detection	Multiple morphologies	`enhanced_blob_detection()`

Package Structure¶

The cryoblob package is organized into the following modules:

adapt: Adaptive image processing with gradient descent optimization
blobs: Core blob detection algorithms and preprocessing
files: File I/O operations and batch processing
image: Basic image processing functions (filtering, resizing, etc.)
multi: Multi-method detection for elongated objects and overlapping blobs
plots: Visualization functions for MRC images and results
types: Type definitions and PyTree structures
valid: Parameter validation using Pydantic models

Use Cases¶

Standard Cryo-EM Particles

# Traditional circular blob detection
blobs = cb.blob_list_log(mrc_image, min_blob_size=5, max_blob_size=20)

Elongated Biological Structures

# Detect pill-shaped, rod-like, or filamentous objects
_, elongated, _ = cb.enhanced_blob_detection(
    mrc_image, use_ridge_detection=True, use_watershed=False
)

Overlapping or Touching Particles

# Separate overlapping circular structures
_, _, separated = cb.enhanced_blob_detection(
    mrc_image, use_ridge_detection=False, use_watershed=True
)

Complex Heterogeneous Samples

# Comprehensive analysis for mixed morphologies
circular, elongated, overlapping = cb.enhanced_blob_detection(
    mrc_image, use_ridge_detection=True, use_watershed=True
)

Performance¶

Memory Efficient: Automatic batch size optimization and memory management
Scalable: Multi-device and multi-host processing support
Fast: JIT compilation and GPU acceleration where available
Flexible: Selective method usage to optimize speed vs. comprehensiveness

Package Organization¶

The codes are located in /src/cryoblob/
The notebooks are located in /tutorials/

Documentation¶

For detailed API documentation and tutorials, visit: https://cryoblob.readthedocs.io

License¶

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

Authors¶

Debangshu Mukherjee (mukherjeed@ornl.gov)
Alexis N. Williams (williamsan@ornl.gov)