adiezsanchez/microglia_dna_damage: COSMIC

This is the first public release of COSMIC (Counting Of Spots in Marker Indicator Cells): an interactive, notebook-driven workflow to quantify puncta (e.g. DNA damage foci) inside nuclei of cell-marker–positive cells. The reference use case is γH2AX-style foci in Iba1⁺ microglia and GFAP⁺ astrocytes from multichannel Zeiss .lsm stacks, but the same steps apply to other 3-channel marker + nuclei + spot assays.

Highlights

• End-to-end pipeline from multichannel .lsm stacks → per-image CSV metrics → QC filtering → exploratory plots and batch image review.
• Cellpose 2.0 nuclei segmentation with tunable pre and post processing (Gaussian blur, contrast stretch, dilation/erosion).
• Cell marker+ (CM+) nuclei via intensity thresholding or optional APOC semantic segmentation, with erosion to suppress protrusion artifacts on MIPs.
• APOC object segmenters (three pretrained DNA-damage versions) for spot detection, with post-segmentation erosion/dilation to control speck size.
• Quality control that flags suboptimal stainings from mask-area outliers and writes qc_*.csv files for downstream filtering.
• Example outputs for microglia and astrocyte parameter sets included under results/.
• CITATION.cff for machine-readable citation metadata (GitHub Cite this repository).

Added

• Core analysis module: utils.py (analyze_images, parameter extraction, QC, aggregation, Plotly exploration helpers).
• Notebooks:
  • 0_data_download.ipynb — download example data via pre-signed URL.
  • 00_presigned_url_generator.ipynb — helper for data hosting (maintainers).
  • 1_image_analysis.ipynb — batch image analysis and CSV export.
  • 2_data_exploration.ipynb — technical-replicate plots, QC, aggregated results.
  • 3_qc_passed_image_display.ipynb / 3_qc_failed_image_display.ipynb — matplotlib review of QC-passed vs failed images.
• Pretrained classifiers:
  • object_segmenters/dna_damage_object_segmenter_v{1,2,3}.cl
  • semantic_segmenters/microglia_segmenter_v1.cl
• Reproducible conda environment: envs/environment.yml (Python 3.9, Cellpose, Napari/devbio stack, APOC, PyTorch CPU, Plotly, Jupyter).
• Documentation: README.md with workflow diagram, parameter glossary, and setup instructions.
• License: BSD 3-Clause.

Workflow summary

1. Segment nuclei (Cellpose) → dilate/erode labels so foci associate with the correct nucleus.
2. Define CM+ nuclei (threshold or APOC glia mask + colocalization erosion).
3. Detect spots (APOC object segmenter v1–v3) → size filtering via erosion/dilation.
4. Export metrics per filename (foci per CM+ nucleus, damage load ratios, mask areas, etc.).
5. Explore & QC in notebook 2; visualize passed/failed cases in notebooks 3.

Notes for users

• GPU: analyze_images uses Cellpose(gpu=True); a CUDA-capable GPU is recommended for practical batch runs.
• Data: Raw .lsm data are not bundled; use 0_data_download.ipynb after obtaining a fresh pre-signed link (see README). Place images under raw_data/, microglia_data/, or astrocyte_data/ as described in the notebooks.
• Channels: Pipeline expects 3 channels (nuclei, spot channel, cell marker); adapt channel indices in code if your acquisition order differs.
• Segmenter choice: v1 is strictest (best on clean stainings); v2/v3 generalize more but can add noise on poor slides (documented in README).
• Training notebooks: README references 0_train_* and 4_quality_checks.ipynb for classifier training and Napari deep-dive QC; those notebooks are not in this repository—training examples are linked to the intestinal organoid brightfield workflow.
• Mouse ID pairing: mouse_ids_Iba1.csv and mouse_ids_GFAP.csv are gitignored; supply your own mapping files for biological replicate pairing.
• Zenodo: Add the DOI to CITATION.cff and the README Zenodo link when the archive record is published.