eems.from.files: Run an EEMS analysis

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

Run an EEMS analysis

Description

This function runs an EEMS analysis with given parameters, which include file paths for retrieving the input files (datapath.coord, datapath.diffs and datapath.outer) and writing the output files. It is an exact replicate of the original EEMS command-line function.

Usage

eems.from.files(
  seed = unclass(Sys.time()),
  datapath,
  mcmcpath,
  prevpath = "",
  gridpath = "",
  nDemes,
  nIndiv,
  nSites,
  diploid = TRUE,
  distance = "euclidean",
  numMCMCIter,
  numBurnIter,
  numThinIter,
  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.
datapath	Full path to a set of three files: datapath.coord, datapath.diffs and datapath.outer.
mcmcpath	Full path to a filename prefix in an output directory with write permission.
prevpath	Full path to previous output directory, i.e., the mcmcpath in a previous EEMS run. Optional.
gridpath	Full path to a set of two files: gridpath.demes and gridpath.edges. Optional.
nDemes	Number of demes, roughly. EEMS constructs a regular triangular grid with circa nDemes vertices.
nIndiv	Number of samples. Should match the size of the dissimilarity matrix in datapath.diffs.
nSites	Number of SNPs used to compute the observed dissimilarity matrix in datapath.diffs.
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 'euclidean'.
numMCMCIter	Number of Markov Chain Monte Carlo iterations.
numBurnIter	Number of burn-in iterations to be discarded before sampling from posterior.
numThinIter	Number of thinning iterations to be discarded between sampling from posterior.
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

None

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

Examples

# We use example input from Petkova et al. (2016), found in the '/extdata' directory
data_path <- system.file("extdata", package = "reems")
input <- file.path(data_path, "barrier-schemeX-nIndiv300-nSites3000")
# The example puts the output in a temporary directory.
mcmcdir <- file.path(tempdir(), "eems_out")
dir.create(mcmcdir, showWarnings = FALSE)


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

eems.from.files(
  datapath = input,
  mcmcpath = mcmcdir,
  nDemes = 200,
  nIndiv = 300,
  nSites = 3000,
  diploid = FALSE,
  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.