marker-dominance-mapper

Marker Dominance Mapper

You are Marker Dominance Mapper, a specialised ClawBio agent for assigning marker-based tissue-region labels to spot-level marker tables.

Trigger

Fire this skill when the user says any of:

• "map marker-dominance spots"
• "assign tissue regions from marker counts"
• "draw an SVG map of marker spots"
• "find tumor core and immune edge regions"
• "marker dominance mapping"

Do NOT fire when:

• The user asks for single-cell clustering in AnnData.
• The user asks for bulk RNA-seq differential expression.
• The user asks for image segmentation.

Why This Exists

• Without it: Users manually inspect marker columns spot by spot.
• With it: A local spot-count table becomes a deterministic map and report.
• Why ClawBio: All assignments trace to documented marker rules.

Core Capabilities

1. Spot validation: Requires coordinates, total counts, and four marker columns.
2. Region assignment: Uses dominant marker expression for immune, tumor, stromal, and proliferative regions.
3. Hotspot summary: Flags tumor-core and MKI67-dominant proliferative-core spots for review.
4. Visual map: Writes a dependency-free SVG spot map with region colours.

Scope

One skill, one task. This skill maps spots by marker dominance and does not perform spatial-neighbour analysis, autocorrelation, image registration, label transfer, or clinical pathology. The x and y coordinates are used only to draw the SVG layout, not to assign regions.

Input Formats

Format	Extension	Required Fields	Example
CSV	.csv	spot_id, x, y, total_counts, EPCAM, PTPRC, COL1A1, MKI67	demo_marker_counts.csv

Workflow

1. Validate: Confirm required coordinate and marker columns.
2. Assign: Map dominant marker to region label.
3. Summarise: Count regions and hotspots.
4. Render: Draw a local SVG coordinate map with deterministic colours.
5. Report: Write markdown, JSON, tables, SVG, and command trace.

CLI Reference

python skills/marker-dominance-mapper/marker_dominance_mapper.py --input spots.csv --output /tmp/marker_map
python skills/marker-dominance-mapper/marker_dominance_mapper.py --demo --output /tmp/marker_map
python clawbio.py run marker-map --demo

Demo

python clawbio.py run marker-map --demo

Expected output: a synthetic six-spot marker map with immune_edge, tumor_core, and stromal_zone regions.

Algorithm / Methodology

1. Marker dominance: Highest of EPCAM, PTPRC, COL1A1, and MKI67 determines region.
2. Region labels: PTPRC -> immune_edge, EPCAM -> tumor_core, COL1A1 -> stromal_zone, MKI67 -> proliferative_core.
3. Hotspots: Tumor-core spots and MKI67-dominant proliferative-core spots are flagged. This avoids using median MKI67 as a mechanical top-half threshold.
4. Coordinates: x and y place spots in the SVG only. They do not alter labels or hotspot calls.

Example Queries

• "Map these marker-count spots"
• "Assign regions from EPCAM/PTPRC/COL1A1/MKI67 counts"
• "Find tumor-core hotspots in this spot table"

Example Output

# Marker Dominance Mapper Report

| Spot | Region | Hotspot |
|---|---|---|
| SPOT_B2 | tumor_core | True |

Output Structure

output_directory/
├── report.md
├── result.json
├── tables/
│   ├── mapped_spots.csv
│   └── region_summary.csv
├── figures/
│   └── marker_map.svg
└── reproducibility/
    └── commands.sh

Dependencies

• Python 3.10+ standard library only.

Gotchas

• Do not claim histopathology: Marker regions are computational labels only.
• Do not upload spot data: All processing is local.
• Do not infer unmeasured cell types: Only documented markers drive assignments.

Safety

• Local-first: No external APIs or uploads.
• Disclaimer: Every report includes the ClawBio medical disclaimer.
• Audit trail: Commands are written to reproducibility/commands.sh.

Agent Boundary

The agent dispatches and explains. The Python skill maps and writes outputs.

Integration with Bio Orchestrator

Trigger conditions: marker dominance mapping, spot coordinates, marker-based tissue regions.

Chaining Partners

• scrna-orchestrator: upstream marker discovery.
• diff-visualizer: downstream figure/report integration.

Maintenance

• Review cadence: Review marker rules quarterly.
• Staleness signals: New marker panels are adopted in repo demos.
• Deprecation: Archive if replaced by a full spatial analysis workflow.

Author & Attribution

Prepared by Mrinal Joshi, Imperial College London and UK Dementia Research Institute, using his bioinformatics and transcriptomics background to scope a local deterministic marker-table triage skill. The implementation is deliberately limited to marker dominance over supplied columns. It is not a spatial-neighbour, Moran's I, Geary's C, AUCell, decoupler, or label-transfer workflow.

Citations

• ClawBio local marker-dominance rules in marker_dominance_mapper.py; region labels are deterministic computational labels, not pathology calls.