Package 'cxr'

Description

A dataset containing abundances for each plant species, where each species was sampled at its developmental peak.

• plot: one of 9 plots of the study area

• subplot: one of 36 1x1 m subplots of each plot

• species: plant species

• individuals: number of individuals observed

Usage

data(abundance)

Format

A data frame with 5184 rows and 4 variables

Note

For details, see Lanuza et al. 2018 Ecology Letters.

Description

The function projects a number of steps of a time-discrete model, with model parameters taken from a 'cxr_pm_multifit' object or as function arguments.

Usage

abundance_projection(
  cxr_fit = NULL,
  model_family = NULL,
  alpha_form = NULL,
  lambda_cov_form = NULL,
  alpha_cov_form = NULL,
  lambda = NULL,
  alpha_matrix = NULL,
  lambda_cov = NULL,
  alpha_cov = NULL,
  covariates = NULL,
  timesteps = 2,
  initial_abundances = 0
)

Arguments

Value

named matrix with projected abundance values for each taxa at each timestep.

Description

computes the average fitness differences among two or more species according to the formulation of the MCT (Chesson 2012, Godoy and Levine 2014), and according to the structural approach (Saavedra et al. 2017). For the MCT version, the average fitness ratio is decomposed in a 'demographic ratio' and a 'competitive response ratio', the product of which is the average fitness ratio (Godoy and Levine 2014). This formulation is only valid for competitive interaction coefficients (i.e. positive alpha values in the interaction matrix). The structural analog can be computed for any interaction matrix, on the other hand. Note that the 'demographic ratio' is model-specific (Hart et al. 2018).

Usage

avg_fitness_diff(
  cxr_multifit = NULL,
  cxr_sp1 = NULL,
  cxr_sp2 = NULL,
  pair_lambdas = NULL,
  pair_matrix = NULL,
  model_family = NULL
)

Arguments

Details

This function, as in niche_overlap and competitive_ability, accepts three different parameterizations:

• A cxr_pm_multifit object, from which average fitness differences will be computed across all species pairs.

• two cxr_pm_fit objects, one for each species.

• explicit lambda and alpha values, as well as the model family from which these parameters were obtained.

If using the third parameterization, the function will try to find a model-specific function for obtaining the demographic ratio, by looking at the 'model_family' parameter. If this specific function is not found, it will resort to the standard Lotka-Volterra formulation (lambda in the numerator term). Overall, we strongly suggest that you use the standard formulation ONLY if you are completely confident that your custom model is consistent with it. Otherwise, you should include your own formulation of the demographic ratio (see vignette 4).

Value

data frame with variable number of rows, and columns specifying the different components of the MCT average fitness ratio, as well as its structural analog. The average fitness ratio informs quantitatively about the better competitor. If the ratio is < 1, sp2 is the better competitor; if = 1, both species are equivalent competitors, if > 1, sp1 is the better competitor.

Examples

avg_fitness_diff(pair_lambdas = runif(2,1,10),
                 pair_matrix = matrix(runif(4,0,1),nrow = 2),
                 model_family = "BH")

Description

The function for calculating fecundity given effect and response values is taken from Godoy et al. (2014). Note that, as e and r are not pair-specific, all species parameters are fit in the same function.

Usage

BH_er_lambdacov_global_effectcov_global_responsecov_global(
  par,
  fitness,
  target,
  density,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

The function for calculating fecundity given effect and response values is taken from Godoy et al. (2014). Note that, as e and r are not pair-specific, all species parameters are fit in the same function.

Usage

BH_er_lambdacov_none_effectcov_none_responsecov_none(
  par,
  fitness,
  target,
  density,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Beverton-Holt model with a global alpha and no covariate effects

Usage

BH_pm_alpha_global_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Beverton-Holt model with no alphas and no covariate effects

Usage

BH_pm_alpha_none_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Beverton-Holt model with pairwise alphas and global covariate effects on lambda and alpha

Usage

BH_pm_alpha_pairwise_lambdacov_global_alphacov_global(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Beverton-Holt model with pairwise alphas, covariate effects on lambda, and pairwise covariate effects on alpha

Usage

BH_pm_alpha_pairwise_lambdacov_global_alphacov_pairwise(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Beverton-Holt model with pairwise alphas and no covariate effects

Usage

BH_pm_alpha_pairwise_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Beverton-Holt model for projecting abundances, with a global alpha and no covariate effects

Usage

BH_project_alpha_global_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Beverton-Holt model for projecting abundances, with no alpha and no covariate effects

Usage

BH_project_alpha_none_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Beverton-Holt model for projecting abundances, with specific alpha values and global covariate effects on alpha and lambda

Usage

BH_project_alpha_pairwise_lambdacov_global_alphacov_global(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Beverton-Holt model for projecting abundances, with specific alpha values and global covariate effects on alpha and lambda

Usage

BH_project_alpha_pairwise_lambdacov_global_alphacov_pairwise(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Beverton-Holt model for projecting abundances, with specific alpha values and no covariate effects

Usage

BH_project_alpha_pairwise_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Builds a nested list for the parameters of a given metapopulation

Usage

build_param(sp, sites, rates, env, num.params = NULL)

Arguments

Value

nested list of the form 'list[[sp]][[site]]'. Each of these elements is a NA matrix with vital rates in rows and expected parameters in columns.

Examples

sp <- c("s1","s2","s3")
sites <- c("sa","sb")
rates <- c("Sj","Sn","Sr","Rn","Rr","D","O")
env <- TRUE
param <- build_param(sp = sp,sites = sites,rates = rates,env = env)

Description

Using the vec-permutation approach as defined in: Hunter and Caswell 2005, doi:10.1016/j.ecolmodel.2005.05.002, Ozgul et al. 2009, doi: 10.1086/597225 In particular, it uses the arrangement by patches, and calculates first demography, then dispersal (Table 1 of Hunter and Caswell 2005).

Usage

calculate_densities(focal.sp, vpm, current.densities)

Arguments

Value

matrix of sites x stages, each element is the density of a given life stage (juvenile, non-reproductive adult, reproductive adult) at a given site.

Description

Computes the competitive ability among two species, as defined by Hart et al. (2018). This metric, as others in MCT, is model-specific; the formulation for a series of Lotka-Volterra-like models is given in table A1 of Hart et al. (2018). We include in cxr by default the formulation for Beverton-Holt, Ricker, Law-Watkinson, and Lotka-Volterra families.

Usage

competitive_ability(
  cxr_multifit = NULL,
  cxr_sp1 = NULL,
  cxr_sp2 = NULL,
  lambda = NULL,
  pair_matrix = NULL,
  model_family = NULL
)

Arguments

Details

The function, as in avg_fitness_diff and niche_overlap, accepts three different parameterizations:

• A cxr_pm_multifit object, from which competitive ability of a focal species relative to a given competitor will be computed across all species pairs.

• two cxr_pm_fit objects, one for a focal species and one for a competitor.

• explicit lambda and alpha values, as well as the model family from which these parameters were obtained.

If the third parameterization is used, the function will try to find a model-specific function for obtaining the competitive ability, by looking at the 'model_family' parameter. If this specific function is not found, it will resort to the standard Lotka-Volterra formulation (lambda - 1 in the numerator term, Hart et al. 2018). Overall, we strongly suggest that you use the standard formulation ONLY if you are completely confident that the model from which you obtained your parameters is consistent with it. Otherwise, you should include your own formulation of competitive ability (see vignette 4).

Value

data frame with variable number of rows and three columns, specifying taxa identity and the competitive ability of focal species (sp1) relative to the competitor (sp2).

Examples

competitive_ability(lambda = runif(1,1,10),
                              pair_matrix = matrix(runif(4,0,1),nrow = 2),
                              model_family = "BH")

Description

Computes bootstrap standard errors for a given effect/response function. This function is provided for completeness, but error calculation is integrated in the function cxr_er_fit.

Usage

cxr_er_bootstrap(
  fitness_model,
  optimization_method,
  data,
  covariates,
  init_par,
  lower_bounds,
  upper_bounds,
  fixed_parameters,
  bootstrap_samples
)

Arguments

Value

1d vector, the standard error of each parameter in init_par

Description

Estimates parameters of user-specified models of competitive effects and responses. NOTE: including covariates on competitive effects is still under development, in this version it is suggested not to use that feature.

Usage

cxr_er_fit(
  data,
  model_family = c("BH"),
  covariates = NULL,
  optimization_method = c("Nelder-Mead", "BFGS", "CG", "ucminf", "L-BFGS-B", "nlm",
    "nlminb", "Rcgmin", "Rvmmin", "spg", "bobyqa", "nmkb", "hjkb", "nloptr_CRS2_LM",
    "nloptr_ISRES", "nloptr_DIRECT_L_RAND", "DEoptimR", "GenSA"),
  lambda_cov_form = c("none", "global"),
  effect_cov_form = c("none", "global"),
  response_cov_form = c("none", "global"),
  initial_values = list(lambda = 1, effect = 1, response = 1, lambda_cov = 0, effect_cov
    = 0, response_cov = 0),
  lower_bounds = NULL,
  upper_bounds = NULL,
  fixed_terms = NULL,
  bootstrap_samples = 0
)

Arguments

Value

an object of class 'cxr_er_fit' which is a list with the following components:

• model_name: string with the name of the fitness model

• model: model function

• data: data supplied

• taxa: names of the taxa fitted

• covariates: covariate data supplied

• optimization_method: optimization method used

• initial_values: list with initial values

• fixed_terms: list with fixed terms

• lambda: fitted values for lambdas, or NULL if fixed

• effect: fitted values for competitive effects, or NULL if fixed

• response: fitted values for competitive responses, or NULL if fixed

• lambda_cov: fitted values for effect of covariates on lambdas, or NULL if fixed

• effect_cov: fitted values for effect of covariates on competitive effects, or NULL if fixed

• response_cov: fitted values for effect of covariates on competitive responses, or NULL if fixed

• lambda_standard_error: standard errors for lambdas, if calculated

• effect_standard_error: standard errors for competitive effects, if calculated

• response_standard_error: standard errors for competitive responses, if calculated

• lambda_cov_standard_error: standard errors for effect of covariates on lambdas, if calculated

• effect_cov_standard_error: standard errors for effect of covariates on competitive effects, if calculated

• response_cov_standard_error: standard errors for effect of covariates on competitive responses, if calculated

• log_likelihood: log-likelihood of the fits

Examples

# fit three species at once
data("neigh_list")
# these species all have >250 observations
example_sp <- c("BEMA","LEMA","HOMA")
sp.pos <- which(names(neigh_list) %in% example_sp)
data <- neigh_list[sp.pos]
n.obs <- 250
# keep only fitness and neighbours columns
for(i in 1:length(data)){
  data[[i]] <- data[[i]][1:n.obs,c(2,sp.pos+2)]#2:length(data[[i]])]
}

# covariates: salinity
data("salinity_list")
salinity <- salinity_list[example_sp]
# keep only salinity column
for(i in 1:length(salinity)){
  salinity[[i]] <- salinity[[i]][1:n.obs,2:length(salinity[[i]])]
}

initial_values = list(lambda = 1, 
                     effect = 1, 
                     response = 1
                     # lambda_cov = 0, 
                     # effect_cov = 0, 
                     # response_cov = 0
)
lower_bounds = list(lambda = 0, 
                   effect = 0, 
                   response = 0
                   # lambda_cov = 0, 
                   # effect_cov = 0, 
                   # response_cov = 0
)
upper_bounds = list(lambda = 100, 
                    effect = 10, 
                    response = 10
                   # lambda_cov = 0, 
                   # effect_cov = 0, 
                   # response_cov = 0
)

er_3sp <- cxr_er_fit(data = data,
                     model_family = "BH",
                     # fit without covariates, 
                     # as it may be very computationally expensive
                     # covariates = salinity,
                     optimization_method = "bobyqa",
                     lambda_cov_form = "none",
                     effect_cov_form = "none",
                     response_cov_form = "none",
                     initial_values = initial_values,
                     lower_bounds = lower_bounds,
                     upper_bounds = upper_bounds,
                     # syntaxis for fixed values
                     # fixed_terms = list("response"),
                     bootstrap_samples = 3)
# brief summary
summary(er_3sp)

Description

Model fitness responses to neighbours and covariates using a Beverton-Holt functional form. This function is fairly restricted and under development, but can be used to generate simple test data to run the main functions of cxr.

Usage

cxr_generate_test_data(
  focal_sp = 1,
  neigh_sp = 1,
  covariates = 0,
  observations = 10,
  alpha_form = c("pairwise", "none", "global"),
  lambda_cov_form = c("none", "global"),
  alpha_cov_form = c("none", "global", "pairwise"),
  focal_lambda = NULL,
  min_lambda = 0,
  max_lambda = 10,
  alpha = NULL,
  min_alpha = 0,
  max_alpha = 1,
  alpha_cov = NULL,
  min_alpha_cov = -1,
  max_alpha_cov = 1,
  lambda_cov = NULL,
  min_lambda_cov = -1,
  max_lambda_cov = 1,
  min_cov = 0,
  max_cov = 1
)

Arguments

Value

list with two components: 'observations' is a list with as many components as focal species. Each component of 'observations' is a dataframe with stochastic number of neighbours and associated fitness. The second component, 'covariates', is again a list with one component per focal species. Each component of 'covariates' is a dataframe with the values of each covariate for each associated observation.

Examples

example_obs <- cxr_generate_test_data(focal_sp = 2,
                                      neigh_sp = 2,
                                      alpha_form = "pairwise",
                                      lambda_cov_form = "global",
                                      alpha_cov_form = "global",
                                      covariates = 1)

Description

Computes bootstrap standard errors for a given population dynamics model. This function is provided for completeness, but error calculation is integrated in the function cxr_pm_fit.

Usage

cxr_pm_bootstrap(
  fitness_model,
  optimization_method,
  data,
  focal_column,
  covariates,
  init_par,
  lower_bounds,
  upper_bounds,
  fixed_parameters,
  bootstrap_samples
)

Arguments

Value

1d vector, the standard error of each parameter in init_par

Description

Estimates parameters of user-specified population dynamics models.

Usage

cxr_pm_fit(
  data,
  focal_column = NULL,
  model_family,
  covariates = NULL,
  optimization_method = c("Nelder-Mead", "BFGS", "CG", "ucminf", "L-BFGS-B", "nlm",
    "nlminb", "Rcgmin", "Rvmmin", "spg", "bobyqa", "nmkb", "hjkb", "nloptr_CRS2_LM",
    "nloptr_ISRES", "nloptr_DIRECT_L_RAND", "DEoptimR", "GenSA"),
  alpha_form = c("none", "global", "pairwise"),
  lambda_cov_form = c("none", "global"),
  alpha_cov_form = c("none", "global", "pairwise"),
  initial_values = list(lambda = 0, alpha_intra = 0, alpha_inter = 0, lambda_cov = 0,
    alpha_cov = 0),
  lower_bounds = NULL,
  upper_bounds = NULL,
  fixed_terms = NULL,
  bootstrap_samples = 0
)

Arguments

Value

an object of class 'cxr_pm_fit' which is a list with the following components:

• model_name: string with the name of the fitness model

• model: model function

• data: data supplied

• focal_ID: name/ID of the focal taxa, if provided in 'focal_column'

• covariates: covariate data supplied

• optimization_method: optimization method used

• initial_values: list with initial values

• fixed_terms: list with fixed terms

• lambda: fitted value for lambda, or NULL if fixed

• alpha_intra: fitted value for intraspecific alpha, or NULL if fixed

• alpha_inter: fitted value for interspecific alpha, or NULL if fixed

• lambda_cov: fitted value(s) for lambda_cov, or NULL if fixed.

• alpha_cov: fitted value(s) for alpha_cov, or NULL if fixed. These are structured as a list with one element for each covariate.

• lambda_standard_error: standard error for lambda, if computed

• alpha_intra_standard_error: standard error for intraspecific alpha, if computed

• alpha_inter_standard_error: standard error for interspecific alpha, if computed

• lambda_cov_standard_error: standard error for lambda_cov, if computed

• alpha_cov_standard_error: standard error for alpha_cov, if computed

• log_likelihood: log-likelihood of the fit

Examples

data("neigh_list")
my.sp <- "BEMA"
# data for a single species, keep only fitness and neighbours columns
sp_data <- neigh_list[[my.sp]][2:ncol(neigh_list[[1]])]

  sp_fit <- cxr_pm_fit(data = sp_data,
                       focal_column = my.sp,
                       optimization_method = "bobyqa",
                       model_family = "BH",
                       alpha_form = "pairwise",
                       lambda_cov_form = "none",
                       alpha_cov_form = "none",
                       initial_values = list(lambda = 1,alpha_intra = 0.1,alpha_inter = 0.1),
                       lower_bounds = list(lambda = 0,alpha_intra = 0,alpha_inter = 0),
                       upper_bounds = list(lambda = 100,alpha_intra = 1,alpha_inter = 1),
                       bootstrap_samples = 3)
  summary(sp_fit)

Description

This function is a wrapper for estimating parameters for several focal species, instead of making separate calls to cxr_pm_fit.

Usage

cxr_pm_multifit(
  data,
  model_family = c("BH"),
  focal_column = NULL,
  covariates = NULL,
  optimization_method = c("BFGS", "CG", "Nelder-Mead", "ucminf", "L-BFGS-B", "nlm",
    "nlminb", "Rcgmin", "Rvmmin", "spg", "bobyqa", "nmkb", "hjkb", "nloptr_CRS2_LM",
    "nloptr_ISRES", "nloptr_DIRECT_L_RAND", "DEoptimR", "GenSA"),
  alpha_form = c("none", "global", "pairwise"),
  lambda_cov_form = c("none", "global"),
  alpha_cov_form = c("none", "global", "pairwise"),
  initial_values = NULL,
  lower_bounds = NULL,
  upper_bounds = NULL,
  fixed_terms = NULL,
  bootstrap_samples = 0
)

Arguments

Value

an object of class 'cxr_pm_multifit' which is a list with the following components:

• model_name: string with the name of the fitness model

• model: model function

• data: data supplied

• taxa: names of the taxa fitted

• covariates: covariate data supplied

• optimization_method: optimization method used

• initial_values: list with initial values

• fixed_terms: list with fixed terms

• lambda: fitted values for lambda, or NULL if fixed

• alpha_intra: fitted values for alpha_intra, or NULL if fixed

• alpha_inter: fitted values for alpha_inter, or NULL if fixed

• lambda_cov: fitted values for lambda_cov, or NULL if fixed

• alpha_cov: fitted values for alpha_cov, or NULL if fixed

• lambda_standard_error: standard errors for lambda, if computed

• alpha_standard_error: standard errors for alpha, if computed

• lambda_cov_standard_error: standard errors for lambda_cov, if computed

• alpha_cov_standard_error: standard errors for alpha_cov, if computed

• log_likelihood: log-likelihoods of the fits

Examples

# fit three species at once
data("neigh_list")
data <- neigh_list[1:3]
# keep only fitness and neighbours columns
for(i in 1:length(data)){
  data[[i]] <- data[[i]][,2:length(data[[i]])]
}
# be explicit about the focal species
focal.sp <- names(data)
# covariates: salinity
data("salinity_list")
salinity <- salinity_list[1:3]
# keep only salinity column
for(i in 1:length(salinity)){
  salinity[[i]] <- data.frame(salinity = salinity[[i]][,2:length(salinity[[i]])])
}

  fit_3sp <- cxr_pm_multifit(data = data,
                             optimization_method = "bobyqa",
                             model_family = "BH",
                             focal_column = focal.sp,
                             covariates = salinity,
                             alpha_form = "pairwise",
                             lambda_cov_form = "global",
                             alpha_cov_form = "global",
                             initial_values = list(lambda = 1,
                                                   alpha_intra = 0.1,
                                                   alpha_inter = 0.1,
                                                   lambda_cov = 0.1, 
                                                   alpha_cov = 0.1),
                             lower_bounds = list(lambda = 0.01,
                                                 alpha_intra = 0,
                                                 alpha_inter = 0,
                                                 lambda_cov = 0, 
                                                 alpha_cov = 0),
                             upper_bounds = list(lambda = 100,
                                                 alpha_intra = 1,
                                                 alpha_inter = 1,
                                                 lambda_cov = 1, 
                                                 alpha_cov = 1),
                             bootstrap_samples = 3)
  # brief summary
  summary(fit_3sp)
  # interaction matrix
  fit_3sp$alpha_matrix

Description

Converts a densities list to a tidy dataframe

Usage

densities_to_df(densities)

Arguments

Value

dataframe with columns species-stage-site(-year)-density

Description

Fill for a given species, across all sites.

Usage

fill_demography_matrix(focal.sp, vpm, transition_matrices)

Arguments

Value

vec-permutation demography matrix for a given species across sites.

Description

Fill for a given species, all sites

Usage

fill_dispersal_matrix(
  focal.sp,
  num.sites,
  param,
  vpm,
  env = NULL,
  current.densities
)

Arguments

Value

dispersal matrix, stages*sites

Description

Calculates the elements of a site-specific transition matrix for a given sp. Note that here, and through all functions, we fix three life stages. Also note that 'param' and 'env' must match, as for the 'vital_rate' function.

Usage

fill_transition_matrix(focal.sp, site, param, env = NULL, current.densities)

Arguments

Value

3x3 transition matrix

Description

Fitness ratio among two or more species

Usage

fitness_ratio(
  effect_response_fit = NULL,
  fitness_sp1 = NULL,
  fitness_sp2 = NULL
)

Arguments

Value

either a matrix with fitness ratios for all pairs of fitted species, or a single numeric value. The matrix elements represent the ratios of species in columns over species in rows, and conversely, the numeric value represents the ratio of sp1 over sp2.

Examples

fitness_ratio(fitness_sp1 = 0.6, fitness_sp2 = 0.3)

Description

Any vital rate is a function of several parameters, potentially including interactions or environmental effects. This function generates the coefficients for these parameters, so that users do not have to introduce them all manually in a 'param' list. Coefficients can be generated from a random sampling of a normal distribution with specified mean and standard deviation, or they can be retrieved from a model object that accepts a 'tidy' function from the broom/broom.mixed packages. This is because coefficients for vital rates can be understood as coefficients from statistical regressions.

Usage

generate_vital_rate_coefs(
  param,
  sp = NULL,
  sites = NULL,
  vital.rate = NULL,
  vr.coef = NULL,
  mean.coef = NULL,
  sd.coef = NULL,
  glm.object = NULL,
  glm.coef.equivalence = NULL
)

Arguments

Details

In the current version, we assume that the model coefficients come from a logistic regression with binomial family. Otherwise, the function will probably not fail, but the coefficients will not be interpretable and the results in terms of obtaining the actual vital rates from these will be meaningless.

Also note that you need to take care manually of the signs of the coefficients, if entered through mean/sd pairs.

Value

the updated parameter list

Description

A table with coefficients from a GLM to serve as an example for importing into the data structure of the metapopulation model.

Usage

data(glm_example_coefs)

Format

A named numerical matrix of 8 rows and 4 columns

Description

Note that, as e and r are not pair-specific, all species parameters are fit in the same function.

Usage

LV_er_lambdacov_global_effectcov_global_responsecov_global(
  par,
  fitness,
  target,
  density,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Note that, as e and r are not pair-specific, all species parameters are fit in the same function.

Usage

LV_er_lambdacov_none_effectcov_none_responsecov_none(
  par,
  fitness,
  target,
  density,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Lotka-Volterra model with a global alpha and no covariate effects

Usage

LV_pm_alpha_global_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

This model, in all families, is simply given by lambda.

Usage

LV_pm_alpha_none_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Lotka-Volterra model with pairwise alphas and global covariate effects on lambda and alpha

Usage

LV_pm_alpha_pairwise_lambdacov_global_alphacov_global(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Lotka-Volterra model with pairwise alphas, covariate effects on lambda, and pairwise covariate effects on alpha

Usage

LV_pm_alpha_pairwise_lambdacov_global_alphacov_pairwise(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Lotka-Volterra model with pairwise alphas and no covariate effects

Usage

LV_pm_alpha_pairwise_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Lotka-Volterra model for projecting abundances, with a global alpha and no covariate effects

Usage

LV_project_alpha_global_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Model for projecting abundances, with no alpha and no covariate effects

Usage

LV_project_alpha_none_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Lotka-Volterra model for projecting abundances, with specific alpha values and global covariate effects on alpha and lambda

Usage

LV_project_alpha_pairwise_lambdacov_global_alphacov_global(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Lotka-Volterra model for projecting abundances, with specific alpha values and global covariate effects on alpha and lambda

Usage

LV_project_alpha_pairwise_lambdacov_global_alphacov_pairwise(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Lotka-Volterra model for projecting abundances, with specific alpha values and no covariate effects

Usage

LV_project_alpha_pairwise_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Note that, as e and r are not pair-specific, all species parameters are fit in the same function.

Usage

LW_er_lambdacov_global_effectcov_global_responsecov_global(
  par,
  fitness,
  target,
  density,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Note that, as e and r are not pair-specific, all species parameters are fit in the same function.

Usage

LW_er_lambdacov_none_effectcov_none_responsecov_none(
  par,
  fitness,
  target,
  density,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Law-Watkinson model with a global alpha and no covariate effects

Usage

LW_pm_alpha_global_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

This model, in all families, is simply given by lambda.

Usage

LW_pm_alpha_none_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Law-Watkinson model with pairwise alphas and global covariate effects on lambda and alpha

Usage

LW_pm_alpha_pairwise_lambdacov_global_alphacov_global(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Law-Watkinson model with pairwise alphas, covariate effects on lambda, and pairwise covariate effects on alpha

Usage

LW_pm_alpha_pairwise_lambdacov_global_alphacov_pairwise(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Law-Watkinson model with pairwise alphas and no covariate effects

Usage

LW_pm_alpha_pairwise_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Law-Watkinson model for projecting abundances, with a global alpha and no covariate effects

Usage

LW_project_alpha_global_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Model for projecting abundances, with no alpha and no covariate effects

Usage

LW_project_alpha_none_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Law-Watkinson model for projecting abundances, with specific alpha values and global covariate effects on alpha and lambda

Usage

LW_project_alpha_pairwise_lambdacov_global_alphacov_global(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Law-Watkinson model for projecting abundances, with specific alpha values and global covariate effects on alpha and lambda

Usage

LW_project_alpha_pairwise_lambdacov_global_alphacov_pairwise(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Law-Watkinson model for projecting abundances, with specific alpha values and no covariate effects

Usage

LW_project_alpha_pairwise_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

A nested list containing vital rate coefficients for projecting metapopulation dynamics. The first level of the list has 3 elements, one for each species modelled. The second level of the list has 2 elements, one for each site modelled. For each combination species-site, there is a data.frame of eight rows - one per each vital rate, and eight columns - one per coefficient, that correspond to the coefficients of a GLM. These are named as alpha,beta1, etc, in the data.frame, and correspond to the intercept, environmental effect, effects of each of the three species' density, and environment:density interactions

Usage

data(metapopulation_example_param)

Format

A nested list with 3x2 elements, each of which a dataframe of 8 rows and 8 numeric columns

Description

A dataset containing fitness and neighbours for plant individuals of 17 species. The dataset is a named list with 16 elements, each of which is a dataframe with the following columns:

• obs_ID: unique identifier for each observation

• fitness: number of viable seeds of the focal individual

• 17 columns indicating the number of neighbours from each plant sp. in a radius of 7.5 cm from the focal individual

Usage

data(neigh_list)

Format

A list with 17 elements, each of which a dataframe of variable number of rows and 18 columns

Note

For details, see Lanuza et al. 2018 Ecology Letters.

Description

quoting Godoy et al. (2014): reflects the average degree to which species limit individuals of their own species relative to competitors. Low niche overlap causes species to have greater per capita growth rates when rare than when common. If species limit individuals of their own species and their competitors equally, then niche overlap is 1, and coexistence is not possible unless species are otherwise identical. At the other extreme, if species have no interspecific effects, then niche overlap is 0.

Usage

niche_overlap(
  cxr_multifit = NULL,
  cxr_sp1 = NULL,
  cxr_sp2 = NULL,
  pair_matrix = NULL
)

Arguments

Details

Niche overlap has a common functional form, in the context of Modern Coexistence Theory (MCT), for a series of models, including those specified in table A1 of Hart et al. (2018) Journal of Ecology 106, 1902-1909. Other model families may not adhere to the general definition.

Furthermore, the MCT definition only accounts for competitive interactions (i.e. positive alpha coefficients in these models). An alternative definition is given in Saavedra et al. (2017) Ecological Monographs 87,470-486. In this 'structural approach', positive interactions are allowed. Incidentally, both approaches yield qualitatively similar, but not equivalent, results for purely competitive matrices.

In all cases, these definitions only apply to models whose feasible equilibrium point can be described by a linear equation (see Saavedra et al. 2017, Hart et al. 2018 for details).

This function calculates niche overlap among two or more taxa, using both the MCT and the structural formulation. The function, as in avg_fitness_diff and competitive_ability, accepts three different parameterizations:

• A cxr_pm_multifit object, from which niche overlap will be computed across all species pairs.

• two cxr_pm_fit objects, one for each species.

• explicit lambda and alpha values, as well as the model family from which these parameters were obtained.

If negative interactions are present, the MCT niche overlap will be NA. The cxr objects may be calculated with user-defined model families. If this is the case, or if simply a 2x2 matrix is provided, the niche overlap metrics will be calculated and a warning will be raised.

Value

either a dataframe with as many rows as species, or a single named numeric vector, containing niche overlap values for the MCT (modern coexistence theory) and SA (structural approach) formulations.

Examples

niche_overlap(pair_matrix = matrix(c(0.33,0.12,0.2,0.4),nrow = 2))

Description

Note that, as e and r are not pair-specific, all species parameters are fit in the same function.

Usage

RK_er_lambdacov_global_effectcov_global_responsecov_global(
  par,
  fitness,
  target,
  density,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Note that, as e and r are not pair-specific, all species parameters are fit in the same function.

Usage

RK_er_lambdacov_none_effectcov_none_responsecov_none(
  par,
  fitness,
  target,
  density,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Ricker model with a global alpha and no covariate effects

Usage

RK_pm_alpha_global_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

This model, in all families, is simply given by lambda.

Usage

RK_pm_alpha_none_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Ricker model with pairwise alphas and global covariate effects on lambda and alpha

Usage

RK_pm_alpha_pairwise_lambdacov_global_alphacov_global(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Ricker model with pairwise alphas, covariate effects on lambda, and pairwise covariate effects on alpha

Usage

RK_pm_alpha_pairwise_lambdacov_global_alphacov_pairwise(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Ricker model with pairwise alphas and no covariate effects

Usage

RK_pm_alpha_pairwise_lambdacov_none_alphacov_none(
  par,
  fitness,
  neigh_intra_matrix = NULL,
  neigh_inter_matrix,
  covariates,
  fixed_parameters
)

Arguments

Value

log-likelihood value

Description

Ricker model for projecting abundances, with a global alpha and no covariate effects

Usage

RK_project_alpha_global_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Model for projecting abundances, with no alpha and no covariate effects

Usage

RK_project_alpha_none_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Ricker model for projecting abundances, with specific alpha values and global covariate effects on alpha and lambda

Usage

RK_project_alpha_pairwise_lambdacov_global_alphacov_global(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Ricker model for projecting abundances, with specific alpha values and global covariate effects on alpha and lambda

Usage

RK_project_alpha_pairwise_lambdacov_global_alphacov_pairwise(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

Ricker model for projecting abundances, with specific alpha values and no covariate effects

Usage

RK_project_alpha_pairwise_lambdacov_none_alphacov_none(
  lambda,
  alpha_intra,
  alpha_inter,
  lambda_cov,
  alpha_cov,
  abundance,
  covariates
)

Arguments

Value

numeric abundance projected one timestep

Description

A list containing salinity values associated to the data from 'neigh_list'. The list has 17 elements, one for each focal species considered. Each element of the list is a dataframe with 2 columns:

• obs_ID: unique identifier of each observation

• salinity: salinity measurement for that observation, in accumulated microsiemens/m2

Usage

data(salinity_list)

Format

A list with 17 elements, each of which a dataframe of variable number of rows and 2 numeric columns

Note

For details, see Lanuza et al. 2018 Ecology Letters.

Description

A dataset giving the spatial arrangement of observations. The dataset is a list of 16 elements following the structure of 'neigh_list'. Each list component is a dataframe with columns:

Usage

data(spatial_sampling)

Format

A list with 16 elements, each of which a dataframe of variable number of rows and 18 columns

Details

• obs_ID: unique identifier for each observation

• plot: one of 9 plots of 8.5 x 8.5 m

• subplot: one of 36 subplots of 1x1 m within each plot

Note

For details, see Lanuza et al. 2018 Ecology Letters.

Description

Calculates the fitness of a species sensu Godoy et al. (2014).Note that its definition is model-specific, i.e. it depends on the model family from which interaction coefficients were estimated. The function given here assumes a community of n-species, so that species fitness is calculated according to a general competitive response (r) substituting the 2-sp denominator terms of table A1 of Hart et al. 2018. This competitive response can be calculated for a series of species with the function 'cxr_er_fit'.

Usage

species_fitness(
  effect_response_fit = NULL,
  lambda = NULL,
  competitive_response = NULL,
  model_family = NULL
)

Arguments

Details

Thus, the function accepts two sets of parameters. First, a 'cxr_er_fit' object returned from that function. In this case, species fitness will be calculated for all focal taxa included in the 'cxr_er_fit' object.

Otherwise, users may enter a specification of the model to use, as well as lambda and competitive response parameters of a single species.

If no model family is provided, or a model family for which there is no associated 'XX_species_fitness' function, the function resorts to the standard Lotka-Volterra formulation (Hart et al. 2018). Overall, we strongly suggest that you use the standard formulation ONLY if you are completely confident that the model from which you obtained your parameters is consistent with it. Otherwise, you should include your own formulation of species fitness (see vignette 4).

Value

single numeric value/vector, species fitness of one or several taxa

Description

A dataset containing germination and survival rates for 17 plant species. It includes columns with the scientific names and their associated codes.

Usage

data(species_rates)

Format

A data frame with 17 rows and 4 variables

Details

• species: binomial name

• code: four-letter code used in other datasets

• germination: germination rate

• seed.survival: annual survival of ungerminated seed in the soil

Note

For details, see Lanuza et al. 2018 Ecology Letters.

Description

CXR summary method for effect response model fits

Usage

## S3 method for class 'cxr_er_fit'
summary(object, ...)

Arguments

Value

console output

Description

CXR summary method for population model fits

Usage

## S3 method for class 'cxr_pm_fit'
summary(object, ...)

Arguments

Value

console output

Description

CXR summary method for multispecies fits

Usage

## S3 method for class 'cxr_pm_multifit'
summary(object, ...)

Arguments

Value

console output

Description

this follows the vec-permutation approach as defined in: Hunter and Caswell 2005, doi:10.1016/j.ecolmodel.2005.05.002, Ozgul et al. 2009, doi: 10.1086/597225

Usage

vec_permutation_matrices(num.sp, num.sites, num.stages)

Arguments

Value

nested list, of the form 'list[[type]][[sp]]', where 'type' is demography, dispersal, or permutation.

Examples

# number of demographic stages - this should be always fixed to 3 for 
# compatibility with other functions
num.stages <- 3
num.sp <- 4
num.sites <- 5
vpm <- vec_permutation_matrices(num.sp,num.sites,num.stages)

Description

Calculates vital rates from their effect sizes and terms. This is equivalent to predicting from a binomial glm with given coefficients. In this version, the user needs to ensure that 'param' and 'env' match, i.e. that if the 'param' list is defined with environmental forcing, it is passed here, and viceversa. In future versions I may implement checks for that here, but for now, be aware that it will fail.

Usage

vital_rate(vr, sp, site, param, env = NULL, densities)

Arguments

Value

numeric value