Package 'alien'

Plot log-likelihood space

Description

Plot a filled-contour heatmap displaying the log-likelihood space calculated using likelihood_space.

Usage

likelihood_map(likelihood_space, x, y, delta = 10)

Arguments

likelihood_space	a data frame resulting from a call to likelihood_space, where columns represent parameter values and an extra column log_likelihoods with the corresponding log-likelihood for each parameter value combination.
x	a string specifying the parameter to be plotted on the x-axis.
y	a string specifying the parameter to be plotted on the y-axis.
delta	the range of log-likelihood values of which different color codes will be plotted. Defaults to 10.

Value

#' A ggplot plot with the corresponding type of plot.

Examples

if (FALSE){ # takes a while to finish
example_model <- snc(sfestuary)
estimates <- example_model$coefficients$Estimate

likelihood_space <- likelihood_space(y = sfestuary, centers = estimates,
                                     ranges = 1.5, steps_from_center = 10,
                                     calculate = TRUE)

likelihood_map(likelihood_space, "beta0", "beta1", 10)
 }

---

Calculate log-likelihood space for a given time series and data

Description

This function allows to calculate the log-likelihood values for a given set of parameter values. It can be used for diagnostics of the likelihood space and check - among others - for parameter contribution to log-likelihood. passing FALSE for the calculate argument allows to experiment with different parameter values sets before calculating their log-likelihoods. Please note: This functions may take a lot of time, depending on the number of parameters, and steps!

Usage

likelihood_space(
  y,
  mu = NULL,
  pi = NULL,
  data = NULL,
  growth = TRUE,
  type = "exponential",
  centers,
  ranges,
  steps_from_centers,
  calculate = TRUE
)

Arguments

y	either a vector describing the number of discovered alien and invasive species (IAS) over a given time period, or the name (quoted or unquoted) of the corresponding column in the provided data.
mu	a formula defining the predictors for $\mu_t$, the annual introduction rate. Formulas should be provided in the syntax ~ x1 + x2 + ... + xn. Use ~ 1 for an intercept only model.
pi	a formula defining the predictors for $\Pi_{st}$, the annual probability of detection. Formulas should be provided in the syntax ~ x1 + x2 + ... + xn. Use ~ 1 for an intercept only model.
data	a data frame containing the variables in the model(s).
growth	logical. Should the population growth parameter $\gamma_2$ be included in the model for $\Pi_{st}$?. Note that values for init, if provided, need to include an initial value for the growth parameter, when growth = TRUE.
type	Define whether the mu function should be on "linear" or "exponential" scale. Defaults to "exponential".
centers	the values used as the center-points for the parameter values. Usually the maximum likelihood estimation from a call to snc. Length should be either 1 or correspond to number of parameters (including the growth parameter).
ranges	the range of the parameter values in term of the center. The values will be withing center - (center * range) and center + (center * range). Length should be either 1 or correspond to number of parameters (including the growth parameter).
steps_from_centers	How many values in the range between center and center + (center * range) should be included in the set. Length should be either 1 or correspond to number of parameters (including the growth parameter).
calculate	Whether to calculate the log-likelihoods (TRUE) or just view the parameter values (FALSE).

Value

A data frame containing the parameter values, and if calculate = TRUE including the log-likelihood values for each parameter combination.

Examples

if (FALSE){ # this takes a while...
example_model <- snc(sfestuary)
estimates <- example_model$coefficients$Estimate

likelihood_space <- likelihood_space(y = sfestuary, centers = estimates,
                                     ranges = 1.5, steps_from_center = 10,
                                     calculate = TRUE)

# with specified formula:
example_buba <- snc(y = aliens, pi = ~ natives, data = medfish)
estimates <- example_buba$coefficients$Estimate

likelihood_space <- likelihood_space(y = aliens, pi = ~ natives,
                                     data = medfish, centers = estimates,
                                     ranges = 1.5, steps_from_center = 10,
                                     calculate = TRUE)
 }

---

Discoveries Of Native And Alien Fish Species In The Eastern Mediterranean Sea

Description

The updated data used in Belmaker et al (2009) describing discoveries of native and alien species in the Mediterranean Sea between the years 1927–2017. The original data is described in full in Golani (2005); see also Golani (2021) for the updated version used here.

Usage

medfish

Format

A data frame with 60 rows and 4 columns:

year

Year of record

time

Time since the first record in the records data

natives

Number of newly recorded native species in corresponding year

aliens

Number of newly recorded alien species in corresponding year

Source

https://esajournals.onlinelibrary.wiley.com/doi/abs/10.1890/07-1904.1

https://www.mapress.com/zt/article/view/zootaxa.4956.1.1

References

Golani, D. 2005. Checklist of the Mediterranean Fishes of Israel. Zootaxa, 947, 1-90. https://mapress.com/zt/article/view/zootaxa.947.1.1

Belmaker, J., Brokovich, E., China, V., Golani, D., and Kiflawi, M. 2009. Estimating the rate of biological introductions: Lessepsian fishes in the Mediterranean. Ecology, 90(4), 1134–1141. https://esajournals.onlinelibrary.wiley.com/doi/10.1890/07-1904.1

Golani, D. 2021. An updated Checklist of the Mediterranean fishes of Israel, with illustrations of recently recorded species and delineation of Lessepsian migrants. Zootaxa, 4956, 1-108. https://www.mapress.com/zt/article/view/zootaxa.4956.1.1

---

Plot an introduction record and the fitted model values

Description

Plot an introduction record and the fitted model values

Usage

plot_snc(object, cumulative = FALSE)

Arguments

object	an object of class "snc", usually a result of a call to snc
cumulative	logical - should plot be annual or cumulative number of IAS.

Value

A ggplot plot with the corresponding type of plot.

Examples

data(sfestuary)
example_model <- snc(sfestuary)
plot_snc(example_model, cumulative = TRUE)

---

Discoveries Of Introduced Species In The San Francisco Estuary (California, USA)

Description

The data provided by Solow and Costello (2004) describing discoveries of introduced species in the San Francisco estuary (California, USA) between the years 1850–1995. These data were compiled by Cohen and Carlton (1995); see also Cohen and Carlton (1998).

The original data in PDF format is described in full in Cohen and Carlton (1995) and can be viewed here: https://repository.library.noaa.gov/view/noaa/40918

Usage

sfestuary

Format

An object of class integer of length 145.

Source

https://esajournals.onlinelibrary.wiley.com/doi/abs/10.1890/03-3102

https://repository.library.noaa.gov/view/noaa/40918

References

Cohen, A. N., and J. T. Carlton. 1995. Nonindigenous aquatic species in a United States estuary: a case study of the biological invasions of the San Francisco Bay and Delta. U.S. Fish and Wildlife Service, Washington, D.C., USA. https://repository.library.noaa.gov/view/noaa/40918

Cohen, A. N., and J. T. Carlton. 1998. Accelerating invasion rate in a highly invaded estuary. Science 279: 555– 558. https://www.science.org/doi/10.1126/science.279.5350.555

Solow, A. R., and Costello, C. J. 2004. Estimating the rate of species introductions from the discovery record. Ecology, 85(7), 1822–1825. https://esajournals.onlinelibrary.wiley.com/doi/abs/10.1890/03-3102

---

Fit a model to discovery records

Description

Fit a model to a time series describing first records of alien species. If no external data is provided, the function fits the model described in Solow and Costello (2004). When external data on either $\mu_t$ or $\Pi_{st}$ is provided, the function fits the modified model (sampling-proxy model in the case of $\Pi_{st}$) as described in Buba et al (2024).

Usage

snc(
  y,
  mu = NULL,
  pi = NULL,
  data = NULL,
  init = NULL,
  growth = TRUE,
  type = "exponential",
  ...
)

Arguments

y	either a vector describing the number of discovered alien and invasive species (IAS) over a given time period, or the name (quoted or unquoted) of the corresponding column in the provided data.
mu	a formula defining the predictors for $\mu_t$, the annual introduction rate. Formulas should be provided in the syntax ~ x1 + x2 + ... + xn. Use ~ 1 for an intercept only model.
pi	a formula defining the predictors for $\Pi_{st}$, the annual probability of detection. Formulas should be provided in the syntax ~ x1 + x2 + ... + xn. Use ~ 1 for an intercept only model.
data	a data frame containing the variables in the model(s).
init	Optional. Initial values supplied to optim. Must be same length as the total number of parameters.
growth	logical. Should the population growth parameter $\gamma_2$ be included in the model for $\Pi_{st}$?. Note that values for init, if provided, need to include an initial value for the growth parameter, when growth = TRUE.
type	Define whether the mu function should be on "linear" or "exponential" scale. Defaults to "exponential".
...	Further arguments passed to optim.

Details

This function expands on the model described in Solow and Costello (2004) by facilitating the inclusion of external data to describe either introduction rate $\mu_t$ or detection probability $\Pi_{st}$. The model with external data for detection probability (sampling-proxy model) is described fully in Buba et al (2024). The use of external data to describe the introduction rate has not been thoroughly evaluated. When no formula is defined for either, the function automatically fits the original Solow and Costello (2004) model using the length of the vector data as the independent variable $t$. All models return estimated parameters for both the introduction rate and the detection probability, with the parameter of interest usually being the change of introduction rate - $\beta_1$. For more details see the Basic Usage vignette: vignette("basic_usage", package = "alien")

Value

snc returns an object of class "snc" containing:

records	the supplied first records data
convergence	the optim convergence code.
log-likelihood	the maximum log-likelihood.
coefficients	a named vector of the ML estimates of the coefficients.
fitted.values	the fitted mean $\lambda$ values.
predict	a data frame containing the estimated mean +- Standard error $\mu$ values.

References

Solow, A. R., & Costello, C. J. (2004). Estimating the rate of species introductions from the discovery record. Ecology, 85(7), 1822–1825. https://doi.org/10.1890/03-3102

Buba, Y., Kiflwai, M., McGeoch, M. A., Belmaker, J. (2024) Evaluating models for estimating introduction rates of alien species from discovery records. https://doi.org/10.1111/geb.13859

Examples

# Solow and Costello (2004) model:
data(sfestuary)
example_model <- snc(sfestuary)
print(example_model)

# Buba et al (2024) sampling-proxy model:
data(medfish)
example_buba <- snc(y = aliens, pi = ~ natives, data = medfish)
print(example_buba)

---

Summarize a Solow and Costello Model Fit

Description

Summarize a Solow and Costello Model Fit

Usage

summary_snc(object)

Arguments

object

an object of class "snc", usually a result of a call to snc

Value

A data.frame containing the model estimates, standard error, and the probability of the true value being 0 under the given estimates and errors.

Examples

data(sfestuary)
example_model <- snc(sfestuary)
summary(example_model)

---