2.1 Minimum requirements

Recalculations in custom panels are performed using user-defined functions that are supplied to the iSEE() call. The only requirements are that the function has to accept:

• A SummarizedExperiment object or its derivatives as the first argument.
• A vector of row names as the second argument, specifying the rows that are selected in the transmitting row-panel panel.
• A vector of column names as the third argument, specifying the columns that are selected in the transmitting column-based panel.

In addition:

• For custom plot panels, the function is expected to produce a ggplot object.
• For custom table panels, the function is expected to produce a data.frame.

2.2 Example of custom plot panel

To demonstrate the use of custom plot panels, we define an example function CUSTOM_PCA below. This takes a subset of features and cells in a SingleCellExperiment object, performs a principal components analysis (PCA) using that subset with runPCA, and creates a plot of the first two principal components with plotPCA (McCarthy et al. 2017).

library(scater)
CUSTOM_PCA <- function(se, rows, columns, colour_by=NULL, scale_features=TRUE) {
    if (!is.null(columns)) {
        kept <- se[, columns]
    } else {
        return(
            ggplot() + theme_void() + geom_text(
                aes(x, y, label=label),
                data.frame(x=0, y=0, label="No column data selected."),
                size=5)
            )
    }

    scale_features <- as.logical(scale_features)
    kept <- runPCA(kept, feature_set=rows, scale_features=scale_features)
    plotPCA(kept, colour_by=colour_by)
}

Note that rows and columns may be NULL if no selection was made in the respective transmitting panels. How these should be treated is up to the user-defined function. In the CUSTOM_PCA example above, an empty ggplot is returned if there is no selection on the columns, while the default runPCA behaviour is used if feature_set=NULL.

2.3 Example of custom table panel

To demonstrate the use of custom table panels, we define an example function CUSTOM_SUMMARY below. This takes a subset of features and cells in a SingleCellExperiment object, and creates data-frame that details the mean, variance and count of samples with expression above a given cut-off within the selection.

CUSTOM_SUMMARY <- function(se, ri, ci, assay="logcounts", min_exprs=0) {
    if (is.null(ri)) {
        ri <- rownames(se)
    }
    if (is.null(ci)) {
        ci <- colnames(se)
    }
    
    assayMatrix <- assay(se, assay)[ri, ci, drop=FALSE]
    
    data.frame(
        Mean = rowMeans(assayMatrix),
        Var = rowVars(assayMatrix),
        Sum = rowSums(assayMatrix),
        n_detected = rowSums(assayMatrix > min_exprs),
        row.names = ri
    )
}

Note that in the CUSTOM_SUMMARY example above, if either rows or columns are NULL, all rows or columns are used, respectively.

2.4 Additional arguments

Users of custom panels can specify additional arguments via a text box that accepts multi-line inputs. This is automatically converted into named arguments before being passed to the custom function. Each line corresponds to one argument:value pair, separated by the first space (ignoring whitespace at the start of the line).

For example, consider the CUSTOM_PCA function. If a user were to type:

colour_by Nanog
scale_features FALSE

… in the text box, this would pass colour_by="Nanog" and scale_features="TRUE" to CUSTOM_PCA. Note that all additional arguments are passed as character strings for the sake of security. It is the responsibility of the custom function to perform any necessary type checks and conversions (hence the as.logical in CUSTOM_PCA).

Similarly, additional arguments can be passed to the CUSTOM_SUMMARY function above. For instance:

assay counts
min_exprs 5

2.5 Example use

Using the sce object that we generated earlier, we will add some fields for examining the mean-variance relationship across features:

rowData(sce)$mean_log <- rowMeans(logcounts(sce))
rowData(sce)$var_log <- apply(logcounts(sce), 1, var)

We will then set up an iSEE instance with four panels - a reduced dimension plot, a row data plot, a custom plot, and a custom table. Note how both custom panels initially receives a column selection from the reduced dimension plot and a row selection from the row data plot. We also set the initial function to the name of CUSTOM_PCA in customDataFun, and the initial arguments to the values described above.

library(iSEE)
reddim <- redDimPlotDefaults(sce, 1)
rowdat <- rowDataPlotDefaults(sce, 1)
rowdat$XAxis <- "Row data"
rowdat$XAxisRowData <- "mean_log"
rowdat$YAxis <- "var_log"

cdp <- customDataPlotDefaults(sce, 1)
cdp$Function <- "CUSTOM_PCA"
cdp$Arguments <- "colour_by Nanog\nscale_features FALSE"
cdp$ColumnSource <- "Reduced dimension plot 1"
cdp$RowSource <- "Row data plot 1"

cst <- customStatTableDefaults(sce, 1)
cst$Function <- "CUSTOM_SUMMARY"
cst$Arguments <- "assay logcounts\nmin_exprs 1"
cst$ColumnSource <- "Reduced dimension plot 1"
cst$RowSource <- "Row data plot 1"

app <- iSEE(
    sce, redDimArgs=reddim, rowDataArgs=rowdat, customDataArgs=cdp, customStatArgs=cst,
    initialPanels=DataFrame(
        Name=c(
            "Reduced dimension plot 1", "Row data plot 1",
            "Custom data plot 1", "Custom statistics table 1"),
        Width=c(4, 4, 4, 12)),
    customDataFun=list(CUSTOM_PCA=CUSTOM_PCA),
    customStatFun=list(CUSTOM_SUMMARY=CUSTOM_SUMMARY)
    )