scvi-tools

Destinado a scvi-tools 1.5.1, lançado em 10 de setembro de 2026. As APIs abaixo foram verificadas contra o código marcado e a documentação oficial. Os exemplos são ilustrativos: os testes do repositório exercitam ajustes rápidos de CPU sintéticos para SCVI, SCANVI, TOTALVI, MULTIVI, METHYLVI, PEAKVI e POISSONVI, além de pré-processamento que preserva contagens, contratos de saída de DE, salvar/carregar e minificação. A pilha testada é Python 3.13, Scanpy 1.12.4, AnnData 0.13.4, MuData 0.4.1, PyTorch 2.14.1 e Lightning 2.6.6. Treinamentos longos, caminhos específicos de hardware e outros fluxos de trabalho especializados permanecem ilustrativos; essas verificações não estabelecem convergência ou validade biológica.

Escolha o modelo e seu contrato de entrada

A regra de contagem é específica do modelo: não alimente contagens de RNA brutas para SysVI ou substitua a cobertura de metilação por razões. Da mesma forma, nunca reconstrua contagens exponenciando dados log-normalizados. Preserve as contagens medidas e a proveniência do pré-processamento.

Leia as referências correspondentes antes de usar um modelo especializado:

• Modelos de RNA: SCVI, SCANVI, AUTOZI, VELOVI, ContrastiveVI, CellAssign, SOLO, LinearSCVI, AmortizedLDA.
• Modelos ATAC: PEAKVI, POISSONVI, SCBASSET.
• Modelos multimodais: TOTALVI, TOTALANVI, MULTIVI, MRVI, DIAGVI.
• Modelos espaciais: CondSCVI/DestVI, Stereoscope, Tangram, GIMVI, SCVIVA, RESOLVI.
• Modelos especializados: metilação, citometria, SysVI, Decipher.

Limites de lançamento: O suporte a JAX, incluindo JaxSCVI, foi removido na versão 1.5. scvi.model.mlxSCVI continua sendo uma implementação separada opcional para Apple Silicon; PyTorch MPS e MLX são backends diferentes. Modelos espaciais e DIAGVI permanecem importáveis na versão 1.5.1, mas o upstream direciona sua manutenção contínua para scVIVA-tools. Use os exemplos de compatibilidade fixados aqui apenas para fluxos de trabalho existentes do scvi-tools.

Fluxo de trabalho

1. Confirme a modalidade, a proveniência dos dados brutos, IDs únicos de células/características, ordem das características, metadados de lote/amostra e a comparação biológica pretendida.
2. Realize QC e seleção de características antes do registro do modelo. Use seleção de HVG consciente de contagem para camadas de contagem e preserve um objeto de contagem de genes completo para análises posteriores fora do conjunto de características selecionado.
3. Registre o objeto de dados exato com o setup_anndata ou setup_mudata do modelo; crie e treine o modelo. A configuração é o registro, não a normalização.
4. Inspecione o histórico de validação, o ajuste com dados retidos, a estabilidade da semente, a mistura de lotes e a retenção da biologia conhecida. Um UMAP bem misturado sozinho não valida a integração.
5. Extraia representações ou saídas normalizadas específicas do modelo; salve o modelo, dados, ordem das características selecionadas, versões do software, semente e parâmetros de treinamento.

Fluxo de trabalho ilustrativo de RNA

Assume que rna_counts.h5ad contém contagens medidas e não normalizadas em .X, com obs['batch'] não ausente. Escolha os limiares de QC para o experimento antes deste bloco.

import numpy as np
import scanpy as sc
import scvi
from scipy import sparse

scvi.settings.seed = 0
adata = sc.read_h5ad("rna_counts.h5ad")
assert adata.obs_names.is_unique and adata.var_names.is_unique
assert adata.obs["batch"].notna().all()
x = adata.X
values = x.data if sparse.issparse(x) else np.asarray(x)
assert np.isfinite(values).all() and (values >= 0).all()
assert np.allclose(values, np.rint(values))
assert (np.asarray(x.sum(axis=1)).ravel() > 0).all()
adata.layers["counts"] = x.copy()

…