scVelo — Análise de Velocidade de RNA
Visão Geral
scVelo é o pacote Python líder para análise de velocidade de RNA em dados de RNA-seq de célula única. Ele infere transições de estado celular modelando a cinética de splicing de mRNA — usando a razão entre as abundâncias de mRNA não processado (pré-mRNA) e processado (mRNA maduro) para determinar se um gene está sendo regulado positivamente ou negativamente em cada célula. Isso permite a reconstrução de trajetórias de desenvolvimento e a identificação de decisões de destino celular sem exigir dados de séries temporais.
Instalação: uv pip install scvelo
Recursos principais:
- Documentação: https://scvelo.readthedocs.io/
- GitHub: https://github.com/theislab/scvelo
- Artigo: Bergen et al. (2020) Nature Biotechnology. PMID: 32747759
Quando Usar Esta Habilidade
Use o scVelo quando:
- Inferência de trajetória a partir de dados de instantâneo: Determinar em qual direção as células estão se diferenciando
- Predição de destino celular: Identificar células progenitoras e seus destinos a jusante
- Identificação de genes condutores: Encontrar genes cuja dinâmica melhor explique as trajetórias observadas
- Biologia do desenvolvimento: Modelar hematopoiese, neurogênese, transições epitélio-mesenquimais
- Estimativa de tempo latente: Ordenar células ao longo de um pseudotempo derivado da dinâmica de splicing
- Complemento ao Scanpy: Adicionar informações direcionais a embeddings UMAP
Pré-requisitos
O scVelo requer matrizes de contagem para RNA não processado e processado. Estas são geradas por:
- STARsolo ou kallisto|bustools com modo
lamanno - velocyto CLI:
velocyto run10x/velocyto run - alevin-fry / simpleaf com saída processado/não processado
Os dados são armazenados em um objeto AnnData com layers["spliced"] e layers["unspliced"].
Fluxo de Trabalho Padrão de Velocidade de RNA
1. Configuração e Carregamento de Dados
import scvelo as scv
import scanpy as sc
import numpy as np
import matplotlib.pyplot as plt
# Configurar opções
scv.settings.verbosity = 3 # Mostrar etapas de computação
scv.settings.presenter_view = True
scv.settings.set_figure_params('scvelo')
# Carregar dados (AnnData com camadas processado/não processado)
# Opção A: Carregar de loom (saída do velocyto)
adata = scv.read("cellranger_output.loom", cache=True)
# Opção B: Mesclar loom do velocyto com AnnData processado pelo Scanpy
adata_processed = sc.read_h5ad("processed.h5ad") # Tem UMAP, clusters
adata_velocity = scv.read("velocyto.loom")
adata = scv.utils.merge(adata_processed, adata_velocity)
# Verificar camadas
print(adata)
# obs × var: N × G
# layers: 'spliced', 'unspliced' (obrigatório)
# obsm['X_umap'] (obrigatório para visualização)
2. Pré-processamento
# Filtrar e normalizar. A partir do scVelo 0.3, filter_and_normalize() apenas filtra
# genes e normaliza por célula -- não aceita mais n_top_genes e não mais
# aplica transformação logarítmica, então a etapa de log e a seleção de HVG vêm do Scanpy.
scv.pp.filter_and_normalize(
adata,
min_shared_counts=20 # Contagens mínimas em processado+não processado
)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, n_top_genes=2000, subset=True)
# Calcular momentos de primeira e segunda ordem (médias e variâncias)
# knn_connectivities deve ser calculado primeiro
sc.pp.neighbors(adata, n_neighbors=30, n_pcs=30)
scv.pp.moments(
adata,
n_pcs=30,
n_neighbors=30
)
3. Estimativa de Velocidade — Modelo Estocástico
O modelo estocástico é rápido e adequado para análises exploratórias:
# Velocidade estocástica (mais rápido, menos preciso)
scv.tl.velocity(adata, mode='stochastic')
scv.tl.velocity_graph(adata)
# Visualizar
scv.pl.velocity_embedding_stream(
adata,
basis='umap',
color='leiden',
title="Velocidade de RNA (Estocástica)"
)
4. Estimativa de Velocidade — Modelo Dinâmico (Recomendado)
O modelo dinâmico ajusta a cinética completa de splicing e é mais preciso:
# Recuperar dinâmica (computacionalmente intenso; ~10-30 min para 10K células)
scv.tl.recover_dynamics(adata, n_jobs=4)
# Calcular velocidade a partir do modelo dinâmico
scv.tl.velocity(adata, mode='dynamical')
scv.tl.velocity_graph(adata)
5. Tempo Latente
O modelo dinâmico permite o cálculo de um tempo latente compartilhado (pseudotempo):
# Calcular tempo latente
scv.tl.latent_time(adata)
# Visualizar tempo latente no UMAP
scv.pl.scatter(
adata,
color='latent_time',
color_map='gnuplot',
size=80,
title='Tempo latente'
)
# Identificar os principais genes ordenados por tempo latente
top_genes = adata.var['fit_likelihood'].sort_values(ascending=False).index[:300]
scv.pl.heatmap(
adata,
var_names=top_genes,
sortby='latent_time',
col_color='leiden',
n_convolve=100
)
6. Análise de Genes Condutores
# Identificar genes com melhor ajuste de velocidade
scv.tl.rank_velocity_genes(adata, groupby='leiden', min_corr=0.3)
df = scv.DataFrame(adata.uns['rank_velocity_genes']['names'])
print(df.head(10))
# Velocidade e coerência
scv.tl.velocity_confidence(adata)
scv.pl.scatter(
adata,
c=['velocity_length', 'velocity_confidence'],
cmap='coolwarm',
perc=[5, 95]
)
# Retratos de fase para genes específicos
scv.pl.velocity(adata, ['Cpe', 'Gnao1', 'Ins2'],
ncols=3, figsize=(16, 4))
7. Setas de Velocidade e Pseudotempo
# Gráfico de setas no UMAP
scv.pl.velocity_embedding(
adata,
arrow_length=3,
arrow_size=2,
color='leiden',
basis='umap'
)
# Gráfico de fluxo (visualização mais limpa)
scv.pl.velocity_embedding_stream(
adata,
basis='umap',
color='leiden',
smooth=0.8,
min_mass=4
)
# Pseudotempo de velocidade (alternativa ao tempo latente)
scv.tl.velocity_pseudotime(adata)
scv.pl.scatter(adata, color='velocity_pseudotime', cmap='gnuplot')
8. Grafo de Trajetória PAGA
# Grafo PAGA com transições informadas por velocidade
scv.tl.paga(adata, groups='leiden')
df = scv.get_df(adata, 'paga/transitions_confidence', precision=2).T
df.style.background_gradient(cmap='Blues').format('{:.2g}')
# Plotar PAGA com velocidade
scv.pl.paga(
adata,
basis='umap',
size=50,
alpha=0.1,
min_edge_width=2,
node_size_scale=1.5
)
Script de Fluxo de Trabalho Completo
import scvelo as scv
import scanpy as sc
def run_rna_velocity(adata, n_top_genes=2000, mode='dynamical', n_jobs=4):
"""
Fluxo de trabalho completo de velocidade de RNA.
Args:
adata: AnnData com camadas 'spliced' e 'unspliced', UMAP em obsm
n_top_genes: Número de principais HVGs para velocidade
mode: 'stochastic' (rápido) ou 'dynamical' (preciso)
n_jobs: Trabalhos paralelos para modelo dinâmico
Retorna:
AnnData processado com informações de velocidade
"""
scv.settings.verbosity = 2
# 1. Pré-processamento (scVelo 0.3 removeu log/HVG de filter_and_normalize)
scv.pp.filter_and_normalize(adata, min_shared_counts=20)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, n_top_genes=n_top_genes, subset=True)
if 'neighbors' not in adata.uns:
sc.pp.neighbors(adata, n_neighbors=30)
scv.pp.moments(adata, n_pcs=30, n_neighbors=30)
# 2. Estimativa de velocidade
if mode == 'dynamical':
scv.tl.recover_dynamics(adata, n_jobs=n_jobs)
scv.tl.velocity(adata, mode=mode)
scv.tl.velocity_graph(adata)
# 3. Análises a jusante
if mode == 'dynamical':
scv.tl.latent_time(adata)
scv.tl.rank_velocity_genes(adata, groupby='leiden', min_corr=0.3)
scv.tl.velocity_confidence(adata)
scv.tl.velocity_pseudotime(adata)
return adata
Principais Campos de Saída no AnnData
Após executar o fluxo de trabalho, os seguintes campos são adicionados:
| Localização | Chave | Descrição |
|---|---|---|
adata.layers | velocity | Velocidade de RNA por gene por célula |
adata.layers | fit_t | Tempo latente ajustado por gene por célula |
adata.obsm | velocity_umap | Vetores de velocidade 2D no UMAP |
adata.obs | velocity_pseudotime | Pseudotempo a partir da velocidade |
adata.obs | latent_time | Tempo latente do modelo dinâmico |
adata.obs | velocity_length | Velocidade de cada célula |
adata.obs | velocity_confidence | Pontuação de confiança por célula |
adata.var | fit_likelihood | Qualidade do ajuste do modelo por gene |
adata.var | fit_alpha | Taxa de transcrição |
adata.var | fit_beta | Taxa de splicing |
adata.var | fit_gamma | Taxa de degradação |
adata.uns | velocity_graph | Matriz de probabilidade de transição célula-célula |
Comparação de Modelos de Velocidade
| Modelo | Velocidade | Precisão | Quando Usar |
|---|---|---|---|
stochastic | Rápida | Moderada | Exploratório; conjuntos de dados grandes |
deterministic | Média | Moderada | Cinética linear simples |
dynamical | Lenta | Alta | Publicação de qualidade; identifica genes condutores |
Melhores Práticas
- Comece com o modo estocástico para exploração; mude para o dinâmico na análise final
- Necessidade de boa cobertura de leituras não processadas: Leituras curtas (< 100 pb) podem perder cobertura de íntrons
- Mínimo de 2.000 células: A velocidade de RNA é ruidosa com menos células
- A velocidade deve ser coerente: As setas devem seguir a biologia conhecida; aleatoriedade indica problemas
- A largura de banda k-NN importa: Muito poucos vizinhos → velocidade ruidosa; muitos → suavizado demais
- Verificação de sanidade: Células raiz (progenitoras) devem ter altas razões não processado/processado para genes marcadores
- O modelo dinâmico requer estados cinéticos distintos: Funciona melhor para processos de diferenciação claros
Solução de Problemas
| Problema | Solução |
|---|---|
| Camada não processada ausente | Execute novamente o velocyto ou use STARsolo com --soloFeatures Gene Velocyto |
| Muito poucos genes de velocidade | Reduza min_shared_counts; verifique a profundidade de sequenciamento |
| Setas com aparência aleatória | Tente diferentes n_neighbors ou modelo de velocidade |
| Erro de memória com dinâmico | Defina n_jobs=1; reduza n_top_genes |
| Velocidade negativa em todos os lugares | Verifique se as camadas processado/não processado não estão trocadas |
Recursos Adicionais
- Documentação do scVelo: https://scvelo.readthedocs.io/
- Cadernos de tutorial: https://scvelo.readthedocs.io/tutorials/
- GitHub: https://github.com/theislab/scvelo
- Artigo: Bergen V et al. (2020) Nature Biotechnology. PMID: 32747759
- velocyto (pré-processamento): http://velocyto.org/
- CellRank (previsão de destino, estende o scVelo): https://cellrank.readthedocs.io/
- dynamo (alternativa de marcação metabólica): https://dynamo-release.readthedocs.io/