mixturePlot: Plot a mixture fit vs the data.
In danjlawson/badMIXTURE: Validating Structure With Chromosome Painting

Description Usage Arguments Value Plot types Advanced usage Examples

This function takes a mixture solution as returned by compareMixtureToData) or compareMixtureToDataDirect) and plots it in a variety of ways.

Focus your attention on only the first two arguments: adc which is the processed mixture solution) and show which is how you choose the plots to display. The remaining arguments affect only the presentation of the plot.

It is essential to understand that there are two key structures being explored simultaneously in these plots. The first is the P-dimensional clustering of the data, which defines the similarities; each of the N data points has a similarity to these P clusters. A representation in this space is called a palette. The second is the K-dimensional set of admixture weights. Each of the K "ancestral" or latent variables also has a P dimensional palette. Further, each of the N data points has a K dimensional "admixture" breakdown, seen as a mixture of the K ancestral palettes.

The variety of plots available each explore different aspects of the fit of the mixture solution to the data. We assume that the individuals are ordered by cluster and plot clusters as separated. These must match the palette in order.

A variety of plot types for "show" are available:

Admixture : the Admixture profile, shown via the classic barplot.
Cluster : The assignment of individuals into the P clusters.
Raw : The palettes, as observed in the data.
Pred : The predicted palettes.
Ancestral : The palettes of the ancestral populations.... See ancestralshow.
Residual : The matrix of residuals. See resid.cols.
Same : The part of the palette that was predicted and is present.
Omni : A visualisation of the raw palette and its fit to the data. The palette is split into three parts: a) the predicted palette that is present in the data, shown immediately above the x-axis up to the black line. b) the additional palette that is present in the data but missing in the prediction, shown above the black line up to 1. c) the predicted palette that is not present in the data; this is shown beneath the x axis. Therefore everything shown above the x-axis represents the data, and everything below the black line represents the prediction.

There are also some other plots which are more experimental:

Over : A comparison of the predicted palettes to the observed palette; the predicted palette is shown on top, with "over-prediction" shown in black. The "missing" part of the prediction is show at the bottom.
Over2 : As "Over", but without "blacking out" the section of the prediction that was overpredicted.
Under :
Under2 :

If you want to produce high quality plots, you may wish to control the plotting very carefully. It is still helpful to use these functions as they ensure that the x-axis aligns; however you might want to display your own annotation.

This is possible by calling with a single "show" argument, and setting layout=FALSE. Then the plot will be drawn in the next available plotting area. You can disable all text overlay and add this yourself. See examples.

mixturePlot(adc, show = c("Admixture", "Cluster", "Residual"),
  mainname = "Admixture", uselayout = TRUE, popy = 0.5,
  height.cluster = 0.2, cex = 1, cex.main = 1, cex.axis = 1,
  cex.poplab = 0.6, cex.residlab = 0.6, cex.residleg = 0.6,
  cex.names = 0.2, cex.ancestral = 1, marx = c(3, 1),
  mary.admixture = c(2, 3), mary.ancestral = c(1, 2), mary.cluster = c(1,
  1), mary.residual = c(1, 1), mary.diff = c(2, 2), mary.raw = c(1, 1),
  omni.lwd = 2, omni.ylim = NULL, line.above = 0, line.below = 0,
  xlim = NULL, showtitles = TRUE, ancestralshow = NULL,
  ancestralspace = 0.5, residual.max = NULL, residual.scale = 0.1,
  residual.showscale = TRUE, ancestral.mean = TRUE,
  ancestral.names = NULL, ancestral.shownames = TRUE, cluster.srt = 0,
  cluster.names = TRUE, resid.cols = MakeColorRYWGB(), gpref = NULL)

`adc`	A mixture solution with data, as returned by `compareMixtureToData`) or `compareMixtureToDataDirect`).
`show`	A character vector of plot types to create. See plots below.
`mainname`	Title for the main plot
`uselayout`	Whether we call layout, or allow the user to set up the plot environment. Default: TRUE
`popy`	height for the cluster names; repeated (default: 0.5)
`height.cluster`	Height of the "cluster" plot relative to the others
`cex`	Overall scale; see par. Default: 1.0
`cex.main`	As described in par. Default: 1.0
`cex.axis`	As described in par. Default: 1.0
`cex.poplab`	cex for the population labels. Default: 0.6
`cex.residlab`	cex for the residuals. Default: 0.6
`cex.residleg`	cex for the legend in residual plots. Default: 0.6
`cex.names`	cex for the names ...? Default: 0.2
`cex.ancestral`	cex for the ancestral ...? Default: 1.0
`marx`	Margin in the x direction. Default: c(3,1)
`mary.admixture`	Margin in the y direction of the admixture plot. Default: c(2,3)
`mary.ancestral`	Margin in the y direction of the ancestral plot. Default: c(1,2)
`mary.cluster`	Margin in the y direction of the cluster plot. Default: c(1,1)
`mary.residual`	Margin in the y direction of the residual plot. Default: c(1,1)
`mary.diff`	Margin in the y direction of the difference, diff & omni plots. Default: c(2,2)
`mary.raw`	Margin in the y direction of the raw plot. Default: c(1,1)
`omni.lwd`	Line width for the omni plot. Default: 2.0
`omni.ylim`	Limits of the omni plot. default: NULL, meaning the range of the data
`line.above`	Line where text is written above the plots with mtext; Default: 0
`line.below`	Line where text is written below the plots with mtext; Default: 0
`xlim`	xlim for the plots; all plots are restricted to this range. Note that you must calculate the spaces between populations; see below. (Default: NULL, meaning the range of the data)
`showtitles`	whether to plot any titles. Default: TRUE
`ancestralshow`	A vector of which of the ancestral populations to show. Default: NULL, meaning all of them.
`ancestralspace`	Spacing between ancestral vectors (they are each of width 1). Default: 0.5
`residual.max`	Maximum value for the resiidual plots. Default:NULL, meaning the range of the data.
`residual.scale`	Scale of the residuals in the AdmixtureResidualMatrix, as compared to the ..? Defualt: 0.1.
`residual.showscale`	Whether to show the scale in the residual matrix plot. Default: TRUE
`ancestral.mean`	Whether to show the global mean in the Ancestral plot. Default: TRUE
`ancestral.names`	A vector of names for the ancestral populations in the Ancestral plot. Default: NULL, meaning label them A1..K.
`ancestral.shownames`	Whether to show the names in the ancestral plot. Default: TRUE.
`cluster.srt`	String rotation in the Cluster plot, as passed to par(srt). Default: 0.
`cluster.names`	Whether to show the names in the Cluster plot. Default: TRUE.
`resid.cols`	Colours for the Residual Matrix. Default: `MakeColorRYWGB`)(), which makes one direction Yellow->Red, and the other Green->Blue, with white around zero.
`gpref`	A list of the above preferences, passed to the helper functions that do the plotting

gpref A list of the graphical preferences that have been specified, so you can call this function again and get consistent output.

## Not run: 
## Straightforward example:
data(arisim_remnants)
adm<-compareMixtureToData(arisim_remnants$mixture,
                          arisim_remnants$data,arisim_remnants$ids)
gpref=mixturePlot(adm)

## Example showing individual names clearly
data(arisimsmall)
adm<-compareMixtureToData(arisimsmall$mixture,arisimsmall$data,arisimsmall$ids)

gpref=mixturePlot(adm,
                  c("Admixture","Cluster","Raw","Residual"),
                  cex.names=0.5,residual.scale=0.2,height.cluster=.4)

## Complex example using layout and data subsetting
data(arisimsmall)
adm<-compareMixtureToData(arisimsmall$mixture,arisimsmall$data,arisimsmall$ids)
adm2=adm
adm2$mycols2[]="lightgrey"
adm2$mycols2[4:7]=c("darkred","orange","green","blue")

layout(matrix(c(1,2,3,4,5,5,5,5),nrow=4,ncol=2),heights=c(1,0.4,1,1))
gpref=mixturePlot(adm2,
                  c("Admixture","Cluster","Raw","Residual"),
                  mainname=paste0("Admixture, Marginalization, Direct"),
                  mary.admixture=c(0,1),
                  cex.names=0,
            ancestralshow=c(1,2,4), 
            residual.max=NULL,
            residual.scale=0.2,
            residual.showscale=TRUE, 
            ancestral.mean=FALSE,
            xlim=c(24,56),
            uselayout=FALSE)
gpref=mixturePlot(adm2,"Ancestral",gpref=gpref,uselayout=FALSE)

## End(Not run)