SuperAPI AI Directory

scientific-cellxgene-census

Coding & development

View repository

Updated 10-15 21:03

About this skill

Scientific CELLxGENE Census

Provides a large-scale single-cell atlas metadata search, gene expression query, cell type distribution analysis, and cross-dataset integration pipeline leveraging the CZ CELLxGENE Census API.

When to Use

  • When extracting data for a specific tissue/disease from a single-cell atlas at the scale of tens of millions of cells
  • When comparing cell type distributions across tissues
  • When searching for the expression pattern of a specific gene across the whole atlas
  • When filtering Census datasets with the metadata database
  • When efficiently retrieving large-scale data as an AnnData/Sparse matrix

Quick Start

1. Census metadata search

import cellxgene_census
import pandas as pd


def census_datasets(organism="Homo sapiens",
                      tissue=None, disease=None):
    """
    CELLxGENE Census — データセットメタデータ検索。

    Parameters:
        organism: str — 生物種
        tissue: str — 組織フィルタ
        disease: str — 疾患フィルタ
    """
    with cellxgene_census.open_soma() as census:
        datasets = census["census_info"]["datasets"].read(
        ).concat().to_pandas()

    if tissue:
        datasets = datasets[
            datasets["dataset_title"].str.contains(
                tissue, case=False, na=False)]
    if disease:
        datasets = datasets[
            datasets["dataset_title"].str.contains(
                disease, case=False, na=False)]

    print(f"Census datasets: {len(datasets)} matched")
    return datasets


def census_cell_metadata(organism="Homo sapiens",
                           tissue=None,
                           cell_type=None,
                           max_cells=10000):
    """
    CELLxGENE Census — セルメタデータ取得。

    Parameters:
        organism: str — 生物種
        tissue: str — 組織フィルタ
        cell_type: str — セルタイプフィルタ
        max_cells: int — 最大セル数
    """
    obs_filters = []
    if tissue:
        obs_filters.append(
            f"tissue_general == '{tissue}'")
    if cell_type:
        obs_filters.append(
            f"cell_type == '{cell_type}'")
    value_filter = " and ".join(obs_filters) \
        if obs_filters else None

    with cellxgene_census.open_soma() as census:
        obs_df = cellxgene_census.get_obs(
            census, organism,
            value_filter=value_filter,
            column_names=[
                "cell_type", "tissue_general",
                "disease", "sex", "development_stage",
                "dataset_id", "assay"],
        )

    df = obs_df.head(max_cells)
    print(f"Census cells: {len(df)} retrieved "
          f"(filter: {value_filter})")
    return df

2. Gene expression query

def census_gene_expression(organism="Homo sapiens",
                             gene_symbols=None,
                             tissue=None,
                             max_cells=5000):
    """
    CELLxGENE Census — 遺伝子発現データ取得。

    Parameters:
        organism: str — 生物種
        gene_symbols: list[str] — 遺伝子シンボルリスト
        tissue: str — 組織フィルタ
        max_cells: int — 最大セル数
    """
    obs_filter = (f"tissue_general == '{tissue}'"
                  if tissue else None)
    var_filter = None
    if gene_symbols:
        genes_str = "', '".join(gene_symbols)
        var_filter = f"feature_name in ['{genes_str}']"

    with cellxgene_census.open_soma() as census:
        adata = cellxgene_census.get_anndata(
            census, organism,
            obs_value_filter=obs_filter,
            var_value_filter=var_filter,
            obs_column_names=[
                "cell_type", "tissue_general",
                "disease"],
        )

    if max_cells and len(adata) > max_cells:
        import numpy as np
        idx = np.random.choice(
            len(adata), max_cells, replace=False)
        adata = adata[idx]

    print(f"Census expression: {adata.shape[0]} cells × "
          f"{adata.shape[1]} genes")
    return adata

3. Cell type distribution analysis

def celltype_distribution(organism="Homo sapiens",
                            tissue=None):
    """
    組織別セルタイプ分布解析。

    Parameters:
        organism: str — 生物種
        tissue: str — 組織フィルタ
    """
    obs_filter = (f"tissue_general == '{tissue}'"
                  if tissue else None)

    with cellxgene_census.open_soma() as census:
        obs_df = cellxgene_census.get_obs(
            census, organism,
            value_filter=obs_filter,
            column_names=["cell_type",
                          "tissue_general"],
        )

    # セルタイプカウント
    ct_counts = obs_df["cell_type"].value_counts()
    ct_df = pd.DataFrame({
        "cell_type": ct_counts.index,
        "count": ct_counts.values,
        "fraction": ct_counts.values / ct_counts.sum(),
    })

    print(f"Cell types: {len(ct_df)} types, "
          f"total {ct_counts.sum()} cells")
    return ct_df

4. Census integration pipeline

def census_pipeline(organism="Homo sapiens",
                      tissue=None,
                      gene_symbols=None,
                      output_dir="results"):
    """
    CELLxGENE Census 統合パイプライン。

    Parameters:
        organism: str — 生物種
        tissue: str — 組織
        gene_symbols: list[str] — 対象遺伝子
        output_dir: str — 出力ディレクトリ
    """
    from pathlib import Path
    output_dir = Path(output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)

    # 1) データセットメタデータ
    datasets = census_datasets(organism, tissue)
    datasets.to_csv(output_dir / "census_datasets.csv",
                    index=False)

    # 2) セルタイプ分布
    ct_dist = celltype_distribution(organism, tissue)
    ct_dist.to_csv(
        output_dir / "celltype_distribution.csv",
        index=False)

    # 3) 遺伝子発現 (指定時)
    adata = None
    if gene_symbols:
        adata = census_gene_expression(
            organism, gene_symbols, tissue)
        adata.write_h5ad(
            output_dir / "census_expression.h5ad")

    print(f"Census pipeline → {output_dir}")
    return {
        "datasets": datasets,
        "celltype_dist": ct_dist,
        "adata": adata,
    }

ToolUniverse integration

TU Key Tool name Integration details
cellxgene_census CELLxGENE Census Large-scale single-cell atlas API

Pipeline integration

human-cell-atlas → cellxgene-census → single-cell-genomics
  (HCA Portal)     (Census 大規模)     (Scanpy 解析)
       │                  │                  ↓
  spatial-multiomics ────┘      scvi-integration
    (空間統合)                   (scVI/scANVI)

Pipeline output

File Description Next skill
results/census_datasets.csv Dataset list → human-cell-atlas
results/celltype_distribution.csv Cell type distribution → single-cell-genomics
results/census_expression.h5ad Expression matrix (AnnData) → scvi-integration