Análise de Célula Única com Scarf

Scarf processa matrizes de contagem baseadas em Zarr em blocos limitados e registra cada computação como um artefato imutável e endereçável por conteúdo. Esta habilidade codifica como usar o Scarf principal para análise de RNA de célula única: quais chamadas fazer, em que ordem, que evidências verificar e o que não fazer. Ela não usa nem descreve scarf.agent.

Leia este arquivo primeiro. Em seguida, abra apenas os módulos de referência que você precisa (índice abaixo). Os caminhos nesta habilidade são relativos ao diretório da habilidade. A cópia mantida vive no repositório Scarf em https://github.com/NygenAnalytics/scarf/tree/master/skills/scarf-single-cell. Cada receita nos módulos foi executada contra um armazenamento real. Os números citados lá vêm do conjunto de dados de documentação 10x 5K PBMC e são ilustrações, não limites.

Quando Usar Esta Habilidade

• Use quando uma tarefa envolve um armazenamento Scarf .zarr, scarf.DataStore, ds.pipeline ou um PipelineRun.
• Use ao converter dados H5AD, 10x, MTX ou Seurat em um armazenamento Scarf, ou ao abrir e montar um conjunto de dados Cytebase.
• Use para análise de RNA-seq de célula única com o Scarf principal: QC com auditorias de remoção, HVG, PCA e grafos de vizinhos, clustering Leiden e Paris, UMAP, marcadores e anotação cuidadosa, correção de lote, comparações em nível de doador, plotagem sem cabeça, proveniência e exportação.
• Use quando as contagens são muito grandes para a memória ou residem em armazenamento de objetos, de modo que devam ser transmitidas sob um orçamento de memória explícito.
• Não o use para scarf.agent (o pacote de agente automatizado), que esta habilidade não cobre.

Configuração

• Instale no ambiente em que você executa Python: pip install "scarf[extra]>=1.0.0rc17", mais scarf[cytebase] para Cytebase. O limite explícito de pré-lançamento é importante: um simples scarf[extra] resolve para a antiga série 0.32, cuja API esta habilidade não descreve.
• Defina os recursos por processo antes de importar Scarf. Os padrões reivindicam toda a RAM detectada e todos os CPUs: SCARF_MEM_BUDGET=8G SCARF_WORKERS=8 (especificações de memória precisam de uma unidade; um simples 8 é rejeitado).
• Sem cabeça: MPLBACKEND=Agg, chame os plots com show=False, depois result.save(path) e result.close().
• Logs silenciosos para scripts: scarf.configure_output(level="WARNING", progress=False).
• Primeira olhada em um armazenamento: abra-o somente leitura e siga "Abrir e inspecionar um armazenamento" (references/data-access.md) e "Verificar a matriz primeiro" (references/quality-control.md) para contagens de células e características, execuções, tipos de artefatos e se as contagens parecem brutas. Em seguida, revise cada coluna de metadados você mesmo: colunas de design (doador, amostra, lote, condição), anotações de autor para reter (regra 14) e colunas derivadas de autor. A cópia mantida desta habilidade no repositório Scarf também inclui scripts/inspect_store.py, um comando somente leitura que executa essas verificações e sinaliza essas colunas por nome (os valores de anotação permanecem ocultos, a menos que você passe --show-annotation-values). Esta cópia do catálogo é apenas Markdown e não inclui o script.
• Etapas longas (uma execução de pipeline em dezenas de milhares de células sobre contagens remotas pode levar muitos minutos): escreva a etapa como um script que registra em um arquivo e termina com uma linha DONE ou FAILED, execute-o em segundo plano e espere com um loop limitado que também para em um Traceback ou um processo morto. Se você iniciar através de um wrapper como uv run, coloque timeout dentro dele (uv run timeout N python step.py; o inverso pode deixar registros running obsoletos) e rastreie o processo por $! em vez de pgrep -f. Veja references/performance-and-export.md. Nunca consulte sem um limite de tempo.

Modelo Mental

• Um DataStore é um diretório Zarr: uma tabela de células compartilhada ds.cells, um grupo por ensaio (ds.RNA, tabela de características ds.RNA.feats, contagens como célula-major counts mais gene-major countsT), artefatos e pipeline/runs. Colunas de QC são prefixadas pelo ensaio: RNA_nCounts, RNA_nFeatures, RNA_percentMito, RNA_percentRibo.
• I é a chave de célula booleana ativa. Filtros analíticos nunca a editam; eles retornam um artefato congelado de seleção de células.
• Cada resultado é um ArtifactRef (scope, kind, artifact_id, assay). Produtores pegam referências e retornam referências: select_hvgs -> run_normalization -> run_pca -> build_ann_index -> query_neighbors -> build_connectivity_map -> run_leiden_clustering / run_umap -> run_marker_search. Uma chamada idêntica retorna o artefato existente sem recomputar.
• ds.pipeline.run(label=...) executa todo o pipeline de RNA (filtragem, ciclo celular, HVG,

…