% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eems.population.grid.R
\name{eems.population.grid}
\alias{eems.population.grid}
\title{A function to plot the constructed population grid and optionally the initial sampling locations}
\usage{
eems.population.grid(
  mcmcpath,
  plotpath,
  longlat,
  plot.width = 10,
  plot.height = 10,
  out.png = FALSE,
  res = 600,
  add.grid = TRUE,
  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 = TRUE,
  col.outline = "gray90",
  lwd.outline = 2,
  add.coord = FALSE,
  col.coord = "red",
  pch.coord = 3,
  datapath = 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{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.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{add.coord}{A logical value indicating whether to add the original sampling locations to
the plot or not.}

\item{col.coord}{The color of the sampling locations. Defaults to \code{red}.}

\item{pch.coord}{The symbol, specified as an integer, or the character to be used for plotting
the sampling locations. Defaults to 3.}

\item{datapath}{The full path and the file name of the input dataset (the three files
datapath.coord, datapath.diffs, datapath.outer). Must be specified if \code{add_coord = TRUE}.}
}
\value{
Passes on the return value of \code{\link[=dev.off]{dev.off()}} indicating the graphics device.
}
\description{
Given an EEMS output directory, this function generates one figure to visualize the EEMS
population grid. All edges are shown in the same color to visualize the grid before estimating
migration and diversity rates. This can be helpful if EEMS exits with the error message
"The population grid is not connected".
}
\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-grid_connected")

eems.population.grid(eems_results,
  name_figures,
  longlat = TRUE,
  add.outline = TRUE,
  col.outline = "purple",
  lwd.outline = 3,
  add.grid = TRUE,
  col.grid = "green",
  lwd.grid = 2,
  out.png = FALSE
)

# It is more interesting to see an example where the grid is unconnected
# due to the unusual shape of the habitat.
eems_results <- file.path(extdata_path, "EEMS-popgrid")

name_figures <- file.path(outdir, "EEMS-grid_not_connected")

eems.population.grid(
  mcmcpath = eems_results,
  plotpath = name_figures,
  longlat = FALSE,
  add.outline = TRUE, col.outline = "purple", lwd.outline = 3,
  add.grid = TRUE, col.grid = "green", lwd.grid = 2
)
# Delete the output file to tidy up.
unlink(outdir, recursive = TRUE, force = TRUE)
}
\seealso{
\code{\link{eems.plots}, \link{eems.voronoi.samples}, \link{eems.posterior.draws}}
}
