LineageFilter
This is an inheritancePostProcessor which removes (or annotates) inheritance graph leaves and their ancestors based on criteria such as the name of the reaction or population the node corresponds to. The element has the following form:
<inheritancePostProcessor spec='LineageFilter'
reactionName="STRING"
populationName="STRING"
reverseTime="BOOLEAN"
discard="BOOLEAN"
leavesOnly="BOOLEAN"
noClean="BOOLEAN"
markAnnotation="STRING" />
One (and only one) of the first two attributes, reactionName
and populationName
must be specified. The value is used to select leaf nodes of the inheritance graph. If reactionName
is specified, the special value NONE
may be used to select leaf nodes which do not correspond to a reaction event. (Such nodes are generated when the simulationTime
of an InheritanceTrajectory or InheritanceEnsemble is reached and lineages still remain in the simulation.)
The optional reverseTime
attribute specifies the direction in which the tree is read (just as in the NEXUS and Newick output elements) and thus the nodes which are interpreted as the "leaves". The default value of "false" causes the filter to interpret the final nodes generated on each lineage in the simulation as being the leaves. For backward-time models such as the coalescent, however, the value "true" should be used.
The optional discard
attribute specifies exactly how to handle a matching node. The default behaviour is to keep only those leaves that match the criterion, together with all of their ancestral nodes. This behaviour corresponds to the default value of "false". Setting this instead to "true" inverts the criterion.
Setting the optional leavesOnly
attribute to "true" (the default value is "false") causes only leaf nodes to be removed - internal nodes are not altered.
Setting the optional noClean
attribute to "true" (default "false") prevents the filter's default behaviour of removing nodes with a single child and single parent that do not correspond to a change in the lineage's population or population type.
Finally, setting the optional markAnnotation
attribute to a string value causes the nodes that are selected by the filter to be marked with this annotation. No other change to the graph is produced in this case.