% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simulate_exposure_rate.R
\name{simulate_exposure_rate}
\alias{simulate_exposure_rate}
\title{Simulate exposure rates}
\usage{
simulate_exposure_rate(
  GT,
  rate_extra_cols = NULL,
  overwrite = FALSE,
  sensitivity = FALSE
)
}
\arguments{
\item{GT}{GeoTox object.}

\item{rate_extra_cols}{Additional columns to match from the
'exposure_rate_params' table (default NULL).}

\item{overwrite}{Logical indicating whether to overwrite existing
'exposure_rate' table (default FALSE).}

\item{sensitivity}{Logical indicating whether to simulate exposure rates for
sensitivity analysis (default FALSE).}
}
\value{
The updated GeoTox object, invisibly.
}
\description{
Simulate exposure rate values for each sample and exposure route based on
parameters in the \code{exposure_rate_params} table.
}
\details{
An 'exposure_rate_params' table must already exist in the GeoTox database,
which is added using \code{\link[=add_exposure_rate_params]{add_exposure_rate_params()}}. There must also be a
'sample' table with an 'age' column, which can be created using
\code{\link[=simulate_age]{simulate_age()}} or \code{\link[=set_sample]{set_sample()}}. 'location' and 'route' tables must also
exist, but they are created when adding the rate parameters and samples.

If \code{rate_exta_cols} is provided it will be added to the GeoTox object
parameter list, \code{GT$par}. These columns must exist in the
'exposure_rate_params' table and will be used to match between the 'sample'
and 'exposure_rate_params' tables when simulating exposure rates.

Typically this function will be called with \code{sensitivity} set to \code{FALSE}. In
this case, the function will create an 'exposure_rate' table with simulated
exposure rates for each sample and exposure route.

If \code{sensitivity} is \code{TRUE}, exposure rates will be simulated for sensitivity
analysis. Typically this shouldn't be used directly by the user, but rather
called by \code{\link[=calc_sensitivity]{calc_sensitivity()}}. In this case, the existing 'exposure_rate'
table will be copied to the 'exposure_rate_sensitivity' table where the rate
values will be overwritten.
}
\examples{
# Setup required tables
# Note: 'gender' is ignored when using the default rate params
sample_df <- tibble::tribble(
  ~FIPS, ~age, ~weight, ~gender,
  10000, 25, "Normal",   "male",
  10000, 35,  "Obese",   "male",
  20000, 50, "Normal", "female"
)
GT <- GeoTox() |>
  add_exposure_rate_params() |>
  set_sample(sample_df)

# Simulate exposure rates
GT |> simulate_exposure_rate()

# Open a connection to GeoTox database
con <- get_con(GT)

# Look at created tables

dplyr::tbl(con, "exposure_rate") |> dplyr::collect()

dplyr::tbl(con, "sample") |> dplyr::collect()

dplyr::tbl(con, "location") |> dplyr::collect()

dplyr::tbl(con, "route") |> dplyr::collect()

# Replace exposure rate params with a new table that includes gender
params_df <- tibble::tribble(
  ~age_lb, ~age_ub, ~gender, ~mean, ~sd,
   0, 49,   "male", 10, 1,
  50, 99,   "male", 20, 1,
   0, 49, "female", 30, 1,
  50, 99, "female", 40, 1
)
DBI::dbRemoveTable(con, "exposure_rate_params")
GT |> add_exposure_rate_params(params = params_df)

# Overwrite 'rate' values in existing 'exposure_rate' table
# Must specify additional column names
# Notice how the column names are added to GT$par
str(GT$par)
GT <- GT |>
  simulate_exposure_rate(rate_extra_cols = c("gender"), overwrite = TRUE)
str(GT$par)

# Look at updated 'exposure_rate' table
dplyr::tbl(con, "exposure_rate") |> dplyr::collect()

# Clean up example
DBI::dbDisconnect(con)
file.remove(GT$db_info$dbdir)
}
\seealso{
\code{\link[=add_exposure_rate_params]{add_exposure_rate_params()}}, \code{\link[=simulate_population]{simulate_population()}}
}
