CZ CELLxGENE Census

Visão Geral

O CZ CELLxGENE Census oferece acesso programático a uma coleção abrangente e versionada de dados padronizados de transcriptômica de célula única e espacial do CZ CELLxGENE Discover. Essa funcionalidade permite a consulta e análise eficientes de lançamentos públicos do Census sem a necessidade de baixar conjuntos de dados inteiros previamente.

O Census inclui:

• Mais de 217 milhões de células totais e mais de 125 milhões de células únicas no lançamento estável LTS de 2025-11-08
• 1.845 conjuntos de dados no lançamento estável LTS de 2025-11-08
• Dados de humano, camundongo, sagui, macaco-rhesus e chimpanzé no esquema atual
• Metadados padronizados (tipos de células, tecidos, doenças, doadores)
• Matrizes de expressão gênica bruta e auxiliares de consulta/download de origem H5AD
• Contagens de resumo pré-calculadas, embeddings e dados espaciais
• Integração com AnnData, Scanpy, TileDB-SOMA, TileDB-SOMA-ML e outras ferramentas de análise

Quando Usar Esta Funcionalidade

Esta funcionalidade deve ser usada quando:

• Consultar dados de expressão de célula única por tipo de célula, tecido ou doença
• Explorar conjuntos de dados de célula única e metadados disponíveis
• Treinar modelos de aprendizado de máquina em dados de célula única
• Realizar análises em larga escala entre conjuntos de dados
• Integrar dados do Census com scanpy ou outros frameworks de análise
• Computar estatísticas em milhões de células
• Acessar embeddings pré-calculados ou previsões de modelos

Instalação e Configuração

Instale a API do Census:

uv pip install "cellxgene-census==1.18.0"

Para fluxos de trabalho espaciais:

uv pip install "cellxgene-census[spatial]==1.18.0"

Para treinamento de modelos PyTorch, use TileDB-SOMA-ML. Os antigos carregadores cellxgene_census.experimental.ml estão ausentes a partir da versão 1.18.0:

uv pip install "cellxgene-census==1.18.0" tiledbsoma-ml

Padrões de Fluxo de Trabalho Principais

Oito padrões, cada um com código, estão em references/core_workflow_patterns.md:

1. Abrindo o Census — sempre fixe census_version para que uma análise permaneça reproduzível.
2. Explorando informações do Census — conjuntos de dados disponíveis, contagens de células e tabelas de resumo.
3. Consultando dados de expressão — pequena a média escala em um AnnData.
4. Consultas em larga escala — processamento fora da memória quando a fatia não couber na memória.
5. Aprendizado de máquina com PyTorch — carregadores de dados TileDB-SOMA-ML.
6. Dados do Census Espacial — acessando ensaios espaciais.
7. Integração com Scanpy — passando uma fatia do Census para um fluxo de trabalho padrão do Scanpy.
8. Integração de múltiplos conjuntos de dados — combinando conjuntos de dados e lidando com efeitos de lote.

Conceitos Chave e Melhores Práticas

Os exemplos fixam a compilação LTS atual 2025-11-08, verificada através do diretório de lançamento ativo em 2026-09-30. O SDK e o lançamento de dados são versões separadas. Resolva stable uma vez com get_census_version_description("stable")["release_build"] e registre essa data; nunca mude silenciosamente as compilações no meio da análise.

Sempre Filtre por Dados Primários

A menos que esteja analisando duplicatas, sempre inclua is_primary_data == True nas consultas para evitar contar células várias vezes:

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

Especifique a Versão do Census para Reprodutibilidade

Sempre especifique a versão do Census em análises de produção:

census = cellxgene_census.open_soma(census_version="2025-11-08")

Estime o Tamanho da Consulta Antes de Carregar

Para consultas grandes, conte as linhas selecionadas sem carregar todas as colunas de metadados. A contagem de células sozinha não é uma estimativa de memória: a contagem de genes, esparsidade, dtype, camadas, embeddings e cópias densas subsequentes também importam:

import tiledbsoma as soma
with census["census_data"]["homo_sapiens"].axis_query(
    measurement_name="RNA",
    obs_query=soma.AxisQuery(
        value_filter="tissue_general == 'brain' and is_primary_data == True"
    ),
) as query:
    print(f"Selected {query.n_obs:,} cells and {query.n_vars:,} genes")

# Query axes consume memory too; stream expression if the matrix will not fit.

Use tissue_general para Agrupamentos Mais Amplos

O campo tissue_general fornece categorias mais gerais do que tissue, útil para análises entre tecidos:

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

# Specific tissue
obs_value_filter="tissue == 'venous blood'"

Selecione Apenas as Colunas Necessárias

Minimize a transferência de dados especificando apenas as colunas de metadados necessárias:

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

…