This release is mainly aimed at avoiding a common confusion about
phylopath output, that was long-standing and avoidable.
When models would use both continuous and binary variables, the
coefficients would be very confusing to interpret, since they mix scales
and are not consistently standardized. The package now tries to be much
more vocal about what path coefficients actually mean and warn the user
about mixing coefficients with different types.
Note that this concerns the coefficients only, comparison of the causal models is not an issue.
New features in this release:
Models that contain both binary and continuous variables now
warn, once per session, that their coefficients cannot be compared with
one another. Every plot and printout of such a model repeats this more
briefly, and coef_plot() refuses to sort the paths by
"strength", since that ordering would be partly an artefact
of the scales.
plot() on a fitted model no longer labels its colour
legend “standardized path coefficient” regardless of what the
coefficients are, but names the scale that is actually shown.
fitted_DAG objects gain a binary
element, recording which variables were modelled as binary. Objects made
by earlier versions do not have it, and are reported without a scale
rather than being assumed to be standardized.
New as.data.frame() method for fitted models,
returning the estimated paths as a data.frame with one row
per path. This function supports a order_by argument just
like coef_plot() to order the paths.
New coef() and confint() methods for
fitted DAGs, returning the path coefficients as a named vector and the
bounds of their bootstrapped confidence intervals.
phylo_path now supports more than 26
models.
There are also a lot of bug fixes and minor improvements in reporting. It is unlikely any of these have affected real analyses, as they deal with either imprecise reporting or very unlikely edge cases:
plot.phylopath_summary now has a help page.
Bug fix: coef_plot(order_by = "causal") derived the
causal ordering from the positive coefficients only, so the ordering was
incorrect in the presence of negative paths.
Bug fix: CICc could not be calculated when the
number of parameters was exactly one less than the number of species,
but silently returned Inf instead of NA.
Affected models now return NA.
Bug fix: the phylo_par column now correctly reports
the alpha parameter in the case of GLMs.
Bug fix: model sets in which only some of the models were named
kept empty names for the others, which made those models impossible to
select with best() and choice(). Unnamed
models in a partially named set are now labelled in the same way as
those in a fully unnamed set.
Bug fix: the notice pointing to show_warnings() was
only shown when more than one model produced a warning, so a single
warning went unmentioned.
Bug fix: show_warnings() and the error for variables
with more than two levels appended FALSE to their
messages.
best() and average() now return an
informative error when CICc could not be calculated for one
or more of the models, rather than failing with an uninformative
error.
Informative errors are now returned when a variable is used in
the causal models but is not a column of data, when the
order argument does not contain exactly the variables used
in the models, and when two causal models are given the same
name.
All errors, warning and messages have been reviewed for clarity,
and many now have more consistent language, more information, and give
tips on how to resolve the issue. They also use rlang now,
for nicer formatting.
est_DAG() now defaults to
model = "lambda" and method = "logistic_MPLE",
matching phylo_path(). Previously these arguments had no
defaults, so calling est_DAG() without them
failed.
Bug fix: implemented more consistent handling of very small p-values and avoidance of numerical underflow.
Updated ggplot2 code to remove deprecated
functionality.
Fixed several inaccuracies in the vignettes, including a
reference to a function that does not exist, and restored two
coef_plot() examples in the introduction.
Fitted models now report clearly what their coefficients are. Paths into a binary variable are log odds ratios, while paths into a continuous variable are standardized regression coefficients, and previously both were presented as though they were the same quantity.
New print() method for fitted models, which lists
the estimated paths with their coefficients and intervals, and states
which variables are continuous and which are binary, rather than
printing the underlying matrices.
coef_plot() now names the scale of the coefficients
on its axis, instead of always describing them as standardized.
Bug fix: est_DAG() did not recognize binary
variables supplied as character vectors, although those are documented
as acceptable, and phylo_path() accepts them. Such a
variable failed with an error from phylolm when it was the
outcome of a path, and was silently treated as continuous when it was
the predictor. Character variables are now converted to factors, as they
already were in phylo_path().
Bug fix: plot_model_set() located the edges of a
causal model incorrectly when a model was not topologically sorted,
which could silently draw edges that were not in the model and omit ones
that were.
Bug fix: passing an argument that neither phylolm()
nor phyloglm() accepts produced one warning per fitted
regression, and did not say which argument was at fault. Such arguments
are now reported once per call, by name.
The vignettes now have descriptive titles in the vignette index, and all figures have alt-text.
Added a unit test suite covering the d-separation basis set, the model comparison statistics, model averaging, and the plotting functions.
A warning is now generated when a user passes a data column with binary data as a numeric vector.
Informative errors are now returned when the order
argument does not contain each variable exactly once.
Fixed a rare bug in find_consensus_order, due to a
particular edge case of order combinations. In old R versions this would
generate a warning about the an if condition with length
> 1, which in newer versions results in an error. (Thanks to Laura
Alencar for the report.)
Replaced parallel processing based on the parallel
package and pbapply to use future instead. Use
e.g. future::plan("multisession", workers = n) to enable
parallel processing for both model comparison (parallel over dsep
statements) and model estimation (when using bootstrapping).
Fixed a bug that no longer allowed parallel processing in
phylo_path.
Fixed a bug where the range of the width scale for paths in
plot.fitted_DAG was incorrectly set to the
max(weight), instead of max(abs(weight)).
(Thanks Yu Xu for the report.)
Better user messaging and documentation around the use of the
boot parameter.
Update of binary vignette to include more info on convergence warnings.
Fixed a bug that made phylo_path fail to pass
additional (…) arguments correctly to phylolm.
Add informative error when trying to plot a DAG without any paths.
Updated plotting functions to work with new ggraph
releases.
Fixed regression with parallel usage of phylo_path
due to an S3 inheritance issue on the cluster (#16, thanks Simon
Greenhill for the report).
Prepare for R v4.0.0.
Bug fix: Very low p-values could cause underflow and result in infinite C statistics. All p-values are now set to be at least the size of the machine accuracy (i.e. 2 * 10^-16).
Warnings are now again correctly reported.
ggraph.Bug fix: It was possible to get CICc values in the summary output
that were not valid. Specifically, to calculate CICc there is a division
by (n - 1 - q), where n is the number of
observations (species) and q the number of parameters in
the causal model. This could lead to infinite CICc when
n == q + 1, or a flipped of CICc when
n < q + 1. This would typically only occur when
attempting to fit models with very few species (e.g. < 10).
New behavior is to set CICc to NA when n is
insufficient, and to give a warning.
Removed dependencies dplyr and tidyr,
but added tibble.
Fixed bug that would return the wrong model in some error messages.
Improved reporting of warnings, and a
show_warnings() function has been added.
Citation info now points to the PeerJ paper.
Citation info now points to the bioRxiv paper.
All modeling functions now completely rely on the
phylolm package, and no longer use ape. This
is a major change, that will possibly change the outcomes of some of
your existing analyses (as can happen when chaning the modeling
package). There are, however, several good reasons to make this change,
which I think make it worth the trouble. Firstly, the package is much
faster for large trees, and this effect is compounded in
phylopath because one may have to fit a few dozen models.
Secondly, I think it is important to have confidence intervals around
the regression coefficients, and those were not available for
ape::binaryPGLMM. Thirdly, phylolm makes it
easy to use a larger variety of models of evolution, including two
versions of OU and early burst, which can be simply set using the
model parameter. Lastly, the phylolm() and
phyloglm() functions give more uniform results, which makes
it easier to code for situation where you may use both.
phylo_path and all related methods now deal
automatically with both continuous and binary data. All separate binary
functions and methods have disappeared as they are no longer needed.
Mixing of binary and continious data in the same models is now
allowed.
The variable order in d-seperation statements now better follows the causal flow of the DAG.
Added plot() method for
phylopath.summary objects, that shows the weights and
p-values for the different models.
coef_plot() gained error_bar,
order_by, from and to arguments.
The first allows the user to choose between confidence invervals and
standard errors, the second to order the paths by several methods, and
the last two can be used to select only certain paths.
Plotting methods of causal models now support a manual layout.
Plotting of fitted DAG’s now uses edge width instead of color to
indicate, the standardized regression coefficient strength, but this can
be reverted using the type argument.
Added a define_model_set() convenience function for
building models, that avoids repeated calls to DAG() and
has an argument to supply paths that are shared between all your models.
It is not needed to specify isolate variables. Old code using
DAG() continues to work as normal.
Added support for additional arguments passed to gls
from phylo_path. This can be helpful, for example, for
setting the fitting method to maximum likelihood
(method = "ML").
####Bugfixes:
The package broke due to an update of purrr, but has
now been fixed (reported by Christoph Liedtke, @hcliedtke).
The package depends on a recent version of nlme, but
this wasn’t specified. All package versions of dependencies are now
defined (reported by @ManuelaGonzalez).
Added support for completely binary models, that are fitted with
ape::binaryPGLMM. Use phylo_path_binary() to
compare models. average(), best() and
choice() are now S3 generics and will handle both
continuous and binary versions. Usage is designed to be as close to the
continuous version as possible. est_DAG_binary() powers the
binary S3 methods.
All plot functions that used DiagrammeR now use
ggraph instead. This gives much more control over the
positioning of the nodes, and allows to plot multiple models at once.
Exporting plots also becomes much easier.
You can now plot a list of causal models with
plot_model_set(). This creates a faceted plot where all
nodes are kept in the same location, which makes it easier to spot how
models are different.
If there are any NA values in data for
the variables in models, these rows are now dropped from
data with a message. Use na.rm = FALSE to
revert to the old behavior.
When PGLS models fail, an informative error is now returned to the user.
phylo_path() now checks for row.names that line up
with the tree tip labels. If the tree contains surplus species, it gets
pruned to size with a message. This includes cases where species are
dropped due to missing values.
citation() now correctly refers to the methods paper
by Von Hardenberg & Gonzalez-Voyer first and the package
second.
Fewer models are now fitted when using phylo_path(),
since any duplicated independence statements are now only fitted once.
This leads to a significant reduction in running time in many cases,
especially when many models are considered.
Implemented support for parallel processing in
phylo_path() using the parallel
argument.
phylo_path() now shows a progress bar.
New function added (choice()) that is a very simple
wrapper around est_DAG(). It adds to best()
and average() by allowing for choosing any model as the
final model, and encourages users to not always pick the lowest CICc
model.
Prepared plotting functions for new release of
DiagrammeR, v0.9 now required.
IMPORTANT: Faulty model averaging has been fixed. This was often introduced due to differences in matrix ordering. Averaging results from versions before 0.2.1 should NOT be trusted.
Using ape::corBrownian() no longer returns an
error.
Averaging is less likely to fail due to errors in
nlme::intervals().
phylo_path() has become more streamlined with
functionality moved to other functions. The phylopath
object now contains all necessary models and data,
summary() is used to obtain the results table, and
best() and average() are used to extract and
fit the best or average model. See the vignette for details.
Model averaging for arbitrary models is now possible with
average_DAGs().
Model averaging now supports both conditional and full model averaging.
Both the old est_DAG() and the new
average_DAGs() now return objects of a new class
fitted_DAG, that has it’s separate plot
method. The plot method for objects of class
DAG has been simplified.
Model averaging now returns standard errors and confidence
intervals based on the MuMIn package (issue #1).
A new function plot_coefs for plotting regression
coefficients and their confidence intervals has been added.