% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hellometry.R
\name{hellometry}
\alias{hellometry}
\title{Wrapper function to estimate size (mm) and biomass (mg) from an input dataset}
\usage{
hellometry(
  dats,
  level_vec,
  biomass_type = "dry",
  model = "lm",
  r_square_cutoff_upper = 0.95,
  r_square_cutoff_lower = 0,
  p_val_cutoff = 0.05
)
}
\arguments{
\item{dats}{The input data table, please include columns "abundance",
"size_col", "biomass_col", "stage" (larva/pupa/adult).}

\item{level_vec}{A character vector indicating the taxonomic levels present
in your data, in increasing order of coarseness.}

\item{biomass_type}{"dry"/"wet". Should data used in inference be "dry" for
just dry biomass (default), or "wet" for just wet biomass. See \code{dry_wet()}
for more information on how this works.}

\item{model}{What kind of allometric model should be computed, "lm" (default)
for a linear model on the log10-log10 scale, or "poisson" for a Poisson glm
with a log link.}

\item{r_square_cutoff_upper}{Upper cutoff for R2 in allometric models, models with values above it will not be used in estimation. Default is 0.95 to avoid overfit models}

\item{r_square_cutoff_lower}{Lower cutoff for R2 in allometric models, models with values below it will not be used in estimation. Default is 0.}

\item{p_val_cutoff}{Upper cutoff for p-value of allometric models, models with p_value above it will not be used in estimation. Default is 0.05.}
}
\value{
A list with three tibbles:
\itemize{
\item data: the input data with added size and biomass estimates, and new columns
with the taxonomic level and name of the taxon at which the estimate
was made.
\item size_estimates: tibble with size estimates that were used,
with columns for taxonomic level, name and size category
of the estimation.
\item model_estimates: tibble with biomass models that were used, with columns
for taxonomic level and name.
See \code{full_estimation_table()} to get all possible size estimates and models
for your data
}
}
\description{
Wrapper function, input your data and get size and measurement.
Please name column with number of specimen "abundance", column with measurement
"size_col", column with life stage (e.g. larva/adult) "stage", column
with biomass type (dry/wet) "biomass_type", and the column with biomass
"biomass_col".
If you do not have a numerical measurement for a given specimen, the function
can do size estimations if you input "small", "medium", "large" or "unknown".
In this case, the algorithm will use existing size measurements for the species,
and use the size distribution to estimate "small", "medium" and "large" inputs,
or a weighted average of all measurements if the input is "unknown". For biomass
measurements, just leave NA for those cells you want estimates in.
}
\details{
Please make sure that the level_vec argument has levels in increasing order
of coarseness, e.g. from species to order.
}
\examples{
# Reference measurements for one family, renamed to the columns the package expects
measurements <-
  bromeliad_inverts_measurements() \%>\%
  dplyr::filter(family == "Culicidae") \%>\%
  dplyr::rename(size_col = body_size_mm,
                biomass_col = body_mass_mg,
                biomass_type = mass_type) \%>\%
  dplyr::mutate(size_col = as.character(size_col),
                biomass_col = as.numeric(biomass_col))

# Taxa to estimate, with no measurement of their own
communities <-
  trini_communities() \%>\%
  dplyr::filter(family == "Culicidae") \%>\%
  dplyr::rename(abundance = n) \%>\%
  dplyr::mutate(size_col = "unknown",
                biomass_col = NA,
                biomass_type = "dry")

# The two together are what the package works on
dats <-
  dplyr::bind_rows(communities, measurements)
level_vec <-
  c("species", "genus", "family")

res <-
  hellometry(dats = dats, level_vec = level_vec, biomass_type = "dry")

# The estimates, joined back to the data
res$data[, c("genus", "size_col", "biomass_col", "size_level", "model_level")]

# The size estimates and the models they came from
res$size_estimates
res$model_estimates
}
