make_eems_plots: Plot effective migration and diversity surfaces

In dipetkov/reemsplots2: Generate plots to inspect and visualize the results of EEMS

Description

Given a vector of EEMS output directories, this function generates several figures to visualize EEMS results. It is a good idea to examine all these figures, which is why they are generated by default.

mrates01

effective migration surface. This contour plot visualizes the estimated effective migration rates m, on the log10 scale after mean centering.

mrates02

posterior probability contours P(log(m) > 0) = p and P(log(m) < 0) = p for the given probability level p. Since migration rates are visualized on the log10 scale after mean centering, 0 corresponds to the overall mean migration rate. This contour plot emphasizes regions with effective migration that is significantly higher/lower than the overall average.

qrates01

effective diversity surface. This contour plot visualizes the estimated effective diversity rates q, on the log10 scale after mean centering.

qrates02

posterior probability contours P(log(q) > 0) = p and P(log(q) < 0) = p. Similar to mrates02 but applied to the effective diversity rates.

rdist01

scatter plot of the observed vs the fitted between-deme component of genetic dissimilarity, where one point represents a pair of sampled demes.

rdist01

scatter plot of the observed vs the fitted within-deme component of genetic dissimilarity, where one point represents a sampled deme.

rdist03

scatter plot of observed genetic dissimilarities between demes vs observed geographic distances between demes.

pilogl01

posterior probability trace

Usage

make_eems_plots(mcmcpath, longlat = TRUE, dpi = 250, add_grid = FALSE,
  col_grid = "#BBBBBB", add_demes = FALSE, col_demes = "#000000",
  add_outline = FALSE, col_outline = "#FFFFFF", eems_colors = NULL,
  prob_level = 0.9, m_colscale = NULL, q_colscale = NULL,
  add_abline = FALSE)

Arguments

mcmcpath	A vector of EEMS output directories, for the same dataset. Warning: There is minimal checking that the directories all correspond to the same dataset.
longlat	A logical value indicating whether the coordinates are given as pairs (longitude, latitude) or (latitude, longitude).
dpi	Resolution of the contour raster. The default is 250.
add_grid	A logical value indicating whether to add the population grid or not.
col_grid	The color of the population grid. Defaults to gray.
add_demes	A logical value indicating whether to add the observed demes or not.
col_demes	The color of the demes. Defaults to black.
add_outline	A logical value indicating whether to add the habitat outline or not.
col_outline	The color of the habitat outline. Defaults to white.
eems_colors	The EEMS color scheme as a vector of colors, ordered from low to high. Defaults to a DarkOrange to Blue divergent palette with six orange shades, white in the middle, six blue shades. Acknowledgement: The default color scheme is adapted from the dichromat package.
prob_level	A probability p to define the posterior probability contours P(log(m) > 0) = p and P(log(m) < 0) = p. Defaults to 0.9.
m_colscale	A fixed range for log10-transformed migration rates. If the estimated rates fall outside the specified range, then the color scale is ignored. The default range is [-2.5, +2.5].
q_colscale	A fixed range for log10-transformed diversity rates. The default range is -0.1, +0.1.
add_abline	Add the line y = x to the diagnostic scatter plots of observed vs fitted genetic dissimilarities.

Details

The function make_eems_plots will work given the results from a single EEMS run (one directory in mcmcpath) but it is better to run EEMS several times, randomly initializing the MCMC chain each time. In other words, simulate several realizations of the Markov chain and let each realization start from a different state in the parameter space (by using a different random seed).

The mrates and qrates figures visualize (properties of) the effective migration and diversity rates across the habitat. The other figures can help to check that the MCMC sampler has converged (the trace plot pilogl) and that the EEMS model fits the data well (the scatter plots of genetic dissimilarities rdist).

To describe the within-deme and between-deme components of genetic dissimilarity, let D(a,b) be the dissimilarity between one individual from deme a and another individual from deme b. Then the within-deme component for a and b is simply D(a,a) and D(b, b), respectively. The between-deme component is D(a,b) - [D(a,a) + D(b,b)] / 2 and it represents dissimilarity that is due to the spatial structure of the population and is not a consequence of the local diversity in the two demes.

References

Light A and Bartlein PJ (2004). The End of the Rainbow? Color Schemes for Improved Data Graphics. EOS Transactions of the American Geophysical Union, 85(40), 385.

See Also

plot_population_grid, plot_resid_heatmap, plot_voronoi_tiles

Examples

# Use the provided example or supply the path to your own EEMS run.
mcmcpath <- system.file("extdata", "EEMS-barrier", package = "reemsplots2")

# Generate contour plots of migration and diversity rates
# as well as several diagnostic plots
plots <- make_eems_plots(mcmcpath, longlat = TRUE)
names(plots)

# Save the various plots
library("ggplot2")
plotpath <- file.path(path.expand("~"), "EEMS-barrier")
ggsave(paste0(plotpath, "-mrates01.png"), plots$mrates01, dpi = 600,
       width = 6, height = 4)
ggsave(paste0(plotpath, "-mrates02.png"), plots$mrates02, dpi = 600,
       width = 6, height = 4)
ggsave(paste0(plotpath, "-qrates01.png"), plots$qrates01, dpi = 600,
       width = 6, height = 4)
ggsave(paste0(plotpath, "-qrates02.png"), plots$qrates02, dpi = 600,
       width = 6, height = 4)
ggsave(paste0(plotpath, "-rdist01.pdf"), plots$rdist01,
       width = 6.5, height = 6)
ggsave(paste0(plotpath, "-rdist02.pdf"), plots$rdist02,
       width = 6.5, height = 6)
ggsave(paste0(plotpath, "-rdist03.pdf"), plots$rdist03,
       width = 6.5, height = 6)
ggsave(paste0(plotpath, "-pilogl01.pdf"), plots$pilogl01,
       width = 7, height = 5)

dipetkov/reemsplots2 documentation built on May 15, 2019, 8:47 a.m.