| Title: | Tools for Modeling Bumblebee Colony Growth and Decline |
| Version: | 1.0.4 |
| Description: | Bumblebee colonies grow during worker production, then decline after switching to production of reproductive individuals (drones and gynes). This package provides tools for modeling and visualizing this pattern by identifying a switchpoint with a growth rate before and a decline rate after the switchpoint. The mathematical models fit by bumbl are described in Crone and Williams (2016) <doi:10.1111/ele.12581>. |
| License: | MIT + file LICENSE |
| URL: | https://github.com/Aariq/bumbl |
| BugReports: | https://github.com/Aariq/bumbl/issues |
| Depends: | R (≥ 3.0) |
| Imports: | broom, dplyr, ggplot2, glue, lifecycle, MASS, purrr, rlang,tidyr (≥ 1.0.0) |
| Suggests: | car, covr, knitr, rmarkdown, rsq, testthat (≥ 2.1.0) |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| Encoding: | UTF-8 |
| LazyData: | true |
| RoxygenNote: | 7.3.2 |
| NeedsCompilation: | no |
| Packaged: | 2025-07-29 19:00:22 UTC; ericscott |
| Author: | Eric R. Scott [aut, cre] |
| Maintainer: | Eric R. Scott <scottericr@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2025-07-29 19:20:22 UTC |
bumbl: Tools for Modeling Bumblebee Colony Growth and Decline
Description
Bumblebee colonies grow during worker production, then decline after switching to production of reproductive individuals (drones and gynes). This package provides tools for modeling and visualizing this pattern by identifying a switchpoint with a growth rate before and a decline rate after the switchpoint. The mathematical models fit by bumbl are described in Crone and Williams (2016)doi:10.1111/ele.12581.
Author(s)
Maintainer: Eric R. Scottscottericr@gmail.com (ORCID)
See Also
Useful links:
Plot observed and fitted results from bumbl()
Description
Plots observed (points) and fitted (red line) values from the model implemented bybumbl(), faceted by colony.
Usage
## S3 method for class 'bumbldf'autoplot(object, ..., colony = NULL, x = deprecated())Arguments
object | a dataframe produced by |
... | other arguments passed to |
colony | a character vector of colony IDs to plot |
x |
|
![[Deprecated]](/image.pl?url=http%3a%2f%2fcran.rstudio.com%2fweb%2fpackages%2fRsolnp%2f..%2fRcpp%2f..%2fjSDM%2f..%2fggplot2%2f..%2fbumbl%2frefman%2f.%2ffigures%2flifecycle-deprecated.svg&f=jpg&w=240)
Value
invisibly returns a ggplot object
Examples
bombus_subset <- bombus[bombus$colony %in% c("17", "104", "20", "24"), ]results <- bumbl(bombus_subset, colonyID = colony, t = week, formula = mass ~ week)library(ggplot2)autoplot(results)Bombus vosnesenskii colony growth and estimated floral resources
Description
This is a subset of the data from Crone and Williams, 2016.Bombusvosnesenskii colonies were placed in sites in a mixed agricultural–naturalarea in California, USA and weighed weekly.
Usage
bombusFormat
A data frame with 178 rows and 10 columns
- site
The site ID
- colony
The colony ID
- wild
The proportion of the habitat for that site classified as wild using GIS
- habitat
The habitat type. Either wild (W), organic agriculture (O),or conventional agriculture (C)
- date
The calendar date the measurements were taken on
- week
Number of weeks since the initial mass was taken
- mass
Colony mass, in grams
- d.mass
Difference in mass from the smallest mass for each colony, in grams
- floral_resources
Floral density in millions of flowers within a 2kmradius around the colony, weighted as a function of distance from colony
- cum_floral
Cumulative floral resources from the start of the study
Details
Floral resources (e) are weighted using the equationw =e^(-D/a) whereD is the distance in meters between the resources andthe colony anda is the typical flight distance for the species. This isdescribed in further detail in Williams et al. 2012.
References
Crone, E. E., and Williams, N. M. (2016). Bumble bee colony dynamics:quantifying the importance of land use and floral resources for colony growthand queen production. Ecol. Lett. 19, 460–468. doi:10.1111/ele.12581.
Williams, N. M., Regetz, J., and Kremen, C. (2012). Landscape-scale resourcespromote colony growth but not reproductive performance of bumble bees.Ecology 93, 1049–1058. doi:10.1890/11-1006.1.
Fit breakpoint model to individual colony
Description
Fits models using a range of taus and picks the best one using maximumlikelihood. Typically only used internally bybumbl().
Usage
brkpt( data, t, formula, family = gaussian(link = "log"), tau_optim_maxit = 100, ...)Arguments
data | a dataframe or tibble |
t | the unquoted column name for the time variable in |
formula | a formula passed to |
family | a description of the error distribution and link function.This is passed to |
tau_optim_maxit | passed to |
... | additional arguments passed to |
Value
a tibble with a column for the winning tau and a column for thewinning model
See Also
Estimate colony growth, switch point, and decay parameters
Description
Fits generalized linear models that assume bumblebee colonies will switchfrom growth to gyne production at some point,\tau. This allows for adifferent switchpoint (\tau) for each colony, chosen by maximumlikelihood methods.
Usage
bumbl( data, t, formula, family = gaussian(link = "log"), colonyID = NULL, augment = FALSE, keep.model = FALSE, tau_optim_maxit = 100, ...)Arguments
data | a dataframe or tibble with a column for colony ID (as a |
t | the unquoted column name of the time variable. |
formula | a formula with the form |
family | a description of the error distribution and link function.This is passed to |
colonyID | the unquoted column name of the colony ID variable. This isrequired, so to run |
augment | when FALSE, |
keep.model | If TRUE, then the output will contain a list-column withthe models for each colony. This may be useful for extracting statisticsand performing model diagnostics not provided by |
tau_optim_maxit | passed to |
... | additional arguments passed to |
Details
Colony growth is modeled as increasing exponentially until thecolony switches from producing workers to producing reproductiveindividuals (drones and gynes), at which time the workers die and gynesleave the colony, causing the colony to decline. The switch point,\tau, may vary among colonies.bumbl() finds the value of\tau that maximizes likelihood and this "winning" model is used tocalculate statistics returned in the output. This function works by fittinggeneralized linear models (GLMs) to modified colony growth data. Because ofthis, the assumptions for GLMs apply, namely independence and homogeneityof variance. Seevignette("bumbl", package = "bumbl") for more details onthe underlying math of the model.
Value
Adata.frame with the additional classbumbldf containing asummary of the data with a row for every colony and the following columns:
convergedindicates whether the winning model converged.tauis the switchpoint, in the same units ast, foreachcolonyID. The colony grows for\tauweeks, then begins todecline in week\tau + 1.logN0is the intercept of thegrowth function. It reflects actual initial colony size, if the colonyinitially grows exponentially. It would also be lower if there were a fewweeks lag before growth started in the field.logLamis theaverage (log-scale) colony growth rate (i.e., rate of weight gain per unitt) during the growth period.decayreflects the rate of decline during the decline period.Equivalent to ln(\delta) - ln(\lambda) (see vignette for morein-depth explanation).logNmaxis the maximum weight reached by each colony. It is afunction oftau,logN0andlogLamAdditional columns arecoefficients for any covariates supplied in the
formula
Whenaugment = TRUE, the original data are returned with these columns aswell as fitted values (.fitted) residuals (.resid) and standard error(.se.fit). Whenkeep.model = TRUE a list-column with theglm modelsfor each colony is returned as well.
Note
This functionassumes there is a switchpoint and does not testwhether the switchpoint model is significantly better than a log-linearmodel. As a result, it may estimate a switchpoint even if the data do notrepresent a true switchpoint. See the vignette for an example of how toextract the GLMs—you could compare them to a simpler log-linear modelwithout the switchpoint by AIC or a likelihood ratio test to test thesignificance of the switchpoint.
References
Crone EE, Williams NM (2016) Bumble bee colony dynamics:quantifying the importance of land use and floral resources for colonygrowth and queen production. Ecology Letters 19:460–468.https://doi.org/10.1111/ele.12581
See Also
Examples
bumbl(bombus, colonyID = colony, t = week, formula = d.mass ~ week)Plot observed and fitted results from bumbl()
Description
Creates one plot per level of colonyID showing the observed (points) and fitted (red line) values from the model implemented bybumbl().
Usage
## S3 method for class 'bumbldf'plot(x, ..., colony = NULL)Arguments
x | a dataframe produced by |
... | other arguments not used by this method. |
colony | optional vector of colony ID's (character) or indexes (numeric) to plot. If not supplied, all colonies will be plotted. |
Value
invisibly returns a list of dataframes used for building the plots.
See Also
Examples
set.seed(687)colonyID_subset <- sample(bombus$colony, 10)colony_subset <- bombus[bombus$colony %in% colonyID_subset, ]results <- bumbl(colony_subset, colonyID = colony, t = week, formula = mass ~ week)plot(results)Simulated colony growth data for internal tests
Description
Simulated data including two colonies (6 and 7) that should always cause errors forbumbl()
Usage
test_dfFormat
An object of classtbl_df (inherits fromtbl,data.frame) with 140 rows and 4 columns.
Details
Colonies 1-5 are generated withsim_colony() using the following parameters:
| colony | tau | n0 | lambda | delta |
| 1 | 11.0 | 30 | 1.42 | 0.30 |
| 2 | 11.5 | 24 | 1.35 | 0.31 |
| 3 | 9.0 | 49 | 1.40 | 0.29 |
| 4 | 12.0 | 37 | 1.34 | 0.48 |
| 5 | 10.6 | 29 | 1.37 | 0.32 |
Colonies 6 and 7 are generated manually. Colony 6 contains negative numbersand should result in the warning "Warning, cannot find valid starting values:please specify some for colonyID '6' Omitting from results." Colony 7 hasall the data pushed up to week 25 and therefore should result in aconvergence error when searching for the optimal switchpoint and the warning,"Warning: search for optimal switchpoint did not converge for colonyID '6'.Omitting from results."