Package {invasible}

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 ORCID iD [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

  1. Computes Fritz & Purvis D statistic

  2. Fits phylogenetic logistic regression

  3. Extracts phylogenetic dependence parameter (alpha)

  4. 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 :

  1. Detecting at least one invasion within n given species, under ranked monitoring, i.e. the highest-probability n species, vs a random selection.

  2. 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 predict_invasible().

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 results for each value until max_n

plot2

2nd plot of results for each value until max_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

  1. Fits a phylogenetic generalized linear mixed model (PGLMM) from the output of invasion_signal()

  2. Calculates the probability of being invasive for all species, based on the phylogeny (and optionally species traits) given to the original prepare_invasible() function

  3. Computes predictive performance metrics such as ROC AUC

  4. 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 invasion_signal()

vcv_alpha

Numeric, optional: set a value of alpha for OU model which is different to the value inherited from the invasion_signal() output

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 Species column formatted as "Genus_species", and an Invasive column (0: not invasive, 1: invasive).

tree

Optional object of class "phylo".

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 tree.

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