cellxgene-census

CZ CELLxGENE Census

概要

CZ CELLxGENE Census は、CZ CELLxGENE Discover の標準化された単一細胞および空間トランスクリプトームデータの、包括的かつバージョン管理されたコレクションにプログラムからアクセスできるようにします。このスキルを使うと、データセット全体を先にダウンロードせずに、公開されている Census リリースを効率的にクエリして解析できます。

Census には次のデータが含まれています。

• 合計 2 億 1,700 万個以上の細胞と1 億 2,500 万個以上のユニークな細胞（2025-11-08 の安定版 LTS リリース）
• 1,845 件のデータセット（2025-11-08 の安定版 LTS リリース）
• 現行スキーマに含まれるヒト、マウス、マーモセット、アカゲザル、チンパンジーのデータ
• 標準化されたメタデータ（細胞型、組織、疾患、ドナー）
• 生の遺伝子発現行列と、ソース H5AD の検索・ダウンロード用ヘルパー
• 事前計算された要約カウント、埋め込み、空間データ
• AnnData、Scanpy、TileDB-SOMA、TileDB-SOMA-ML、その他の解析ツールとの統合

このスキルを使用する場面

次の場合にこのスキルを使用してください。

• 細胞型、組織、疾患で単一細胞の発現データをクエリする
• 利用可能な単一細胞データセットとメタデータを調べる
• 単一細胞データで機械学習モデルをトレーニングする
• 大規模なデータセット横断解析を実施する
• Census データを scanpy やその他の解析フレームワークと統合する
• 数百万個の細胞を対象に統計量を計算する
• 事前計算された埋め込みやモデル予測にアクセスする

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

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

uv pip install "cellxgene-census==1.17.*"

空間ワークフローの場合：

uv pip install "cellxgene-census[spatial]==1.17.*" "spatialdata[extra]>=0.2.5"

PyTorch モデルのトレーニングには TileDB-SOMA-ML を使用してください。旧 cellxgene_census.experimental.ml ローダーは非推奨です。

uv pip install "cellxgene-census==1.17.*" tiledbsoma-ml

基本的なワークフローパターン

コード付きの 8 つのパターンを、 references/core_workflow_patterns.md に記載しています。

1. Census を開く — 解析の再現性を保つため、必ず census_version を固定します。
2. Census 情報を調べる — 利用可能なデータセット、細胞数、要約テーブルを確認します。
3. 発現データをクエリする — 小〜中規模のデータを AnnData に読み込みます。
4. 大規模なクエリ — データの一部がメモリに収まらない場合は、メモリ外処理を行います。
5. PyTorch による機械学習 — Census のデータローダーを使用します。
6. 空間 Census データ — 空間アッセイにアクセスします。
7. Scanpy との統合 — Census のデータ部分を標準的な Scanpy ワークフローに渡します。
8. 複数データセットの統合 — データセットを組み合わせ、バッチ効果に対処します。

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

常にプライマリデータでフィルタリングする

重複を解析する場合を除き、細胞の二重カウントを防ぐため、クエリには常に 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="2025-11-08")

読み込み前にクエリサイズを推定する

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

# 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 を使用する

tiss ue_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（ブール値：True = ユニークな細胞）

現行スキーマには、ヒトとマウス以外の生物種のコレクションも含まれています。選択したリリースで利用可能な生物種を list(census["census_data"].keys()) で確認してください。

Gene Metadata（var）

• feature_id（Ensembl gene ID、例：「ENSG00000161798」）
• feature_name（Gene symbol、例：「FOXP2」）
• feature_type
• feature_length（塩基対で表した遺伝子長）
• nnz、n_measured_obs（スパース性とカバレッジの確認に役立つ可用性の概要）

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

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

references/census_schema.md

以下の包括的なドキュメントです。

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

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

references/common_patterns.md

以下の例とパターンを紹介しています。

• 探索的クエリ（メタデータのみ）
• 小〜中規模のクエリ（AnnData）
• 大規模クエリ（アウト・オブ・コア処理）
• PyTorch との統合
• Spatial Census へのアクセスパターン
• 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：細胞種分類器をトレーニングする

import tiledbsoma as soma
from tiledbsoma_ml import ExperimentDataset, experiment_dataloader

with cellxgene_census.open_soma() as census:
    experiment = census["census_data"]["homo_sapiens"]
    with experiment.axis_query(
        measurement_name="RNA",
        obs_query=soma.AxisQuery(value_filter="is_primary_data == True"),
    ) as query:
        dataset = ExperimentDataset(
            query=query,
            layer_name="raw",
            obs_column_names=["cell_type"],
            batch_size=128,
            shuffle=True,
        )
        dataloader = experiment_dataloader(dataset)

        for X, obs in dataloader:
            labels = obs["cell_type"]
            # 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 は必ず明示的に指定します
• すべての解析で同じバージョンを使用します
• バージョン固有の変更については、リリースノートを確認します

エージェントの操作手順

1. 環境を確認します。 ネットワークへのアクセス、API キー（必要な場合）、データベースの最新の API ドキュメントとレート制限を確認します。
2. 入力を特定します。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 既知のレコードを 1 件取得し、一括クエリの前にレスポンスの形式を確認します。
4. 上記の手順と参考資料を使用して、タスク全体を実行します。
5. 結果を検証します。 識別子が解決できること、レコード数が報告されていること、データベースのバージョンまたはアクセス日が記録されていることを確認します。
6. 報告します。 実行内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を伝えます。

このような場合	対応方法
HTTP 429 または 5xx エラーが発生した場合	バックオフを行ってレート制限を守り、リクエストをバッチ処理し、部分的な結果は正直に報告します。
これらの手順に記載された関数、フラグ、エンドポイントがインストール済みのバージョンに存在しない場合	インストール済みのバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧な場合	ユーザーに質問するか、実行前に前提を明示します。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計を捏造してはいけません。実行または検証できないことは、明確に伝えます。
• アクセッション番号、ID、レコードを捏造してはいけません。見つからない場合は「見つかりませんでした」と報告します。
• ここにあるバージョン固有の情報は古くなっている可能性があるものとして扱い、インストール済みのバージョンの公式ドキュメントで確認します。
• 費用が発生する操作、共有 GPU やクラウドのクォータを消費する操作、個人データや患者データを扱う操作、取り消せない操作を行う前に、ユーザーに確認します。

関連スキル

• anndata：単一細胞解析におけるアノテーション付き行列のデータ構造です。
• scanpy：標準的な単一細胞 RNA-seq 解析パイプラインです。
• scvi-tools：確率的な深層生成モデル（scVI、scANVI、totalVI、MultiVI、PeakVI、DestVI、Solo、CellAssign、MrVI…）をトレーニングして適用します。