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.
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)An input string containing the simulation program input commands.
A file containing the simulation program input commands (for ms, msa, or MaCS), or parameter files (for cosi).
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.
Population positions in the plot at time 0.
Four times the effective population size. This parameter has the same definition as the 4N0 parameter for the ms simulation program.
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 factor,which will be applied when size.scale = "linear".
The base of logarithm, which will be applied when size.scale = "log".
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.
Years per generation. Default value is 25.
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.
Color for each population.
Color for each migration arrow.
Size of arrow tips.
Controls the width of arrow representing a migration. The arrow width is determined by 0.5+migration strength*lwd.arrow.
Arrow end angle, between 0 and 90.
Population name labels. Default as 1:number of populations.
Title for the x-axis.
Title for the y-axis.
Range of x-axis.
Range of y-axis.
A logical variable that controls the production of the demographic plot. If TRUE, the demographic plot will be produced.
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.
The magnification to be used for x and y labels relative to the current setting of cex.
The magnification to be used for axis annotation relative to the current setting of cex.
A logical value to plot the axes or not.
if the parameter plot = F/FALSE, the following three lists will be returned:
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.
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.
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.
4Ne: http://home.uchicago.edu/rhudson1/source/mksamples.html