trps: Bayesian Trophic Position Models using 'stan'

Description

Bayesian trophic position models using 'stan' by leveraging 'brms' for stable isotope data. Trophic position models are derived by using equations from Post (2002) doi:10.1890/0012-9658(2002)083[0703:USITET]2.0.CO;2, Vander Zanden and Vadeboncoeur (2002) doi:10.1890/0012-9658(2002)083[2152:FAIOBA]2.0.CO;2, and Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028.

Author(s)

Maintainer: Benjamin L. Hlina benjamin.hlina@gmail.com

See Also

Useful links:

• https://benjaminhlina.github.io/trps/

• https://github.com/benjaminhlina/trps

• Report bugs at https://github.com/benjaminhlina/trps/issues

Calculate and add \alpha

Description

Calculate \alpha for a two source trophic position model using equations from Post 2002.

Usage

add_alpha(data, abs = FALSE)

Arguments

Details

\alpha = (\delta^{13}C_c - \delta ^{13}C_2) / (\delta ^{13}C_1 - \delta ^{13}C_2)

where \delta^{13}C_c is the isotopic value for consumer, \delta^{13}C_1 is the mean isotopic value for baseline 1 and \delta^{13}C_2 is the mean isotopic value for baseline 2.

Value

a data.frame that has alpha, min_alpha, and max_alpha added.

Examples

combined_iso |>
  add_alpha()

Stable isotope data for amphipods (baseline 1)

Description

Stable isotope data (\delta^{13}C and \delta^{15}N) for amphipods collected from an ecoregion in Lake Ontario.

Usage

baseline_1_iso

Format

data.frame containing 14 rows and 5 variables

common_name

name of the spcies (i.e., Amphipoda)

ecoregion

ecoregion where samples were collected

d13c_b1

observed values for \delta^{13}C

d15n_b1

observed values for \delta^{15}N

Stable isotope data for dreissenids (baseline 2)

Description

Stable isotope data (\delta^{13}C and \delta^{15}N) for dreissenid collected from an ecoregion in Lake Ontario.

Usage

baseline_2_iso

Format

data.frame containing 12 rows and 5 variables

common_name

name of the spcies (i.e., Dreissenids)

ecoregion

ecoregion where samples were collected

d13c_b2

observed values for \delta^{13}C

d15n_b2

observed values for \delta^{15}N

Stable isotope data for lake trout, amphipods (benthic baseline; baseline 1) and dreissenids (pelagic baseline; baseline 2),

Description

Stable isotope data (\delta^{13}C and \delta ^{15}N) for lake trout collected from two ecoregions in Lake Ontario. Values of \delta ^{13}C and \delta ^{15}N for a benthic baseline (amphipods; baseline 1; d13c_b1 and d15n_b1) and pelagic baseline (dreissenids; baseline 2; d13c_b2 and d15n_b2) with the means for each baseline calculated (c1, n1, c2, and n2).

Usage

combined_iso

Format

data.frame containing 117 rows and 13 variables

id

row id number

common_name

name of the spcies (i.e., Lake Trout)

ecoregion

ecoregion where samples were collected

d13c

observed values for \delta^{13}C of consumer

d15n

observed values for \delta^{15}N of consumer

d13c_b1

observed values for \delta^{13}C of baseline 1

d15n_b1

observed values for \delta^{15}N of baseline 1

d13c_b2

observed values for \delta^{13}C of baseline 2

d15n_b2

observed values for \delta^{15}N of baseline 2

c1

mean values for \delta^{13}C of baseline 1

n1

mean values for \delta^{15}N of baseline 1

c2

mean values for \delta^{13}C of baseline 2

n2

mean values for \delta^{15}N of baseline 2

Stable isotope data for lake trout (consumer)

Description

Stable isotope data (\delta^{13}C and \delta^ {15}N) for lake trout collected from an ecoregion in Lake Ontario.

Usage

consumer_iso

Format

data.frame containing 30 rows and 6 variables

common_name

name of the spcies (i.e., Lake Trout)

ecoregion

ecoregion where samples were collected

d13c

observed values for \delta^{13}C

d15n

observed values for \delta^{15}N

Bayesian model - One Source Trophic Position

Description

Estimate trophic position using a one source model derived from Post 2002 using a Bayesian framework.

Usage

one_source_model(bp = FALSE)

Arguments

Details

\delta^{15}N = \delta^{15} N_1 + \Delta N \times (tp - \lambda_1)

\delta^{15}N are values from the consumer, \delta^{15} N_1 is mean \delta^{15}N values of baseline 1, \DeltaN is the trophic discrimination factor for N (i.e., dn mean of 3.4), tp is trophic position, and \lambda_1 is the trophic level of baselines which are often a primary consumer (e.g., 2).

The data supplied to brms() needs to have the following variables d15n, n1, and l1 (\lambda) which is usually 2.

Value

returns model structure for one source model to be used in a brms() call.

See Also

brms::brms()

Examples

one_source_model()

Bayesian priors - One Source Trophic Position

Description

Create priors for one source trophic position model derived from Post 2002.

Usage

one_source_priors(bp = FALSE)

Arguments

Value

returns priors for one source model to be used in a brms() call.

See Also

brms::brms()

Examples

one_source_priors()

Adjust Bayesian priors - One Source Trophic Position

Description

Adjust priors for one source trophic position model derived from Post 2002.

Usage

one_source_priors_params(
  n1 = NULL,
  n1_sigma = NULL,
  dn = NULL,
  dn_sigma = NULL,
  tp_lb = NULL,
  tp_ub = NULL,
  sigma_lb = NULL,
  sigma_ub = NULL,
  bp = FALSE
)

Arguments

Details

\delta^{15}N = \delta^{15} N_1 + \delta N \times (tp - \lambda_1)

This function allows the user to adjust the priors for the following variables in the equation above:

• The mean (n1; \mu) and variance (n1_sigma; \sigma) for the mean \delta^{15}N for a given baseline (\delta^{15}N_1). This prior assumes a normal distribution.

• The mean (dn; \mu) and variance (dn_sigma; \sigma) of \DeltaN (i.e, trophic enrichment factor). This prior assumes a normal distribution.

• The lower (tp_lb) and upper (tp_ub) bounds for trophic position. This prior assumes a uniform distribution.

• The lower (sigma_lb) and upper (sigma_ub) bounds for variance (\sigma). This prior assumes a uniform distribution.

Value

stanvars object to be used with brms() call.

See Also

one_source_priors(), one_source_model(), and brms::brms()

Examples

one_source_priors_params()

Bayesian model - Two Source Trophic Position

Description

Trophic position using a two source model derived from Post 2002 using a Bayesian framework.

Usage

two_source_model(bp = FALSE, lambda = NULL)

Arguments

Details

We will use the following equations from Post 2002:

1. \delta^{13}C_c = \alpha \times (\delta ^{13}C_1 - \delta ^{13}C_2) + \delta ^{13}C_2

2. \delta^{15}N = \Delta N \times (tp - \lambda_1) + n_1 \times \alpha + n_2 \times (1 - \alpha)

3. \delta^{15}N = \Delta N \times (tp - (\lambda_1 \times \alpha + \lambda_2 \times (1 - \alpha))) + n_1 \times \alpha + n_2 \times (1 - \alpha)

For equation 1)

where \delta^{13}C_c is the isotopic value for consumer, \alpha is the ratio between baselines and consumer \delta^{13}C, \delta^{13}C_1 is the mean isotopic value for baseline 1, and \delta^{13}C_2 is the mean isotopic value for baseline 2

For equation 2) and 3)

\delta^{15}N are values from the consumer, n_1 is \delta^{15}N values of baseline 1, n_2 is \delta^{15}N values of baseline 2, \DeltaN is the trophic discrimination factor for N (i.e., mean of 3.4), tp is trophic position, and \lambda_1 and/or \lambda_2 are the trophic levels of baselines which are often a primary consumer (e.g., 2 or 2.5).

The data supplied to brms() when using baselines at the same trophic level (lambda argument set to 1) needs to have the following variables, d15n, c1, c2, n1, n2, l1 (\lambda_1) which is usually 2. If using baselines at different trophic levels (lambda argument set to 2) the data frame needs to have l1 and l2 with a numerical value for each trophic level (e.g.,2 and 2.5; \lambda_1 and \lambda_2).

Value

returns model structure for two source model to be used in a brms() call.

See Also

brms::brms()

Examples

two_source_model()

Bayesian model - Two Source Trophic Position with \alpha_r

Description

Estimate trophic position using a two source model with \alpha_r derived from Post 2002 and Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028 using a Bayesian framework.

Usage

two_source_model_ar(bp = FALSE, lambda = NULL)

Arguments

Details

We will use the following equations derived from Post 2002 and Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028:

1. \alpha = (\delta^{13} C_c - \delta ^{13}C_2) / (\delta ^{13}C_1 - \delta ^{13}C_2)

2. \alpha = \alpha_r \times (\alpha_{max} - \alpha_{min}) + \alpha_{min}

3. \delta^{15}N = \Delta N \times (tp - \lambda_1) + n_1 \times \alpha_r + n_2 \times (1 - \alpha_r)

4. \delta^{15}N = \Delta N \times (tp - (\lambda_1 \times \alpha_r + \lambda_2 \times (1 - \alpha_r))) + n_1 \times \alpha_r + n_2 \times (1 - \alpha_r)

For equation 1)

This equation is a carbon source mixing model with \delta^{13}C_c is the isotopic value for consumer, \delta^{13}C_1 is the mean isotopic value for baseline 1 and \delta^{13}C_2 is the mean isotopic value for baseline 2. This equation is added to the data frame using add_alpha().

For equation 2)

\alpha is being corrected using equations in Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028 with \alpha_r being the corrected value (bound by 0 and 1), \alpha_{min} is the minimum \alpha value calculated using add_alpha() and \alpha_{max} being the maximum \alpha value calculated using add_alpha().

For equation 3) and 4)

\delta^{15}N are values from the consumer, n_1 is \delta^{15}N values of baseline 1, n_2 is \delta^{15}N values of baseline 2, \DeltaN is the trophic discrimination factor for N (i.e., mean of 3.4), tp is trophic position, and \lambda_1 and/or \lambda_2 are the trophic levels of baselines which are often a primary consumer (e.g., 2 or 2.5).

The data supplied to brms() when using baselines at the same trophic level (lambda argument set to 1) needs to have the following variables, d15n, n1, n2, l1 (\lambda_1) which is usually 2. If using baselines at different trophic levels (lambda argument set to 2) the data frame needs to have l1 and l2 with a numerical value for each trophic level (e.g., 2 and 2.5; \lambda_1 and \lambda_2).

Value

returns model structure for two source model to be used in a brms() call.

See Also

brms::brms()

Examples

two_source_model_ar()

Bayesian model - Two Source Trophic Position with \alpha_r and carbon mixing model

Description

Estimate trophic position using a two source model with \alpha_r derived from Post 2002 and Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028 using a Bayesian framework.

Usage

two_source_model_arc(bp = FALSE, lambda = NULL)

Arguments

Details

We will use the following equations derived from Post 2002 and Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028:

1. \alpha = (\delta^{13} C_c - \delta ^{13}C_2) / (\delta ^{13}C_1 - \delta ^{13}C_2)

2. \alpha = \alpha_r \times (\alpha_{max} - \alpha_{min}) + \alpha_{min}

3. \delta^{13}C = c_1 \times \alpha_c + c_2 \times (1 - \alpha_c)

4. \delta^{15}N = \Delta N \times (tp - \lambda_1) + n_1 \times \alpha_c + n_2 \times (1 - \alpha_c)

5. \delta^{15}N = \Delta N \times (tp - (\lambda_1 \times \alpha_c + \lambda_2 \times (1 - \alpha_c))) + n_1 \times \alpha_c + n_2 \times (1 - \alpha_c)

For equation 1)

This equation is a carbon source mixing model with \delta^{13}C_c is the isotopic value for consumer, \delta^{13}C_1 is the mean isotopic value for baseline 1 and \delta^{13}C_2 is the mean isotopic value for baseline 2.

For equation 2)

\alpha is being corrected using equations in Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028. with \alpha_r being the corrected value (bound by 0 and 1), \alpha_{min} is the minimum \alpha value calculated using add_alpha() and \alpha_{max} being the maximum \alpha value calculated using add_alpha().

For equation 3)

This equation is a carbon source mixing model with \delta^{13}C being estimated using c_1, c_2 and \alpha_c calculated in equation 1.

For equation 4) and 5)

\delta^{15}N are values from the consumer, n_1 is \delta^{15}N values of baseline 1, n_2 is \delta^{15}N values of baseline 2, \DeltaN is the trophic discrimination factor for N (i.e., mean of 3.4), tp is trophic position, and \lambda_1 and/or \lambda_2 are the trophic levels of baselines which are often a primary consumer (e.g., 2 or 2.5).

The data supplied to brms() when using baselines at the same trophic level (lambda argument set to 1) needs to have the following variables, d15n, n1, n2, l1 (\lambda_1) which is usually 2. If using baselines at different trophic levels (lambda argument set to 2) the data frame needs to have l1 and l2 with a numerical value for each trophic level (e.g., 2 and 2.5; \lambda_1 and \lambda_2).

Value

returns model structure for two source model to be used in a brms() call.

See Also

brms::brms()

Examples

two_source_model_arc()

Bayesian priors - Two Source Trophic Position

Description

Create priors for two source trophic position model derived from Post 2002.

Usage

two_source_priors(bp = FALSE)

Arguments

Value

returns priors for two source model to be used in a brms() call.

See Also

two_source_model() and brms::brms()

Examples

two_source_priors()

Bayesian priors - Two Source Trophic Position with \alpha_r

Description

Create priors for trophic position using a two source model with \alpha_r derived from Post 2002 and Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028.

Usage

two_source_priors_ar(bp = FALSE)

Arguments

Value

returns priors for two source model to be used in a brms() call.

See Also

brms::brms()

Examples

two_source_priors_ar()

Bayesian priors - Two Source Trophic Position with \alpha_r and carbon mixing model

Description

Create priors for trophic position using a two source model with \alpha_r derived from Post 2002 and Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028.

Usage

two_source_priors_arc(bp = FALSE)

Arguments

Value

returns priors for two source model to be used in a brms() call.

See Also

brms::brms()

Examples

two_source_priors_arc()

Adjust Bayesian priors - Two Source Trophic Position

Description

Adjust priors for two source trophic position model derived from Post 2002.

Usage

two_source_priors_params(
  a = NULL,
  b = NULL,
  c1 = NULL,
  c1_sigma = NULL,
  c2 = NULL,
  c2_sigma = NULL,
  n1 = NULL,
  n1_sigma = NULL,
  n2 = NULL,
  n2_sigma = NULL,
  dn = NULL,
  dn_sigma = NULL,
  tp_lb = NULL,
  tp_ub = NULL,
  sigma_lb = NULL,
  sigma_ub = NULL,
  bp = FALSE
)

Arguments

Details

We will use the following equations from Post 2002:

1. \delta^{13}C_c = \alpha * (\delta ^{13}C_1 - \delta ^{13}C_2) + \delta ^{13}C_2

2. \delta^{15}N = \Delta N \times (tp - \lambda_1) + n_1 \times \alpha + n_2 \times (1 - \alpha)

3. \delta^{15}N = \Delta N \times (tp - (\lambda_1 \times \alpha + \lambda_2 \times (1 - \alpha))) + n_1 \times \alpha + n_2 \times (1 - \alpha)

• The random exponent (\alpha; a) and shape parameters (\beta; b) for \alpha. This prior assumes a beta distribution.

• The mean (c1; \mu) and variance (c1_sigma; \sigma) of the mean for the first \delta^{13}C for a given baseline. This prior assumes a normal distributions.

• The mean (c2;\mu) and variance (c2_sigma; \sigma) of the mean for the second \delta^{13}C for a given baseline. This prior assumes a normal distributions.

• The mean (n1; \mu) and variance (n1_sigma; \sigma) of the mean for the first \delta^{15}N for a given baseline. This prior assumes a normal distributions.

• The mean (n2;\mu) and variance (n2_sigma; \sigma) of the mean for the second \delta^{15}N for a given baseline. This prior assumes a normal distributions.

• The mean (dn; \mu) and variance (dn_sigma; \sigma) of \DeltaN (i.e, trophic enrichment factor). This prior assumes a normal distributions.

• The lower (tp_lb) and upper (tp_ub) bounds for priors for trophic position. This prior assumes a uniform distributions.

• The lower (sigma_lb) and upper (sigma_ub) bounds for variance (\sigma). This prior assumes a uniform distributions.

Value

stanvars object to be used with brms() call.

See Also

two_source_priors(), two_source_model(), and brms::brms()

Examples

two_source_priors_params()

Adjust Bayesian priors - Two Source Trophic Position with \alpha_r

Description

Create priors for trophic position using a two source model with \alpha_r derived from Post 2002 and Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028.

Usage

two_source_priors_params_ar(
  a = NULL,
  b = NULL,
  n1 = NULL,
  n1_sigma = NULL,
  n2 = NULL,
  n2_sigma = NULL,
  dn = NULL,
  dn_sigma = NULL,
  tp_lb = NULL,
  tp_ub = NULL,
  sigma_lb = NULL,
  sigma_ub = NULL,
  bp = FALSE
)

Arguments

Details

We will use the following equations derived from Post 2002 and Heuvel et al. (2024 doi:10.1139/cjfas-2024-0028):

1. \alpha = (\delta^{13} C_c - \delta ^{13}C_2) / (\delta ^{13}C_1 - \delta ^{13}C_2)

2. \alpha = \alpha_r \times (\alpha_{max} - \alpha_{min}) + \alpha_{min}

3. \delta^{15}N = \Delta N \times (tp - \lambda_1) + n_1 \times \alpha_r + n_2 \times (1 - \alpha_r)

4. \delta^{15}N = \Delta N \times (tp - (\lambda_1 \times \alpha_r + \lambda_2 \times (1 - \alpha_r))) + n_1 \times \alpha_r + n_2 \times (1 - \alpha_r)

For equation 1)

This equation is a carbon source mixing model with \delta^{13}C_c is the isotopic value for consumer, \delta^{13}C_1 is the mean isotopic value for baseline 1 and \delta^{13}C_2 is the mean isotopic value for baseline 2. This equation is added to the data frame using add_alpha().

For equation 2)

\alpha is being corrected using equations in Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028 with \alpha_r being the corrected value (bound by 0 and 1), \alpha_{min} is the minimum \alpha value calculated using add_alpha() and \alpha_{max} being the maximum \alpha value calculated using add_alpha().

For equation 3) and 4)

\delta^{15}N are values from the consumer, n_1 is \delta^{15}N values of baseline 1, n_2 is \delta^{15}N values of baseline 2, \DeltaN is the trophic discrimination factor for N (i.e., mean of 3.4), tp is trophic position, and \lambda_1 and/or \lambda_2 are the trophic levels of baselines which are often a primary consumer (e.g., 2 or 2.5).

This function allows the user to adjust the priors for the following variables in the equation above:

• The random exponent (\alpha; a) and shape parameters (\beta; b) for \alpha_r. This prior assumes a beta distribution.

• The mean (n2;\mu) and variance (n2_sigma; \sigma) of the second \delta^{15}N for a given baseline. This prior assumes a normal distributions.

• The mean (c1;\mu) and variance (c1_sigma; \sigma) of the second \delta^{13}C for a given baseline. This prior assumes a normal distributions.

• The mean (c2;\mu) and variance (c2_sigma; \sigma) of the second \delta^{13}C for a given baseline. This prior assumes a normal distributions.

• The mean (dn; \mu) and variance (dn_sigma; \sigma) of \DeltaN (i.e, trophic enrichment factor). This prior assumes a normal distributions.

• The lower (tp_lb) and upper (tp_ub) bounds for priors for trophic position. This prior assumes a uniform distributions.

• The lower (sigma_lb) and upper (sigma_ub) bounds for variance (\sigma). This prior assumes a uniform distributions.

Value

stanvars object to be used with brms() call.

See Also

two_source_priors_ar(), two_source_model_ar(), and brms::brms()

Examples

two_source_priors_params_ar()

Adjust Bayesian priors - Two Source Trophic Position with \alpha_r and carbon mixing model

Description

Adjust priors for trophic position using a two source model with \alpha_r derived from Post 2002 and Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028

Usage

two_source_priors_params_arc(
  a = NULL,
  b = NULL,
  n1 = NULL,
  n1_sigma = NULL,
  n2 = NULL,
  n2_sigma = NULL,
  c1 = NULL,
  c1_sigma = NULL,
  c2 = NULL,
  c2_sigma = NULL,
  dn = NULL,
  dn_sigma = NULL,
  tp_lb = NULL,
  tp_ub = NULL,
  sigma_lb = NULL,
  sigma_ub = NULL,
  bp = FALSE
)

Arguments

Details

We will use the following equations derived from Post 2002 and Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028:

1. \alpha = (\delta^{13} C_c - \delta ^{13}C_2) / (\delta ^{13}C_1 - \delta ^{13}C_2)

2. \alpha = \alpha_r \times (\alpha_{max} - \alpha_{min}) + \alpha_{min}

3. \delta^{13}C = c_1 \times \alpha_r + c_2 \times (1 - \alpha_r)

4. \delta^{15}N = \Delta N \times (tp - \lambda_1) + n_1 \times \alpha_r + n_2 \times (1 - \alpha_r)

5. \delta^{15}N = \Delta N \times (tp - (\lambda_1 \times \alpha_r + \lambda_2 \times (1 - \alpha_r))) + n_1 \times \alpha_r + n_2 \times (1 - \alpha_r)

For equation 1)

This equation is a carbon source mixing model with \delta^{13}C_c is the isotopic value for consumer, \delta^{13}C_1 is the mean isotopic value for baseline 1 and \delta^{13}C_2 is the mean isotopic value for baseline 2.

For equation 2)

\alpha is being corrected using equations in Heuvel et al. (2024) doi:10.1139/cjfas-2024-0028. with \alpha_r being the corrected value (bound by 0 and 1), \alpha_{min} is the minimum \alpha value calculated using add_alpha() and \alpha_{max} being the maximum \alpha value calculated using add_alpha().

For equation 3)

This equation is a carbon source mixing model with \delta^{13}C being estimated using c_1, c_2 and \alpha_r calculated in equation 1.

For equation 4) and 5)

\delta^{15}N are values from the consumer, n_1 is \delta^{15}N values of baseline 1, n_2 is \delta^{15}N values of baseline 2, \DeltaN is the trophic discrimination factor for N (i.e., mean of 3.4), tp is trophic position, and \lambda_1 and/or \lambda_2 are the trophic levels of baselines which are often a primary consumer (e.g., 2 or 2.5).

This function allows the user to adjust the priors for the following variables in the equation above:

• The random exponent (\alpha; a) and shape parameters (\beta; b) for \alpha_r. This prior assumes a beta distribution.

• The mean (n2;\mu) and variance (n2_sigma; \sigma) of the second \delta^{15}N for a given baseline. This prior assumes a normal distributions.

• The mean (c1;\mu) and variance (c1_sigma; \sigma) of the second \delta^{13}C for a given baseline. This prior assumes a normal distributions.

• The mean (c2;\mu) and variance (c2_sigma; \sigma) of the second \delta^{13}C for a given baseline. This prior assumes a normal distributions.

• The mean (dn; \mu) and variance (dn_sigma; \sigma) of \DeltaN (i.e, trophic enrichment factor). This prior assumes a normal distributions.

• The lower (tp_lb) and upper (tp_ub) bounds for priors for trophic position. This prior assumes a uniform distributions.

• The lower (sigma_lb) and upper (sigma_ub) bounds for variance (\sigma). This prior assumes a uniform distributions.

Value

stanvars object to be used with brms() call.

See Also

two_source_priors_arc(), two_source_model_arc(), and brms::brms()

Examples

two_source_priors_params_ar()