internalFunctions: 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

web: data for an interaction network in vector form, e.g. from predict_tapnet;
P: matrix of same size as observed web, summing to 1, representing something like the probability of selecting a link; typically constructed as part of tapnet, i.e. the I-mat of fit_tapnet;
tapnet: a tapnet object;
tree: phylogenetic tree in phylo format;
species: a named vector of species, representing (some of) the tips of the phylogenetic tree;
delta_t: vector of pairwise trait differences (higher - lower);
type: trait matching function: either "normal" or "shiftlnorm";
width: width parameter of trait matching function, similar to sd in the normal;
shift: shift parameter (optimum trait distance), currently ignored in fitting;
xi: penalty for increasing the width of the (unstandardised) trait-matching function; defaults to 1 (implying a quadratically increasing weight of width in the optimisatino function, i.e. strongly acting against large values of sigma)
err: "baseline" probability of match, even if traits do not match at all;
params: parameter vector with setting for tapnet simulation;
n: number of latent trait linear combination parameters (lower level);
m: number of latent trait linear combination parameters (higher level);
fit.delta: logical; should the trait-weighting exponent delta be fitted?
networks: the "networks" part of a tapnet object;
tmatch_type_pem: type of trait matching function for latent traits;
tmatch_type_obs: type(s) of trait matching functions for observed traits; can be a vector as long as there are traits;
TmatchMatrixList: list of independent trait-matching matrices (one per network);
lambda: LASSO shrinkage parameter to avoid collinearity issues when observed traits are phylogenetically correlated;
obj_function: objective function, either "multinom" or "least squares" (leads to OLS fitting) or "bjorn" (leading to use of a somewhat weird but in some opinion the correct way to compute the likelihood);
true_pars: parameters used for simulating the network;
fitted_pars: parameters estimated by fit_tapnet;
pems_low: phylogenetic eigenvectors for the lower trophic level;
pems_high: phylogenetic eigenvectors for the higher trophic level;
web_dim: vector of two numbers indicating the rows and column of the network matrix;
indices: vector of names of network indices to compute; see networklevel for what is available;
fit: a fitted tapnet;
fitted_I_mat: the fitted I-matrix of a fitted tapnet object.

Author

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>

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.

References

Benadi et al. in prep