% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eems.posterior.draws.R
\name{eems.posterior.draws}
\alias{eems.posterior.draws}
\title{Plotting smoothed Voronoi diagrams of effective migration and diversity rates}
\usage{
eems.posterior.draws(
  mcmcpath,
  plotpath,
  longlat,
  post.draws = 1,
  plot.width = 10,
  plot.height = 10,
  out.png = TRUE,
  res = 600,
  xpd = TRUE,
  add.grid = FALSE,
  col.grid = "gray80",
  lwd.grid = 1,
  add.demes = FALSE,
  col.demes = "black",
  pch.demes = 19,
  min.cex.demes = 1,
  max.cex.demes = 3,
  add.outline = FALSE,
  col.outline = "gray90",
  lwd.outline = 2,
  projection.in = NULL,
  projection.out = NULL,
  add.map = FALSE,
  col.map = "gray60",
  lwd.map = 2,
  eems.colors = NULL,
  add.colbar = FALSE,
  m.colscale = NULL,
  q.colscale = NULL,
  add.title = FALSE,
  m.plot.xy = NULL,
  q.plot.xy = NULL
)
}
\arguments{
\item{mcmcpath}{A vector of EEMS output directories, for the same dataset. Warning: There is
minimal checking that the given  directories are for the same dataset.}

\item{plotpath}{The full path and the file name for the graphics to be generated.}

\item{longlat}{A logical value indicating whether the coordinates are given as pairs
(longitude, latitude) or (latitude, longitude).}

\item{post.draws}{Number of times to sample from the posterior. The default is 1.}

\item{plot.width}{The width of the graphics region for the two rate contour plots, in inches.
The default value is 10.}

\item{plot.height}{The height of the graphics region, in inches. The default value is 10.}

\item{out.png}{A logical value which, if set,  forces output graphics to be generated as PNGs
(if \code{TRUE}) or PDFs (if \code{FALSE}). Defaults to \code{TRUE}.}

\item{res}{Resolution, in dots per inch; used only for PNG images.
The default is 600.}

\item{xpd}{A logical value indicating whether to clip plotting to the figure region
(\code{xpd} = TRUE, which is the default) or clip plotting to the plot region
(\code{xpd} = FALSE).}

\item{add.grid}{A logical value indicating whether to add the population grid or not.}

\item{col.grid}{The color of the population grid. Defaults to \code{gray80}.}

\item{lwd.grid}{The line width of the population grid. Defaults to 1.}

\item{add.demes}{A logical value indicating whether to add the observed demes or not.}

\item{col.demes}{The color of the demes. Defaults to \code{black}.}

\item{pch.demes}{The symbol, specified as an integer, or the character to be used for
plotting the demes. Defaults to 19.}

\item{min.cex.demes}{The minimum size of the deme symbol/character.}

\item{max.cex.demes}{The maximum size of the deme symbol/character. Defaults to 1 and 3,
respectively. If \code{max.cex.demes} > \code{min.cex.demes}, then demes with more samples
also have bigger size: the deme with the fewest samples has size \code{min.cex.demes} and
the deme with the most samples has size \code{max.cex.demes}.}

\item{add.outline}{A logical value indicating whether to add the habitat outline or not.}

\item{col.outline}{The color of the habitat outline. Defaults to \code{white}.}

\item{lwd.outline}{The line width of the habitat outline. Defaults to 2.}

\item{projection.in}{The input cartographic projection, specified as a PROJ.4 string.}

\item{projection.out}{The output cartographic projection, specified as a PROJ.4 string.}

\item{add.map}{A logical value indicating whether to add a high-resolution geographic map.
Requires the \code{rworldmap} and \code{rworldxtra} packages. It also requires that
\code{projection.in} is specified.}

\item{col.map}{The color of the geographic map. Default is \code{gray60}.}

\item{lwd.map}{The line width of the geographic map. Defaults to 2.}

\item{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 \code{dichromat}
package.}

\item{add.colbar}{A logical value indicating whether to add the color bar (the key that shows
how colors map to rates) to the right of the plot. Defaults to TRUE.}

\item{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. By default, no range is
specified for either type of rates.}

\item{q.colscale}{A fixed range for log10-transformed diversity rates.}

\item{add.title}{A logical value indicating whether to add the main title in the contour plots.
Defaults to TRUE.}

\item{m.plot.xy}{Statements which add graphical elements (e.g. points) on top of the migration
sufrace.}

\item{q.plot.xy}{Statements which add graphical elements (e.g. points) on top of the diversity
surface.}
}
\value{
None
}
\description{
Given a set of EEMS output directories, this function takes random draws from the posterior
distribution of the migration and diversity rate parameters. Each draw is visualized as two
smoothed Voronoi diagrams; the migration diagram is saved to a file ending in \code{mvoronoiXX},
the diversity diagram is saved to a file ending in \code{qvoronoiXX} where \code{XX} is a
numeric id. Specify the number of times to draw from the posterior with the argument
\code{post.draws}. If \code{post.draws = 10}, then \code{eems.posterior.draws} will generate
plots with id \code{XX = 1} to \code{XX = 10}.
This function differs from \code{\link[=eems.voronoi.samples]{eems.voronoi.samples()}} by plotting smoothed contour diagrams
rather than raw Voronoi plots.
}
\details{
Note about the implementation: \code{eems.voronoi.samples} samples randomly from the posterior
draws saved during the execution of EEMS, after burn-in and thinning.
}
\examples{
# Use the provided example or supply the path to your own EEMS run.
extdata_path <- system.file("extdata", package = "reems")
eems_results <- file.path(extdata_path, "EEMS-example")
# Create a temporary output directory for this example 
outdir <- file.path(tempdir(), "path_out")
dir.create(outdir, showWarnings = FALSE)
name_figures <- file.path(outdir, "EEMS-example")

# Plot a series of Voronoi diagrams for the EEMS model parameters:
# the effective migration rates (m) and the effective diversity rates (q).
eems.posterior.draws(
  mcmcpath = eems_results,
  plotpath = paste0(name_figures, "-posterior-draws"),
  longlat = TRUE,
  post.draws = 2,
  out.png = FALSE
)
# Delete the output directory to tidy up. 
unlink(outdir, recursive = TRUE, force = TRUE)
}
\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.
}
\seealso{
\code{\link{eems.voronoi.samples}}
}
