🚀 UNRAVEL Release: MapMySections + Expanded ABC Atlas Support

This release delivers a major upgrade to UNRAVEL, focused on full support for the Allen Institute MapMySections Challenge, along with broader improvements to Allen Brain Cell Atlas (ABCA) integration, documentation, CLI tools, and internal module organization.

🧭 New Documentation

📘 MapMySections Analysis Guide

• End-to-end guide for:
  • Downloading and organizing Genetic Tools Atlas (GTA) data
  • Segmenting STPT brains with pretrained Ilastik models
  • Registering brains to CCFv3 and warping to MERFISH space
  • Filtering MERFISH cells using segmentations
  • Visualizing and quantifying cell types across brains and regions
• Includes flowcharts, best practices, and detailed CLI usage

🛠️ Major Features and Tools

🧪 MapMySections CLI Tools (new)

• mms_seg_summary: quantify voxel counts per segmentation label
• mms_soma_ratio: estimate oligodendrocyte enrichment in anterior commissure
• mms_cell_type_proportions, mms_cell_type_proportions_concat: whole-brain or region-specific cell type proportion summaries
• seg_ilastik: wrapper for running Ilastik segmentation in batch mode

🧬 ABCA / MERFISH Integration Enhancements

• abca_merfish_filter: neuron-only filtering, region-based extraction
• abca_sunburst, abca_sunburst_expression: hierarchical and gene expression sunburst plots
• abca_mean_expression_color_scale, abca_percent_expression_color_scale: expression-based LUTs
• abca_merfish_join_gene: map gene expression across filtered cells
• RNAseq_join_expression_data: join gene expression with scRNA-seq metadata
• Human/Mice support handled via --species flag across tools

🗜️ Zarr Image Utilities (GTA)

• gta_download: download GTA Zarr images at specific resolution levels
• gta_auto_crop, gta_bbox_crop: automated 3D bounding box cropping
• gta_org_samples: organize TIFF directories into sample folders
• zarr_compress: recursive compression/decompression of .zarr to .zarr.tar.gz

🔀 Registration + Warping Tools

• warp_to_atlas: warp segmentations to CCFv3 atlas space
• warp_ccf30_to_merfish: convert 30 µm segmentations to MERFISH space
• reg_prep, reg, reg_check: preprocessing and registration with template
• affine_initializer_check: detect initial alignment issues during registration
• mirror, img_math: image mirroring and math utilities

🧩 Tabular + Utility Tools

• print_columns, print_unique_values: explore CSV column contents
• edit_columns: rename or reorder CSV columns
• filter_data_by_column: flexible row filtering with include/exclude modes
• csv_concat_with_source: add source_file column when combining CSVs

📦 Package & Internal Refactors

• Refactored module structure
  • Moved abca and gta scripts to unravel/allen_institute/
  • Centralized image I/O and tabular utils
  • Unified function naming, argparse logic, and CLI descriptions
• Updated pyproject.toml
  • Aliases added for new CLI tools
  • Optional [abca] dependencies (e.g., boto3, abc_atlas_access) declared
• Improved .gitignore for Sphinx and log files

📚 Documentation Improvements

• Added:
  • merfish_slice and utils module docs
  • Instructions for PyPI install: pip install unravel
• Improved:
  • Index and landing page formatting
  • Output path and argument help across scripts
  • Clarified Next Steps and visualization tips in guides

🧪 Summary

This release empowers users to:

• Process and register large-scale 3D STPT images
• Segment major cell types (somata, astrocytes, endothelial)
• Analyze filtered MERFISH cells with ABCA metadata
• Quantify and visualize gene expression across the brain

Try the new MapMySections workflow now or explore the expanded ABCA functionality!