1 Visão geral

Nesta vinheta, visualizaremos a expressão do gene Camk2n1 na região anterior de uma seção de cérebro de camundongo. Primeiro, o sinal será observado diretamente nos spots com o Seurat. Em seguida, as coordenadas dos spots e a imagem histológica serão organizadas em um GraphSpace, a partir do qual o PathwaySpace produzirá uma representação contínua da expressão no tecido (Tercan et al. 2025).

O objeto de entrada é data/brain.RDS, produzido na etapa anterior do curso. O fluxo segue a ordem: inspeção do objeto, seleção da região anterior, escolha do gene, construção do espaço gráfico, projeção do sinal e comparação das visualizações.

A versão HTML, quando for produzida, apresentará o roteiro sem executar a análise. Durante o curso, abra este arquivo .Rmd no RStudio e execute os blocos na ordem em que aparecem.

Essa vinheta segue o fluxo de trabalho apresentado na vinheta do pacote: Visualizing spatial transcriptomics.

2 Preparar o ambiente

2.1 Definir as pastas

Antes de executar o código, defina o diretório de trabalho como a pasta vinhetas/. No RStudio, use Session > Set Working Directory > To Source File Location. Será utilizado o objeto pré-processado da vinheta anterior, ele será carregado da pasta data/ e a figura final será gravada em formato PNG na pasta imagens/.

diretorio_vinhetas <- getwd()
diretorio_curso <- dirname(diretorio_vinhetas)
diretorio_dados <- file.path(diretorio_curso, "data")
diretorio_imagens <- file.path(diretorio_curso, "imagens")

dir.create(diretorio_imagens, showWarnings = FALSE, recursive = TRUE)

2.2 Conferir o PathwaySpace

A instalação do PathwaySpace, do RGraphSpace e das demais dependências está centralizada em Configuracao_do_ambiente_RStudio.Rmd. Depois de executar a primeira vinheta e reiniciar a sessão do R, use o bloco abaixo apenas para confirmar que o ambiente está pronto.

pacotes_visualizacao <- c(
  "Seurat", "SeuratObject", "ggplot2", "patchwork", "gridExtra",
  "RGraphSpace", "PathwaySpace"
)

pacotes_ausentes <- pacotes_visualizacao[
  !vapply(pacotes_visualizacao, requireNamespace, logical(1), quietly = TRUE)
]

if (length(pacotes_ausentes) > 0) {
  stop(
    "Execute primeiro Configuracao_do_ambiente_RStudio.Rmd. ",
    "Pacotes ausentes: ",
    paste(pacotes_ausentes, collapse = ", ")
  )
}

2.3 Carregar os pacotes

library("Seurat")
library("SeuratObject")
library("ggplot2")
library("RGraphSpace")
library("PathwaySpace")
library("patchwork")

3 Carregar e inspecionar o objeto espacial

O arquivo brain.RDS contém o objeto Seurat já processado nas etapas anteriores do curso, ele está localizado na pasta data/.

brain <- readRDS(file.path(diretorio_dados, "brain.RDS"))

SpatialDimPlot(brain,label = TRUE,label.size = 3)

4 Selecionar a região anterior

Como a projeção será demonstrada em uma única seção histológica, manteremos somente os spots identificados como pertencentes à região anterior. A distribuição espacial dos clusters é exibida novamente após o recorte.

brain <- subset(brain,subset = region == "anterior")

SpatialDimPlot(brain,
  label = TRUE,label.size = 3)

5 Selecionar e visualizar um gene de interesse

O gene Camk2n1 será usado como exemplo. O mapa do Seurat representa sua expressão diretamente nos spots medidos e será armazenado no objeto g para a comparação final.

gene <- "Camk2n1"

g_s <- SpatialFeaturePlot(brain,
  features = gene,ncol = 3,alpha = c(0.1, 1)) +
  labs(title = "Seurat")

g_s

6 Construir o espaço gráfico: RGraphSpace

O pacote RGraphSpace é um desenvolvimento do Sysbiolab (é do BR!). Ele possui funcionalidades de interface para plotagem de dados de transcriptômica espacial integrados com o ggplot2.

Além disso, ele constroi o objeto GraphSpace que depois será utilizado pelo próximo pacote (PathwaySpace) que irá realizar a visualização contínua.

6.1 Obter coordenadas, imagem e expressão

As coordenadas em baixa resolução posicionam os spots sobre a imagem histológica. A matriz da camada data fornece a expressão normalizada por transformação de estabilização da variância (VST) que será atribuída aos vértices do grafo.

# Coordenadas dos spots
spot_coord <- GetTissueCoordinates(brain,scale = "lowres")

# Imagem histológica em formato raster
raster_image <- GetImage(brain,"raster")

# Expressão gênica normalizada por VST
vst_gexp <- GetAssayData(brain,layer = "data")

6.2 Criar e normalizar o GraphSpace

Cada spot será tratado como um vértice. O tamanho dos vértices é reduzido para facilitar a inspeção visual.

Aqui, vamos extrair os principais atributos do objeto Seurat para vocês verem tudo acontecendo. Esses principais atributos são: spot_coord que possui as coordenadas XY dos spots; raster_image que é a imagem de fundo (corte histológico); e vst_gexp que é a matriz de counts dos genes em cada spot.

spot_coord$nodeSize <- 1

# Para construir o objeto GraphSpace, se usa a função GraphSpace()
gs <- GraphSpace(spot_coord,)
# Atribuir imagem raster ao objeto
gs_image(gs) <- raster_image
# Atribuir a matriz de contagem ao objeto
gs_fdata(gs) <- vst_gexp

gs

6.3 Coerção e normalização do GraphSpace

Acima, foi demonstrada a contrução do objeto para fins educativos. Contudo o pacote já possui uma função de coerção do objeto Seurat, ou seja, ela extrai todos os dados do Seurat e converter automaticamente para o objeto GraphSpace. Esse de coreção é o fluxo recomendado por passar todos atributos que estavam armazenados no objeto Seurat.

Na sequência, a função normalizeGraphSpace() alinha as coordenadas cartesianas do grafo à orientação matricial da imagem. Assim, o RGraphSpace irá criar o “sistema de coordenadas normalizado” em que a imagem e as coordenas dos spots serão alinhados a nível do pixel.

# Função de coerção do objeto Seurat
gs <- as.GraphSpace(brain, space = "spatial", scale = "lowres")
# Atribuir imagem raster ao objeto
gs_image(gs) <- SeuratObject::GetImage(brain, mode = "raster") # igual que raster_image
gs

# Etapa de normalização.
gs <- normalizeGraphSpace(gs)

6.4 Conferir a sobreposição espacial

O gráfico abaixo sobrepõe os vértices à imagem do tecido. Se as coordenadas de outro conjunto estiverem invertidas no eixo vertical, o argumento flip.y = TRUE poderá ser usado em normalizeGraphSpace().

xy_labs <- labs(x = "Coordenada dos spots 1",y = "Coordenada dos spots 2")

plotGraphSpace(gs,add.image = TRUE) +
  xy_labs

6.5 Plotagem com RGraphSpace

cpal <- hcl.colors(100, palette = "Spectral", rev = TRUE)

g <- ggplot(gs) + 
  annotation_gspace_image(gs) +
  geom_nodespace(mapping = aes(colour = Camk2n1), size = 1.2, pch = 19) + 
            #Altere tamanho do spot em size para melhorar a visualização
  scale_colour_continuous(palette = cpal) +
  theme_gspace_coords(theme = "th3", is_norm = TRUE, 
    xlab = "Tissue coordinates 1", ylab = "Tissue coordinates 2") + 
  labs(title = "RGraphSpace")
g

ggsave(filename = file.path(
    diretorio_imagens,
    "Brain_ant_RGraphSpace_Camk2n1.png"
  ),plot = g,width = 5,height = 5,units = "in",dpi = 120,bg = "white")

7 Construir o PathwaySpace

O pacote PathwaySpace também é um desenvolvimento do Sysbiolab (é do BR de novo!!). Esse pacote é focado na projeção de sinal que permite realizar a visualização contínua de dados transcriptômica espacial. Com essa projeção é possível “preencher” os espaços entre os spots que não se conhece o sinal.

7.1 Calcular a distância entre spots

O PathwaySpace é construído a partir do objeto GraphSpace. A distância média de cada spot ao seu vizinho mais próximo (pdist) será usada como referência espacial pela função de decaimento da projeção.

pspace_obj <- buildPathwaySpace(gs)

nspot <- getNearestNode(pspace_obj)

pdist <- mean(nspot$dist)
pdist

pdist é a média das distâncias (euclidianas) entre os spots e seus vizinhos mais próximos. No caso de Visium v1/v2 essa distância relativa do sistema de coordenadas normalizado seria comparável à 100um (distância entre os centros dos spots nessa versão da plataforma).

7.2 Mapear a silhueta do tecido

A silhueta delimita a área sobre a qual o sinal será projetado. O valor de base controla a extensão inicial dessa representação em torno do grafo.

pspace_obj <- silhouetteMapping(pspace_obj,baseline = 0.1)

plotPathwaySpace(ps = pspace_obj,
  theme = "th3",add.image = TRUE,si.alpha = 0.5) +
  xy_labs

8 Projetar o sinal gênico

A expressão de Camk2n1 é associada aos vértices correspondentes aos spots. A projeção circular espalha esse sinal no espaço contínuo, ponderando a contribuição de cada spot pela distância e agregando as contribuições por média ponderada.

# Informar nome do gene de interesse para plotar
activeFeature(pspace_obj) <- "Camk2n1"

pspace_obj <- circularProjection(pspace_obj,
  k = gs_vcount(pspace_obj),
  decay.fun = weibullDecay(decay = 0.5,pdist = pdist),
  aggregate.fun = signalAggregation("wmean"))

Aqui a projeção foi calculada e armazenada no objeto. A projeção depende de duas funções: decaimento e agregação. Caso queira entender melhor como elas funcionam, por favor acesse as vinhetas introdutórias do pacote: PathwaySpace.

9 Visualizar a projeção

9.1 Separar a imagem e o sinal projetado

# Apenas imagem histológica de fundo
p1 <- ggplot(pspace_obj) + 
  annotation_gspace_image(pspace_obj) +
  xy_labs

# Sinal do gene sobreposto à imagem de fundo
p2 <- ggplot(pspace_obj) + 
  annotation_gspace_image(pspace_obj) + 
  annotation_pspace_signal(pspace_obj, si.alpha = 0.5) + 
  xy_labs

p1 + p2

O primeiro painel mostra a imagem do tecido e o segundo apresenta o sinal contínuo produzido pelo PathwaySpace sobreposto à imagem.

9.2 Destacar os valores mais altos

Nesta visualização, a escala é truncada para o intervalo de 0,5 a 1. Assim, o painel enfatiza as áreas com maior sinal projetado.

p <- ggplot(pspace_obj) + 
  annotation_gspace_image(pspace_obj) + 
  annotation_pspace_signal(pspace_obj, si.alpha = 0.25, zlim = c(0.5, 1)) + 
  xy_labs + labs(title = "PathwaySpace")

p

ggsave(filename = file.path(
    diretorio_imagens,
    "Brain_ant_PathwaySpace_Camk2n1.png"
  ),plot = p,width = 7,height = 5,units = "in",dpi = 120,bg = "white")

10 Comparar Seurat, RGraphSpace e PathwaySpace

O painel final coloca lado a lado a expressão observada nos spots pelo Seurat e a projeção contínua produzida pelo PathwaySpace.

g_s + g + p

ggsave(filename = file.path(diretorio_imagens,"Brain_anterior_Camk2n1.png"),
       plot = g_s + g + p,
  width = 12,height = 6,units = "in",dpi = 120,bg = "white")

11 Arquivos produzidos

Ao concluir a vinheta, as imagens salvas estarão disponíveis em:

  • imagens/Brain_ant_RGraphSpace_Camk2n1.png

  • imagens/Brain_ant_PathwaySpace_Camk2n1.png

  • imagens/Brain_anterior_Camk2n1.png

12 Informações da sessão

sessionInfo()

Referências

Tercan, Bahar, Victor H. Apolonio, Vinicius S. Chagas, Christopher K. Wong, Jordan A. Lee, Christina Yau, Christopher C. Benz, et al. 2025. “Protocol for Assessing Distances in Pathway Space for Classifier Feature Sets from Machine Learning Methods.” STAR Protocols 6 (2): 103681. https://doi.org/10.1016/j.xpro.2025.103681.