Claude Cursor Skill

cellxgene-context

Guide for integrating CellxGene Census single-cell data with ENCODE bulk experiments. Use when users need cell-type-specific expression context for ENCODE regulatory data, want to deconvolve bulk ENCODE signals, or validate regulatory elements at single-cell resolution. Trigger o

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download ammawla-encode-toolkit-plugin_skills_cellxgene-context-36836c8.zip · 11 KB

Install

skills CLI npx skills add https://github.com/ammawla/encode-toolkit/tree/main/plugin/skills/cellxgene-context
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install ammawla-encode-toolkit@llmmart
Git git clone https://github.com/ammawla/encode-toolkit.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole ammawla/encode-toolkit collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Integrating CellxGene Census Single-Cell Data with ENCODE Bulk Experiments

Bridge bulk ENCODE functional genomics data with cell-type-specific expression from the CellxGene Census, the largest unified single-cell RNA-seq atlas, to resolve cell-type contributions to regulatory element activity.

Scientific Rationale

The question: "Which specific cell types within my tissue drive the regulatory signals I see in bulk ENCODE data?"

ENCODE provides deeply sequenced bulk functional genomics (ChIP-seq, ATAC-seq, Hi-C) across hundreds of biosamples. But bulk data from a tissue like "pancreas" is a mixture of acinar cells (~80%), duct cells (~10%), endocrine cells (~5%), and others. An H3K27ac peak in bulk pancreas could be driven by any of these cell types. CellxGene Census provides cell-type-resolved expression data from 50M+ single-cell observations across thousands of datasets, enabling deconvolution of bulk ENCODE signals.

The Bulk-to-Single-Cell Bridge

Bulk ENCODE Signal Single-Cell Question CellxGene Answer
H3K27ac peak near INS gene in pancreas Which cell type expresses INS? Beta cells (>500 TPM), not acinar (<1 TPM)
ATAC-seq peak in liver near ALB Is this hepatocyte-specific? Yes — ALB expressed only in hepatocytes
Enhancer active in brain cortex Neurons or glia? CellxGene resolves excitatory neurons vs. astrocytes vs. oligodendrocytes
Broad H3K27ac domain in blood Which immune cell type? Can distinguish T cells, B cells, monocytes, NK cells

What CellxGene Census Provides

  • 50M+ single-cell observations from thousands of published datasets
  • Standardized cell ontology (Cell Ontology terms) across all datasets
  • Unified gene expression in a consistent format
  • Metadata: tissue, disease status, sex, ethnicity, developmental stage
  • API access via Python (cellxgene-census) or R (cellxgene.census)
  • No authentication required for public data

Key Literature

  • Megill et al. 2021 "cellxgene: a performant, scalable exploration platform for high dimensional sparse matrices" (bioRxiv preprint). Describes the CellxGene platform architecture and exploration capabilities. DOI: 10.1101/2021.04.05.438318
  • CZ CELLxGENE Discover (Chan Zuckerberg Initiative, 2023). CellxGene Census provides programmatic access to the entire CellxGene data corpus as a single unified dataset. https://cellxgene.cziscience.com/
  • Regev et al. 2017 "The Human Cell Atlas" (eLife, ~1,500 citations). The vision paper for comprehensive single-cell reference maps of all human cells. CellxGene Census is the largest realization of this vision. DOI: 10.7554/eLife.27041
  • Tabula Sapiens Consortium 2022 "The Tabula Sapiens: A multiple-organ, single-cell transcriptomic atlas of humans" (Science, ~800 citations). Multi-organ human cell atlas contributing to CellxGene Census. DOI: 10.1126/science.abl4896
  • ENCODE Project Consortium 2020 (Nature, ~1,656 citations). The bulk regulatory element catalog that CellxGene single-cell data contextualizes. DOI: 10.1038/s41586-020-2493-4

When to Use This Skill

Scenario How CellxGene Helps
Bulk ENCODE peak near a gene — which cell type? Query gene expression by cell type in matching tissue
ENCODE enhancer active in tissue X — cell-type-specific? Check if enhancer target gene is restricted to one cell type
Choosing ENCODE cell line as proxy Verify which primary cell type the cell line best represents
Interpreting differential peaks between tissues Determine if difference is due to cell-type composition
Validating ENCODE scATAC-seq findings Cross-reference with CellxGene scRNA-seq for same cell types
Designing follow-up experiments Identify which cell types to isolate for validation

Python API Reference

Installation

pip install cellxgene-census

Requires Python 3.8+. The package uses TileDB-SOMA for efficient data access.

Core API Pattern

import cellxgene_census

# Open the Census (reads metadata, does not download all data)
with cellxgene_census.open_soma() as census:
    # Access human data
    human = census["census_data"]["homo_sapiens"]

    # Query specific genes in specific tissues/cell types
    # This is where filtering happens — be specific to control memory

Step 1: Identify the ENCODE Target Gene

Start from an ENCODE finding — a regulatory element near a gene of interest:

# Find enhancers in pancreas
encode_search_experiments(
    assay_title="Histone ChIP-seq",
    target="H3K27ac",
    organ="pancreas",
    biosample_type="tissue"
)

# Get peaks
encode_list_files(
    experiment_accession="ENCSR...",
    file_format="bed",
    output_type="IDR thresholded peaks",
    assembly="GRCh38"
)

From peaks, identify the nearest gene(s). You need the gene symbol or Ensembl ID.

Step 2: Query CellxGene Census for Cell-Type Expression

Basic Gene Expression Query

import cellxgene_census
import pandas as pd

gene_symbol = "INS"  # Insulin — example for pancreas

with cellxgene_census.open_soma() as census:
    human = census["census_data"]["homo_sapiens"]

    # Get expression for INS in pancreas tissue
    # Use obs_value_filter to restrict to pancreas
    # Use var_value_filter to restrict to the gene
    adata = cellxgene_census.get_anndata(
        census,
        organism="Homo sapiens",
        var_value_filter=f"feature_name == '{gene_symbol}'",
        obs_value_filter="tissue_general == 'pancreas'",
        obs_column_names=["cell_type", "tissue", "disease", "dataset_id"]
    )

    # Summarize expression by cell type
    expr_by_celltype = adata.to_df().join(adata.obs["cell_type"])
    summary = expr_by_celltype.groupby("cell_type").agg(
        mean_expr=(gene_symbol, "mean"),
        pct_expressed=(gene_symbol, lambda x: (x > 0).mean() * 100),
        n_cells=(gene_symbol, "count")
    ).sort_values("mean_expr", ascending=False)

    print(summary.head(10))

Multi-Gene Query

genes_of_interest = ["INS", "GCG", "SST", "PPY"]  # Islet hormones

with cellxgene_census.open_soma() as census:
    gene_filter = " or ".join([f"feature_name == '{g}'" for g in genes_of_interest])

    adata = cellxgene_census.get_anndata(
        census,
        organism="Homo sapiens",
        var_value_filter=gene_filter,
        obs_value_filter="tissue_general == 'pancreas'",
        obs_column_names=["cell_type", "tissue", "disease"]
    )

Query by Cell Ontology Term

# More precise than tissue — query specific cell types
with cellxgene_census.open_soma() as census:
    adata = cellxgene_census.get_anndata(
        census,
        organism="Homo sapiens",
        var_value_filter="feature_name == 'INS'",
        obs_value_filter="cell_type == 'type B pancreatic cell'",  # Cell Ontology term for beta cells
        obs_column_names=["cell_type", "tissue", "disease", "sex"]
    )

Step 3: Map CellxGene Cell Types to ENCODE Biosamples

CellxGene uses Cell Ontology (CL) terms. ENCODE uses its own biosample ontology. Key mappings:

CellxGene Cell Type (CL term) ENCODE Biosample Notes
type B pancreatic cell pancreatic beta cell Beta cells
hepatocyte hepatocyte Direct match
CD4-positive, alpha-beta T cell CD4+ T cell ENCODE may have more specific subtypes
monocyte monocyte Direct match
excitatory neuron neuron ENCODE may use broader category
oligodendrocyte oligodendrocyte Direct match
fibroblast fibroblast Direct match
endothelial cell endothelial cell of umbilical vein (HUVEC) ENCODE often uses HUVEC cell line
erythrocyte K562 (CML, erythroid features) K562 is a proxy, not primary

Getting Available Cell Types for a Tissue

with cellxgene_census.open_soma() as census:
    # Get all cell types observed in pancreas
    obs_df = cellxgene_census.get_obs(
        census,
        organism="Homo sapiens",
        value_filter="tissue_general == 'pancreas'",
        column_names=["cell_type"]
    )
    cell_types = obs_df["cell_type"].value_counts()
    print(cell_types)

Step 4: Interpret Cell-Type Expression in ENCODE Context

Interpretation Framework

IF gene is expressed in only ONE cell type in the tissue:
    -> Bulk ENCODE peak near that gene likely reflects that cell type
    -> Example: INS expressed only in beta cells -> pancreas H3K27ac peak at INS is beta-cell-driven

IF gene is expressed in MULTIPLE cell types:
    -> Bulk ENCODE peak could be from any contributing cell type
    -> Need additional evidence (cell-type-specific TF, scATAC-seq) to resolve

IF gene is expressed at low levels in the dominant cell type:
    -> Bulk signal may be weak despite real expression
    -> Example: A gene at 100 TPM in beta cells (2% of pancreas) shows ~2 TPM in bulk

IF gene is NOT expressed in any cell type in the tissue:
    -> ENCODE peak near that gene likely regulates a DIFFERENT gene
    -> Check other nearby genes, or consider long-range regulation

Estimating Bulk Signal Contribution

# Simple deconvolution estimate
# If beta cells = 2% of pancreas, and INS = 500 TPM in beta cells:
# Expected bulk signal contribution = 0.02 * 500 = 10 TPM
# This matches GTEx pancreas INS ~400 TPM (higher due to actual beta cell fraction ~5-10%)

cell_fraction = 0.05  # estimated fraction of cell type in tissue
sc_expression = 500   # TPM in the specific cell type
estimated_bulk = cell_fraction * sc_expression

Step 5: Cross-Reference with ENCODE scATAC-seq

ENCODE has single-cell ATAC-seq data for some tissues. These provide cell-type-resolved chromatin accessibility that directly complements CellxGene scRNA-seq.

# Find ENCODE single-cell data
encode_search_experiments(
    assay_title="snATAC-seq",
    organ="pancreas"
)

encode_search_experiments(
    assay_title="scRNA-seq",
    organ="pancreas"
)

When both ENCODE scATAC-seq and CellxGene scRNA-seq are available for the same tissue:

  1. Use CellxGene to identify which cell types express the gene
  2. Use ENCODE scATAC-seq to confirm chromatin accessibility at the regulatory element in those cell types
  3. Convergent evidence (expression + accessibility in same cell type) is strongest

Step 6: Present Results

Cell-Type Expression Summary Table

Cell Type N Cells Mean Expression % Expressing ENCODE Biosample Available Bulk Contribution
type B pancreatic cell 12,456 487.3 92% pancreatic beta cell (limited) ~24 TPM (5% fraction)
acinar cell 45,678 0.1 2% pancreas tissue (bulk) ~0.08 TPM
ductal cell 8,901 0.0 0% — 0 TPM
alpha cell 9,234 0.0 0% — 0 TPM

Key Numbers to Report

  • Gene queried and tissue
  • Total cells analyzed and number of datasets
  • Number of cell types with expression (> threshold)
  • Dominant cell type and its expression level
  • Estimated contribution to bulk ENCODE signal
  • Whether ENCODE has cell-type-specific data for validation

Pitfalls & Edge Cases

  • Cell type ontology inconsistency: Different datasets in CellxGene use different cell type annotation schemes. "Macrophage" in one dataset may be labeled "M1 macrophage" or "tissue-resident macrophage" in another. Use Cell Ontology IDs for consistent matching.
  • Batch effects across studies: CellxGene aggregates data from many labs. Direct comparison of expression values across datasets requires batch correction (Harmony, scVI). Raw counts are NOT comparable.
  • Sparse single-cell data: scRNA-seq has high dropout rates. A gene showing 0 expression in a cell may still be expressed — zero does not mean absent. Use imputation cautiously.
  • Species mismatch with ENCODE: CellxGene contains both human and mouse data. Ensure you match the species when cross-referencing with ENCODE experiments. Gene symbols may differ between species.
  • Dataset size affects resolution: Large datasets (>100K cells) can resolve rare cell types that small datasets miss. Check dataset size before concluding a cell type is absent.

Walkthrough: Single-Cell Resolution for ENCODE Bulk Epigenomic Data

Goal: Use CellxGene single-cell RNA-seq atlases to deconvolve which cell types within a tissue contribute to ENCODE bulk epigenomic signals. Context: ENCODE bulk ChIP-seq/ATAC-seq captures signals from all cell types in a tissue. CellxGene reveals the cellular composition.

Step 1: Find ENCODE bulk experiments for a tissue

encode_search_experiments(assay_title="ATAC-seq", organ="lung", organism="Homo sapiens")

Expected output:

{
  "results": [
    {"accession": "ENCSR500LNG", "assay_title": "ATAC-seq", "biosample_summary": "lung", "organ": "lung", "status": "released"}
  ],
  "total": 14,
  "limit": 25,
  "offset": 0,
  "has_more": false,
  "next_offset": null
}

Step 2: Query CellxGene for lung cell types

Using CellxGene Census API (via skill guidance):

import cellxgene_census
census = cellxgene_census.open_soma()
lung_cells = census["census_data"]["homo_sapiens"].obs.read(
    value_filter="tissue_general == 'lung'",
    column_names=["cell_type", "tissue"]
).concat().to_pandas()
lung_cells["cell_type"].value_counts().head(10)

Expected output:

AT2 cell                 45,230
macrophage               32,100
endothelial cell         28,450
AT1 cell                 22,890
fibroblast               18,670
ciliated cell            15,320
basal cell                9,850
club cell                 7,200
NK cell                   6,100
dendritic cell            4,800

Interpretation: AT2 cells dominate (45K cells) — bulk ATAC-seq signal likely reflects AT2 accessibility primarily. Immune cells (macrophages, NK, dendritic) contribute ~25% of cells.

Step 3: Identify cell-type markers for deconvolution

For each cell type, identify marker genes with high expression specificity. Use these to estimate which fraction of the ENCODE bulk signal comes from each cell type.

Step 4: Cross-reference with ENCODE single-cell data

encode_search_experiments(assay_title="snATAC-seq", organ="lung", organism="Homo sapiens")

Expected output:

{
  "results": [
    {"accession": "ENCSR600SCA", "assay_title": "snATAC-seq", "biosample_summary": "lung", "organ": "lung", "status": "released"}
  ],
  "total": 4,
  "limit": 25,
  "offset": 0,
  "has_more": false,
  "next_offset": null
}

Interpretation: 4 snATAC-seq experiments available in lung. Compare cell-type accessibility profiles from snATAC-seq with the bulk ATAC-seq to validate deconvolution estimates.

Integration with downstream skills

  • Cell-type composition informs compare-biosamples interpretation of tissue differences
  • Cell-type markers feed into gtex-expression for bulk deconvolution validation
  • Cell-type-specific peaks from scATAC-seq integrate with regulatory-elements
  • Cell-type proportions inform disease-research for cell-type-specific disease mechanisms

Code Examples

1. Find ENCODE single-cell experiments for CellxGene comparison

encode_search_experiments(assay_title="scRNA-seq", organ="brain", organism="Homo sapiens")

Expected output:

{
  "results": [
    {"accession": "ENCSR700SCR", "assay_title": "scRNA-seq", "biosample_summary": "brain", "organ": "brain", "status": "released"}
  ],
  "total": 22,
  "limit": 25,
  "offset": 0,
  "has_more": false,
  "next_offset": null
}

2. Survey single-cell data availability

encode_get_facets(assay_title="scRNA-seq", organism="Homo sapiens")

Expected output:

{
  "biosample_ontology.organ_slims": [
    {"term": "brain", "count": 22},
    {"term": "blood", "count": 15},
    {"term": "lung", "count": 8}
  ]
}

3. Compare bulk vs single-cell experiments

encode_compare_experiments(accession1="ENCSR500LNG", accession2="ENCSR600SCA")

Expected output:

{
  "experiment_1": {
    "accession": "ENCSR500LNG",
    "assay": "ATAC-seq",
    "biosample": "lung"
  },
  "experiment_2": {
    "accession": "ENCSR600SCA",
    "assay": "snATAC-seq",
    "biosample": "lung"
  },
  "verdict": "COMPATIBLE_WITH_CAVEATS",
  "recommendation": "These experiments can be compared, but the warnings should be addressed in your analysis.",
  "compatible_aspects": [
    "Same organism: Homo sapiens",
    "Same organ: lung"
  ],
  "issues": [],
  "warnings": [
    "Different assay types: ATAC-seq vs snATAC-seq. Multi-omic integration may be needed."
  ]
}

Integration

This skill produces... Feed into... Purpose
Cell-type composition estimates compare-biosamples Explain tissue differences by cellular composition
Cell-type marker genes gtex-expression Validate markers against GTEx bulk expression
Cell-type-specific gene sets peak-annotation Assign peaks to cell-type-specific genes
Deconvolution proportions disease-research Identify disease-relevant cell types within tissues
Single-cell expression matrix scrna-meta-analysis Integrate CellxGene data with ENCODE scRNA-seq
Cell-type-resolved enhancers regulatory-elements Map cCREs to specific cell types
Cell-type abundance data visualization-workflow Generate UMAP/t-SNE plots alongside epigenomic data

Presenting Results

When reporting CellxGene expression context:

  • Expression table: Present a table with columns: cell_type, mean_expression, pct_expressing, n_cells, and tissue_source for the queried gene(s)
  • Dataset metadata: Report the CellxGene Census version/snapshot date, organism, tissue filter applied, and whether disease samples were included or excluded
  • Key fields to include: Gene symbol, Ensembl ID, tissue of origin, number of datasets contributing, and total cells queried
  • Always report: Whether expression values are raw counts or normalized (log1p), the obs_value_filter used, and any cell type ontology terms (CL IDs) for reproducibility
  • Context to provide: Note that cross-dataset expression comparisons are affected by protocol differences (10x v2 vs v3 vs Smart-seq2) and that presence/absence is more robust than quantitative levels across studies
  • Next steps: Suggest single-cell-encode for ENCODE-specific scRNA-seq data, or gtex-expression for complementary bulk tissue expression context

Related Skills

  • single-cell-encode — Working with ENCODE's own single-cell data (scATAC-seq, scRNA-seq)
  • regulatory-elements — Characterizing the bulk ENCODE regulatory elements that CellxGene contextualizes
  • gtex-expression — Bulk tissue expression from GTEx (complements CellxGene single-cell)
  • cross-reference — Linking ENCODE experiments to external databases
  • compare-biosamples — Comparing ENCODE data across biosamples informed by cell-type composition
  • epigenome-profiling — Building tissue epigenomic profiles informed by cell-type context
  • publication-trust — Verify literature claims backing analytical decisions

For the request: "$ARGUMENTS"

Files (encode-toolkit)
  • references
    • literature.md 10.9 KB
      Loading…
  • SKILL.md 19.6 KB
    ---
    name: cellxgene-context
    description: "Guide for integrating CellxGene Census single-cell data with ENCODE bulk experiments. Use when users need cell-type-specific expression context for ENCODE regulatory data, want to deconvolve bulk ENCODE signals, or validate regulatory elements at single-cell resolution. Trigger on: CellxGene, single-cell atlas, cell type expression, Census, cell type specificity, single-cell context, scRNA-seq atlas."
    ---
    
    # Integrating CellxGene Census Single-Cell Data with ENCODE Bulk Experiments
    
    Bridge bulk ENCODE functional genomics data with cell-type-specific expression from the CellxGene Census, the largest unified single-cell RNA-seq atlas, to resolve cell-type contributions to regulatory element activity.
    
    ## Scientific Rationale
    
    **The question**: "Which specific cell types within my tissue drive the regulatory signals I see in bulk ENCODE data?"
    
    ENCODE provides deeply sequenced bulk functional genomics (ChIP-seq, ATAC-seq, Hi-C) across hundreds of biosamples. But bulk data from a tissue like "pancreas" is a mixture of acinar cells (~80%), duct cells (~10%), endocrine cells (~5%), and others. An H3K27ac peak in bulk pancreas could be driven by any of these cell types. CellxGene Census provides cell-type-resolved expression data from 50M+ single-cell observations across thousands of datasets, enabling deconvolution of bulk ENCODE signals.
    
    ### The Bulk-to-Single-Cell Bridge
    
    | Bulk ENCODE Signal | Single-Cell Question | CellxGene Answer |
    |-------------------|---------------------|-----------------|
    | H3K27ac peak near INS gene in pancreas | Which cell type expresses INS? | Beta cells (>500 TPM), not acinar (<1 TPM) |
    | ATAC-seq peak in liver near ALB | Is this hepatocyte-specific? | Yes — ALB expressed only in hepatocytes |
    | Enhancer active in brain cortex | Neurons or glia? | CellxGene resolves excitatory neurons vs. astrocytes vs. oligodendrocytes |
    | Broad H3K27ac domain in blood | Which immune cell type? | Can distinguish T cells, B cells, monocytes, NK cells |
    
    ### What CellxGene Census Provides
    
    - **50M+ single-cell observations** from thousands of published datasets
    - **Standardized cell ontology** (Cell Ontology terms) across all datasets
    - **Unified gene expression** in a consistent format
    - **Metadata**: tissue, disease status, sex, ethnicity, developmental stage
    - **API access** via Python (`cellxgene-census`) or R (`cellxgene.census`)
    - **No authentication required** for public data
    
    ## Key Literature
    
    - **Megill et al. 2021** "cellxgene: a performant, scalable exploration platform for high dimensional sparse matrices" (bioRxiv preprint). Describes the CellxGene platform architecture and exploration capabilities. [DOI: 10.1101/2021.04.05.438318](https://doi.org/10.1101/2021.04.05.438318)
    - **CZ CELLxGENE Discover** (Chan Zuckerberg Initiative, 2023). CellxGene Census provides programmatic access to the entire CellxGene data corpus as a single unified dataset. [https://cellxgene.cziscience.com/](https://cellxgene.cziscience.com/)
    - **Regev et al. 2017** "The Human Cell Atlas" (eLife, ~1,500 citations). The vision paper for comprehensive single-cell reference maps of all human cells. CellxGene Census is the largest realization of this vision. [DOI: 10.7554/eLife.27041](https://doi.org/10.7554/eLife.27041)
    - **Tabula Sapiens Consortium 2022** "The Tabula Sapiens: A multiple-organ, single-cell transcriptomic atlas of humans" (Science, ~800 citations). Multi-organ human cell atlas contributing to CellxGene Census. [DOI: 10.1126/science.abl4896](https://doi.org/10.1126/science.abl4896)
    - **ENCODE Project Consortium 2020** (Nature, ~1,656 citations). The bulk regulatory element catalog that CellxGene single-cell data contextualizes. [DOI: 10.1038/s41586-020-2493-4](https://doi.org/10.1038/s41586-020-2493-4)
    
    ## When to Use This Skill
    
    | Scenario | How CellxGene Helps |
    |---------|-------------------|
    | Bulk ENCODE peak near a gene — which cell type? | Query gene expression by cell type in matching tissue |
    | ENCODE enhancer active in tissue X — cell-type-specific? | Check if enhancer target gene is restricted to one cell type |
    | Choosing ENCODE cell line as proxy | Verify which primary cell type the cell line best represents |
    | Interpreting differential peaks between tissues | Determine if difference is due to cell-type composition |
    | Validating ENCODE scATAC-seq findings | Cross-reference with CellxGene scRNA-seq for same cell types |
    | Designing follow-up experiments | Identify which cell types to isolate for validation |
    
    ## Python API Reference
    
    ### Installation
    
    ```bash
    pip install cellxgene-census
    ```
    
    Requires Python 3.8+. The package uses TileDB-SOMA for efficient data access.
    
    ### Core API Pattern
    
    ```python
    import cellxgene_census
    
    # Open the Census (reads metadata, does not download all data)
    with cellxgene_census.open_soma() as census:
        # Access human data
        human = census["census_data"]["homo_sapiens"]
    
        # Query specific genes in specific tissues/cell types
        # This is where filtering happens — be specific to control memory
    ```
    
    ## Step 1: Identify the ENCODE Target Gene
    
    Start from an ENCODE finding — a regulatory element near a gene of interest:
    
    ```
    # Find enhancers in pancreas
    encode_search_experiments(
        assay_title="Histone ChIP-seq",
        target="H3K27ac",
        organ="pancreas",
        biosample_type="tissue"
    )
    
    # Get peaks
    encode_list_files(
        experiment_accession="ENCSR...",
        file_format="bed",
        output_type="IDR thresholded peaks",
        assembly="GRCh38"
    )
    ```
    
    From peaks, identify the nearest gene(s). You need the gene symbol or Ensembl ID.
    
    ## Step 2: Query CellxGene Census for Cell-Type Expression
    
    ### Basic Gene Expression Query
    
    ```python
    import cellxgene_census
    import pandas as pd
    
    gene_symbol = "INS"  # Insulin — example for pancreas
    
    with cellxgene_census.open_soma() as census:
        human = census["census_data"]["homo_sapiens"]
    
        # Get expression for INS in pancreas tissue
        # Use obs_value_filter to restrict to pancreas
        # Use var_value_filter to restrict to the gene
        adata = cellxgene_census.get_anndata(
            census,
            organism="Homo sapiens",
            var_value_filter=f"feature_name == '{gene_symbol}'",
            obs_value_filter="tissue_general == 'pancreas'",
            obs_column_names=["cell_type", "tissue", "disease", "dataset_id"]
        )
    
        # Summarize expression by cell type
        expr_by_celltype = adata.to_df().join(adata.obs["cell_type"])
        summary = expr_by_celltype.groupby("cell_type").agg(
            mean_expr=(gene_symbol, "mean"),
            pct_expressed=(gene_symbol, lambda x: (x > 0).mean() * 100),
            n_cells=(gene_symbol, "count")
        ).sort_values("mean_expr", ascending=False)
    
        print(summary.head(10))
    ```
    
    ### Multi-Gene Query
    
    ```python
    genes_of_interest = ["INS", "GCG", "SST", "PPY"]  # Islet hormones
    
    with cellxgene_census.open_soma() as census:
        gene_filter = " or ".join([f"feature_name == '{g}'" for g in genes_of_interest])
    
        adata = cellxgene_census.get_anndata(
            census,
            organism="Homo sapiens",
            var_value_filter=gene_filter,
            obs_value_filter="tissue_general == 'pancreas'",
            obs_column_names=["cell_type", "tissue", "disease"]
        )
    ```
    
    ### Query by Cell Ontology Term
    
    ```python
    # More precise than tissue — query specific cell types
    with cellxgene_census.open_soma() as census:
        adata = cellxgene_census.get_anndata(
            census,
            organism="Homo sapiens",
            var_value_filter="feature_name == 'INS'",
            obs_value_filter="cell_type == 'type B pancreatic cell'",  # Cell Ontology term for beta cells
            obs_column_names=["cell_type", "tissue", "disease", "sex"]
        )
    ```
    
    ## Step 3: Map CellxGene Cell Types to ENCODE Biosamples
    
    CellxGene uses Cell Ontology (CL) terms. ENCODE uses its own biosample ontology. Key mappings:
    
    | CellxGene Cell Type (CL term) | ENCODE Biosample | Notes |
    |-------------------------------|-----------------|-------|
    | type B pancreatic cell | pancreatic beta cell | Beta cells |
    | hepatocyte | hepatocyte | Direct match |
    | CD4-positive, alpha-beta T cell | CD4+ T cell | ENCODE may have more specific subtypes |
    | monocyte | monocyte | Direct match |
    | excitatory neuron | neuron | ENCODE may use broader category |
    | oligodendrocyte | oligodendrocyte | Direct match |
    | fibroblast | fibroblast | Direct match |
    | endothelial cell | endothelial cell of umbilical vein (HUVEC) | ENCODE often uses HUVEC cell line |
    | erythrocyte | K562 (CML, erythroid features) | K562 is a proxy, not primary |
    
    ### Getting Available Cell Types for a Tissue
    
    ```python
    with cellxgene_census.open_soma() as census:
        # Get all cell types observed in pancreas
        obs_df = cellxgene_census.get_obs(
            census,
            organism="Homo sapiens",
            value_filter="tissue_general == 'pancreas'",
            column_names=["cell_type"]
        )
        cell_types = obs_df["cell_type"].value_counts()
        print(cell_types)
    ```
    
    ## Step 4: Interpret Cell-Type Expression in ENCODE Context
    
    ### Interpretation Framework
    
    ```
    IF gene is expressed in only ONE cell type in the tissue:
        -> Bulk ENCODE peak near that gene likely reflects that cell type
        -> Example: INS expressed only in beta cells -> pancreas H3K27ac peak at INS is beta-cell-driven
    
    IF gene is expressed in MULTIPLE cell types:
        -> Bulk ENCODE peak could be from any contributing cell type
        -> Need additional evidence (cell-type-specific TF, scATAC-seq) to resolve
    
    IF gene is expressed at low levels in the dominant cell type:
        -> Bulk signal may be weak despite real expression
        -> Example: A gene at 100 TPM in beta cells (2% of pancreas) shows ~2 TPM in bulk
    
    IF gene is NOT expressed in any cell type in the tissue:
        -> ENCODE peak near that gene likely regulates a DIFFERENT gene
        -> Check other nearby genes, or consider long-range regulation
    ```
    
    ### Estimating Bulk Signal Contribution
    
    ```python
    # Simple deconvolution estimate
    # If beta cells = 2% of pancreas, and INS = 500 TPM in beta cells:
    # Expected bulk signal contribution = 0.02 * 500 = 10 TPM
    # This matches GTEx pancreas INS ~400 TPM (higher due to actual beta cell fraction ~5-10%)
    
    cell_fraction = 0.05  # estimated fraction of cell type in tissue
    sc_expression = 500   # TPM in the specific cell type
    estimated_bulk = cell_fraction * sc_expression
    ```
    
    ## Step 5: Cross-Reference with ENCODE scATAC-seq
    
    ENCODE has single-cell ATAC-seq data for some tissues. These provide cell-type-resolved chromatin accessibility that directly complements CellxGene scRNA-seq.
    
    ```
    # Find ENCODE single-cell data
    encode_search_experiments(
        assay_title="snATAC-seq",
        organ="pancreas"
    )
    
    encode_search_experiments(
        assay_title="scRNA-seq",
        organ="pancreas"
    )
    ```
    
    When both ENCODE scATAC-seq and CellxGene scRNA-seq are available for the same tissue:
    1. Use CellxGene to identify which cell types express the gene
    2. Use ENCODE scATAC-seq to confirm chromatin accessibility at the regulatory element in those cell types
    3. Convergent evidence (expression + accessibility in same cell type) is strongest
    
    ## Step 6: Present Results
    
    ### Cell-Type Expression Summary Table
    
    | Cell Type | N Cells | Mean Expression | % Expressing | ENCODE Biosample Available | Bulk Contribution |
    |-----------|---------|----------------|-------------|---------------------------|-------------------|
    | type B pancreatic cell | 12,456 | 487.3 | 92% | pancreatic beta cell (limited) | ~24 TPM (5% fraction) |
    | acinar cell | 45,678 | 0.1 | 2% | pancreas tissue (bulk) | ~0.08 TPM |
    | ductal cell | 8,901 | 0.0 | 0% | — | 0 TPM |
    | alpha cell | 9,234 | 0.0 | 0% | — | 0 TPM |
    
    ### Key Numbers to Report
    
    - Gene queried and tissue
    - Total cells analyzed and number of datasets
    - Number of cell types with expression (> threshold)
    - Dominant cell type and its expression level
    - Estimated contribution to bulk ENCODE signal
    - Whether ENCODE has cell-type-specific data for validation
    
    ## Pitfalls & Edge Cases
    
    - **Cell type ontology inconsistency**: Different datasets in CellxGene use different cell type annotation schemes. "Macrophage" in one dataset may be labeled "M1 macrophage" or "tissue-resident macrophage" in another. Use Cell Ontology IDs for consistent matching.
    - **Batch effects across studies**: CellxGene aggregates data from many labs. Direct comparison of expression values across datasets requires batch correction (Harmony, scVI). Raw counts are NOT comparable.
    - **Sparse single-cell data**: scRNA-seq has high dropout rates. A gene showing 0 expression in a cell may still be expressed — zero does not mean absent. Use imputation cautiously.
    - **Species mismatch with ENCODE**: CellxGene contains both human and mouse data. Ensure you match the species when cross-referencing with ENCODE experiments. Gene symbols may differ between species.
    - **Dataset size affects resolution**: Large datasets (>100K cells) can resolve rare cell types that small datasets miss. Check dataset size before concluding a cell type is absent.
    
    ## Walkthrough: Single-Cell Resolution for ENCODE Bulk Epigenomic Data
    
    **Goal**: Use CellxGene single-cell RNA-seq atlases to deconvolve which cell types within a tissue contribute to ENCODE bulk epigenomic signals.
    **Context**: ENCODE bulk ChIP-seq/ATAC-seq captures signals from all cell types in a tissue. CellxGene reveals the cellular composition.
    
    ### Step 1: Find ENCODE bulk experiments for a tissue
    
    ```
    encode_search_experiments(assay_title="ATAC-seq", organ="lung", organism="Homo sapiens")
    ```
    
    Expected output:
    ```json
    {
      "results": [
        {"accession": "ENCSR500LNG", "assay_title": "ATAC-seq", "biosample_summary": "lung", "organ": "lung", "status": "released"}
      ],
      "total": 14,
      "limit": 25,
      "offset": 0,
      "has_more": false,
      "next_offset": null
    }
    ```
    
    ### Step 2: Query CellxGene for lung cell types
    
    Using CellxGene Census API (via skill guidance):
    ```python
    import cellxgene_census
    census = cellxgene_census.open_soma()
    lung_cells = census["census_data"]["homo_sapiens"].obs.read(
        value_filter="tissue_general == 'lung'",
        column_names=["cell_type", "tissue"]
    ).concat().to_pandas()
    lung_cells["cell_type"].value_counts().head(10)
    ```
    
    Expected output:
    ```
    AT2 cell                 45,230
    macrophage               32,100
    endothelial cell         28,450
    AT1 cell                 22,890
    fibroblast               18,670
    ciliated cell            15,320
    basal cell                9,850
    club cell                 7,200
    NK cell                   6,100
    dendritic cell            4,800
    ```
    
    **Interpretation**: AT2 cells dominate (45K cells) — bulk ATAC-seq signal likely reflects AT2 accessibility primarily. Immune cells (macrophages, NK, dendritic) contribute ~25% of cells.
    
    ### Step 3: Identify cell-type markers for deconvolution
    
    For each cell type, identify marker genes with high expression specificity. Use these to estimate which fraction of the ENCODE bulk signal comes from each cell type.
    
    ### Step 4: Cross-reference with ENCODE single-cell data
    
    ```
    encode_search_experiments(assay_title="snATAC-seq", organ="lung", organism="Homo sapiens")
    ```
    
    Expected output:
    ```json
    {
      "results": [
        {"accession": "ENCSR600SCA", "assay_title": "snATAC-seq", "biosample_summary": "lung", "organ": "lung", "status": "released"}
      ],
      "total": 4,
      "limit": 25,
      "offset": 0,
      "has_more": false,
      "next_offset": null
    }
    ```
    
    **Interpretation**: 4 snATAC-seq experiments available in lung. Compare cell-type accessibility profiles from snATAC-seq with the bulk ATAC-seq to validate deconvolution estimates.
    
    ### Integration with downstream skills
    - Cell-type composition informs **compare-biosamples** interpretation of tissue differences
    - Cell-type markers feed into **gtex-expression** for bulk deconvolution validation
    - Cell-type-specific peaks from scATAC-seq integrate with **regulatory-elements**
    - Cell-type proportions inform **disease-research** for cell-type-specific disease mechanisms
    
    ## Code Examples
    
    ### 1. Find ENCODE single-cell experiments for CellxGene comparison
    ```
    encode_search_experiments(assay_title="scRNA-seq", organ="brain", organism="Homo sapiens")
    ```
    
    Expected output:
    ```json
    {
      "results": [
        {"accession": "ENCSR700SCR", "assay_title": "scRNA-seq", "biosample_summary": "brain", "organ": "brain", "status": "released"}
      ],
      "total": 22,
      "limit": 25,
      "offset": 0,
      "has_more": false,
      "next_offset": null
    }
    ```
    
    ### 2. Survey single-cell data availability
    ```
    encode_get_facets(assay_title="scRNA-seq", organism="Homo sapiens")
    ```
    
    Expected output:
    ```json
    {
      "biosample_ontology.organ_slims": [
        {"term": "brain", "count": 22},
        {"term": "blood", "count": 15},
        {"term": "lung", "count": 8}
      ]
    }
    ```
    
    ### 3. Compare bulk vs single-cell experiments
    ```
    encode_compare_experiments(accession1="ENCSR500LNG", accession2="ENCSR600SCA")
    ```
    
    Expected output:
    ```json
    {
      "experiment_1": {
        "accession": "ENCSR500LNG",
        "assay": "ATAC-seq",
        "biosample": "lung"
      },
      "experiment_2": {
        "accession": "ENCSR600SCA",
        "assay": "snATAC-seq",
        "biosample": "lung"
      },
      "verdict": "COMPATIBLE_WITH_CAVEATS",
      "recommendation": "These experiments can be compared, but the warnings should be addressed in your analysis.",
      "compatible_aspects": [
        "Same organism: Homo sapiens",
        "Same organ: lung"
      ],
      "issues": [],
      "warnings": [
        "Different assay types: ATAC-seq vs snATAC-seq. Multi-omic integration may be needed."
      ]
    }
    ```
    
    ## Integration
    
    | This skill produces... | Feed into... | Purpose |
    |---|---|---|
    | Cell-type composition estimates | **compare-biosamples** | Explain tissue differences by cellular composition |
    | Cell-type marker genes | **gtex-expression** | Validate markers against GTEx bulk expression |
    | Cell-type-specific gene sets | **peak-annotation** | Assign peaks to cell-type-specific genes |
    | Deconvolution proportions | **disease-research** | Identify disease-relevant cell types within tissues |
    | Single-cell expression matrix | **scrna-meta-analysis** | Integrate CellxGene data with ENCODE scRNA-seq |
    | Cell-type-resolved enhancers | **regulatory-elements** | Map cCREs to specific cell types |
    | Cell-type abundance data | **visualization-workflow** | Generate UMAP/t-SNE plots alongside epigenomic data |
    
    ## Presenting Results
    
    When reporting CellxGene expression context:
    
    - **Expression table**: Present a table with columns: cell_type, mean_expression, pct_expressing, n_cells, and tissue_source for the queried gene(s)
    - **Dataset metadata**: Report the CellxGene Census version/snapshot date, organism, tissue filter applied, and whether disease samples were included or excluded
    - **Key fields to include**: Gene symbol, Ensembl ID, tissue of origin, number of datasets contributing, and total cells queried
    - **Always report**: Whether expression values are raw counts or normalized (log1p), the `obs_value_filter` used, and any cell type ontology terms (CL IDs) for reproducibility
    - **Context to provide**: Note that cross-dataset expression comparisons are affected by protocol differences (10x v2 vs v3 vs Smart-seq2) and that presence/absence is more robust than quantitative levels across studies
    - **Next steps**: Suggest `single-cell-encode` for ENCODE-specific scRNA-seq data, or `gtex-expression` for complementary bulk tissue expression context
    
    ## Related Skills
    
    - `single-cell-encode` — Working with ENCODE's own single-cell data (scATAC-seq, scRNA-seq)
    - `regulatory-elements` — Characterizing the bulk ENCODE regulatory elements that CellxGene contextualizes
    - `gtex-expression` — Bulk tissue expression from GTEx (complements CellxGene single-cell)
    - `cross-reference` — Linking ENCODE experiments to external databases
    - `compare-biosamples` — Comparing ENCODE data across biosamples informed by cell-type composition
    - `epigenome-profiling` — Building tissue epigenomic profiles informed by cell-type context
    - `publication-trust` — Verify literature claims backing analytical decisions
    
    ## For the request: "$ARGUMENTS"
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.