% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eems.voronoi.samples.R
\name{eems.voronoi.samples}
\alias{eems.voronoi.samples}
\title{A function to plot raw Voronoi diagrams of effective migration and diversity rates}
\usage{
eems.voronoi.samples(
  mcmcpath,
  plotpath,
  longlat,
  post.draws = 1,
  plot.width = 10,
  plot.height = 10,
  out.png = FALSE,
  res = 600,
  add.grid = FALSE,
  col.grid = "gray80",
  lwd.grid = 1,
  add.outline = TRUE,
  col.outline = "gray80",
  lwd.outline = 2,
  add.demes = FALSE,
  col.demes = "gray80",
  pch.demes = 19,
  cex.demes = 1,
  add.seeds = TRUE,
  col.seeds = "#8AE234",
  pch.seeds = 4,
  cex.seeds = 1,
  eems.colors = NULL,
  m.colscale = NULL,
  q.colscale = NULL,
  add.title = FALSE
)
}
\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{FALSE}.}

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

\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.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{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{cex.demes}{The size of the symbol/character used for plotting observed demes.
Defaults to 1.}

\item{add.seeds}{A logical value indicating whether to add the Voronoi seeds or not.}

\item{col.seeds}{The color of the Voronoi seeds. Defaults to \code{green}.}

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

\item{cex.seeds}{The size of the symbol/character used for plotting the Voronoi seeds.
Defaults to 1.}

\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{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.}
}
\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
raw 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.voronoi.samples} will generate
plots with id \code{XX = 1} to \code{XX = 10}.
This function differs from \code{\link[=eems.posterior.draws]{eems.posterior.draws()}} by displaying raw, unsmoothed Voronoi diagrams.
}
\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, "eemsplot_out")

# Plot a series of Voronoi diagrams for the EEMS model parameters:
# the effective migration rates (m) and the effective diversity rates (q).
eems.voronoi.samples(
  mcmcpath = eems_results,
  plotpath = paste0(name_figures, "-voronoi-diagrams"),
  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.posterior.draws}}
}
