output
The <output>
elements are used to specify particular ways of writing the results of MASTER calculations to disk. There are a number of different types of <output>
elements, some of which only make sense for certain simulation types.
The most general type of output element is the JsonOutput
type which is specified in the following way:
<output spec='JsonOutput' fileName='STRING'/>
where the fileName
attribute is used to specify the name of the output file. As indicated by the name of the type, this output generates a JSON-formatted output file. The precise contents of the file depend on the type of the simulation, however:
-
For
Trajectory
simulations, the file contains at
element which is a vector of the times at which population sizes were recorded. It contains additional elements (one for each population type) containing the population sizes at those times. -
For
Ensemble
simulations, the file contains atrajectories
element which is a vector containingt
elements and population type elements for each of the populations generated. -
For
EnsembleSummary
simulations, the file contains at
element which is a vector of times at which the moments were estimated, as well as additional elements (one for each moment) containing the moment estimates themselves. -
The
InheritanceTrajectory
simulation type results in a similar output file to that of theTrajectory
type, with the caveat that the population sizes and times elements will contain no entries unless thesamplePopulationSizes
attribute of that simulation type is "true". -
Likewise, the
InheritanceEnsemble
simulation type results in a similar output file to that of theEnsemble
type, providedsamplePopulationSizes
is set to "true".
The NewickOutput
output element is applicable only to those simulations that result in inheritance graphs. It is specified in the following way:
<output spec='NewickOutput' fileName='STRING'
reverseTime='BOOLEAN'
collapseSingleChildNodes='BOOLEAN'/>
where the fileName
attribute specifies the name of an output file and reverseTime
determines whether the graph should be read in forward or reverse time. Once the simulation is complete, the output file contains one (in the case of InheritanceTrajectory
simulations) or more (as in the case of InheritanceEnsemble
simulations) extended Newick representations of the simulated inheritance graph(s). (In the special case that a graph is tree-like in the time-direction specified, this extended format reduces to the standard Newick representation.) If the collapseSingleChildNodes
attribute is set to "true", nodes that represent changes of lineage state (e.g. migration events) rather than multifurcations are removed from the graph prior to constructing the Newick representation. This is sometimes necessary for the Newick string to be parsed by external utilities such as APE.
The NexusOutput
output element is also only applicable to inheritance simulations. It is specified via:
<output spec='NexusOutput' fileName='STRING'
reverseTime='BOOLEAN'
collapseSingleChildNodes='BOOLEAN'/>
where the attributes have the meanings described above. Just as for NewickOutput
, this output produces extended Newick representations of the graphs. This output, however, packs these representations into a NEXUS file. Additionally, this output includes annotations that provide information about the specific population carrying each lineage at each node and the name of the reaction which produced that node. (A grammar for the annotated tree/network format used is available here.) When reticulation is absent, these files can be visualized using FigTree and IcyTree.