| Title: | Predicting Invasion Probabilities from Phylogenetic Data and Species Traits |
| Version: | 0.1.0 |
| Description: | A phylogenetic modelling approach for predicting species invasion risk, out of a given pool of local species where a subset is known to be invasive elsewhere. The package uses phylogenetic signal estimation and phylogenetic linear and logistic models to estimate probabilities of being invasive based on phylogeny and any set of additional predictors. A ranking method is implemented to evaluate prioritisation strategies. A manuscript describing these methods, by Shahar Dubiner and Tamar Guy-Haim, is in preparation. |
| License: | GPL-3 |
| Encoding: | UTF-8 |
| Imports: | ape, caper, ggplot2, phylolm, phyr, phytools, pROC, rotl, stats |
| RoxygenNote: | 7.3.3 |
| NeedsCompilation: | no |
| Packaged: | 2026-07-12 00:14:38 UTC; shadu |
| Author: | Shahar Dubiner 
[aut, cre] |
| Maintainer: | Shahar Dubiner <dubiner@mail.tau.ac.il> |
| Depends: | R (≥ 3.5) |
| LazyData: | true |
| Repository: | CRAN |
| Date/Publication: | 2026-07-21 10:30:30 UTC |
Fish dataset with invasive status
Description
A few fish species and their binary invasiveness status
Usage
fish_beginning_with_E
Format
A data frame with 2 variables:
- Species
Character species name
- Invasive
0/1 indicator of invasiveness
- Fake_continuous_trait
a simulated predictor
- Fake_categorical_trait
another simulated predictor
Source
Example data.
Compute phylogenetic signal and baseline invasion model
Description
This function must be run before all prediction/evaluation steps.
Usage
invasion_signal(prepared)
Arguments
prepared |
Output of prepare_invasible() #' |
Details
Computes Fritz & Purvis D statistic
Fits phylogenetic logistic regression
Extracts phylogenetic dependence parameter (alpha)
Returns an "invasible_signal" object for prediction functions
Value
An object of class invasible_signal, a list containing:
- phylo_model
- predictors
- prepared
- tree
- D
- p_random
,
- p_brownian
- alpha
Examples
species_list <- fish_beginning_with_E
prep <- prepare_invasible(species_list)
signal <- invasion_signal(prep)
signal$D
signal$p_random
Simulated monitoring performance for predicted invaders
Description
Evaluates the probability of :
Detecting at least one invasion within n given species, under ranked monitoring, i.e. the highest-probability n species, vs a random selection.
Given an invasion, detecting it within the n species, under ranked monitoring, i.e. the highest-probability n species, vs a random selection.
Usage
monitor_species(pred_out, plot = FALSE, max_n = 25)
Arguments
pred_out |
Output from |
plot |
Logical. If TRUE, returns ggplot objects. |
max_n |
Integer. Highest n value to be plotted (n=25 as default). |
Value
a list containing:
- results
simulation results for each value of n
- plot1
1st plot of
resultsfor each value untilmax_n- plot2
2nd plot of
resultsfor each value untilmax_n
dev
Examples
species_list <- fish_beginning_with_E
prep <- prepare_invasible(species_list,rho=1, predictors=c("Fake_continuous_trait"))
signal <- invasion_signal(prep)
pred <- predict_invasible(signal)
set.seed(10)
probs <- monitor_species(pred,plot=TRUE,max_n=16)
probs$plot1
probs$plot2
Predict invasion risk and evaluate model performance
Description
Fits a phylogenetic generalized linear mixed model (PGLMM) from the output of
invasion_signal()Calculates the probability of being invasive for all species, based on the phylogeny (and optionally species traits) given to the original
prepare_invasible()functionComputes predictive performance metrics such as ROC AUC
Plots the predicted values for observed invasive species (1) vs non-invading species (0) (optional)
Usage
predict_invasible(signal, vcv_alpha = NULL, plot = FALSE)
Arguments
signal |
Output of |
vcv_alpha |
Numeric, optional: set a value of alpha for OU model which is
different to the value inherited from the |
plot |
Logical. If TRUE, returns diagnostic plot of observed vs predicted |
Value
An object of class pred_output, a list containing:
- model
Fitted PGLMM model object.
- predictions
Data frame with observed and predicted values for all species.
- ranked_predictions
Candidate invasives ordered by decreasing probability.
- roc
ROC object
- auc
Numeric AUC (area under the curve) value.
- plot
ggplot object (if requested; run pred_output$plot to show).
Examples
species_list <- fish_beginning_with_E
prep <- prepare_invasible(species_list,rho=1, predictors=c("Fake_continuous_trait"))
signal <- invasion_signal(prep)
pred <- predict_invasible(signal,plot=TRUE)
pred$ranked_predictions
pred$auc
pred$plot
Prepare data and phylogeny for analyses (mandatory step)
Description
Aligns species-level invasion data with a phylogeny and stores predictor information for downstream analyses.
Usage
prepare_invasible(
df,
tree = NULL,
predictors = NULL,
species_col = "Species",
rho = 0.5,
plot = FALSE
)
Arguments
df |
Data frame containing at least a |
tree |
Optional object of class |
predictors |
Optional character vector of column names (additional predictors beyond phylogeny; if NULL, models will be based on the tree alone). |
species_col |
Name of species column (default "Species" is recommended). |
rho |
Grafen branch length scaling parameter (default 0.5). |
plot |
Logical. If TRUE, visualizes the phylogeny in |
Details
If no phylogeny is supplied, a tree is retrieved from the Open Tree of Life using rotl; Grafen branch lengths are added if branch lengths are absent. We recommend providing a high-quality tree if available, and also recommend fully matching the species in the data and phylogeny.
Value
An object of class "invasible_prepared".
Examples
species_list <- fish_beginning_with_E
prep <- prepare_invasible(species_list,rho=1,plot=TRUE, predictors=
c("Fake_categorical_trait","Fake_continuous_trait"))
prep$tree