# Overview of the tidyseurat package

## Stefano Mangiola

### 2025-11-10

Brings Seurat to the tidyverse!

website: stemangiola.github.io/tidyseurat/

Please also have a look at

- tidyseurat for tidy single-cell RNA sequencing analysis
- tidySummarizedExperiment for tidy bulk RNA sequencing analysis
- tidybulk for tidy bulk RNA-seq analysis
- tidygate for adding custom gate information to your tibble
- tidyHeatmap for heatmaps produced with tidy principles

# Introduction

tidyseurat provides a bridge between the Seurat single-cell package Butler 2018 Stuart 2019 and the tidyverse Wickham 2019. It creates an invisible layer that enables viewing the Seurat object as a tidyverse tibble, and provides Seurat-compatible dplyr, tidyr, ggplot and plotly functions.

## Functions/utilities available

Seurat-compatible Functions | Description
--- | ---
`all` |

tidyverse Packages | Description
--- | ---
`dplyr` | All `dplyr` APIs like for any tibble
`tidyr` | All `tidyr` APIs like for any tibble
`ggplot2` | `ggplot` like for any tibble
`plotly` | `plot_ly` like for any tibble

Utilities | Description
--- | ---
`tidy` | Add `tidyseurat` invisible layer over a Seurat object
`as_tibble` | Convert cell-wise information to a `tbl_df`
`join_features` | Add feature-wise information, returns a `tbl_df`
`aggregate_cells` | Aggregate cell gene-transcription abundance as pseudobulk tissue

## Installation

From CRAN

    install.packages("tidyseurat")

From Github (development)

    devtools::install_github("stemangiola/tidyseurat")

    library(dplyr)
    library(tidyr)
    library(purrr)
    library(magrittr)
    library(ggplot2)
    library(Seurat)
    library(tidyseurat)

## Create `tidyseurat`, the best of both worlds!

This is a seurat object but it is evaluated as tibble. So it is fully compatible both with Seurat and tidyverse APIs.

    pbmc_small = SeuratObject::pbmc_small

It looks like a tibble

    pbmc_small

    ## # A Seurat-tibble abstraction: 80 × 15
    ## # [90mFeatures=230 | Cells=80 | Active assay=RNA | Assays=RNA[0m
    ##    .cell orig.ident nCount_RNA nFeature_RNA RNA_snn_res.0.8 letter.idents groups
    ##    <chr> <fct>           <dbl>        <int> <fct>           <fct>         <chr>
    ##  1 ATGC… SeuratPro…         70           47 0               A             g2
    ##  2 CATG… SeuratPro…         85           52 0               A             g1
    ##  3 GAAC… SeuratPro…         87           50 1               B             g2
    ##  4 TGAC… SeuratPro…        127           56 0               A             g2
    ##  5 AGTC… SeuratPro…        173           53 0               A             g2
    ##  6 TCTG… SeuratPro…         70           48 0               A             g1
    ##  7 TGGT… SeuratPro…         64           36 0               A             g1
    ##  8 GCAG… SeuratPro…         72           45 0               A             g1
    ##  9 GATA… SeuratPro…         52           36 0               A             g1
    ## 10 AATG… SeuratPro…        100           41 0               A             g1
    ## # ℹ 70 more rows
    ## # ℹ 8 more variables: RNA_snn_res.1 <fct>, PC_1 <dbl>, PC_2 <dbl>, PC_3 <dbl>,
    ## #   PC_4 <dbl>, PC_5 <dbl>, tSNE_1 <dbl>, tSNE_2 <dbl>

But it is a Seurat object after all

    pbmc_small@assays

    ## $RNA
    ## Assay data with 230 features for 80 cells
    ## Top 10 variable features:
    ##  PPBP, IGLL5, VDAC3, CD1C, AKR1C3, PF4, MYL9, GNLY, TREML1, CA2

# Preliminary plots

Set colours and theme for plots.

    # Use colourblind-friendly colours
    friendly_cols <- c("#88CCEE", "#CC6677", "#DDCC77", "#117733", "#332288", "#AA4499", "#44AA99", "#999933", "#882255", "#661100", "#6699CC")

    # Set theme
    my_theme <-
      list(
        scale_fill_manual(values = friendly_cols),
        scale_color_manual(values = friendly_cols),
        theme_bw() +
          theme(
            panel.border = element_blank(),
            axis.line = element_line(),
            panel.grid.major = element_line(size = 0.2),
            panel.grid.minor = element_line(size = 0.1),
            text = element_text(size = 12),
            legend.position = "bottom",
            aspect.ratio = 1,
            strip.background = element_blank(),
            axis.title.x = element_text(margin = margin(t = 10, r = 10, b = 10, l = 10)),
            axis.title.y = element_text(margin = margin(t = 10, r = 10, b = 10, l = 10))
          )
      )

We can treat `pbmc_small` effectively as a normal tibble for plotting.

Here we plot number of features per cell.

    pbmc_small %>%
      ggplot(aes(nFeature_RNA, fill = groups)) +
      geom_histogram() +
      my_theme

Here we plot total features per cell.

    pbmc_small %>%
      ggplot(aes(groups, nCount_RNA, fill = groups)) +
      geom_boxplot(outlier.shape = NA) +
      geom_jitter(width = 0.1) +
      my_theme

Here we plot abundance of two features for each group.

    pbmc_small %>%
      join_features(features = c("HLA-DRA", "LYZ"), shape = "long") %>%
      ggplot(aes(groups, .abundance_RNA + 1, fill = groups)) +
      geom_boxplot(outlier.shape = NA) +
      geom_jitter(aes(size = nCount_RNA), alpha = 0.5, width = 0.2) +
      scale_y_log10() +
      my_theme

# Preprocess the dataset

Also you can treat the object as Seurat object and proceed with data processing.

    pbmc_small_pca <-
      pbmc_small %>%
      SCTransform(verbose = FALSE) %>%
      FindVariableFeatures(verbose = FALSE) %>%
      RunPCA(verbose = FALSE)

    pbmc_small_pca

    ## # A Seurat-tibble abstraction: 80 × 17
    ## # [90mFeatures=220 | Cells=80 | Active assay=SCT | Assays=RNA, SCT[0m
    ##    .cell orig.ident nCount_RNA nFeature_RNA RNA_snn_res.0.8 letter.idents groups
    ##    <chr> <fct>           <dbl>        <int> <fct>           <fct>         <chr>
    ##  1 ATGC… SeuratPro…         70           47 0               A             g2
    ##  2 CATG… SeuratPro…         85           52 0               A             g1
    ##  3 GAAC… SeuratPro…         87           50 1               B             g2
    ##  4 TGAC… SeuratPro…        127           56 0               A             g2
    ##  5 AGTC… SeuratPro…        173           53 0               A             g2
    ##  6 TCTG… SeuratPro…         70           48 0               A             g1
    ##  7 TGGT… SeuratPro…         64           36 0               A             g1
    ##  8 GCAG… SeuratPro…         72           45 0               A             g1
    ##  9 GATA… SeuratPro…         52           36 0               A             g1
    ## 10 AATG… SeuratPro…        100           41 0               A             g1
    ## # ℹ 70 more rows
    ## # ℹ 10 more variables: RNA_snn_res.1 <fct>, nCount_SCT <dbl>,
    ## #   nFeature_SCT <int>, PC_1 <dbl>, PC_2 <dbl>, PC_3 <dbl>, PC_4 <dbl>,
    ## #   PC_5 <dbl>, tSNE_1 <dbl>, tSNE_2 <dbl>

If a tool is not included in the tidyseurat collection, we can use `as_tibble` to permanently convert `tidyseurat` into tibble.

    pbmc_small_pca %>%
      as_tibble() %>%
      select(contains("PC"), everything()) %>%
      GGally::ggpairs(columns = 1:5, ggplot2::aes(colour = groups)) +
      my_theme

# Identify clusters

We proceed with cluster identification with Seurat.

    pbmc_small_cluster <-
      pbmc_small_pca %>%
      FindNeighbors(verbose = FALSE) %>%
      FindClusters(method = "igraph", verbose = FALSE)

    pbmc_small_cluster

    ## # A Seurat-tibble abstraction: 80 × 19
    ## # [90mFeatures=220 | Cells=80 | Active assay=SCT | Assays=RNA, SCT[0m
    ##    .cell orig.ident nCount_RNA nFeature_RNA RNA_snn_res.0.8 letter.idents groups
    ##    <chr> <fct>           <dbl>        <int> <fct>           <fct>         <chr>
    ##  1 ATGC… SeuratPro…         70           47 0               A             g2
    ##  2 CATG… SeuratPro…         85           52 0               A             g1
    ##  3 GAAC… SeuratPro…         87           50 1               B             g2
    ##  4 TGAC… SeuratPro…        127           56 0               A             g2
    ##  5 AGTC… SeuratPro…        173           53 0               A             g2
    ##  6 TCTG… SeuratPro…         70           48 0               A             g1
    ##  7 TGGT… SeuratPro…         64           36 0               A             g1
    ##  8 GCAG… SeuratPro…         72           45 0               A             g1
    ##  9 GATA… SeuratPro…         52           36 0               A             g1
    ## 10 AATG… SeuratPro…        100           41 0               A             g1
    ## # ℹ 70 more rows
    ## # ℹ 12 more variables: RNA_snn_res.1 <fct>, nCount_SCT <dbl>,
    ## #   nFeature_SCT <int>, SCT_snn_res.0.8 <fct>, seurat_clusters <fct>,
    ## #   PC_1 <dbl>, PC_2 <dbl>, PC_3 <dbl>, PC_4 <dbl>, PC_5 <dbl>, tSNE_1 <dbl>,
    ## #   tSNE_2 <dbl>

Now we can interrogate the object as if it was a regular tibble data frame.

    pbmc_small_cluster %>%
      count(groups, seurat_clusters)

    ## # A tibble: 6 × 3
    ##   groups seurat_clusters     n
    ##   <chr>  <fct>           <int>
    ## 1 g1     0                  23
    ## 2 g1     1                  17
    ## 3 g1     2                   4
    ## 4 g2     0                  17
    ## 5 g2     1                  13
    ## 6 g2     2                   6

We can identify cluster markers using Seurat.

    # Identify top 10 markers per cluster
    markers <-
      pbmc_small_cluster %>%
      FindAllMarkers(only.pos = TRUE, min.pct = 0.25, thresh.use = 0.25) %>%
      group_by(cluster) %>%
      top_n(10, avg_log2FC)

    # Plot heatmap
    pbmc_small_cluster %>%
      DoHeatmap(
        features = markers$gene,
        group.colors = friendly_cols
      )

# Reduce dimensions

We can calculate the first 3 UMAP dimensions using the Seurat framework.

    pbmc_small_UMAP <-
      pbmc_small_cluster %>%
      RunUMAP(reduction = "pca", dims = 1:15, n.components = 3L)

And we can plot them using 3D plot using plotly.

    pbmc_small_UMAP %>%
      plot_ly(
        x = ~`UMAP_1`,
        y = ~`UMAP_2`,
        z = ~`UMAP_3`,
        color = ~seurat_clusters,
        colors = friendly_cols[1:4]
      )

## Cell type prediction

We can infer cell type identities using SingleR Aran 2019 and manipulate the output using tidyverse.

    # Get cell type reference data
    blueprint <- celldex::BlueprintEncodeData()

    # Infer cell identities
    cell_type_df <-
      GetAssayData(pbmc_small_UMAP, slot = 'counts', assay = "SCT") %>%
      log1p() %>%
      Matrix::Matrix(sparse = TRUE) %>%
      SingleR::SingleR(
        ref = blueprint,
        labels = blueprint$label.main,
        method = "single"
      ) %>%
      as.data.frame() %>%
      as_tibble(rownames = "cell") %>%
      select(cell, first.labels)

    # Join UMAP and cell type info
    pbmc_small_cell_type <-
      pbmc_small_UMAP %>%
      left_join(cell_type_df, by = "cell")

    # Reorder columns
    pbmc_small_cell_type %>%
      select(cell, first.labels, everything())

We can easily summarise the results. For example, we can see how cell type classification overlaps with cluster classification.

    pbmc_small_cell_type %>%
      count(seurat_clusters, first.labels)

We can easily reshape the data for building information-rich faceted plots.

    pbmc_small_cell_type %>%

      # Reshape and add classifier column
      pivot_longer(
        cols = c(seurat_clusters, first.labels),
        names_to = "classifier", values_to = "label"
      ) %>%

      # UMAP plots for cell type and cluster
      ggplot(aes(UMAP_1, UMAP_2, color = label)) +
      geom_point() +
      facet_wrap(~classifier) +
      my_theme

We can easily plot gene correlation per cell category, adding multi-layer annotations.

    pbmc_small_cell_type %>%

      # Add some mitochondrial abundance values
      mutate(mitochondrial = rnorm(n())) %>%

      # Plot correlation
      join_features(features = c("CST3", "LYZ"), shape = "wide") %>%
      ggplot(aes(CST3 + 1, LYZ + 1, color = groups, size = mitochondrial)) +
      geom_point() +
      facet_wrap(~first.labels, scales = "free") +
      scale_x_log10() +
      scale_y_log10() +
      my_theme

# Nested analyses

A powerful tool we can use with tidyseurat is `nest`. We can easily perform independent analyses on subsets of the dataset. First we classify cell types in lymphoid and myeloid; then, nest based on the new classification

    pbmc_small_nested <-
      pbmc_small_cell_type %>%
      filter(first.labels != "Erythrocytes") %>%
      mutate(cell_class = if_else(`first.labels` %in% c("Macrophages", "Monocytes"), "myeloid", "lymphoid")) %>%
      nest(data = -cell_class)

    pbmc_small_nested

Now we can independently for the lymphoid and myeloid subsets (i) find variable features, (ii) reduce dimensions, and (iii) cluster using both tidyverse and Seurat seamlessly.

    pbmc_small_nested_reanalysed <-
      pbmc_small_nested %>%
      mutate(data = map(
        data, ~ .x %>%
          FindVariableFeatures(verbose = FALSE) %>%
          RunPCA(npcs = 10, verbose = FALSE) %>%
          FindNeighbors(verbose = FALSE) %>%
          FindClusters(method = "igraph", verbose = FALSE) %>%
          RunUMAP(reduction = "pca", dims = 1:10, n.components = 3L, verbose = FALSE)
      ))

    pbmc_small_nested_reanalysed

Now we can unnest and plot the new classification.

    pbmc_small_nested_reanalysed %>%

      # Convert to tibble otherwise Seurat drops reduced dimensions when unifying data sets.
      mutate(data = map(data, ~ .x %>% as_tibble())) %>%
      unnest(data) %>%

      # Define unique clusters
      unite("cluster", c(cell_class, seurat_clusters), remove = FALSE) %>%

      # Plotting
      ggplot(aes(UMAP_1, UMAP_2, color = cluster)) +
      geom_point() +
      facet_wrap(~cell_class) +
      my_theme

# Aggregating cells

Sometimes, it is necessary to aggregate the gene-transcript abundance from a group of cells into a single value. For example, when comparing groups of cells across different samples with fixed-effect models.

In tidyseurat, cell aggregation can be achieved using the `aggregate_cells` function.

    pbmc_small %>%
      aggregate_cells(groups, assays = "RNA")

# Session Info

    sessionInfo()

    ## R version 4.5.0 (2025-04-11)
    ## Platform: x86_64-apple-darwin20
    ## Running under: macOS Sonoma 14.6.1
    ##
    ## Matrix products: default
    ## BLAS:   /Library/Frameworks/R.framework/Versions/4.5-x86_64/Resources/lib/libRblas.0.dylib
    ## LAPACK: /Library/Frameworks/R.framework/Versions/4.5-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
    ##
    ## locale:
    ## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    ##
    ## time zone: Australia/Adelaide
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ##  [1] future_1.67.0      tidyseurat_0.8.7   ttservice_0.5.3    Seurat_5.3.0
    ##  [5] SeuratObject_5.2.0 sp_2.2-0           ggplot2_4.0.0      magrittr_2.0.4
    ##  [9] purrr_1.1.0        tidyr_1.3.1        dplyr_1.1.4        knitr_1.50
    ##
    ## loaded via a namespace (and not attached):
    ##   [1] deldir_2.0-4           pbapply_1.7-4          gridExtra_2.3
    ##   [4] rlang_1.1.6            RcppAnnoy_0.0.22       otel_0.2.0
    ##   [7] spatstat.geom_3.6-0    matrixStats_1.5.0      ggridges_0.5.7
    ##  [10] compiler_4.5.0         png_0.1-8              vctrs_0.6.5
    ##  [13] reshape2_1.4.4         stringr_1.5.2          pkgconfig_2.0.3
    ##  [16] fastmap_1.2.0          labeling_0.4.3         utf8_1.2.6
    ##  [19] promises_1.4.0         markdown_2.0           xfun_0.53
    ##  [22] litedown_0.7           jsonlite_2.0.0         goftest_1.2-3
    ##  [25] later_1.4.4            spatstat.utils_3.2-0   irlba_2.3.5.1
    ##  [28] parallel_4.5.0         cluster_2.1.8.1        R6_2.6.1
    ##  [31] ica_1.0-3              stringi_1.8.7          RColorBrewer_1.1-3
    ##  [34] spatstat.data_3.1-9    GGally_2.4.0           reticulate_1.44.0
    ##  [37] spatstat.univar_3.1-4  parallelly_1.45.1      lmtest_0.9-40
    ##  [40] scattermore_1.2        Rcpp_1.1.0             tensor_1.5.1
    ##  [43] future.apply_1.20.0    zoo_1.8-14             sctransform_0.4.2
    ##  [46] httpuv_1.6.16          Matrix_1.7-4           splines_4.5.0
    ##  [49] igraph_2.2.1           tidyselect_1.2.1       abind_1.4-8
    ##  [52] rstudioapi_0.17.1      spatstat.random_3.4-2  codetools_0.2-20
    ##  [55] miniUI_0.1.2           spatstat.explore_3.5-3 listenv_0.9.1
    ##  [58] lattice_0.22-7         tibble_3.3.0           plyr_1.8.9
    ##  [61] shiny_1.11.1           withr_3.0.2            S7_0.2.0
    ##  [64] ROCR_1.0-11            evaluate_1.0.5         Rtsne_0.17
    ##  [67] fastDummies_1.7.5      survival_3.8-3         ggstats_0.11.0
    ##  [70] polyclip_1.10-7        fitdistrplus_1.2-4     pillar_1.11.1
    ##  [73] KernSmooth_2.23-26     plotly_4.11.0          generics_0.1.4
    ##  [76] RcppHNSW_0.6.0         commonmark_2.0.0       scales_1.4.0
    ##  [79] globals_0.18.0         xtable_1.8-4           glue_1.8.0
    ##  [82] lazyeval_0.2.2         tools_4.5.0            data.table_1.17.8
    ##  [85] RSpectra_0.16-2        RANN_2.6.2             dotCall64_1.2
    ##  [88] cowplot_1.2.0          grid_4.5.0             colorspace_2.1-2
    ##  [91] nlme_3.1-168           patchwork_1.3.2        cli_3.6.5
    ##  [94] spatstat.sparse_3.1-0  fansi_1.0.6            spam_2.11-1
    ##  [97] viridisLite_0.4.2      uwot_0.2.3             gtable_0.3.6
    ## [100] digest_0.6.37          progressr_0.17.0       ggrepel_0.9.6
    ## [103] htmlwidgets_1.6.4      farver_2.1.2           htmltools_0.5.8.1
    ## [106] lifecycle_1.0.4        httr_1.4.7             mime_0.13
    ## [109] MASS_7.3-65

# References

Aran D, Looney AP, Liu L, Wu E, Fong V, Hsu A, Chak S, Naikawadi RP, Wolters PJ, Abate AR, others (2019). “Reference-based analysis of lung single-cell sequencing reveals a transitional profibrotic macrophage.” Nature immunology, 20(2), 163–172.

Butler A, Hoffman P, Smibert P, Papalexi E, Satija R (2018). “Integrating single-cell transcriptomic data across different conditions, technologies, and species.” Nature biotechnology, 36(5), 411–420.

Stuart T, Butler A, Hoffman P, Hafemeister C, Papalexi E, Mauck III WM, Hao Y, Stoeckius M, Smibert P, Satija R (2019). “Comprehensive integration of single-cell data.” Cell, 177(7), 1888–1902.

Wickham H, Averick M, Bryan J, Chang W, McGowan LD, François R, Grolemund G, Hayes A, Henry L, Hester J, others (2019). “Welcome to the Tidyverse.” Journal of Open Source Software, 4(43), 1686.