eems: Run an EEMS analysis from data in R format

In reems: Estimating Effective Migration Surfaces from Single Nucleotide Polymorphism Data

Run an EEMS analysis from data in R format

Description

This function runs an EEMS analysis with given parameters in the input format for 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 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 eems.plots().

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

seed	The random seed. Defaults to the current system time in seconds.
coords	The coordinate matrix, a two-column matrix with a line for every sample.
freqs	An allele frequency matrix in 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.
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 outer.buffered().
buffer	The rough distance of the boundary from the convex hull. Defaults to 0.2 times the length of the hull. Unused if outer is specified.
mcmcpath	Full path to a filename prefix in an output directory with write permission.
demes	Matrix of coordinates of demes; optional, and usually unnecessary. Only in conjunction with edges.
edges	Matrix of custom input grid; optional, and usually unnecessary. Only in conjunction with demes.
prevpath	Full path to previous output directory, i.e., the mcmcpath in a previous EEMS run. Optional.
nChains	Number of chains to be run. Defaults to 1.
parallel	Logical values that indicates whether chains should be run in parallel. Defaults to FALSE.
nWorkers	If parallel is TRUE, then the number of workers used is the minimum of nChains and nWorkers. Defaults to the number of available cores.
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.
diploid	Logical value that indicates whether the species is diploid (TRUE) or haploid (FALSE). Defaults to TRUE.
distance	Distance metric. Either euclidean or greatcirc, that is, great circle distance. Defaults to 'greatcirc', which is more accurate at larger scales.
numMCMCIter	Number of Markov Chain Monte Carlo iterations. Defaults to 2000000.
numBurnIter	Number of burn-in iterations to be discarded before sampling from posterior. Defaults to 1000000.
numThinIter	Number of thinning iterations to be discarded between sampling from posterior. Defaults to 9999.
mSeedsProposalS2	Variance of normal proposals to update the seeds of the migration tiles. Defaults to 0.01.
qSeedsProposalS2	Variance of normal proposals to update the seeds of the diversity tiles. Defaults to 0.1.
mEffctProposalS2	Variance of normal proposals to update the log10 rates of the migration tiles. Defaults to 0.1.
qEffctProposalS2	Variance of normal proposals to update the log10 rates of the diversity tiles. Defaults to 0.001.
mrateMuProposalS2	Variance of normal proposals to update the overall mean migration rate, on the log10 scale. Defaults to 0.01.
qVoronoiPr	With probability qVoronoiPr, update diversity Voronoi; with probability 1-qVoronoiPr, update migration Voronoi. Defaults to 0.25.
qrateShape	Shape hyperparameter for the diversity rates variance, qrateS2 ~ invgamma(qrateShape, qrateScale). Defaults to 0.001
mrateShape	Shape hyperparameter for the migration rates variance, mrateS2 ~ invgamma(mrateShape, mrateScale). Defaults to 0.001.
sigmaShape	Shape hyperparameter for the scaling factor sigma^2 ~ invgamma(sigmaShape, sigmaScale). Defaults to 0.001.
qrateScale	Scale hyperparameter for the diversity rates variance, qrateS2 ~ invgamma(qrateShape, qrateScale). Defaults to 1.0.
mrateScale	Scale hyperparameter for the migration rates variance, mrateS2 ~ invgamma(mrateShape, mrateScale). Defaults to 1.0.
sigmaScale	Scale hyperparameter for the scaling factor sigma^2 ~ invgamma(sigmaShape, sigmaScale). Defaults to 1.0.
negBiProb	Success probability for the number of Voronoi tiles ~ negbinom(negBiSize, negBiProb). Defaults to 0.67.
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 eems.plots().

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

See Also

eems.plots, eems.from.files

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)

reems documentation built on May 6, 2026, 1:07 a.m.