PlotMS: Plot population demographic graph and generate demographic...

In POPdemog: Plot Population Demographic History

Description

This is the main function to plot demographic graph for single/multiple populations. The function is named after Hudson's ms program. It can read the simulation input data used for the ms, msa, msHot, MaCS, scrm, and cosi programs.

The input.file or imput.cmd and command type are required to plot the demographic history. The output graph can be customized.

In the demographic graph, each population has a lineage that stretches back in time. The width of the lineage reflects the population size. Population splits and migrations are represented by arrows.

Usage

PlotMS(input.cmd = NULL, input.file = NULL, type, inpos = NULL,
  N4 = 10000, size.scale = "linear", linear.scale = 0.2, log.base = 10,
  time.scale = "4Ne", gen = 25, m.adjust = 0, col.pop = "gray45",
  col.arrow = col.pop, length.arrowtip = 0.15, lwd.arrow = 1,
  angle.arrowtip = 15, pops = NULL, xlab = "Population",
  ylab = paste("Time before present (", time.scale, ")", sep = ""),
  xlim = NULL, ylim = NULL, plot.out = T, demo.out = F, cex.lab = 1,
  cex.axis = 1, axes = T)

Arguments

input.cmd	An input string containing the simulation program input commands.
input.file	A file containing the simulation program input commands (for ms, msa, or MaCS), or parameter files (for cosi).
type	A keyword indicating the type of simulation command: "ms" for ms, "msa" for msa, "macs" for MaCS, "scrm" for scrm, "cosi" for cosi, "msprime" for msprime. Please check the online tutorial file to see more supported simulation programs.
inpos	Population positions in the plot at time 0.
N4	Four times the effective population size. This parameter has the same definition as the 4N0 parameter for the ms simulation program.
size.scale	A keyword to define the scaling of lineage width. "topology" returns only topology structure among simulated populations, ignoring both the population sizes and the length of time between any demographic events. "linear" linearly scales the lineage widths as a function of the population size, with the scale factor defined by the variable linear.scale; "log" scales the lineage width logarithmically as a function of the population size. The logarithm base is defined by the variable log.base.
linear.scale	Linear scale factor,which will be applied when size.scale = "linear".
log.base	The base of logarithm, which will be applied when size.scale = "log".
time.scale	A keyword to define the time scale used in the plot. It can be "4Ne", "generation", "year", "kyear", and "log10year". When the size.scale = "topology", this parameter will be ignored.
gen	Years per generation. Default value is 25.
m.adjust	Migration threshold for plotting migration events. Migration events with strength higher than m.adjust will be shown. The migration strength is defined as the proportion of the target population being replaced by the source population per generation. Default value is 0. This value should be between 0 and 1.
col.pop	Color for each population.
col.arrow	Color for each migration arrow.
length.arrowtip	Size of arrow tips.
lwd.arrow	Controls the width of arrow representing a migration. The arrow width is determined by 0.5+migration strength*lwd.arrow.
angle.arrowtip	Arrow end angle, between 0 and 90.
pops	Population name labels. Default as 1:number of populations.
xlab	Title for the x-axis.
ylab	Title for the y-axis.
xlim	Range of x-axis.
ylim	Range of y-axis.
plot.out	A logical variable that controls the production of the demographic plot. If TRUE, the demographic plot will be produced.
demo.out	A logical variable that controls the output of the demographic parameters. If TRUE, all demographic parameters that are used for the graph will be returned.
cex.lab	The magnification to be used for x and y labels relative to the current setting of cex.
cex.axis	The magnification to be used for axis annotation relative to the current setting of cex.
axes	A logical value to plot the axes or not.

Value

if the parameter plot = F/FALSE, the following three lists will be returned:

demograph_out	This list contains all demographic details from the input command file: time.series is a vector of time; Pos is a numeric matrix of positions for each population at every demographic event; N is a numeric matrix of population size for each population at every demographic event; m is a 3-D numeric matrix of migration rates between populations at every demographic event; survive is a matrix recording the begining and end for each population according to the demographic events; g.rate is a matrix of exponential growth rates at every demographic event; pop.pos is a numeric vector of the population positions at time 0; pop.lab is a vector of population names; mscmd is the ms command for the demographic plot. Demographic information from simulation scripts will be turned to ms command format for further extraction; present.pop.num is the number of populations at present; total.pop.num is the number of total populations exist in the plot; N4 is 4Ne; gen is the number of years per generation.
evo_par	This list contains all parameters used to draw the demographic graph, including: size.scale,linear.scale, log.base, time.scale, time, col.pop, col.arrow, length.arrowtip, lwd.arrow, angle.arrowtip, lab.pop, lab.pos, xlim, ylim, xlab, ylab, cex.lab, cex.axis, axes. See more details in the parameter description.
mig_par	This list contains all parameters used to draw the migrations, including: size.scale, linear.scale, log.base, time.scale, time, lab.pop, col.pop, col.arrow, length.arrowtip, lwd.arrow, angle.arrowtip, xlim,ylim, events, cex.lab See more details in the parameter description.

References

4Ne: http://home.uchicago.edu/rhudson1/source/mksamples.html

POPdemog documentation built on May 2, 2019, 8:18 a.m.