- tipTimes
This input may be either: (a) a timeList object,
consisting of a list of length = 2, composed of a table of interval
upper and lower time boundaries (i.e., the earlier and latter bounds of the intervals) and
a table of first and last intervals for taxa, or (b) a matrix with row names
corresponding to taxon names, matching those names listed in the MrBayes block,
with either one, two or four columns containing ages (respectively) for point occurrences with
precise dates (for a single column), uncertainty bounds on a point occurrence
(for two columns), or uncertainty bounds on the first and
last occurrence (for four columns). Note that precise first and last occurrence
dates should not be entered as a two column matrix, as this will instead be interpreted
as uncertainty bounds on a single occurrence. Instead, either select which you want to
use for tip-dates and give a one-column matrix, or repeat (and collate) the columns, so that
the first and last appearances has uncertainty bounds of zero.
- ageCalibrationType
This argument decides how age calibrations are defined,
and currently allows for four options: "fixedDateEarlier" which fixes tip
ages at the earlier (lower) bound for the selected age of appearance (see argument
whichAppearance for how that selection is made), "fixedDateLatter"
which fixes the date to the latter (upper) bound of the selected age of appearance,
"fixedDateRandom" which fixes tips to a date that is randomly drawn from a
uniform distribution bounded by the upper and lower bounds on the selected age of
appearance, or (the recommended option) "uniformRange" which places a uniform
prior on the age of the tip, bounded by the latest and earliest (upper and lower)
bounds on the the selected age.
- whichAppearance
Which appearance date of the taxa should be used:
their 'first' or their 'last' appearance date? The default
option is to use the 'first' appearance date. Note that use of the last
appearance date means that tips will be constrained to occur before their
last occurrence, and thus could occur long after their first occurrence (!).
- treeAgeOffset
A parameter given by the user controlling the offset
between the minimum and expected tree age prior. mean tree age for the
offset exponential prior on tree age will be set to the minimum tree age,
plus this offset value. Thus, an offset of 10 million years would equate to a prior
assuming that the expected tree age is around 10 million years before the minimum age.
- minTreeAge
if NULL (the default), then minTreeAge will
be set as the oldest date among the tip age used (those used being
determine by user choices (or oldest bound on a tip age). Otherwise,
the user can supply their own minimum tree, which must be greater than
whatever the oldest tip age used is.
- collapseUniform
MrBayes won't accept uniform age priors where the maximum and
minimum age are identical (i.e. its actually a fixed age). Thus, if this argument
is TRUE (the default), this function
will treat any taxon ages where the maximum and minimum are identical as a fixed age, and
will override setting ageCalibrationType = "uniformRange" for those dates.
All taxa with their ages set to fixed by the behavior of anchorTaxon or collapseUniform
are returned as a list within a commented line of the returned MrBayes block.
- anchorTaxon
This argument may be a logical (default is TRUE,
or a character string of length = 1.
This argument has no effect if ageCalibrationType is not set to
"uniformRange", but the argument may still be evaluated.
If ageCalibrationType = "uniformRange",
MrBayes will do a tip-dating analysis with uniform age uncertainties on
all taxa (if such uncertainties exist; see collapseUniform).
However, MrBayes does not record how each tree sits on an absolute time-scale,
so if the placement of every tip is uncertain, lining up multiple dated trees
sampled from the posterior (where each tip's true age might
differ) could be a nightmare to back-calculate, if not impossible.
Thus, if ageCalibrationType = "uniformRange", and there are no tip taxa given
fixed dates due to collapseUniform (i.e. all of the tip ages have a range of uncertainty on them),
then a particular taxon will be selected and given a fixed date equal to its
earliest appearance time for its respective whichAppearance.
This taxon can either be indicated by the user or instead the first taxon listed
in tipTimes will be arbitrary selected. All taxa with their ages set
to fixed by the behavior of anchorTaxon or collapseUniform
are returned as a list within a commented line of the returned MrBayes block.
- file
Filename (possibly with path) as a character string
to a file which will be overwritten with the output tip age calibrations.
If NULL, tip calibration commands are output to the console.