cellxgene-census

CZ CELLxGENE Census

概要

CZ CELLxGENE Census は、CZ CELLxGENE Discover 由来の、バージョン管理された包括的な標準化シングルセルゲノミクスデータのコレクションへのプログラムによるアクセスを提供します。このスキルにより、数千のデータセットにまたがる数百万の細胞を効率的にクエリおよび分析できます。

Census には次のものが含まれます:

• 6,100 万以上の細胞（ヒトおよびマウス由来）
• 標準化されたメタデータ（細胞型、組織、疾患、ドナー）
• 生の遺伝子発現マトリックス
• 事前計算された埋め込みと統計量
• PyTorch、scanpy、その他の分析ツールとの統合

このスキルを使用するタイミング

このスキルは、次の場合に使用してください:

• 細胞型、組織、または疾患によってシングルセル発現データをクエリする場合
• 利用可能なシングルセルデータセットとメタデータを調べる場合
• シングルセルデータで機械学習モデルを学習させる場合
• 大規模なデータセット横断分析を実行する場合
• Census データを scanpy などの分析フレームワークと統合する場合
• 数百万の細胞にわたる統計量を計算する場合
• 事前計算された埋め込みやモデルの予測結果にアクセスする場合

インストールとセットアップ

Census API をインストールします:

uv pip install cellxgene-census

機械学習ワークフロー向けに、追加の依存関係をインストールします:

uv pip install cellxgene-census[experimental]

主要なワークフローパターン

1. Census を開く

リソースが適切にクリーンアップされるよう、常にコンテキストマネージャーを使用してください:

import cellxgene_census

# Open latest stable version
with cellxgene_census.open_soma() as census:
    # Work with census data

# Open specific version for reproducibility
with cellxgene_census.open_soma(census_version="2023-07-25") as census:
    # Work with census data

要点:

• 自動クリーンアップのためにコンテキストマネージャー（with 文）を使用します
• 再現可能な分析のために census_version を指定します
• デフォルトでは最新の「stable」リリースが開かれます

2. Census 情報の確認

発現データをクエリする前に、利用可能なデータセットとメタデータを確認してください。

概要情報にアクセスする:

# Get summary statistics
summary = census["census_info"]["summary"].read().concat().to_pandas()
print(f"Total cells: {summary['total_cell_count'][0]}")

# Get all datasets
datasets = census["census_info"]["datasets"].read().concat().to_pandas()

# Filter datasets by criteria
covid_datasets = datasets[datasets["disease"].str.contains("COVID", na=False)]

利用可能なデータを把握するために細胞メタデータをクエリする:

# Get unique cell types in a tissue
cell_metadata = cellxgene_census.get_obs(
    census,
    "homo_sapiens",
    value_filter="tissue_general == 'brain' and is_primary_data == True",
    column_names=["cell_type"]
)
unique_cell_types = cell_metadata["cell_type"].unique()
print(f"Found {len(unique_cell_types)} cell types in brain")

# Count cells by tissue
tissue_counts = cell_metadata.groupby("tissue_general").size()

重要: 重複した細胞を数えないよう、特に重複を分析する場合を除き、常に is_primary_data == True でフィルタリングしてください。

3. 発現データのクエリ（小～中規模）

結果が 10 万細胞未満でメモリに収まるクエリには、get_anndata() を使用します:

# Basic query with cell type and tissue filters
adata = cellxgene_census.get_anndata(
    census=census,
    organism="Homo sapiens",  # or "Mus musculus"
    obs_value_filter="cell_type == 'B cell' and tissue_general == 'lung' and is_primary_data == True",
    obs_column_names=["assay", "disease", "sex", "donor_id"],
)

# Query specific genes with multiple filters
adata = cellxgene_census.get_anndata(
    census=census,
    organism="Homo sapiens",
    var_value_filter="feature_name in ['CD4', 'CD8A', 'CD19', 'FOXP3']",
    obs_value_filter="cell_type == 'T cell' and disease == 'COVID-19' and is_primary_data == True",
    obs_column_names=["cell_type", "tissue_general", "donor_id"],
)

フィルター構文:

• 細胞のフィルタリングには obs_value_filter を使用します
• 遺伝子のフィルタリングには var_value_filter を使用します
• 条件は and、or で組み合わせます
• 複数の値には in を使用します: tissue in ['lung', 'liver']
• obs_column_names で必要な列だけを選択します

メタデータを別途取得する:

# Query cell metadata
cell_metadata = cellxgene_census.get_obs(
    census, "homo_sapiens",
    value_filter="disease == 'COVID-19' and is_primary_data == True",
    column_names=["cell_type", "tissue_general", "donor_id"]
)

# Query gene metadata
gene_metadata = cellxgene_census.get_var(
    census, "homo_sapiens",
    value_filter="feature_name in ['CD4', 'CD8A']",
    column_names=["feature_id", "feature_name", "feature_length"]
)

4. 大規模クエリ（アウトオブコア処理）

利用可能な RAM を超えるクエリには、反復処理を伴う axis_query() を使用します:

import tiledbsoma as soma

# Create axis query
query = census["census_data"]["homo_sapiens"].axis_query(
    measurement_name="RNA",
    obs_query=soma.AxisQuery(
        value_filter="tissue_general == 'brain' and is_primary_data == True"
    ),
    var_query=soma.AxisQuery(
        value_filter="feature_name in ['FOXP2', 'TBR1', 'SATB2']"
    )
)

# Iterate through expression matrix in chunks
iterator = query.X("raw").tables()
for batch in iterator:
    # batch is a pyarrow.Table with columns:
    # - soma_data: expression value
    # - soma_dim_0: cell (obs) coordinate
    # - soma_dim_1: gene (var) coordinate
    process_batch(batch)

増分統計量の計算:

# Example: Calculate mean expression
n_observations = 0
sum_values = 0.0

iterator = query.X("raw").tables()
for batch in iterator:
    values = batch["soma_data"].to_numpy()
    n_observations += len(values)
    sum_values += values.sum()

mean_expression = sum_values / n_observations

5. PyTorch による機械学習

モデルを学習させる場合は、実験的な PyTorch 統合を使用します:

from cellxgene_census.experimental.ml import experiment_dataloader

with cellxgene_census.open_soma() as census:
    # Create dataloader
    dataloader = experiment_dataloader(
        census["census_data"]["homo_sapiens"],
        measurement_name="RNA",
        X_name="raw",
        obs_value_filter="tissue_general == 'liver' and is_primary_data == True",
        obs_column_names=["cell_type"],
        batch_size=128,
        shuffle=True,
    )

    # Training loop
    for epoch in range(num_epochs):
        for batch in dataloader:
            X = batch["X"]  # Gene expression tensor
            labels = batch["obs"]["cell_type"]  # Cell type labels

            # Forward pass
            outputs = model(X)
            loss = criterion(outputs, labels)

            # Backward pass
            optimizer.zero_grad()
            loss.backward()
            optimizer.step()

学習/テストへの分割:

from cellxgene_census.experimental.ml import ExperimentDataset

# Create dataset from experiment
dataset = ExperimentDataset(
    experiment_axis_query,
    layer_name="raw",
    obs_column_names=["cell_type"],
    batch_size=128,
)

# Split into train and test
train_dataset, test_dataset = dataset.random_split(
    split=[0.8, 0.2],
    seed=42
)

6. Scanpy との統合

Census データを scanpy のワークフローにシームレスに統合します:

import scanpy as sc

# Load data from Census
adata = cellxgene_census.get_anndata(
    census=census,
    organism="Homo sapiens",
    obs_value_filter="cell_type == 'neuron' and tissue_general == 'cortex' and is_primary_data == True",
)

# Standard scanpy workflow
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, n_top_genes=2000)

# Dimensionality reduction
sc.pp.pca(adata, n_comps=50)
sc.pp.neighbors(adata)
sc.tl.umap(adata)

# Visualization
sc.pl.umap(adata, color=["cell_type", "tissue", "disease"])

7. 複数データセットの統合

複数のデータセットをクエリして統合します:

# Strategy 1: Query multiple tissues separately
tissues = ["lung", "liver", "kidney"]
adatas = []

for tissue in tissues:
    adata = cellxgene_census.get_anndata(
        census=census,
        organism="Homo sapiens",
        obs_value_filter=f"tissue_general == '{tissue}' and is_primary_data == True",
    )
    adata.obs["tissue"] = tissue
    adatas.append(adata)

# Concatenate
combined = adatas[0].concatenate(adatas[1:])

# Strategy 2: Query multiple datasets directly
adata = cellxgene_census.get_anndata(
    census=census,
    organism="Homo sapiens",
    obs_value_filter="tissue_general in ['lung', 'liver', 'kidney'] and is_primary_data == True",
)

主要な概念とベストプラクティス

常に primary データでフィルタリングする

重複を分析する場合を除き、細胞を複数回数えないよう、クエリには常に is_primary_data == True を含めてください:

obs_value_filter="cell_type == 'B cell' and is_primary_data == True"

再現性のために Census バージョンを指定する

本番環境の分析では、必ず Census バージョンを指定してください:

census = cellxgene_census.open_soma(census_version="2023-07-25")

読み込み前にクエリサイズを見積もる

大規模なクエリでは、メモリの問題を避けるために、まず細胞数を確認してください:

# Get cell count
metadata = cellxgene_census.get_obs(
    census, "homo_sapiens",
    value_filter="tissue_general == 'brain' and is_primary_data == True",
    column_names=["soma_joinid"]
)
n_cells = len(metadata)
print(f"Query will return {n_cells:,} cells")

# If too large (>100k), use out-of-core processing

大まかなグループには tissue_general を使用する

tissue_general フィールドは tissue よりも粗いカテゴリを提供するため、組織横断的な分析に役立ちます:

# Broader grouping
obs_value_filter="tissue_general == 'immune system'"

# Specific tissue
obs_value_filter="tissue == 'peripheral blood mononuclear cell'"

必要な列だけを選択する

必要なメタデータ列のみを指定して、データ転送量を最小限に抑えてください:

obs_column_names=["cell_type", "tissue_general", "disease"]  # Not all columns

遺伝子固有のクエリではデータセットの有無を確認する

特定の遺伝子を分析する場合は、どのデータセットでその遺伝子が測定されているかを確認してください:

presence = cellxgene_census.get_presence_matrix(
    census,
    "homo_sapiens",
    var_value_filter="feature_name in ['CD4', 'CD8A']"
)

2 段階のワークフロー: 探索してからクエリする

まずメタデータを調べて利用可能なデータを把握し、その後で発現データをクエリしてください:

# Step 1: Explore what's available
metadata = cellxgene_census.get_obs(
    census, "homo_sapiens",
    value_filter="disease == 'COVID-19' and is_primary_data == True",
    column_names=["cell_type", "tissue_general"]
)
print(metadata.value_counts())

# Step 2: Query based on findings
adata = cellxgene_census.get_anndata(
    census=census,
    organism="Homo sapiens",
    obs_value_filter="disease == 'COVID-19' and cell_type == 'T cell' and is_primary_data == True",
)

利用可能なメタデータフィールド

セルメタデータ (obs)

フィルタリングに使う主要フィールド:

• cell_type, cell_type_ontology_term_id
• tissue, tissue_general, tissue_ontology_term_id
• disease, disease_ontology_term_id
• assay, assay_ontology_term_id
• donor_id, sex, self_reported_ethnicity
• development_stage, development_stage_ontology_term_id
• dataset_id
• is_primary_data (Boolean: True = 一意の細胞)

遺伝子メタデータ (var)

• feature_id (Ensembl 遺伝子 ID、例: "ENSG00000161798")
• feature_name (遺伝子シンボル、例: "FOXP2")
• feature_length (遺伝子の長さ、塩基対単位)

リファレンスドキュメント

このスキルには詳細なリファレンスドキュメントが含まれています:

references/census_schema.md

以下の詳細なドキュメント:

• Census データの構造と編成
• 利用可能なすべてのメタデータフィールド
• 値フィルターの構文と演算子
• SOMA オブジェクトの種類
• データの包含基準

参照のタイミング: 詳細なスキーマ情報、メタデータフィールドの完全な一覧、または複雑なフィルター構文が必要な場合。

references/common_patterns.md

以下の例とパターン:

• 探索的クエリ（メタデータのみ）
• 小〜中規模クエリ（AnnData）
• 大規模クエリ（アウトオブコア処理）
• PyTorch 連携
• Scanpy 連携ワークフロー
• 複数データセットの統合
• ベストプラクティスと一般的な落とし穴

参照のタイミング: 特定のクエリパターンを実装する場合、コード例を探す場合、または一般的な問題をトラブルシューティングする場合。

一般的なユースケース

ユースケース 1: 組織内の細胞種を探索する

with cellxgene_census.open_soma() as census:
    cells = cellxgene_census.get_obs(
        census, "homo_sapiens",
        value_filter="tissue_general == 'lung' and is_primary_data == True",
        column_names=["cell_type"]
    )
    print(cells["cell_type"].value_counts())

ユースケース 2: マーカー遺伝子の発現をクエリする

with cellxgene_census.open_soma() as census:
    adata = cellxgene_census.get_anndata(
        census=census,
        organism="Homo sapiens",
        var_value_filter="feature_name in ['CD4', 'CD8A', 'CD19']",
        obs_value_filter="cell_type in ['T cell', 'B cell'] and is_primary_data == True",
    )

ユースケース 3: 細胞種分類器を学習する

from cellxgene_census.experimental.ml import experiment_dataloader

with cellxgene_census.open_soma() as census:
    dataloader = experiment_dataloader(
        census["census_data"]["homo_sapiens"],
        measurement_name="RNA",
        X_name="raw",
        obs_value_filter="is_primary_data == True",
        obs_column_names=["cell_type"],
        batch_size=128,
        shuffle=True,
    )

    # Train model
    for epoch in range(epochs):
        for batch in dataloader:
            # Training logic
            pass

ユースケース 4: 組織横断的解析

with cellxgene_census.open_soma() as census:
    adata = cellxgene_census.get_anndata(
        census=census,
        organism="Homo sapiens",
        obs_value_filter="cell_type == 'macrophage' and tissue_general in ['lung', 'liver', 'brain'] and is_primary_data == True",
    )

    # Analyze macrophage differences across tissues
    sc.tl.rank_genes_groups(adata, groupby="tissue_general")

トラブルシューティング

クエリの結果となる細胞が多すぎる

• より具体的なフィルターを追加して対象範囲を絞り込む
• より細かい粒度が必要な場合は tissue_general ではなく tissue を使用する
• 既知であれば特定の dataset_id でフィルタリングする
• 大規模なクエリにはアウトオブコア処理に切り替える

メモリエラー

• より制限の厳しいフィルターでクエリの範囲を絞る
• var_value_filter で選択する遺伝子を減らす
• axis_query() を使ってアウトオブコア処理を行う
• データをバッチに分けて処理する

結果に重複した細胞がある

• フィルターには必ず is_primary_data == True を含める
• 複数のデータセットにまたがるクエリが意図したものか確認する

遺伝子が見つからない

• 遺伝子名のスペルを確認する（大文字と小文字は区別される）
• feature_name の代わりに feature_id で Ensembl ID を指定してみる
• データセットの存在マトリックスを確認し、その遺伝子が測定されたかを調べる
• Census の構築時にフィルタリングされた遺伝子もある

バージョンの不整合

• 必ず census_version を明示的に指定する
• すべての解析で同じバージョンを使用する
• バージョン固有の変更点はリリースノートで確認する