@bgicli/bgicli 2.1.1 → 2.2.1

package/data/workflows/scrnaseq-seurat-core-analysis/scripts/setup_and_import.R

@@ -0,0 +1,193 @@
+# ============================================================================
+# SETUP AND DATA IMPORT FOR SEURAT ANALYSIS
+# ============================================================================
+#
+# This script handles initial setup and data loading for Seurat scRNA-seq analysis.
+#
+# Functions:
+#   - setup_seurat_libraries(): Load required R packages
+#   - import_10x_data(): Load 10X Genomics CellRanger output
+#   - import_h5_data(): Load H5 format data
+#   - import_count_matrix(): Load from CSV/TSV count matrix
+#   - add_metadata(): Add sample metadata to Seurat object
+#
+# Usage:
+#   source("scripts/setup_and_import.R")
+#   setup_seurat_libraries()
+#   seurat_obj <- import_10x_data("path/to/filtered_feature_bc_matrix/")
+
+#' Load required libraries for Seurat analysis
+#'
+#' @return NULL (loads packages into environment)
+#' @export
+setup_seurat_libraries <- function() {
+  suppressPackageStartupMessages({
+    library(Seurat)
+    library(ggplot2)
+    library(ggprism)   # For publication-quality plots
+    library(dplyr)
+    library(patchwork) # For combining plots
+  })
+  message("Required libraries loaded successfully")
+  message(paste0("Seurat version: ", packageVersion("Seurat")))
+}
+
+#' Import 10X Genomics data
+#'
+#' @param data_dir Path to directory containing barcodes, features, and matrix files
+#' @param project_name Project name for Seurat object (default: "scRNAseq")
+#' @param min_cells Minimum number of cells for a gene to be included (default: 3)
+#' @param min_features Minimum number of features for a cell to be included (default: 200)
+#' @return Seurat object with raw counts
+#' @export
+import_10x_data <- function(data_dir,
+                            project_name = "scRNAseq",
+                            min_cells = 3,
+                            min_features = 200) {
+
+  if (!dir.exists(data_dir)) {
+    stop("Data directory does not exist: ", data_dir)
+  }
+
+  message("Loading 10X data from: ", data_dir)
+
+  # Read 10X data
+  data <- Read10X(data.dir = data_dir)
+
+  # Create Seurat object
+  seurat_obj <- CreateSeuratObject(
+    counts = data,
+    project = project_name,
+    min.cells = min_cells,
+    min.features = min_features
+  )
+
+  message(sprintf("Created Seurat object: %d genes x %d cells",
+                  nrow(seurat_obj), ncol(seurat_obj)))
+
+  return(seurat_obj)
+}
+
+#' Import H5 format data
+#'
+#' @param h5_file Path to H5 file
+#' @param project_name Project name for Seurat object (default: "scRNAseq")
+#' @param min_cells Minimum number of cells for a gene to be included (default: 3)
+#' @param min_features Minimum number of features for a cell to be included (default: 200)
+#' @return Seurat object with raw counts
+#' @export
+import_h5_data <- function(h5_file,
+                          project_name = "scRNAseq",
+                          min_cells = 3,
+                          min_features = 200) {
+
+  if (!file.exists(h5_file)) {
+    stop("H5 file does not exist: ", h5_file)
+  }
+
+  message("Loading H5 data from: ", h5_file)
+
+  # Read H5 data
+  data <- Read10X_h5(filename = h5_file)
+
+  # Create Seurat object
+  seurat_obj <- CreateSeuratObject(
+    counts = data,
+    project = project_name,
+    min.cells = min_cells,
+    min.features = min_features
+  )
+
+  message(sprintf("Created Seurat object: %d genes x %d cells",
+                  nrow(seurat_obj), ncol(seurat_obj)))
+
+  return(seurat_obj)
+}
+
+#' Import count matrix from CSV/TSV
+#'
+#' @param file_path Path to count matrix file (genes as rows, cells as columns)
+#' @param sep Separator character (default: auto-detect)
+#' @param project_name Project name for Seurat object (default: "scRNAseq")
+#' @param min_cells Minimum number of cells for a gene to be included (default: 3)
+#' @param min_features Minimum number of features for a cell to be included (default: 200)
+#' @return Seurat object with raw counts
+#' @export
+import_count_matrix <- function(file_path,
+                                sep = NULL,
+                                project_name = "scRNAseq",
+                                min_cells = 3,
+                                min_features = 200) {
+
+  if (!file.exists(file_path)) {
+    stop("Count matrix file does not exist: ", file_path)
+  }
+
+  # Auto-detect separator
+  if (is.null(sep)) {
+    if (grepl("\\.tsv$", file_path)) {
+      sep <- "\t"
+    } else {
+      sep <- ","
+    }
+  }
+
+  message("Loading count matrix from: ", file_path)
+
+  # Read count matrix
+  if (sep == "\t") {
+    counts <- read.csv(file_path, sep = "\t", row.names = 1, check.names = FALSE)
+  } else {
+    counts <- read.csv(file_path, row.names = 1, check.names = FALSE)
+  }
+
+  # Convert to sparse matrix for efficiency
+  counts <- as(as.matrix(counts), "dgCMatrix")
+
+  # Create Seurat object
+  seurat_obj <- CreateSeuratObject(
+    counts = counts,
+    project = project_name,
+    min.cells = min_cells,
+    min.features = min_features
+  )
+
+  message(sprintf("Created Seurat object: %d genes x %d cells",
+                  nrow(seurat_obj), ncol(seurat_obj)))
+
+  return(seurat_obj)
+}
+
+#' Add sample metadata to Seurat object
+#'
+#' @param seurat_obj Seurat object
+#' @param metadata_file Path to metadata CSV file (with cell barcodes as row names)
+#' @return Seurat object with added metadata
+#' @export
+add_metadata <- function(seurat_obj, metadata_file) {
+
+  if (!file.exists(metadata_file)) {
+    stop("Metadata file does not exist: ", metadata_file)
+  }
+
+  message("Loading metadata from: ", metadata_file)
+
+  # Read metadata
+  metadata <- read.csv(metadata_file, row.names = 1)
+
+  # Check that cell barcodes match
+  cells_in_obj <- colnames(seurat_obj)
+  cells_in_meta <- rownames(metadata)
+
+  if (length(intersect(cells_in_obj, cells_in_meta)) == 0) {
+    stop("No matching cell barcodes between Seurat object and metadata file")
+  }
+
+  # Add metadata to Seurat object
+  seurat_obj <- AddMetaData(seurat_obj, metadata = metadata)
+
+  message(sprintf("Added %d metadata columns to %d cells",
+                  ncol(metadata), nrow(metadata)))
+
+  return(seurat_obj)
+}

package/data/workflows/spatial-transcriptomics/SKILL.md

@@ -0,0 +1,256 @@
+---
+id: spatial-transcriptomics
+name: Spatial Transcriptomics Visium Analysis
+category: transcriptomics
+short-description: "Analyze 10x Visium spatial transcriptomics data from QC through spatial domain analysis with clustering, spatially variable genes, and neighborhood enrichment."
+detailed-description: "Complete spatial transcriptomics analysis for 10x Visium data using Squidpy and Scanpy. Performs quality control, normalization, Leiden clustering, spatial neighbor graph construction, spatially variable gene identification via Moran's I, neighborhood enrichment analysis, and co-occurrence scoring. Produces publication-ready spatial tissue overlays, UMAP plots, enrichment heatmaps, and SVG bar charts. Supports Space Ranger output, H5AD files, or built-in 10x Genomics example datasets including V1_Human_Heart for cardiometabolic research."
+starting-prompt: Analyze spatial transcriptomics data from a 10x Visium experiment to identify spatially variable genes and tissue domains.
+---
+
+# Spatial Transcriptomics Visium Analysis
+
+## When to Use This Skill
+
+- You have **10x Visium** spatial gene expression data (with or without H&E image)
+- You want to identify **spatially variable genes** across a tissue section
+- You want to discover **spatial tissue domains** via clustering
+- You want to quantify **neighborhood enrichment** between cell clusters
+- You want to analyze **co-occurrence** patterns of cell types across distances
+- Input is Space Ranger output, `.h5ad`, or `.h5` file
+
+**Not for:** Single-molecule FISH (MERFISH/Xenium), Slide-seq, or single-cell RNA-seq without spatial coordinates. For scRNA-seq, use `scrnaseq-scanpy-core-analysis`.
+
+## Installation
+
+```bash
+pip install squidpy scanpy anndata scikit-misc plotnine plotnine-prism seaborn matplotlib numpy pandas scikit-learn
+```
+
+| Package | Version | License | Commercial Use | Installation |
+|---------|---------|---------|----------------|--------------|
+| squidpy | ≥1.4 | BSD-3-Clause | ✅ Permitted | `pip install squidpy` |
+| scanpy | ≥1.9 | BSD-3-Clause | ✅ Permitted | `pip install scanpy` |
+| anndata | ≥0.8 | BSD-3-Clause | ✅ Permitted | `pip install anndata` |
+| plotnine | ≥0.12 | MIT | ✅ Permitted | `pip install plotnine` |
+| plotnine-prism | ≥0.2 | MIT | ✅ Permitted | `pip install plotnine-prism` |
+| seaborn | ≥0.11 | BSD-3-Clause | ✅ Permitted | `pip install seaborn` |
+| matplotlib | ≥3.5 | PSF | ✅ Permitted | `pip install matplotlib` |
+| scikit-learn | ≥1.0 | BSD-3-Clause | ✅ Permitted | `pip install scikit-learn` |
+| scikit-misc | ≥0.1 | BSD-3-Clause | ✅ Permitted | `pip install scikit-misc` |
+| numpy | ≥1.21 | BSD-3-Clause | ✅ Permitted | `pip install numpy` |
+| pandas | ≥1.3 | BSD-3-Clause | ✅ Permitted | `pip install pandas` |
+
+**License Compliance:** All packages use permissive licenses (BSD, MIT, PSF) that permit commercial use in AI agent applications.
+
+## Inputs
+
+| Input | Format | Description |
+|-------|--------|-------------|
+| Visium data | `.h5ad`, `.h5`, or Space Ranger directory | Gene expression + spatial coordinates |
+| H&E image | Embedded in above | Tissue histology (optional, enhances spatial plots) |
+
+**Built-in example:** V1_Human_Heart from 10x Genomics (~4,247 spots, ~33,538 genes, includes H&E image).
+
+## Outputs
+
+**Analysis objects:**
+- `adata_processed.h5ad` — Complete processed AnnData for downstream use
+  - Load with: `adata = sc.read_h5ad('adata_processed.h5ad')`
+  - Contains: clusters, embeddings, SVG results, spatial graph
+
+**Tables (CSV):**
+- `spatially_variable_genes.csv` — SVGs ranked by Moran's I with FDR
+- `cluster_assignments.csv` — Spot barcodes + Leiden cluster + spatial coordinates
+- `neighborhood_enrichment.csv` — Cluster-cluster enrichment z-scores
+- `spot_metadata.csv` — All spot-level QC and annotation metadata
+- `analysis_summary.txt` — Human-readable report
+
+**Plots (PNG + SVG):**
+- `qc_violins` — QC metric distributions
+- `spatial_clusters` — Leiden clusters overlaid on tissue
+- `spatial_markers` — Selected marker gene expression on tissue
+- `umap_clusters` — UMAP embedding colored by cluster
+- `neighborhood_enrichment` — Cluster enrichment heatmap
+- `co_occurrence` — Co-occurrence probability vs distance
+- `top_svgs` — Bar chart of top spatially variable genes
+- `spatial_svg_[GENE]` — Spatial expression of top SVG
+
+## Clarification Questions
+
+**ALWAYS ask Question 1 FIRST:**
+
+### 1. Input Files (ASK THIS FIRST):
+- Do you have Visium data files to analyze?
+  - **Supported formats:** `.h5ad`, `.h5`, or Space Ranger output directory
+- **Or use example data?** V1_Human_Heart from 10x Genomics (human cardiac tissue, ~4K spots)
+
+> 🚨 **IF EXAMPLE DATA SELECTED:** All parameters are pre-configured. **Skip remaining questions.** Proceed directly to Step 1.
+
+### 2. Analysis Parameters (ONLY if user provides own data):
+- **Clustering resolution?**
+  - a) 0.5 (fewer, broader clusters)
+  - b) 0.8 (standard — recommended)
+  - c) 1.2 (more, finer clusters)
+- **Mitochondrial threshold?**
+  - a) 50% (recommended for cardiac/muscle tissue — high MT is normal)
+  - b) 20% (standard for most tissues)
+  - c) 30% (moderate)
+
+### 3. Marker Genes (ONLY if user provides own data):
+- Which marker genes to highlight in spatial plots?
+  - Provide a list or use tissue-appropriate defaults
+
+## Standard Workflow
+
+🚨 **MANDATORY: USE SCRIPTS EXACTLY AS SHOWN — DO NOT WRITE INLINE CODE** 🚨
+
+> **Note:** Run from the `spatial-transcriptomics/` directory, or add `scripts/` to `sys.path`:
+> ```python
+> import sys; sys.path.insert(0, 'scripts')
+> ```
+
+**Step 1 — Load data:**
+```python
+from load_example_data import load_visium_heart
+adata = load_visium_heart()
+```
+**DO NOT write inline data loading code. Just use the script.**
+
+**✅ VERIFICATION:** You MUST see: `"✓ Data loaded successfully!"`
+
+---
+
+**Step 2 — Run analysis:**
+```python
+from spatial_workflow import run_spatial_analysis
+adata = run_spatial_analysis(adata, output_dir="visium_results")
+```
+**DO NOT write inline analysis code. Just use the script.**
+
+**✅ VERIFICATION:** You MUST see: `"✓ Spatial analysis completed successfully!"`
+
+**❌ IF YOU DON'T SEE THIS:** You wrote inline code. Stop and use the script.
+
+---
+
+**Step 3 — Generate visualizations:**
+```python
+from generate_all_plots import generate_all_plots
+generate_all_plots(adata, output_dir="visium_results")
+# For non-cardiac tissue, pass tissue-appropriate markers:
+# generate_all_plots(adata, output_dir="visium_results", marker_genes=["GENE1", "GENE2"])
+```
+🚨 **DO NOT write inline plotting code (plt.savefig, ggplot, clustermap, etc.). Just use the script.** 🚨
+
+**The script handles PNG + SVG export with graceful fallback for SVG.**
+
+**✅ VERIFICATION:** You MUST see: `"✓ All visualizations generated successfully!"`
+
+---
+
+**Step 4 — Export results:**
+```python
+from export_results import export_all
+export_all(adata, output_dir="visium_results")
+```
+**DO NOT write custom export code. Use export_all().**
+
+**✅ VERIFICATION:** You MUST see:
+```
+==================================================
+=== Export Complete ===
+==================================================
+```
+
+---
+
+⚠️ **CRITICAL — DO NOT:**
+- ❌ **Write inline analysis code** → **STOP: Use `run_spatial_analysis()`**
+- ❌ **Write inline plotting code** → **STOP: Use `generate_all_plots()`**
+- ❌ **Write custom export code** → **STOP: Use `export_all()`**
+- ❌ **Try to install system libraries** → scripts handle optional deps gracefully
+
+**⚠️ IF SCRIPTS FAIL — Script Failure Hierarchy:**
+1. **Fix and Retry (90%)** — Install missing package, re-run script
+2. **Modify Script (5%)** — Edit the script file itself, document changes
+3. **Use as Reference (4%)** — Read script, adapt approach, cite source
+4. **Write from Scratch (1%)** — Only if genuinely impossible, explain why
+
+**NEVER skip directly to writing inline code without trying the script first.**
+
+## Common Issues
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| **`ModuleNotFoundError: squidpy`** | Missing package | `pip install squidpy` |
+| **`ModuleNotFoundError: plotnine_prism`** | Missing theme package | `pip install plotnine-prism` |
+| **SVG export failed** | Missing SVG backend | Normal — PNG always generated. SVG is best-effort. |
+| **`ValueError: coord_type='grid'`** | Non-grid spatial data | Use `coord_type='generic'` for non-Visium data |
+| **0 SVGs found (FDR < 0.05)** | Low signal or few permutations | Increase `svgs_n_perms=1000` or relax FDR threshold |
+| **Memory error on large dataset** | Too many spots/genes | Filter more aggressively or use `sc.pp.subsample()` |
+| **`KeyError: 'spatial'`** | Missing spatial coordinates | Ensure data was loaded with `sc.read_visium()` or has `.obsm['spatial']` |
+| **NaN in co-occurrence** | Known squidpy issue with `n_splits` | Use default `n_splits` parameter (do not override) |
+
+## Interpreting Results
+
+**Spatially Variable Genes (SVGs):**
+- **Moran's I close to +1** → Gene expression is spatially clustered (strong spatial pattern)
+- **Moran's I close to 0** → No spatial structure (random distribution)
+- **Moran's I close to -1** → Dispersed pattern (checkerboard; rare in practice)
+- **FDR < 0.05** is the standard significance threshold; use < 0.01 for stringent filtering
+- Top SVGs typically include tissue-specific markers and boundary genes
+
+**Neighborhood Enrichment Z-scores:**
+- **Z > 2** → Clusters are significantly co-localized (tend to be spatially adjacent)
+- **Z < -2** → Clusters are significantly segregated (avoid each other spatially)
+- **-2 to 2** → No significant spatial preference
+- Diagonal values (self-enrichment) indicate how spatially cohesive each cluster is
+
+**Co-occurrence Curves:**
+- Probability above expected → Clusters co-occur more than random at that distance
+- Distance-dependent changes reveal spatial organization (e.g., border zone cell types co-occur at short range)
+
+**Cluster-to-Tissue Mapping:**
+- Compare spatial cluster plots with H&E histology to validate biological relevance
+- Well-defined spatial clusters that match visible tissue structures (e.g., myocardium, fibrotic region) indicate meaningful tissue domains
+
+## Agent Summary Guidelines
+
+When presenting results to the user, the agent should:
+
+- **Report key numbers:** spots analyzed, clusters found, number of significant SVGs
+- **Highlight top 5-10 SVGs** with Moran's I values and known biological roles
+- **Describe spatial patterns:** which clusters are co-localized vs segregated
+- **Connect to biology:** relate spatial patterns to tissue architecture visible in H&E
+- **Note limitations:** permutation count affects SVG p-values; low `n_perms` may miss weak signals
+- **DO NOT** hallucinate gene functions — only report known annotations or suggest looking up unknown genes
+- **DO NOT** over-interpret co-occurrence curves from small datasets or few clusters
+
+**Mitochondrial content note:** Cardiac/muscle tissue has naturally high MT% (~30-40%) due to mitochondria-rich cells. The default `max_pct_mito=50%` is appropriate for heart tissue. For other tissues (brain, liver, immune), use 20% or lower.
+
+## Suggested Next Steps
+
+- **Functional enrichment** on SVG gene sets → `functional-enrichment-from-degs`
+- **Cell type deconvolution** with cell2location or RCTD (specialized workflow)
+- **Cell-cell communication** with CellChat or COMMOT on spatial data
+- **Multi-sample integration** for comparing conditions (e.g., MI vs healthy)
+- **Gene regulatory networks** on spatial clusters → `grn-pyscenic`
+
+## Related Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `scrnaseq-scanpy-core-analysis` | Companion scRNA-seq analysis (non-spatial) |
+| `functional-enrichment-from-degs` | Downstream: enrichment on SVG gene lists |
+| `de-results-to-gene-lists` | Downstream: gene list preparation from SVGs |
+| `grn-pyscenic` | Downstream: regulatory networks from spatial clusters |
+| `coexpression-network` | Downstream: co-expression on spatial domains |
+
+## References
+
+- **Squidpy:** Palla G, et al. "Squidpy: a scalable framework for spatial omics analysis." *Nature Methods* (2022). doi:10.1038/s41592-021-01358-2
+- **Scanpy:** Wolf FA, et al. "SCANPY: large-scale single-cell gene expression data analysis." *Genome Biology* (2018). doi:10.1186/s13059-017-1382-0
+- **Moran's I:** Moran PAP. "Notes on continuous stochastic phenomena." *Biometrika* (1950). doi:10.2307/2332142
+- **10x Visium:** 10x Genomics. "Visium Spatial Gene Expression." https://www.10xgenomics.com/platforms/visium
+
+**Detailed parameter guidance:** See `references/spatial-analysis-guide.md`

package/data/workflows/spatial-transcriptomics/references/spatial-analysis-guide.md

@@ -0,0 +1,216 @@
+# Spatial Transcriptomics Analysis Guide
+
+Detailed parameter tuning and interpretation guide for 10x Visium spatial
+analysis using Squidpy and Scanpy.
+
+---
+
+## Spatial Neighbors Graph
+
+The spatial neighbors graph defines which spots are considered "neighbors" in
+tissue space. This graph underpins all downstream spatial analyses (SVGs,
+neighborhood enrichment, co-occurrence).
+
+### Coordinate Types
+
+| `coord_type` | When to Use                 | Description                                                            |
+| ------------ | --------------------------- | ---------------------------------------------------------------------- |
+| `'grid'`     | **Visium** (hexagonal grid) | Uses array row/col indices. Default `n_neighs=6` for hexagonal layout. |
+| `'generic'`  | Slide-seq, MERFISH, custom  | Uses spatial coordinates directly. Requires `n_neighs` or `radius`.    |
+
+**Visium default:**
+`sq.gr.spatial_neighbors(adata, coord_type='grid', n_neighs=6)` — each spot
+connects to its 6 hexagonal neighbors.
+
+### Parameters
+
+- **`n_neighs`** (default: 6 for grid): Number of neighbors per spot. For
+  Visium, 6 matches the hexagonal geometry. Increase to 12-18 for second-ring
+  neighbors.
+- **`n_rings`** (default: 1): Number of hexagonal rings around each spot (Visium
+  only). `n_rings=2` captures broader spatial context.
+- **`radius`** (generic only): Fixed distance radius for neighborhood
+  definition. Used when `coord_type='generic'`.
+
+---
+
+## Spatially Variable Genes (Moran's I)
+
+### What Is Moran's I?
+
+Moran's I measures spatial autocorrelation — whether a gene's expression is
+spatially clustered, dispersed, or random across the tissue.
+
+| Moran's I Value | Interpretation                                                               |
+| --------------- | ---------------------------------------------------------------------------- |
+| Close to **+1** | **Clustered** — high values near high, low near low (strong spatial pattern) |
+| Close to **0**  | **Random** — no spatial structure                                            |
+| Close to **-1** | **Dispersed** — checkerboard pattern (high near low)                         |
+
+### Statistical Significance
+
+- **`n_perms`** (default: 100): Number of permutations for the null
+  distribution. Higher = more accurate p-values but slower.
+  - **Quick exploration:** `n_perms=100` (~1-2 min)
+  - **Publication quality:** `n_perms=1000` (~10-15 min)
+- **FDR correction:** Uses Benjamini-Hochberg (`pval_norm_fdr_bh`). Standard
+  threshold: FDR < 0.05.
+- **Alternative method:** Geary's C (`mode='geary'`) — similar but more
+  sensitive to local differences. Use when Moran's I misses fine-grained
+  patterns.
+
+### Interpreting SVG Results
+
+The output DataFrame (`adata.uns['moranI']`) contains:
+
+| Column             | Description                                              |
+| ------------------ | -------------------------------------------------------- |
+| `I`                | Moran's I statistic (higher = more spatially structured) |
+| `pval_norm`        | P-value from normal approximation                        |
+| `pval_norm_fdr_bh` | FDR-corrected p-value                                    |
+| `var_norm`         | Variance under normality assumption                      |
+
+**Top SVGs** typically include:
+
+- Tissue-specific markers (e.g., cardiomyocyte genes in heart)
+- Extracellular matrix genes at tissue boundaries
+- Immune markers in infiltrated regions
+
+---
+
+## Neighborhood Enrichment
+
+### What It Measures
+
+Neighborhood enrichment quantifies whether two cluster types are **spatially
+co-localized** (positive z-score) or **spatially segregated** (negative z-score)
+beyond what's expected by chance.
+
+### Interpreting Z-Scores
+
+| Z-score     | Interpretation                                            |
+| ----------- | --------------------------------------------------------- |
+| **> 2**     | Significantly co-localized (clusters tend to be adjacent) |
+| **-2 to 2** | No significant spatial preference                         |
+| **< -2**    | Significantly segregated (clusters avoid each other)      |
+
+### Biological Examples (Cardiac Tissue)
+
+- **Cardiomyocyte ↔ Fibroblast:** Positive enrichment at infarct border zone
+- **Endothelial ↔ Cardiomyocyte:** Positive enrichment (vascular proximity)
+- **Immune ↔ Remote myocardium:** Negative enrichment (immune infiltration
+  localized to injury)
+
+---
+
+## Co-occurrence Analysis
+
+### What It Measures
+
+Co-occurrence computes the probability of observing two cluster types within
+increasing spatial distances. Unlike neighborhood enrichment (binary
+adjacent/not), co-occurrence captures **distance-dependent** spatial
+relationships.
+
+### Interpreting Co-occurrence Curves
+
+- **Probability > expected:** Clusters co-occur more than random at that
+  distance
+- **Probability < expected:** Clusters avoid each other at that distance
+- **Distance-dependent patterns:** Clusters may co-occur at short range but
+  segregate at long range (e.g., border zone cell types)
+
+### Known Issues
+
+- `n_splits` parameter can cause NaN values in some squidpy versions — use the
+  default value
+- Very small clusters (< 10 spots) produce noisy co-occurrence estimates
+
+---
+
+## Parameter Tuning Guide
+
+### QC Filtering
+
+| Parameter      | Typical Range | Heart Tissue | Notes                                          |
+| -------------- | ------------- | ------------ | ---------------------------------------------- |
+| `min_genes`    | 200-500       | 200          | Lower for sparse tissues                       |
+| `min_cells`    | 3-20          | 10           | Higher removes noise genes                     |
+| `max_pct_mito` | 10-30%        | 50%          | Cardiac tissue has naturally high MT (~30-40%) |
+
+**Cardiac-specific:** Heart tissue has naturally high mitochondrial content
+(~30-40% median) due to the energy demands of cardiomyocytes. The default
+`max_pct_mito=50%` retains >95% of spots. For non-cardiac tissues (brain, liver,
+immune), use 20% instead.
+
+### Clustering
+
+| Parameter     | Range   | Default | Effect                        |
+| ------------- | ------- | ------- | ----------------------------- |
+| `resolution`  | 0.2-2.0 | 0.8     | Higher = more clusters        |
+| `n_neighbors` | 5-30    | 15      | Higher = smoother clusters    |
+| `n_pcs`       | 10-50   | 30      | Higher captures more variance |
+
+**Spatial data:** Lower resolution (0.5-0.8) often produces more biologically
+interpretable spatial domains than high resolution. Check that clusters
+correspond to visible tissue regions in the H&E image.
+
+### HVG Selection
+
+| Parameter     | Range       | Default     | Notes                                             |
+| ------------- | ----------- | ----------- | ------------------------------------------------- |
+| `n_top_genes` | 1000-3000   | 2000        | Standard for Visium (~33K genes)                  |
+| `flavor`      | `seurat_v3` | `seurat_v3` | Works on raw counts; recommended for spatial data |
+
+---
+
+## Advanced Options
+
+### Alternative Autocorrelation: Geary's C
+
+```python
+sq.gr.spatial_autocorr(adata, mode='geary', n_perms=100)
+# Results in adata.uns['gearyC']
+```
+
+Geary's C is more sensitive to **local** spatial differences while Moran's I
+captures **global** spatial patterns. Consider running both for comprehensive
+SVG detection.
+
+### Custom Spatial Graphs
+
+For non-standard spatial layouts (e.g., multiple tissue sections merged):
+
+```python
+# Fixed radius neighbors
+sq.gr.spatial_neighbors(adata, coord_type='generic', radius=150)
+
+# KNN on coordinates
+sq.gr.spatial_neighbors(adata, coord_type='generic', n_neighs=10)
+
+# Delaunay triangulation
+sq.gr.spatial_neighbors(adata, coord_type='generic', delaunay=True)
+```
+
+### Subsetting for Performance
+
+For datasets with >10K spots, consider analyzing regions of interest:
+
+```python
+# Subset to a spatial region
+mask = (adata.obsm['spatial'][:, 0] > x_min) & (adata.obsm['spatial'][:, 0] < x_max)
+adata_subset = adata[mask].copy()
+```
+
+---
+
+## Downstream Analysis Suggestions
+
+1. **Cell type deconvolution:** Use SVG results + scRNA-seq reference to
+   estimate cell type proportions per spot (cell2location, RCTD, STdeconvolve)
+2. **Receptor-ligand analysis:** Identify spatially co-localized ligand-receptor
+   pairs using CellChat or COMMOT
+3. **Spatial gene-gene correlation:** Compute spatially-weighted correlation
+   between SVGs to identify co-regulated programs
+4. **Multi-sample comparison:** Integrate multiple Visium sections (e.g., MI vs
+   control) using batch correction + differential spatial analysis