Support custom plot order in ggcyto.

[djhammill]

@mikejiang here is my attempt at adding support for custom plot ordering in ggcyto to address the ordering issues raised here:

flowWorkspace: Setting pData factor levels · Issue #297 · RGLab/flowWorkspace

ggcyto: Facet ordering in ggcyto · Issue #76 · RGLab/ggcyto

The proposed approach adds a new pData argument to flowSet and GatingSet methods of ggcyto and autoplot to allow users to manually supply metadata with appropriate formatting and ordering (i.e. factor levels). We make sure that pData has exactly the same row and column names as the input cytoset or GatingSet.

We simply inherit pData when fortifying using a data.table join on the rownames. The underlying pData in the cytoset or GatingSet remains unchanged.

I've added a couple of tests to the test suite and confirmed that all other tests are passing locally.

Here is a quick demo where I indicate a specific Treatement order and reverse the OVAConc order.

library(CytoExploreR)
library(CytoExploreRData)
library(ggcyto)

gs <- GatingSet(Activation)
gs <- cyto_compensate(gs)
gs <- cyto_transform(gs)
gs <- cyto_gatingTemplate_apply(gs, Activation_gatingTemplate)
pd <- pData(gs)

# all columns are characters
apply(pd, 2, class)
  Treatment     OVAConc        name 
"character" "character" "character" 

# default ggcyto ordering
ggcyto(
  gs, 
  aes(CD8, CD4),
  subset = "T Cells"
) +
geom_gate(c("CD4 T Cells", "CD8 T Cells")) +
geom_hex(bins = 256) +
geom_stats() +
facet_wrap(~Treatment+OVAConc, ncol = 4)

Using this method users can automatically reorder by multiple variables without having to manually specify the order for every plot - simply pass the the ordered metadata to each ggcyto or autoplot call for consistent ordering.

# set factor levels manually
pd$Treatment <- factor(
  pd$Treatment, 
  levels = c("Stim-A", "Stim-D", "Stim-C", "Stim-B", "NA")
)
pd$OVAConc <- factor(
  pd$OVAConc,
  levels = c(500, 50, 5, 0)
)

# plot using custom ordering
ggcyto(
  gs, 
  aes(CD8, CD4),
  pData = pd,
  subset = "T Cells"
) +
geom_gate(c("CD4 T Cells", "CD8 T Cells")) +
geom_hex(bins = 256) +
geom_stats() +
facet_wrap(~Treatment+OVAConc, ncol = 4)

[mikejiang]

This is a bit too intrusive to ggcyto codebase just for supporting R factor-level for pdata
I may have simpler self-contained approach if this doesn't need to be persist to disk

[mikejiang]

RGLab/flowWorkspace#406
see if this works for you