---
title: "splots: visualization of data from assays in microtitre plate or slide format"
author: "Wolfgang Huber"
package: splots
date: "2021-01-04"
output: 
    BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{splots: visualization of data from assays in microtitre plate or slide format}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}  

---

The `splots` package was written in 2006, and it is still here to support legacy code and to not disrupt other packages that depend on it. It should not be used for new code development. The package provides a single function, `plotScreen`, for visualising data in microtitre plate or slide format. Please consider using the `r CRANpkg("platetools")` package (see also https://github.com/Swarchal/platetools), or simply `r CRANpkg("ggplot2")`, as exemplified below.
  
# Example data

```{r exampledata1, message=FALSE, warning=FALSE} 
data("featuresPerWell", package = "HD2013SGI")
```

This dataset contains measurements of a combinatorial RNAi screen on a human cell line (HCT116) with fluorescent microscopy as a phenotypic readout, as described in the documentation of the `HD2013SGI` package.
There are `r length(unique(featuresPerWell[[1]]$plate))` plates, each with 384 wells. Within each well, the microscope took images at `r length(unique(featuresPerWell[[1]]$field))` locations, called `field`. Plate, row, column and field ID are given in the following dataframe.

```{r exampledata2} 
str(featuresPerWell[[1]])
```

The actual measurements are in the following matrix, whose rows are aligned with the above dataframe. Its `r ncol(featuresPerWell[[2]])` columns are different morphometric measurements, averaged across the cells in that image.

```{r exampledata3} 
str(featuresPerWell[[2]])
```
```{r exampledata4, echo = FALSE} 
stopifnot(nrow(featuresPerWell[[1]]) == nrow(featuresPerWell[[2]]))
```

For the purpose of this demo, we only use the first 40 plates and the `count` measurement in field 1, i.e., the number of cells in that field---a proxy for the cells' viability. We also convert the `row` and `col` variables into integers.

```{r exampledata5, message=FALSE, warning=FALSE}
library("dplyr")
sgi = tibble(featuresPerWell[[1]], count = featuresPerWell[[2]][, "count"]) |>
  filter(plate %in% unique(plate)[1:40],
         field == "1") |>
  mutate (col = as.integer(col),
          row = match(row, LETTERS))
sgi
```

# Using `ggplot2`

```{r plotgg, fig.wide = TRUE, fig.cap = "Visualization using `ggplot`", fig.dim=c(10, 18), message=FALSE, warning=FALSE}
library("ggplot2")
ggplot(sgi, aes(x = col, y = row, fill = count)) + geom_raster() +
  facet_wrap(vars(plate), ncol = 4) +
  scale_fill_gradient(low = "white", high = "#00008B")
```

# Using `splots::plotScreen`

The `plotScreen` takes as input the list `xl`, constructed below. As you can see, this is a lot more clumsy.

```{r xl1, results = "hide"}
np = 40
nx = 24
ny = 16
plateNames = unique(featuresPerWell[[1]]$plate)
assertthat::assert_that(length(plateNames) >= np)
plateNames = plateNames[seq_len(np)]
xl = lapply(plateNames, function(pl) {
  sel = with(featuresPerWell[[1]], plate == pl & field == "1")
  rv = rep(NA_real_, nx * ny)
  r = match(featuresPerWell[[1]]$row[sel], LETTERS)
  c = match(featuresPerWell[[1]]$col[sel], paste(seq_len(nx)))
  i = (r-1) * nx + c
  assertthat::assert_that(!any(is.na(r)), !any(is.na(c)), !any(duplicated(i)),
                          all(r>=1), all(r<=ny), all(c>=1), all(c<=nx))
  rv[i] = featuresPerWell[[2]][sel, "count"]
  rv
})
names(xl) = plateNames
```

So this the list `xl`:

```{r xl2}
length(xl)
names(xl)[1:4]
unique(vapply(xl, function(x) paste(class(x), length(x)), character(1)))
xl[[1]][1:30]
```

```{r fig1, fig.wide = TRUE, fig.cap = "Visualization using `splots::plotScreen`", fig.dim=c(10, 18)}
splots::plotScreen(xl, nx = nx, ny = ny, ncol = 4, 
           fill = c("white", "#00008B"), 
           main = "HD2013SGI", legend.label = "count",
           zrange = c(0, max(unlist(xl), na.rm = TRUE)))
```


```{r sessionInfo}
sessionInfo()
```