TEST 3: Spatial Transcriptomics Analysis
=========================================

> **Prompt library:** This is the canonical prompt for [Clinical Workflow Prompt 3](../../../../prompts/clinical-workflow.md#prompt-3-spatial-tumor-microenvironment-analysis). See that page for clinical interpretation context and expected output summary.

Patient ID: PAT001-OVC-2025

⚠️ IMPORTANT: This test uses TABULAR DATA (CSV files), NOT images.
Use ONLY the spatialtools server to read and analyze files.
DeepCell is NOT needed - we have no images to segment.

## Spatial Analysis (use mcp-spatialtools)

For patient PAT001-OVC-2025, analyze spatial gene expression patterns:

### Data Files Location:
Files are in GCS at: `gs://sample-inputs-patientone/patient-data/PAT001-OVC-2025/spatial/`
(Also accessible as relative path: `patient-data/PAT001-OVC-2025/spatial/`)
- visium_spatial_coordinates.csv
- visium_gene_expression.csv
- visium_region_annotations.csv

### Pre-Flight Validation:

Before starting analysis, verify data quality:

1. **File existence check:**
   - Confirm all 3 CSV files are accessible
   - Check file sizes are reasonable (coordinates ~34 KB, expression ~117 KB, regions ~18 KB)

2. **Data integrity check:**
   - Coordinates file: Should have ~900 rows (spots) with x, y coordinates
   - Expression file: Should have ~900 rows × 31 genes columns
   - Regions file: Should have ~900 rows with 6 unique region labels

3. **Expected genes present:**
   - Verify all 8 key genes exist in expression file: MKI67, PCNA, PIK3CA, AKT1, ABCB1, CD3D, CD8A, CD68
   - If any genes missing, report and continue with available genes

4. **Expected regions present:**
   - Verify all 6 regions exist: tumor_core, tumor_proliferative, tumor_interface, stroma_immune, stroma, necrotic_hypoxic
   - If any regions missing, report and adjust analysis accordingly

**If validation fails:** Report specific issues but continue with best-effort analysis using available data.

### Analysis Steps:

1. **Load spatial data:**
   - How many spatial spots? (Expect: 900)
   - What spatial regions are identified? (Expect: 6 regions)
   - How many spots per region?

2. **Focus on KEY GENES ONLY** (8 genes to reduce context):
   - **Proliferation:** MKI67, PCNA
   - **Resistance:** PIK3CA, AKT1, ABCB1
   - **Immune:** CD3D, CD8A, CD68

3. **Gene expression by region:**
   - Which regions have high proliferation (MKI67, PCNA)?
   - Where are resistance markers (PIK3CA, AKT1, ABCB1) expressed?
   - Where are immune cells (CD3D, CD8A, CD68) located?

4. **Spatial patterns:**
   - Is there spatial heterogeneity in resistance markers?
   - Are immune cells excluded from tumor regions?
   - Tumor-stroma interface patterns?

5. **Generate visualizations** (CRITICAL for validation):

   **Use mcp-spatialtools visualization tools:**

   - **Spatial heatmap** (use tool: `generate_spatial_heatmap`):
     * Show expression of top 6 spatially variable genes overlaid on tissue coordinates
     * Use different color scale for each gene
     * Include spatial coordinates (x, y) to show tissue layout
     * Expected: MKI67 high in tumor_proliferative, CD8A high in stroma_immune

     ```
     Tool: generate_spatial_heatmap
     Inputs:
     - expression_file: visium_gene_expression.csv
     - coordinates_file: visium_spatial_coordinates.csv
     - genes: ["MKI67", "PCNA", "PIK3CA", "AKT1", "CD8A", "CD68"]
     - colormap: "viridis"
     ```

   - **Region composition bar chart** (use tool: `generate_region_composition_chart`):
     * Show number of spots per tissue region
     * 6 regions on x-axis, spot count on y-axis
     * Expected: stroma_immune has most spots (~212), tumor_core has fewest (~69)

     ```
     Tool: generate_region_composition_chart
     Inputs:
     - regions_file: visium_region_annotations.csv
     - colormap: "tab10"
     ```

   - **Gene expression heatmap** (use tool: `generate_gene_expression_heatmap`):
     * 8 genes (rows) × 6 regions (columns)
     * Color intensity = mean expression level per region
     * Expected: MKI67/PCNA high in tumor_proliferative, CD3D/CD8A/CD68 high in stroma_immune

     ```
     Tool: generate_gene_expression_heatmap
     Inputs:
     - expression_file: visium_gene_expression.csv
     - regions_file: visium_region_annotations.csv
     - genes: ["MKI67", "PCNA", "PIK3CA", "AKT1", "ABCB1", "CD3D", "CD8A", "CD68"]
     - colormap: "RdYlBu_r"
     ```

   - **Spatial autocorrelation plot** (use tool: `visualize_spatial_autocorrelation`):
     * Bar chart showing Moran's I statistic for each gene
     * Expected: High autocorrelation (I > 0.5) for regionalized markers

     ```
     Tool: visualize_spatial_autocorrelation
     Inputs:
     - autocorrelation_results: (output from calculate_spatial_autocorrelation tool)
     - top_n: 10
     ```

   **Note:** If spatialtools cannot generate images, provide detailed text descriptions of what each plot would show, including:
   - Which genes/regions would be highlighted
   - Expected patterns (hotspots, gradients, exclusion zones)
   - Quantitative values for validation

## Expected Results:

**Spatial Structure:**
- Total spots: 900
- Regions: 6
  1. tumor_core (~69 spots)
  2. tumor_proliferative (~124 spots)
  3. tumor_interface (~112 spots)
  4. stroma_immune (~212 spots)
  5. stroma (~180 spots)
  6. necrotic_hypoxic (~203 spots)

**Expression Patterns:**

| Gene | High Expression Region | Pattern |
|------|----------------------|---------|
| MKI67 | tumor_proliferative | High proliferation |
| PCNA | tumor_proliferative | High proliferation |
| PIK3CA | tumor_core, tumor_proliferative | Resistance mechanism |
| AKT1 | tumor regions | PI3K/AKT pathway |
| ABCB1 | tumor regions | Drug efflux |
| CD3D | stroma_immune | T cells |
| CD8A | stroma_immune | Cytotoxic T cells |
| CD68 | stroma_immune | Macrophages |

**Spatial Findings:**
- Proliferation: Highest in tumor_proliferative region
- Resistance markers: Concentrated in tumor regions (heterogeneous)
- Immune cells: Primarily in stroma_immune region (EXCLUDED from tumor)
- Tumor microenvironment: Immunologically "cold" (immune exclusion)

## Output Format:

Please provide:

1. **Spatial Structure:**
   - Total spots: 900
   - Region breakdown with spot counts
   - Visual description of tissue layout

2. **Gene Expression Heatmap:**
   - 8 genes × 6 regions
   - Which genes are high/low in each region?

3. **Key Spatial Findings:**
   - Where is proliferation highest?
   - Resistance marker distribution pattern
   - Immune cell localization

4. **Visualizations** (Required):
   - Spatial heatmap (or detailed text description if image not available)
   - Region composition bar chart (or data table)
   - Gene expression heatmap (8×6 matrix with values)
   - Spatial autocorrelation plot (or Moran's I values table)

   **If providing text descriptions instead of images, include:**
   - Quantitative values (expression levels, spot counts, Moran's I)
   - Spatial patterns (which regions show hotspots, gradients, exclusion)
   - Color mapping descriptions (what high/low values represent)

5. **Clinical Interpretation:**
   - Is there spatial heterogeneity in resistance markers? (Yes)
   - Are immune cells excluded from tumor? (Yes)
   - Tumor microenvironment classification: Cold vs Hot? (Cold)
   - Implications for immunotherapy? (Limited efficacy expected)

## Validation Checkpoints:

✅ Loaded: 900 spots across 6 regions
✅ Proliferation: High in tumor_proliferative region
✅ Resistance markers: Present in tumor regions
✅ Immune cells: Localized to stroma_immune region
✅ Immune exclusion: Confirmed (immune cells away from tumor)
✅ Heterogeneity: Spatial variation in resistance markers
