tapnet: A package for fitting, and predicting from, bipartite interaction networks.

Description

The package provides three categories of important functions: making tapnet objects, fitting the tapnet, and predicting to new data. All other functions are helpers or quality monitoring. The idea of using abundances, observed traits and phylogeny-derived latent traits to quantitatively fit and predict interaction is detailed in Benadi et al. (2021). This package accompanies the paper.

Making a tapnet object

The typical tapnet object contains information on (1) an interaction network in the form of one or more matrices; (2) a phylogenetic tree for both groups; (3) observed traits for both groups, arranged in such a way that they are supposed to match when the difference is 0. These information can come separately, and the make_tapnet function aims at putting them into a tapnet object, as is expected by the functions in this package. Also, the function simulate_tapnet can be used to simulate data of this format.

Fitting a tapnet

Fitting of a tapnet refers to the idea of trying to find a function that predicts interactions depending on species abundances, their observed traits (and the match of these traits) and the match of unobserved "latent" traits constructed from the phylogeny. This fitted function can have quite a few parameter (we refer to the paper here), and fit_tapnet is the function to call all relevant optimisers and likelihood functions. At present, the observed interactions are evaluated as multinomial likelihood given the expectation from the parameters that are fitted. Also a least-square option is available. The fit can be evaluated in different ways, e.g. using the gof_tapnet function.

Predicting from a tapnet

At present only predictions to altered abundances are possible. To predict to a new species, this means fitting the original network with this species in it, but no observed interactions. For prediction, the new abundances and the fitted tapnet need to be provided. See predict_tapnet for an example.

News/versions

0.6: 20-Jan-2026

Relaxation of type check in predict_tapnet

Allowed abundances to be named 1-dimensional arrays, too.

0.5: 01-Dec-2023

Bug fix in make_tapnet:

Did not set abundances and network dimensions to the same lengths. Now uses bipartite::empty along the way.

Bug fix in tapnet2df:

Without traits the function threw an error.

Hand-coding interactions probabilities:

Added option to hand over an externally prepared "mask" of "forbidden links", which is multiplied onto fits.

gof_tapnet output

enriched by the fitted I_mat. There was no way to output the I_mat until now, so the fit_tapnet output was not really useable.

0.4: 15-Sep-2022

Added the option to fit networks without phylogenetic information. To do so, use tmatch_type_pems="no". Rather experimental at this stage.

0.3; 10-Jun-2019

Added option "tapnet" to predict_tapnet in order to be able to use it on simulations. Cleaned up the code according to devtools::check-report.

0.2; 19-Sep-2019

Tinoco-data updated to now also contain external abundances (thanks Boris for providing these!). Help file for these data updated accordingly. By now we have used tapnet on many simulations and some real data and are fairly confident that the functions work as they should. The real test comes when data are not carefully prepared, with corrupted names and in non-alphabetical order, networks have NAs and so forth. Hopefully we have coded properly for these cases, too.

0.1

Initial version with all functions complete and a data set for demonstration. Code written by Gita Benadi, Carsten Dormann and Jochen Fründ, data provided by Boris Tinoco.

References

Benadi, G., Dormann, C.F., Fründ, J., Stephan, R. and Vázquez, D.P. (2022) Quantitative prediction of interactions in bipartite networks based on traits, abundances, and phylogeny. The American Naturalist 199, 841–854.

Hummingbird-flower networks

Description

An example dataset for tapnet analysis

Usage

data(Tinoco)

Format

An object of class matrix (inherits from array) with 14 rows and 1 columns.

Details

These data are from the supplement of Tinoco et al. (2017) and contain three observed networks (forest at Mazan, shrubland at Llaviuco, cattle farm at Nero, all in Ecuador), along with traits of flowers and birds (corolla and beak length, respectively) as well as phylogenies and external abundances for all species. These data are in several ways special, but most of all because of the very high sampling effort that went into the networks.

For sake of clarity, we provide the data as separate objects. So when "Tinoco" is called, it will load seven objects: networks, humm_traits, humm_tree, humm_abun, plant_traits, plant_tree and plant_abun. To combine them into a useable tapnet object, use make_tapnet. Phylogenetic trees are of class "phylo" (as used/produced by phytools). Abundance data were provided independently of the other data directly by Boris (the other data are on dryad doi:10.5061/dryad.j860v). For the external abundances of hummingbirds, 12 point counts were performed in the same habitats where hummingbird - plant interactions were observed. "Abundance were obtained by averaging the abundance of each species per point count across the study period." "Plant abundances are averages across the study period." Many thanks to Boris for making his data freely available!

Author(s)

Boris A. Tinoco Molina btinoco@uazuay.edu.ec collected the data; Carsten F. Dormann carsten.dormann@biom.uni-freiburg.de packaged them

References

Tinoco, B. A.; Graham, C. H.; Aguilar, J. M. & Schleuning, M. Effects of hummingbird morphology on specialization in pollination networks vary with resource availability. Oikos 126, 52-–60

Examples

ls()
data(Tinoco)
ls() # adds seven objects!

Fit the tapnet model to a network

Description

Estimates the parameters of the tapnet model by log-likelihood based on the observed network(s)

Usage

fit_tapnet(
  tapnet,
  ini = NULL,
  tmatch_type_pem = "normal",
  tmatch_type_obs = "normal",
  TmatchMatrixList = NULL,
  lambda = 0,
  method = "Nelder",
  maxit = 50000,
  hessian = FALSE,
  obj_function = "multinom",
  fit.delta = FALSE
)

Arguments

Details

The core function for using the tapnet approach: it fits the model to the data (= networks). Then, the estimated parameters can be used to predict to other networks (using predict_tapnet).

Value

A tapnet-fit object, containing the tapnet model parameters as entries "par_opt", the settings of the tmatch_type for PEMs and observed traits, the parameter set for lambda, the optimisation method set, along with its maxit-value, and, finally, the output of the call to optim, including the target value (the negative log-likelihood), the convergence report and the parameters as fitted at the transformed scale. Note that the entries under "opt" will not be the same as those under "par_opt"!

Author(s)

Gita Benadi <gita.benadi@biom.uni-freiburg.de> and Carsten Dormann <carsten.dormann@biom.uni-freiburg.de>

References

Benadi et al. in prep

Examples

 # takes about 35 s
 data(Tinoco)
 tap <- make_tapnet(tree_low = plant_tree, tree_high = humm_tree, networks = networks[2:3], 
        traits_low = plant_traits, traits_high = humm_traits, npems_lat = 4)
 fit <- fit_tapnet(tap) # fits to networks 2 and 3 only
 str(fit)
  

Goodness-of-fit of a tapnet fit

Description

Provides various measures to describe how well the tapnet model fits the data

Usage

gof_tapnet(
  fit,
  tapnet = NULL,
  indices = c("connectance", "NODF", "weighted NODF", "H2"),
  nrep = 1000,
  se_refit = FALSE,
  se_nsim = 1000
)

Arguments

Details

This is a function particularly interesting for simulated data, when the true parameters are known. In this case, GOF for fitted latent traits and so forth are computed.

Value

A list of goodness-of-fit measures: bc_sim_web are the Bray-Curtis similarities between fitted and observed network; cor_web are Spearman correlations between fitted and observed; and net_indices compute the selected network indices for fitted and observed networks. Also outputs the fitted I_mat for users to do other gymnastics with it. If more than one network is used for fitting, all these measures are returned for all networks (as vector or list under the respective label). See example.

Author(s)

Gita Benadi <gita.benadi@biom.uni-freiburg.de> and Carsten Dormann <carsten.dormann@biom.uni-freiburg.de>

References

Benadi et al. in prep

Examples

  data(Tinoco)
  tap <- make_tapnet(tree_low = plant_tree, tree_high = humm_tree, networks = networks[2:3], 
         traits_low = plant_traits, traits_high = humm_traits, npems_lat = 4)
  fit <- fit_tapnet(tap) # uses networks 2 and 3 for fitting!
  gof_tapnet(fit)

Helper functions for tapnet

Description

Lower-level, non-exported functions to be called by the main tapnet functions

Usage

internalFunctions()

bjornloglik(web, P)

fit_abund(tapnet)

pems_from_tree(tree)

select_relevant_pems(tree, species)

tmatch(delta_t, type = "normal", width = 1, shift = 0, xi = 1, err = 1e-05)

param_vec2list(params, n, m, fit.delta = FALSE)

loglik_tapnet(
  params,
  networks,
  tmatch_type_pem,
  tmatch_type_obs,
  TmatchMatrixList = NULL,
  lambda = 0,
  obj_function = "multinom",
  fit.delta = TRUE
)

latent_cor(true_pars, fitted_pars, pems_low, pems_high)

web_indices(web, web_dim, indices)

refit_params(tapnet, fit, fitted_I_mat)

Arguments

Details

They do roughly the following:

bjornloglik

computes likelihood of obtaining the observed interaction matrix, given some expected matrix of interaction propabilities (P). In contrast to the multinomial, this function assumes that the marginal totals of P constrain the probabilities. Hence, if all observations for one column (or row) have been evaluated for their probabilities, any new observation cannot come from this column (or row) anymore. This means, the probabilities in that "depleted" column (or row) have to be proportionally distributed over the other rows (or columns). There are ongoing discussions among the authors, when this is the right approach. Function written by Björn Reineking, ISRAE Grenoble (many thanks!), hence the name.

fit_abund

computes expected P-matrix of observed interactions based only on abundances; if no external abundances are provided in the tapnet-object, it will use the marginal totals of the network(s) instead.

pems_from_tree

computes phylogenetic eigenvectors from a phylogenetic tree;

select_relevant_pems

identifies those phylogenetic eigenvectors (PEMs) of the full tree most relevant for a network containing only a subset of species;

tmatch

calculates interaction probabilities based on trait matching;

param_vec2list

converts a vector of parameters (for trait matching and latent trait combinations) into a named list;

loglik_tapnet

the (negative!) log-likelihood function for fitting the tapnet model; actually quite an important function, easy to break, so not for the user to easily access;

latent_cor

computes correlation of fitted latent with true constructed traits for simulated data;

web_indices

computes the specified network indices for the provided network, after turning the prediction vector into a matrix;

refit_params

Simulate new networks from a fitted tapnet object, re-fit on the simulated network and output the parameter values.

Author(s)

Gita Benadi <gita.benadi@biom.uni-freiburg.de>, Carsten Dormann <carsten.dormann@biom.uni-freiburg.de> and Jochen Fründ <jochen.fruend@biom.uni-freiburg.de>

References

Benadi et al. in prep

Constructs an object of type "tapnet"

Description

Collates networks, traits and phylogenies into a consistent data structure used for all other tapnet functions

Usage

make_tapnet(
  tree_low,
  tree_high,
  networks,
  abun_low = NULL,
  abun_high = NULL,
  traits_low = NULL,
  traits_high = NULL,
  npems_lat = NULL,
  use.all.pems = FALSE,
  empty = TRUE
)

Arguments

Details

Tapnet objects are the starting point for almost all other tapnet functions. They contain the information on the species and the (quantitative) interaction network data.

Value

A tapnet object, i.e. an thoroughly organised list with the inputs as entries. If multiple networks are provided, each has its own list entry, with PEMs, traits and abundances given for each network separately, in addition to the overall phylogenetic eigenvectors across all networks. See example for, well, for an example.

Author(s)

Gita Benadi <gita.benadi@biom.uni-freiburg.de>

References

Benadi et al. in prep

Examples

data(Tinoco)
tapnet_web1 <- make_tapnet(tree_low = plant_tree, tree_high = humm_tree, networks = networks[1], 
               traits_low = plant_traits, traits_high = humm_traits, npems_lat = 4)
str(tapnet_web1) # show tapnet structure

Predict from fitted tapnet to new data

Description

Function allows direct use of data prepared for tapnet analysis by other statistical methods, e.g. regression approaches

Usage

predict_tapnet(fit, abuns, tapnet = NULL)

Arguments

Details

The fitted tapnet object contains the estimated parameters, describing how traits, abundance and phylogeny play together to produce the network(s) used for fitting. This information is now used to predict interaction probabilities for a new network. Accordingly, we need to know this new network's species abundances (an input to the function), PEMs and traits. The latter are computed based on the information contained in the tapnet object (which is linked in by attribute reference). For new species, their PEMs are computed and the network is simulated, using simnetfromtap, for the information provided.

Value

A matrix of predicted interaction probabilities, summing to 1. This would need to be multiplied by the total number of interactions in the new network to be comparable to the observations.

Author(s)

Ruth Stephan, Gita Benadi and Carsten Dormann <carsten.dormann@biom.uni-freiburg.de>

References

Benadi et al. in prep

Examples

  data(Tinoco)
  tap <- make_tapnet(tree_low = plant_tree, tree_high = humm_tree, networks = networks[1:2], 
         traits_low = plant_traits, traits_high = humm_traits, npems_lat = 4)
  fit <- fit_tapnet(tap) # uses two networks for fitting!
  gof_tapnet(fit)
  # predict to omitted forest network's abundances:
  pred1 <- predict_tapnet(fit, abuns=list("low"=plant_abun[[3]], "high"=humm_abun[[3]] )) 
  cor(as.vector(pred1*sum(networks[[3]])), as.vector(networks[[3]])) 

Simulates a network from parameters, abundances, traits and phylogeny provided

Description

The workhorse function of this package, called by various other functions to construct a bipartite interaction network

Usage

simnetfromtap(
  traits,
  abuns,
  paramsList,
  pems,
  tmatch_type_pem,
  tmatch_type_obs
)

Arguments

Details

Details in here!

Value

A named interaction matrix.

Author(s)

Gita Benadi <gita.benadi@biom.uni-freiburg.de> and Carsten Dormann <carsten.dormann@biom.uni-freiburg.de>

References

Benadi et al. in prep

Creates a simulated along with all parameters, abundances, traits and phylogeny used

Description

Simulation function to produce a tapnet object, i.e. one or more networks along with their descriptors, abundances, traits, phylogenetic information

Usage

simulate_tapnet(
  nlower,
  nhigher,
  ntraits_nopem,
  ntraits_pem,
  pem_noise = 0.5,
  abuns = "lognormal",
  meanlog = 0,
  sdlog = 1,
  tmatch_type_pem = "normal",
  tmatch_type_obs = "normal",
  npems_lat = NULL,
  lat_low = 1,
  lat_high = 1,
  tmatch_width_pem = 1,
  pem_shift = 0,
  tmatch_width_obs = 1,
  Nwebs = 1,
  prop_species = 1,
  new_abuns = FALSE,
  Nobs = 1000
)

Arguments

Details

This function was written to explore the fitting of networks by different methods. Hence, we first have to simulate such networks. It is a very nice starting point for simulations, but irrelevant for tapnet-based analyses. The function internally sets up all the parameters and then calls simnetfromtap for the simulation of the actual network. Lots of options means, regrettably, lots of decisions for the user.

Value

A tapnet object, with a highly nested structure. There are six entries at the top level: trees, traits_all, networks, sim_params and the two tmatch types. Within networks, there is a list of 5 entries (for each of the Nweb networks): abundances, traits, PEMs, web and I_mat. "I_mat" is the actual output from simnetfromtap, while "web" is a single draw from a multinomial distribution with I_mat as probabilities and Nobs as size.

Author(s)

Gita Benadi <gita.benadi@biom.uni-freiburg.de>, Jochen Fründ <jochen.fruend@biom.uni-freiburg.de> and Carsten Dormann <carsten.dormann@biom.uni-freiburg.de>

References

Benadi et al. in prep

Examples

tapnet <- simulate_tapnet(nlower=10, nhigher=20, ntraits_nopem=2, ntraits_pem=0) 
# a minimal call of simulate_tapnet
str(tapnet, 1) # the structure at the first level
str(tapnet, 2) # the structure at the first and second level

Convert tapnet object into data.frame

Description

Function allows direct use of data prepared for tapnet analysis by other statistical methods, e.g. regression approaches

Usage

tapnet2df(tapnetObject)

Arguments

Details

This function simply puts all data into a data.frame, with each row an entry in the network matrix.

Value

A data.frame containing network observations, PEMs, traits and abundances for regression-type analysis.

Author(s)

Carsten Dormann <carsten.dormann@biom.uni-freiburg.de>

References

Benadi et al. in prep

Examples

ex <- simulate_tapnet(nlower=10, nhigher=50, ntraits_pem=3, ntraits_nopem=2, Nwebs = 3)
df <- tapnet2df(ex)
head(df)
## Not run: 
  library(ranger)
  frf <- ranger(interactions ~ ., data=df[, -c(1:2)], importance="impurity")
  sort(importance(frf), decreasing=TRUE)

## End(Not run)