--- title: "Cell-type annotation and spatial clustering with STBench" output: rmarkdown::html_vignette: toc: true toc_depth: 3 vignette: > %\VignetteIndexEntry{Cell-type annotation and spatial clustering with STBench} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.width = 8, fig.height = 5, message = FALSE, warning = FALSE ) library(STBench) ``` # Introduction This vignette uses the cell-type labels already supplied in `norm_example`, so an external SingleR reference is not required. ```{r load-data} data(norm_example) norm <- norm_example names(norm) ``` # Cell-type annotation The example data include existing `cell_type` annotations. We use these to demonstrate downstream comparisons without requiring an external SingleR reference. In a full analysis, `run_annotation()` can be used with an appropriate reference. ```{r annotations-ready} annotated_norm <- norm annotation_col <- "cell_type" ``` ## Visualise spatial cell-type assignments ```{r annotation-maps} p_annotation <- plot_spatial_annotation( norm_list = annotated_norm, annotation_col = annotation_col, method_order = NULL, point_size = 0.5, ncol = 2, theme_name = "classic", palette = "turbo" ) p_annotation$plot ``` ## Compare cell-type composition We examine relative proportions and absolute spot counts assigned to each cell type. ```{r annotation-proportions} p_prop <- plot_celltype_proportion( norm_list = annotated_norm, annotation_col = annotation_col, palette = "turbo", show = "proportion", theme_name = "classic" ) p_prop$plot ``` ```{r annotation-counts} p_count <- plot_celltype_proportion( norm_list = annotated_norm, annotation_col = annotation_col, show = "count", theme_name = "classic" ) p_count$plot ``` ## Calculate and plot annotation agreement Pairwise agreement measures the fraction of spots receiving the same label under two methods. It measures consistency, not accuracy against a known ground truth. ```{r annotation-agreement} annotation_agreement <- calculate_annotation_agreement( norm_list = annotated_norm, annotation_col = annotation_col, remove_na = TRUE ) annotation_agreement p_agreement <- plot_annotation_agreement( norm_list = annotated_norm, annotation_col = annotation_col, remove_na = TRUE, show_values = TRUE, digits = 2, colour_option = "viridis", theme_name = "classic" ) p_agreement$plot ``` ## Marker investigations Marker comparisons depend on the presence of biologically relevant genes. The following code demonstrates how to specify candidate markers when available. ```{r marker-expression} p_marker <- plot_marker_expression( norm_list = annotated_norm, markers = head(rownames(annotated_norm[[1]]), 2), annotation_col = "cell_type", palette = "turbo" ) p_marker$plot ``` # BANKSY spatial clustering BANKSY incorporates spatial neighbourhood information alongside gene expression to identify spatial domains. We execute clustering on the small example dataset. ```{r banksy-clustering} banksy_norm <- run_banksy_individual( norm_list = norm, methods = names(norm), assay_name = "logcounts", cluster_col = "banksy_cluster", k_geom = 15, lambda = 0.8, resolution = 0.2, seed = 123 ) ``` ## Visualise and evaluate BANKSY clusters These functions operate on the output of `run_banksy_individual()` above. ```{r banksy-maps} p_banksy <- plot_spatial_clustering( norm_list = banksy_norm, cluster_col = "banksy_cluster", ground_truth_col = "layer_guess", show = "both", methods = names(banksy_norm), point_size = 0.5, ncol = 2, theme_name = "classic" ) p_banksy$plot ``` ```{r banksy-clustering-metrics} metrics_df <- calculate_clustering_metrics( norm_list = banksy_norm, ground_truth_col = "layer_guess", cluster_col = "banksy_cluster", methods = names(banksy_norm) ) metrics_df p_metrics <- plot_clustering_metrics( metrics_df = metrics_df, metrics = c("ARI", "NMI", "HOM", "COM", "ASW", "Overall"), ncol = 2, scales = "free_y", theme_name = "bw" ) p_metrics$plot ``` ```{r banksy-ranking} ranking_df <- rank_normalization_methods(metrics_df = metrics_df) ranking_df p_ranking <- plot_normalization_ranking( ranking_df = ranking_df, bar_width = 0.7, label_size = 3.5, theme_name = "classic" ) p_ranking$plot ``` ## BANKSY with different gene-selection strategies For a small example dataset, a selection size of 500 can exceed the number of available genes. For the small dataset, each selection strategy uses up to the available number of genes. ```{r banksy-gene-selection} data(svg_example) banksy_genes <- run_banksy_gene_selection( norm_list = norm, svg_list = svg_example, gene_selection = "all", assay_name = "logcounts", k_geom = 15, lambda = 0.8, resolution = 0.2, seed = 123 ) metrics_genes <- calculate_gene_selection_metrics( banksy_list = banksy_genes, ground_truth_col = "layer_guess" ) p_genes <- plot_gene_selection_metrics( metrics_df = metrics_genes, ncol = 3, scales = "free_y", theme_name = "classic" ) p_genes$plot ``` # Session information ```{r session-info} sessionInfo() ```