alterlab-cellxgene

CZ CELLxGENE Census

概要

CZ CELLxGENE Census は、CZ CELLxGENE Discover の標準化された単一細胞ゲノミクスデータに、プログラムからバージョン管理された状態でアクセスできるようにします。2025-11-08 LTS リリースには、標準化されたメタデータ（細胞型、組織、疾患、ドナー）、生の遺伝子発現行列、事前計算済みの埋め込み、および PyTorch、scanpy などの解析ツールとの統合とともに、162,025,130 個のヒト細胞と 46,299,127 個のマウス細胞が収録されています。リリースごとに細胞数は増加するため、方法のセクションで数値を引用するのではなく、census["census_info"]["summary"] から取得してください。

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

次の用途でこのスキルを使用してください：

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

参照アトラスではなく独自のデータセットを解析する場合は、代わりに scanpy または scvi-tools を使用してください。

インストール

uv pip install cellxgene-census
# For PyTorch ML workflows (loaders moved out of cellxgene-census):
uv pip install tiledbsoma-ml

基本的なワークフロー

1. コンテキストマネージャーを使って Census を開き、再現性のために census_version を固定します。"stable" は最新の LTS リリースの別名（2026-09 時点では 2025-11-08）で、"latest" は週次ビルドを追跡します。LTS リリースは少なくとも 5 年間利用できます。
2. まずメタデータを調べ（get_obs／データセットの概要）、利用可能な内容を把握します。重複した細胞を避けるため、必ず is_primary_data == True でフィルタリングしてください。
3. 発現データを読み込む前にクエリサイズを見積もります。細胞数が 100k 未満なら get_anndata()（メモリ内）、それより大きい場合は axis_query() によるメモリ外イテレーションを使用します。
4. obs_value_filter（細胞）と var_value_filter（遺伝子）を使って発現データをクエリし、必要な obs_column_names のみを選択します。
5. 後続処理：返された AnnData を scanpy に渡すか、バッチを PyTorch のデータローダーにストリーミングして ML に使用します。

最小限のひな形：

import cellxgene_census

with cellxgene_census.open_soma(census_version="2025-11-08") as census:  # pinned LTS
    adata = cellxgene_census.get_anndata(
        census=census,
        organism="Homo sapiens",
        obs_value_filter="cell_type == 'B cell' and tissue_general == 'lung' and is_primary_data == True",
    )

該当しないケース

シナリオ	代わりに使用
すでに手元にある AnnData を正規化／クラスタリング／UMAP する	alterlab-scanpy
ローカルの .h5ad／zarr ファイルを結合または加工する	alterlab-anndata
深層生成モデルをトレーニングする／独自データをバッチ統合する	alterlab-scvi-tools
特定の GEO／ArrayExpress アクセッションを閲覧またはダウンロードする	alterlab-geo
CLI から単発で gget cellxgene を検索する	alterlab-gget

振り分けのガイダンス

• 小規模／中規模のクエリ（RAM に収まる） → get_anndata()。references/querying_expression.md を参照してください。
• クエリが RAM を超える → チャンクごとのイテレーションと逐次統計処理に axis_query() を使用します。references/querying_expression.md を参照してください。
• ML モデルのトレーニング → tiledbsoma_ml の PyTorch データローダー／ExperimentDataset を使用します。references/ml_and_scanpy.md を参照してください。
• 標準的な scanpy 解析／複数組織の統合 → references/ml_and_scanpy.md を参照してください。
• スキーマ全体、すべてのメタデータフィールド、またはフィルター構文の詳細が必要 → references/census_schema.md を参照してください。

リファレンス一覧

• references/querying_expression.md — Census の開き方、メタデータの調査、小規模・中規模の get_anndata() クエリ、増分統計を用いた大規模なアウトオブコア axis_query() 処理について説明します。
• references/ml_and_scanpy.md — tiledbsoma_ml の PyTorch データローダー／ExperimentDataset のトレーニング・テスト分割、scanpy との統合、複数データセット／組織の統合（anndata.concat）、および4つのユースケースを取り上げます。
• references/best_practices_and_troubleshooting.md — プライマリデータのフィルタリング、バージョンの固定、クエリサイズの見積もり、tissue_general と tissue の違い、存在行列、obs／var メタデータフィールドの全一覧、トラブルシューティングガイドについて説明します。
• references/census_schema.md — Census のデータ構造、すべてのメタデータフィールド、値フィルターの構文と演算子、SOMA オブジェクトの種類、データの収録基準について説明します。
• references/common_patterns.md — コアレシピ以外の内容として、アウトオブコアでの増分（Welford）分散、オントロジー用語によるフィルタリング、バッチ処理の一括実行、よくある落とし穴の一覧を紹介します。

AlterLab Academic Skills スイートの一部です。