Package {pollimetry}

Type: Package
Title: Estimate Pollinator Body Size and Co-Varying Ecological Traits
Version: 1.1.1
Maintainer: Liam Kendall <liam.k.kendall@gmail.com>
Description: Tools to estimate pollinator body size and co-varying traits. This package contains Bayesian predictive models of pollinator body size (for bees and hoverflies) and bee foraging range, as well as preexisting predictive models for pollinator body size (currently implemented for ants, bees, butterflies, flies, moths and wasps), bee tongue length, foraging range, total field nectar loads and wing loading. An additional GitHub repository https://github.com/liamkendall/pollimetrydata provides model objects to use the bodysize and foraging.range functions internally. The Bayesian models are described in Kendall et al. (2019) <doi:10.1002/ece3.4835> & Kendall et al. (2022) <doi:10.1002/ecy.3809>.
Depends: R (≥ 4.0.0)
Imports: stats, utils, lifecycle, brms (≥ 2.16.1)
Suggests: pollimetrydata (≥ 1.0.1)
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
LazyData: true
Encoding: UTF-8
Config/roxygen2/version: 8.1.1
URL: https://github.com/liamkendall/pollimetry
BugReports: https://github.com/liamkendall/pollimetry/issues
NeedsCompilation: no
Packaged: 2026-11-03 07:10:16 UTC; liamkendall
Author: Liam Kendall [aut, cre], Ignasi Bartomeus [aut]
Repository: CRAN
Date/Publication: 2026-11-03 09:00:17 UTC

Predict bee and hoverfly dry body weight

Description

Predict dry body weight (mg) from intertegular distance and covariates using the fitted models of Kendall et al. (2019).

Usage

bodysize(x, taxa, type)

Arguments

x

A nonempty data frame with positive, finite ITD measurements in mm. Sex (Female or Male) is required except for type = "ITD". Taxonomic models also require Family for bees or Subfamily for hoverflies. Accepted hoverfly subfamilies are Eristalinae, Pipizinae and Syrphinae. Optional grouping columns are Region and Species (Genus_species); Species requires Region. The phylogenetic model requires both Region and Species.

taxa

One string: "bee" or "hov".

type

One string: "taxo", "sex", "ITD", or "phylo" (bees only).

Details

With Region and Species, both fitted grouping effects are included. With Region alone, only the regional effect is included. With neither, group effects are excluded (set to zero, not integrated out). Species alone is rejected because the fitted species effect is nested within Region. New grouping levels use brms uncertainty sampling from existing levels; this does not place a new species on a phylogenetic tree. Fixed-effect categories must be supported by the fitted model. Est.Weight is exp(mean(log-scale predictive draws)), not arithmetic mean weight. Intervals include residual variation. Use set.seed() for reproducibility. Requires brms. Uses pollimetrydata (>= 1.0.1) when installed; otherwise downloads only the required fitted models from GitHub. Downloaded models are cached in memory for the current R session. An internet connection is required for each model's first download in a session. No Bayesian models are fitted during prediction.

Value

The input data frame with Est.Weight, CI_Lower and CI_Upper appended, in mg. Bounds are the 5th and 95th percentiles of the posterior predictive distribution.

References

Kendall et al. (2019). Pollinator size and its consequences: Robust estimates of body size in pollinating insects. Ecology and Evolution, 9, 1702-1714. doi:10.1002/ece3.4835.

Examples

if (requireNamespace("pollimetrydata", quietly = TRUE) && 
utils::packageVersion("pollimetrydata") >= "1.0.1") {
  x <- data.frame(ITD = c(1.5, 2), Sex = c("Female", "Male"),
                  Subfamily = c("Pipizinae", "Syrphinae"))
  bodysize(x, taxa = "hov", type = "taxo")
}

Bee foraging range measurements.

Description

A dataset of 425 foraging range estimates, with body size, sociality, taxonomic and study metadata.

Usage

data(forage_dataset)

Format

A data frame with 425 rows and 23 columns.

publication

Source publication and publication year.

year

Source publication and publication year.

region

Study location and habitat.

country

Study location and habitat.

habitat

Study location and habitat.

family

Taxonomic identifiers and sex.

genus

Taxonomic identifiers and sex.

species

Taxonomic identifiers and sex.

sex

Taxonomic identifiers and sex.

range.type

Range category, potential or realized measure, and measurement method.

measure.type

Range category, potential or realized measure, and measurement method.

metric

Range category, potential or realized measure, and measurement method.

N

Reported sample size.

distance

Reported foraging distance in metres.

sd

Reported uncertainty metadata: standard deviation, standard error and 95 percent confidence interval.

se

Reported uncertainty metadata: standard deviation, standard error and 95 percent confidence interval.

ci95

Reported uncertainty metadata: standard deviation, standard error and 95 percent confidence interval.

itd

Intertegular distance in mm.

sociality

Social organisation.

notes

Original study notes.

dist10

Stored log10 foraging distance in kilometres.

range.4

Stored combination of range and measure categories.

wgt10

Stored predicted log10 body mass in mg used in the original models.

Details

Stored model predictors are missing outside the original training subsets. The model_training attribute contains specifications for two models, including row selections, columns, factor levels, factor attributes and row names required to reconstruct their training data. Body masses have not been re-estimated.

References

Kendall et al. (2022). The potential and realized foraging movements of bees are differentially determined by body size and sociality. Ecology, 103(11), e3809. doi:10.1002/ecy.3809.

(Deprecated) Converts body measurements to measures of foraging range for bees.

Description

This function is now deprecated and has been superseded by 'foraging.range'

Calculates foraging range from Greenleaf et al. (2007) using intertegular distance (ITD) values, van Nieuwstadt and Iraheta (1996) using head width (HW) values for Meliponini (stingless bees) and Guedot et al. (2009) using dry weight (mg) values for Osmia species.

Usage

foragedist(x, type = "GreenleafAll")

Arguments

x

A nonempty numeric vector of finite, positive measurements without missing values: intertegular distance (mm) for Greenleaf equations, head width (mm) for Meli equations, or dry body weight (mg) for Osmia.

type

A single character string selecting the equation or equation group. Options are "GreenleafAll", GrMhd ("Maximum homing distance"), GrThd ("Typical homing distance"), GrMfd ("Maximum feeder training distance"), GrMcd("Maximum communication distance"),"Osmia", "MeliMR" , "MeliFT" or "MeliAll". See details in Greenleaf et al. (2007), Guedot et al. (2009) and van Nieuwstadt and Iraheta (1996).

Details

Linear equations can return negative distances for small input values; these indicate inappropriate extrapolation, not biological distances. Values are not truncated to zero. The replacement foraging.range function uses different models and inputs and is not a numerical substitute for these equations.

Value

A numeric vector for a single equation, or a named-column matrix for GreenleafAll and MeliAll. Greenleaf estimates are in kilometres; Meliponini and Osmia estimates are in metres. Rows follow input order. No uncertainty intervals are returned.

References

Examples

foragedist(c(10,5,2), type = "MeliMR")

Predict typical and maximum bee foraging ranges

Description

Predict realized or potential bee foraging ranges using the models of Kendall et al. (2022).

Usage

foraging.range(
  data,
  model.type = "social",
  random.effects = "reduced",
  measure.type = "realized"
)

Arguments

data

A nonempty data frame with positive, finite ITD measurements in mm. The social model requires sociality: "Highly Eusocial", "Primitively Eusocial" or "Solitary". Group effects require species in Genus_species format; genus is derived from species.

model.type

One string: "social" (default) or "ITD". Both models use estimated body weight; the social model also uses sociality.

random.effects

One string: "reduced" (default, no group effects), "phylo" (genus effect), or "full" (genus and species effects). Publication and metric effects are excluded for all choices.

measure.type

One string: "realized" (default) or "potential".

Details

The response is log10(range in km), so predictions and interval endpoints are back-transformed with 10^x. range.estimate is 10 raised to the mean log10-scale predictive draw, not arithmetic mean distance. Intervals include residual variation. Female body weight is estimated once per input row using the bee sex model without group effects, then reused for both range types. Body-weight uncertainty is not propagated through the range model. Excluded group effects are set to zero, not integrated out. New included grouping levels use uncertainty sampling from existing levels, not a new phylogenetic placement. Use set.seed() for reproducibility. Requires brms. Uses pollimetrydata (>= 1.0.1) when installed; otherwise downloads only the required fitted models from GitHub. Downloaded models are cached in memory for the current R session. An internet connection is required for each model's first download in a session. No Bayesian models are fitted during prediction.

Value

A data frame with two rows per input specimen, typical then maximum range. range.estimate, range.lower and range.upper are in kilometres; bounds give a 95

References

Kendall et al. (2022). The potential and realized foraging movements of bees are differentially determined by body size and sociality. Ecology, 103(11), e3809. doi:10.1002/ecy.3809.

Examples

if (requireNamespace("pollimetrydata", quietly = TRUE) && 
utils::packageVersion("pollimetrydata") >= "1.0.1") {
  x <- data.frame(ITD = c(2.9, 2.5),
                  sociality = c("Highly Eusocial", "Solitary"))
  foraging.range(x)
}

Converts pollinator (Diptera, Hymenoptera and Lepidoptera) head width (mm) to body size (dry weight (mg)).

Description

Calculates dry body weight (mg) using head width (mm) from Hodar (1997).

Usage

headwidthsize(HW, Eq = "H97DB")

Arguments

HW

A nonempty numeric vector of head widths in mm. All values must be finite, strictly positive and nonmissing.

Eq

A single character string selecting an equation from Hodar (1997). Options implemented are: H97DB (Brachycera), H97DN (Nematocera), H97HA (Hymenoptera), H97LH (Heterocera) and H97LR (Rhopalocera).

Value

A numeric vector of predicted dry weights (mg), one per input measurement.

References

Examples

headwidthsize(HW = c(1, 2, 3), Eq = "H97HA")

Converts body length to body size (body weight (mg)) for three pollinating insect groups (Diptera, Hymenoptera and Lepidoptera).

Description

Calculates dry body weight (mg) from existing allometries using body length (mm).

Usage

lengthsize(BL, Eq = "DIP")

Arguments

BL

A nonempty numeric vector of body lengths in mm. All values must be finite, strictly positive and nonmissing.

Eq

A single character string selecting one equation or a group of equations. Acronyms denote author, publication date and taxon. DIP, HYM and LEP select the implemented collections for each order. Other group selectors are Brachycera, Nematocera, Asilidae, Bombyliidae, Formicidae, Vespidae and Noctuidea. Taxon labels below identify equation applicability; only these listed group selectors and equation codes are accepted. Options implemented are:

Diptera

  • All: BN06D, G97D, GR84D, JS00DA, R77D, S80DCF, S80DCR, S80DMF, S93DA, W13D.

  • Brachycera (2 equations): S93DB, Sabo02DB.

  • Nematocera (3 equations): JS00DN, S93DN, Sabo02DN.

  • Asilidae (2 equations): Sabo02DA, S93DB.

  • Bombyliidae (2 equations): S93DB, Sabo02DBB.

  • Cyclorrapha: S93DC.

Hymenoptera

  • All: BN06H1, G97H, G97F, GR84H, JS00HA, R77H, S80HCF, S80HCR, S80HMF, S93HA, Sabo02H, W13H.

  • Formicidae (13 equations): BN06HF, GR84F, JS00HF, R77A, S80FCF, S80FCR, S80FMF, S93HF, S93HH, S93HI, BN06H1, G97H, G97F.

  • Apidae: Sabo02HA.

  • Braconidae: S93HB.

  • Halictidae: S93HH.

  • Ichneumonidae: S93HI.

  • Pompilidae: S93HP.

  • Vespidae: S93HV & Sabo02HV.

Lepidoptera

  • All: BN06L, G97L, JS00L, R77L, S80LCF, S80LCR, S80LMF,S93LA,W13L.

  • Noctuidea: S93LC, S93LN.

  • Geometridae: S93LG.

  • Microlepidoptera: S93LM.

  • Arctiinae: S93LC.

Value

A numeric vector of predicted dry weights (mg) for one equation, or a numeric matrix for a group of equations. Matrix rows follow input order and columns are named by equation.

References

Full reference list provided within Kendall et al. (2019) Pollinator size and its consequences: Robust estimates of body size in pollinating insects. Ecology and Evolution, 9(4), 1702-1714. doi:10.1002/ece3.4835.

Examples

lengthsize(BL = c(10, 5, 2), Eq = "S80DCR")
lengthsize(BL = c(10, 5, 2), Eq = "HYM")

Converts pollinator body length*body width to body size (dry weight (mg)).

Description

Calculates body size as dry weight (mg) from the equations described by Sample (1993) and others using body length multiplied by body width (mm squared).

Usage

lengthwidthsize(BLW, Eq = "DIP")

Arguments

BLW

A nonempty numeric vector of body length multiplied by body width, in square millimetres (mm squared). All values must be finite, strictly positive and nonmissing.

Eq

A single character string selecting an equation or the LEP group. Options implemented are:

  • Diptera: Brachycera, Cyclorrapha, DIP (the default general Diptera equation), Nematocera.

  • Hymenoptera: S93HBLW, S93HFLW, S93HHLW, S93HILW, S93HALW, S93HPLW, S93HVLW.

  • Lepidoptera: S93LGLW, S93LMLW, S93LALW, W13LLW, S93LCLW, S93LNLW. LEP returns W13LLW and S93LALW, in that order.

Value

A numeric vector of predicted dry weights (mg) for one equation, or a numeric matrix for a group of equations. Matrix rows follow input order and columns are named by equation.

References

Examples

lengthwidthsize(BLW = c(3, 5, 2), Eq = "Brachycera")
lengthwidthsize(BLW = c(3, 5, 2))
lengthwidthsize(BLW = c(3, 5, 2), Eq = "LEP")

Converts bee body length (mm) to total field nectar load (ul).

Description

Calculates total field nectar load (ul) using body length (mm) from Henry & Rodet (2018).

Usage

nectarload(BL)

Arguments

BL

A nonempty numeric vector of finite, positive body lengths (mm), without missing values.

Value

A numeric vector of total field nectar load estimates in microlitres, one per input measurement.

References

Examples

nectarload(BL=c(10,5,2))

Body size measurements of pollinating insects.

Description

A dataset of 4,434 bee and hoverfly specimens, containing dry body mass (mg), intertegular distance (mm), body length (mm), taxonomy and collection metadata.

Usage

data(pollimetry_dataset)

Format

A data frame with 4,434 rows and 26 columns.

Superfamily

Taxonomic identifiers.

Family

Taxonomic identifiers.

Subfamily

Taxonomic identifiers.

Tribe

Taxonomic identifiers.

Genus

Taxonomic identifiers.

Subgenus

Taxonomic identifiers.

Species

Taxonomic identifiers.

Sex

Specimen sex.

Spec.wgt

Dry body mass in mg.

IT

Intertegular distance in mm.

BL

Body length in mm.

Tag

Specimen identifier.

Region

Geographical and collection-location metadata.

Country

Geographical and collection-location metadata.

Locality

Geographical and collection-location metadata.

Location

Geographical and collection-location metadata.

Latitude

Collection coordinates in decimal degrees.

Longitude

Collection coordinates in decimal degrees.

Measurement

Original measurement, preservation, collection-date, plant and collection-method metadata.

Pres.time

Original measurement, preservation, collection-date, plant and collection-method metadata.

Col.date

Original measurement, preservation, collection-date, plant and collection-method metadata.

Plant

Original measurement, preservation, collection-date, plant and collection-method metadata.

Col.method

Original measurement, preservation, collection-date, plant and collection-method metadata.

log(Spec.wgt)

Stored transformed predictors and grouping identifier used by the original models.

log(IT)

Stored transformed predictors and grouping identifier used by the original models.

Region:Species

Stored transformed predictors and grouping identifier used by the original models.

Details

Original observations are retained. Stored model predictors are missing outside the original training subsets. The model_training attribute contains specifications for seven models, including row selections, columns, factor levels, factor attributes and row names required to reconstruct their training data.

References

Kendall et al. (2019). Pollinator size and its consequences: Robust estimates of body size in pollinating insects. doi:10.1002/ece3.4835.

Combined bee tongue-length training data.

Description

Combined training measurements from Cariveau et al. (2016) and Melin et al. (2019), covering six bee families, including Melittidae.

Usage

data(tongue_dataset)

Format

A data frame with 112 rows and eight columns.

Family

Bee family.

mean_tongue_length_mm

Mean total proboscis length in mm.

IT

Mean intertegular distance in mm.

mean_glossa_length_mm

Mean glossa length in mm.

mean_prementum_length_mm

Mean prementum length in mm.

genus

Genus and species identifiers retained from each source.

species

Genus and species identifiers retained from each source.

source

Source publication.

Details

Contains the 101 original Cariveau training rows followed by 11 Melin species means. Melin measurements are averaged within Family, genus and species using the same aggregation as the prediction function previously used. Cariveau rows are retained without further aggregation. This is the combined training dataset used by tonguelength; no observations have been added. The original Cariveau file was obtained from the ibartomeus/traitbase repository (raw_data/Cariveau_2016.rda).

References

Cariveau et al. (2016). The Allometry of Bee Proboscis Length and Its Uses in Ecology. doi:10.1371/journal.pone.0151482.

Melin et al. (2019). The allometry of proboscis length in Melittidae (Hymenoptera: Apoidae) and an estimate of their foraging distance using museum collections. doi:10.1371/journal.pone.0217839.

Converts ITD (mm) to tongue length for bees.

Description

Calculates tongue length (mm) from Cariveau et al. (2016) and Melin et al. (2019) using intertegular distance (ITD) values (mm).

Usage

tonguelength(x, mouthpart = "all")

Arguments

x

A dataframe with the following two columns: IT (finite, positive intertegular distance in mm) and Family (capital F). Missing measurements are not accepted. Only six out of the extant seven families are implemented: "Andrenidae", "Apidae", "Colletidae", "Halictidae", "Melittidae" and "Megachilidae".

mouthpart

The mouthpart you are interested in. Options are: "all", "glossa", "prementum" and "tongue" (i.e. glossa + prementum)

Details

Models are fitted to tongue_dataset, which combines the Cariveau data with species means from Melin et al. (2019). Predictions and confidence bounds are exponentiated from the natural-log scale. They describe fitted geometric means, not arithmetic means or individual prediction intervals. Total tongue length is modelled separately, so its prediction need not equal the sum of separately predicted glossa and prementum lengths. No data are downloaded during a call.

Value

The input data frame with predicted mouthpart lengths (mm) and 95

References

Examples

example=cbind.data.frame(IT=c(1.3,2.3),
                         Family=c("Andrenidae","Apidae"))
tonguelength(example,mouthpart="all")

Converts intertegular distance (mm) to wing loading (mg/mm^2).

Description

Calculates wing loading (mg/mm^2) expressed as dry weight per total wing area using intertegular distance (mm) from Bullock (1999).

Usage

wingloading(IT)

Arguments

IT

A nonempty numeric vector of finite, positive intertegular distances (mm), without missing values.

Value

A numeric vector of wing-loading estimates (mg/mm^2), one per input measurement.

References

Examples

wingloading(IT=c(10,5,2))