/spatial-panel-design

name: "spatial-panel-design"
description: "Spatial transcriptomics gene panel design (Xenium, MERFISH, CosMx custom panels) for cell type identification: rank markers on a tissue-matched CELLxGENE scRNA-seq reference, add PanglaoDB and CellMarker 2.0 marker evidence, build a per-gene evidence table, allocate per-cell-type quotas, and check that the panel separates cell types in the reference. Output: final_gene_panel.csv with N genes, cell type and reason. For annotating data from an existing panel use spatial-transcriptomics-cell-type-annotation."
license: "CC-BY-4.0"

Spatial Gene Panel Design

Overview

Pick exactly N genes that let an imaging-based platform identify every major cell type of a tissue. Code builds the evidence; you (the agent) make the final selection from the evidence table and write a reason per gene. Output: a per-gene evidence table and `final_gene_panel.csv` with N genes, the cell type each marks, its evidence and a reason.

When to Use

• Designing a custom Xenium, MERFISH or CosMx gene panel for a tissue and state
• Choosing add-on genes to extend a vendor base panel for missing cell types
• Checking that a proposed panel can separate the cell types the study needs
• Documenting why each panel gene was chosen, with reference and database evidence
• Comparing candidate markers from a reference with PanglaoDB and CellMarker 2.0
• Use `spatial-transcriptomics-cell-type-annotation` instead when the panel already exists and data must be annotated
• For genes the panel will not measure, use the gene imputation route of `spatial-mapping-tangram` after the experiment

Prerequisites

• **From the user**: organism, tissue, state (healthy or a disease) and panel size N
• **Reference**: tissue- and state-matched; run Steps 3-4 of

`spatial-transcriptomics-cell-type-annotation` (same code), adding `"cell_type_ontology_term_id"` to `obs_column_names`, with `GENES = None` (markers are ranked over every gene) and `MAX_PER_TYPE = 300`, to get `reference.h5ad`

• **Literature**: ask the research subagent / literature tools for published panels

and canonical markers of this tissue; add what they return in Step 5

• **Python packages**: `cellxgene-census`, `scanpy`, `openpyxl`, `scikit-learn`

# Install only what `import` reports missing. `--pypi` keeps the env's scanpy/numba
# stack; a conda add can swap it and bare pip can shadow it.
pixi add --pypi cellxgene-census scanpy openpyxl scikit-learn

Pre-flight Interview

decisions:
  - id: D1
    param: ORGANISM
    kind: required
    source: user
    ask: "Human or mouse tissue?"
    default: null
  - id: D2
    param: TISSUE
    kind: required
    source: user
    ask: "Which tissue will be profiled?"
    default: null
  - id: D3
    param: STATE
    kind: required
    source: user
    ask: "Healthy tissue, or which disease or tumour?"
    default: null
  - id: D4
    param: PANEL_SIZE
    kind: required
    source: user
    ask: "How many genes can the panel hold?"
    default: null
  - id: D5
    param: basePanel
    kind: required
    source: user
    ask: "Is this a standalone custom panel, or add-on genes for a vendor base panel (which one)?"
    default: "standalone panel"
  - id: D6
    param: DATASET_ID
    kind: required
    source: data
    depends_on: [D1, D2, D3]
    ask: "These CELLxGENE datasets match the tissue and state: which one should be the reference?"
    default: null
  - id: D7
    param: cellTypeResolution
    kind: required
    source: data
    depends_on: [D4, D6]
    ask: "These are the reference cell types; for a panel of this size I propose merging <fine states> into <lineages>. Which types must the panel separate?"
    default: "major lineages; merge fine states the panel size cannot resolve"
  - id: D8
    param: requiredGenes
    kind: optional
    source: user
    ask: "Are there genes that must be on the panel (study targets, known markers)?"
    default: "none"
  - id: D9
    param: MIN_PER_TYPE
    kind: optional
    source: user
    ask: "At least how many genes per cell type, so rare but important types are covered?"
    default: "3"
  - id: D10
    param: cancerTypeFilter
    kind: derived
    source: upstream
    depends_on: [D3]
    ask: "Keep tumour-derived CellMarker entries?"
    default: "Normal only for healthy tissue; drop the filter for tumour panels"

Ask D1-D5 together. D6 and D7 come in a later round, after the Census search and the reference's cell types are known; D8 genes join the evidence table as rows in Step 5.

Workflow

1. Load the reference and true cell type abundance 2. Rank reference markers per cell type 3. PanglaoDB markers 4. CellMarker 2.0 markers 5. Build the evidence table 6. Allocate quotas and draft the panel 7. Check the panel separates cell types, then save

Step 1: Reference and Abundance

The Step 4 reference is capped per cell type, so take real abundance from the full dataset metadata:

import cellxgene_census
import numpy as np
import pandas as pd
import scanpy as sc

ORGANISM, TISSUE, PANEL_SIZE = "Homo sapiens", "liver", 100
DATASET_ID = "<dataset_id used for reference.h5ad>"

ref = sc.read_h5ad("reference.h5ad")          # X = raw counts
ref.layers["counts"] = ref.X.copy()
sc.pp.normalize_total(ref)
sc.pp.log1p(ref)

with cellxgene_census.open_soma(census_version="stable") as census:
    obs = census["census_data"][ORGANISM.lower().replace(" ", "_")].obs.read(
        value_filter=f"dataset_id == '{DATASET_ID}'", column_names=["cell_type"]).concat().to_pandas()
abundance = obs["cell_type"].value_counts(normalize=True)

keep = ref.obs["cell_type"].value_counts()
keep = keep[keep >= 20].index                  # too few cells for stable markers
ref = ref[ref.obs["cell_type"].isin(keep)].copy()
ref.obs["cell_type"] = ref.obs["cell_type"].astype("category").cat.remove_unused_categories()
ct_ids = ref.obs.groupby("cell_type", observed=True)["cell_type_ontology_term_id"].first()
print(pd.Data