## ----setup, message=FALSE, warning=FALSE, include=FALSE-----------------------
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    fig.width = 5,
    fig.height = 4,
    fig.align="center",
    dpi = 96,
    fig.retina = 1,
    dev = "png"
    
)


## ----install-bioconductor, eval=FALSE-----------------------------------------
# if (!requireNamespace("BiocManager", quietly = TRUE)) {
#     install.packages("BiocManager")
# }
# 
# BiocManager::install("scOverlay")

## ----load-package-example, eval=FALSE-----------------------------------------
# library(scOverlay)

## ----install-github, eval=FALSE-----------------------------------------------
# if (!requireNamespace("BiocManager", quietly = TRUE)) {
#     install.packages("BiocManager")
# }
# 
# BiocManager::install("bernatgel/scOverlay")

## ----load-package-and-example-data, eval=TRUE, results="hide", message=FALSE, warning=FALSE----
library(scOverlay)
library(SingleCellExperiment)

data("sce_mpnst_example")

## ----view-example-data, eval=TRUE---------------------------------------------
sce_mpnst_example

## ----quick-start-1------------------------------------------------------------
plotOverlay(
    sce = sce_mpnst_example,
    foreground = "CDH19",
    background = "sample_type",
    bg_dimming = 0.7,
    reduced_dim = "TSNE"    
)

## ----quick-start-background---------------------------------------------------
plotOverlay(
    sce = sce_mpnst_example,
    reduced_dim = "UMAP",
    foreground = "scDblFinder.score",
    fg_palette = "viridis",
    fg_point_size = 0.5,
    background = "cluster",
    bg_palette = "pastel",
    bg_point_size = 4,
    bg_dimming = 0.6,
    bg_legend = FALSE,
    title = "Doublet score over clusters"
)

## ----quick-start-sample-subset------------------------------------------------
plotOverlay(
    sce = sce_mpnst_example,
    foreground = "CDH19",
    fg_point_size = 0.8,
    background = "cluster",
    reduced_dim = "TSNE",
    fg_subset_cells = quote(sample == "ANF1"),
    title = "CDH19 in ANF1",
    bg_dimming = 0.9,
    bg_legend = FALSE
)


## ----load-data----------------------------------------------------------------
data("sce_mpnst_example")
sce_mpnst_example

## ----inspect-object-----------------------------------------------------------
reducedDimNames(sce_mpnst_example)
assayNames(sce_mpnst_example)
colnames(colData(sce_mpnst_example))

## ----inspect-genes------------------------------------------------------------
c("SOX10", "S100B", "CDH19", "MKI67") %in% rownames(sce_mpnst_example)

## ----overlay-model-gene, eval=FALSE-------------------------------------------
# plotOverlay(
#     sce = sce_mpnst_example,
#     foreground = "CDH19",
#     background = "sample_type",
#     reduced_dim = "TSNE"
# )

## ----foreground-numeric-metadata, eval=FALSE----------------------------------
# plotOverlay(
#     sce = sce_mpnst_example,
#     foreground = "scDblFinder.score",
#     fg_type = "continuous",
#     background = "cluster",
#     bg_type = "categorical",
#     reduced_dim = "TSNE"
# )

## ----foreground-example-------------------------------------------------------
p4 <- plotOverlay(
    sce = sce_mpnst_example,
    foreground = "scDblFinder.score",
    fg_type = "continuous",
    fg_order = "ascending",
    fg_subset_cells = quote(sample_type != "MPNST"),
    reduced_dim = "TSNE",
    background = "cluster",
    bg_point_size = 3,
    title = "scDblFinder.score in non-MPNST samples",
    bg_legend = FALSE
)
p4

## ----bivariate-foreground, fig.width=7, fig.height=4, fig.wide=TRUE-----------
p_biv <- plotOverlay(
    sce = sce_mpnst_example,
    foreground = c("SOX10", "MKI67"),
    fg_type = "bivariate",
    fg_palette = "bivariateBright",
    background = "cluster",
    bg_dimming = 0.9,
    bg_legend = FALSE,
    reduced_dim = "TSNE"
)

leg_biv <- plotBivariateLegend(
    features = c("SOX10", "MKI67"),
    palette = "bivariateBright"
)

patchwork::wrap_plots(p_biv, leg_biv, widths = c(1, 0.25))

## ----custom-bivariate-palette, eval=FALSE-------------------------------------
# custom_biv <- c(
#     low_xy = "#e6e6e6",
#     high_x = "#ff4346",
#     high_y = "#55b2ff",
#     high_xy = "#7a1fa2"
# )
# 
# plotBivariateLegend(
#     features = c("SOX10", "MKI67"),
#     palette = custom_biv
# )

## ----combination-foreground, fig.width=5, fig.height=4------------------------
plotOverlay(
    sce = sce_mpnst_example,
    foreground = c("SOX10", "MKI67"),
    fg_type = "combination",
    fg_threshold = 0,
    background = "cluster",
    bg_dimming = 0.9,
    bg_legend = FALSE,
    reduced_dim = "TSNE"
)

## ----combination-foreground-median, eval=FALSE--------------------------------
# plotOverlay(
#     sce = sce_mpnst_example,
#     foreground = c("SOX10", "MKI67", "CDH19"),
#     fg_type = "combination",
#     fg_threshold = "median",
#     background = "solid",
#     reduced_dim = "TSNE"
# )

## ----gene-overlay-list--------------------------------------------------------
gene_plots <- plotGeneOverlay(
    sce = sce_mpnst_example,
    genes = c("S100B", "CDH19", "PRRX1", "EGFR"),
    background = "solid",
    reduced_dim = "TSNE",
    fg_order = "ascending"
)

names(gene_plots)

## ----gene-overlay-single, eval=FALSE------------------------------------------
# gene_plots$CDH19

## ----gene-overlay-background, fig.width=12, fig.height=8, fig.wide=TRUE-------
library(patchwork)

gene_plots_bg <- plotGeneOverlay(
    sce = sce_mpnst_example,
    genes = c("SOX10", "CDH19", "PRRX1", "EGFR"),
    background = "sample_type",
    reduced_dim = "TSNE",
    fg_order = "ascending",
    bg_dimming = 0.7
)

(gene_plots_bg$SOX10 + gene_plots_bg$CDH19) /
    (gene_plots_bg$PRRX1 + gene_plots_bg$EGFR)

## ----gene-overlay-missing, warning=TRUE---------------------------------------
gene_plots_subset <- plotGeneOverlay(
    sce = sce_mpnst_example,
    genes = c("SOX10", "NOT_A_GENE"),
    background = "solid",
    reduced_dim = "TSNE",
    fg_order = "ascending"
)

names(gene_plots_subset)

## ----per-group-sample-type-order, fig.width=12, fig.height=3, fig.wide=TRUE----
p2 <- plotOverlayPerGroup(
    sce = sce_mpnst_example,
    group_col = "sample_type",
    group_order = c("Nerve", "PNF", "ANF", "MPNST"),
    foreground = "CDH19",
    background = "cluster",
    reduced_dim = "TSNE",
    fg_order = "ascending",
    fg_legend = FALSE,
    bg_legend = FALSE,
    bg_dimming = 0.9
)
p2

## ----per-group-extra-subset, fig.width=12, fig.height=3, fig.wide=TRUE--------
p4 <- plotOverlayPerGroup(
    sce = sce_mpnst_example,
    group_col = "sample_type",
    group_order = c("Nerve", "PNF", "ANF", "MPNST"),
    foreground = "S100B",
    background = "cluster",
    reduced_dim = "TSNE",
    fg_subset_cells = quote(celltype.main == "Schwann cell"),
    fg_order = "ascending",
    fg_legend = FALSE,
    bg_legend = FALSE
)
p4

## ----per-group-shared-scales, fig.width=12, fig.height=4.5, fig.wide=TRUE-----
p_shared <- plotOverlayPerGroup(
    sce = sce_mpnst_example,
    group_col = "sample_type",
    group_order = c("Nerve", "PNF", "ANF", "MPNST"),
    foreground = "CDH19",
    background = "cluster",
    bg_dimming = 0.9,
    reduced_dim = "TSNE",
    fg_order = "ascending",
    fg_legend = TRUE,
    bg_legend = FALSE,
    fg_limits = "shared",
    shared_legend = TRUE
)

p_shared & ggplot2::theme(legend.position = "bottom")

## ----nested-groups-1, fig.width=12, fig.height=12, fig.wide=TRUE--------------
p1 <- plotOverlayPerNestedGroup(
    sce = sce_mpnst_example,
    group_col = "sample",
    outer_col = "sample_type",
    outer_order = c("Nerve", "PNF", "ANF", "MPNST"),
    foreground = "CDH19",
    background = "cluster",
    reduced_dim = "TSNE",
    bg_dimming = 0.9,
    fg_order = "ascending",
    fg_limits = "shared",
    shared_legend = TRUE,
    bg_legend = FALSE,
    layout = "auto"
)
p1

## ----nested-groups-grid, fig.width=8, fig.height=7, fig.wide=TRUE-------------
sce_mpnst_example$detected_group <- ifelse(
    sce_mpnst_example$n_detected > median(sce_mpnst_example$n_detected),
    "High detected genes",
    "Low detected genes"
)

p_grid <- plotOverlayPerNestedGroup(
    sce = sce_mpnst_example,
    outer_col = "sample_type",
    group_col = "detected_group",
    foreground = "SOX10",
    background = "celltype.main",
    layout = "auto",
    fg_limits = "shared",
    shared_legend = TRUE,
    bg_legend = FALSE,
    reduced_dim = "TSNE"
)
p_grid

## ----nested-groups-2, fig.width=12, fig.height=12, fig.wide=TRUE--------------
p1 <- plotOverlayPerNestedGroup(
    sce = sce_mpnst_example,
    group_col = "sample",
    outer_col = "sample_type",
    outer_order = c("Nerve", "PNF", "ANF", "MPNST"),
    foreground = "PRRX1",
    background = "cluster",
    reduced_dim = "TSNE",
    bg_dimming = 0.9,
    fg_order = "ascending",
    fg_limits = "shared",
    shared_legend = TRUE,
    bg_legend = FALSE,
    fg_subset_cells = quote(celltype.main == "Mesenchymal"),
    layout = "auto"
)
p1

## ----list-palettes------------------------------------------------------------
listPalettes()

## ----list-bivariate-palettes--------------------------------------------------
listPalettes(type = "bivariate")

## ----list-palettes-plot, fig.width=9, fig.height=7, fig.wide=TRUE-------------
plotPalettes(n = 9)

## ----palette-patchwork, fig.width=8, fig.height=7, fig.wide=TRUE--------------
my_palettes <- list(
    "gray_red",
    "blue_gold",
    "viridis",
    c("cornsilk", "khaki1", "yellow2", "darkgoldenrod")
)

plots <- lapply(my_palettes, function(pal) {
    plotOverlay(
        sce = sce_mpnst_example,
        foreground = "CDH19",
        background = "solid",
        reduced_dim = "TSNE",
        fg_palette = pal,
        fg_order = "ascending",
        fg_legend = FALSE,
        title = pal
    )
})


patchwork::wrap_plots(plots, ncol = 2)

## ----palette-named-categorical------------------------------------------------
sample_type_palette <- c(
    Nerve = "#4E79A7",
    PNF = "#59A14F",
    ANF = "#F28E2B",
    MPNST = "#E15759"
)

plotOverlay(
    sce = sce_mpnst_example,
    foreground = "sample_type",
    background = "solid",
    reduced_dim = "TSNE",
    fg_type = "categorical",
    fg_palette = sample_type_palette
)

## ----palette-named-categorical-rules------------------------------------------
sample_type_palette <- c(
    Nerve = "#4E79A7",
    PNF = "#59A14F",
    ANF = "#F28E2B",
    MPNST = "#E15759"
)

getPalette(
    palette = sample_type_palette,
    type = "categorical",
    values = c("Nerve", "PNF", "ANF", "MPNST")
)

pal <- getPalette("scOverlay", type = "categorical", n = 4)
setNames(
    unname(pal),
    c("Nerve", "PNF", "ANF", "MPNST")
)

## ----raster-background--------------------------------------------------------
p1 <- plotOverlay(
    sce = sce_mpnst_example,
    foreground = "SOX10",
    background = "sample_type",
    reduced_dim = "TSNE",
    fg_order = "ascending",
    bg_raster = TRUE,
    bg_dimming = 0.7
)
p1

## ----raster-background-only---------------------------------------------------
p2 <- plotOverlay(
    sce = sce_mpnst_example,
    foreground = "CDH19",
    background = "sample_type",
    reduced_dim = "TSNE",
    fg_subset_cells = quote(sample_type == "MPNST"),
    fg_order = "ascending",
    bg_raster = TRUE,
    fg_raster = FALSE
)
p2

## ----raster-both, eval=FALSE--------------------------------------------------
# p3 <- plotOverlay(
#     sce = sce_mpnst_example,
#     foreground = "SOX10",
#     background = "sample_type",
#     reduced_dim = "TSNE",
#     fg_order = "ascending",
#     bg_raster = TRUE,
#     fg_raster = TRUE,
#     raster_dpi = 300
# )
# p3

## ----save-create-plot---------------------------------------------------------
p <- plotOverlay(
    sce = sce_mpnst_example,
    foreground = "SOX10",
    background = "sample_type",
    reduced_dim = "TSNE",
    fg_order = "ascending",
    bg_raster = TRUE
)

## ----save-plot-files, eval=FALSE----------------------------------------------
# ggplot2::ggsave(
#     filename = "SOX10_overlay.png",
#     plot = p,
#     width = 5,
#     height = 5,
#     dpi = 300
# )
# 
# ggplot2::ggsave(
#     filename = "SOX10_overlay.pdf",
#     plot = p,
#     width = 5,
#     height = 5
# )
# 
# ggplot2::ggsave(
#     filename = "SOX10_overlay.svg",
#     plot = p,
#     width = 5,
#     height = 5
# )

## ----save-grouped-plot, eval=FALSE--------------------------------------------
# p_grouped <- plotOverlayPerGroup(
#     sce = sce_mpnst_example,
#     group_col = "sample_type",
#     group_order = c("Nerve", "PNF", "ANF", "MPNST"),
#     foreground = "SOX10",
#     background = "solid",
#     reduced_dim = "TSNE",
#     fg_order = "ascending"
# )
# 
# panel_width <- 4
# panel_height <- 4
# n_panels <- length(unique(sce_mpnst_example$sample_type))
# 
# ggplot2::ggsave(
#     filename = "SOX10_by_sample_type.pdf",
#     plot = p_grouped,
#     width = panel_width * n_panels,
#     height = panel_height
# )

## ----session-info-------------------------------------------------------------
sessionInfo()