% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eems.run.R
\name{eems}
\alias{eems}
\title{Run an EEMS analysis from data in R format}
\usage{
eems(
  seed = unclass(Sys.time()),
  coords,
  freqs,
  outer = NULL,
  buffer = NULL,
  mcmcpath,
  demes = NULL,
  edges = NULL,
  prevpath = "",
  nChains = 1,
  parallel = FALSE,
  nWorkers = NULL,
  nDemes = NULL,
  diploid = TRUE,
  distance = "greatcircle",
  numMCMCIter = 2e+06,
  numBurnIter = 1e+06,
  numThinIter = 9999,
  mSeedsProposalS2 = 0.01,
  qSeedsProposalS2 = 0.1,
  mEffctProposalS2 = 0.1,
  qEffctProposalS2 = 0.001,
  mrateMuProposalS2 = 0.01,
  qVoronoiPr = 0.25,
  qrateShape = 0.001,
  mrateShape = 0.001,
  sigmaShape = 0.001,
  qrateScale = 1,
  mrateScale = 1,
  sigmaScale = 1,
  negBiProb = 0.67,
  negBiSize = 10
)
}
\arguments{
\item{seed}{The random seed. Defaults to the current system time in seconds.}

\item{coords}{The coordinate matrix, a two-column matrix with a line for every sample.}

\item{freqs}{An allele frequency  matrix in \code{conStruct} format, with a column for every site and a row for every sample.
Choosing one main allele, it tabulates the average genotypes of the sample at that locus.}

\item{outer}{Matrix of coordinates of the outer polygon.
Defaults to a polygon larger than the convex hull of the supplied coordinates to mitigate EEMS boundary effects,
which is created by \code{\link[=outer.buffered]{outer.buffered()}}.}

\item{buffer}{The rough distance of the boundary from the convex hull. Defaults to 0.2 times the length of the hull.
Unused if \code{outer} is specified.}

\item{mcmcpath}{Full path to a filename prefix in an output directory with write permission.}

\item{demes}{Matrix of coordinates of demes; optional, and usually unnecessary. Only in conjunction with \code{edges}.}

\item{edges}{Matrix of custom input grid; optional, and usually unnecessary. Only in conjunction with \code{demes}.}

\item{prevpath}{Full path to previous output directory, i.e., the mcmcpath in a previous EEMS run. Optional.}

\item{nChains}{Number of chains to be run. Defaults to 1.}

\item{parallel}{Logical values that indicates whether chains should be run in parallel. Defaults to FALSE.}

\item{nWorkers}{If \code{parallel} is TRUE, then the number of workers used is the minimum of \code{nChains} and \code{nWorkers}.
Defaults to the number of available cores.}

\item{nDemes}{Number of demes, roughly. EEMS constructs a regular triangular grid with circa nDemes vertices.
Defaults to 6 times the number of individuals, aiming for sufficient resolution.}

\item{diploid}{Logical value that indicates whether the species is diploid (TRUE) or haploid (FALSE). Defaults to TRUE.}

\item{distance}{Distance metric. Either \code{euclidean} or \code{greatcirc}, that is, great circle distance.
Defaults to 'greatcirc', which is more accurate at larger scales.}

\item{numMCMCIter}{Number of Markov Chain Monte Carlo iterations. Defaults to 2000000.}

\item{numBurnIter}{Number of burn-in iterations to be discarded before sampling from posterior. Defaults to 1000000.}

\item{numThinIter}{Number of thinning iterations to be discarded between sampling from posterior. Defaults to 9999.}

\item{mSeedsProposalS2}{Variance of normal proposals to update the seeds of the migration tiles. Defaults to 0.01.}

\item{qSeedsProposalS2}{Variance of normal proposals to update the seeds of the diversity tiles. Defaults to 0.1.}

\item{mEffctProposalS2}{Variance of normal proposals to update the log10 rates of the migration tiles. Defaults to 0.1.}

\item{qEffctProposalS2}{Variance of normal proposals to update the log10 rates of the diversity tiles. Defaults to 0.001.}

\item{mrateMuProposalS2}{Variance of normal proposals to update the overall mean migration rate, on the log10 scale.
Defaults to 0.01.}

\item{qVoronoiPr}{With probability qVoronoiPr, update diversity Voronoi;
with probability 1-qVoronoiPr, update migration Voronoi. Defaults to 0.25.}

\item{qrateShape}{Shape hyperparameter for the diversity rates variance, qrateS2 ~ invgamma(qrateShape, qrateScale).
Defaults to 0.001}

\item{mrateShape}{Shape hyperparameter for the migration rates variance, mrateS2 ~ invgamma(mrateShape, mrateScale).
Defaults to 0.001.}

\item{sigmaShape}{Shape hyperparameter for the scaling factor sigma^2 ~ invgamma(sigmaShape, sigmaScale).
Defaults to 0.001.}

\item{qrateScale}{Scale hyperparameter for the diversity rates variance, qrateS2 ~ invgamma(qrateShape, qrateScale).
Defaults to 1.0.}

\item{mrateScale}{Scale hyperparameter for the migration rates variance, mrateS2 ~ invgamma(mrateShape, mrateScale).
Defaults to 1.0.}

\item{sigmaScale}{Scale hyperparameter for the scaling factor sigma^2 ~ invgamma(sigmaShape, sigmaScale).
Defaults to 1.0.}

\item{negBiProb}{Success probability for the number of Voronoi tiles ~ negbinom(negBiSize, negBiProb). Defaults to 0.67.}

\item{negBiSize}{Size for the number of Voronoi tiles ~ negbinom(negBiSize, negBiProb). Defaults to 10.}
}
\value{
A vector of output directories which can be given as input to \code{\link[=eems.plots]{eems.plots()}}.
}
\description{
This function runs an EEMS analysis with given parameters in the input format for \code{conStruct},
which include R matrices for allele frequency data and coordinates.
In addition to taking R objects as inputs,
it also provides additional default values over the original \code{EEMS} command-line utility.
Furthermore, it allows for running more than one chain, either in parallel or sequentially,
and returns a vector of output directories as input to \code{\link[=eems.plots]{eems.plots()}}.
}
\examples{
# The example puts the output in a temporary directory.
mcmcdir <- file.path(tempdir(), "eems_out")
dir.create(mcmcdir, showWarnings = FALSE)
mcmcpath <- file.path(mcmcdir,"example")

# Run an example EEMS analysis with a small number of iterations to ensure quick termination. 

eems(
  freqs = ex.freqs,
  coords = ex.coords,
  mcmcpath = mcmcpath,   
  numMCMCIter = 200,
  numBurnIter = 100,
  numThinIter = 99,
)
# Delete the output directory to tidy up. 
unlink(mcmcdir, recursive = TRUE, force = TRUE)
}
\references{
Petkova, D., Novembre, J. & Stephens, M.
Visualizing spatial population structure with estimated effective migration surfaces.
Nat Genet 48, 94–100 (2016). https://doi.org/10.1038/ng.3464
}
\seealso{
\code{\link{eems.plots}, \link{eems.from.files}}
}
