% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/calc_sensitivity.R
\name{calc_sensitivity}
\alias{calc_sensitivity}
\title{Calculate risk sensitivity to a single variable}
\usage{
calc_sensitivity(
  GT,
  vary = c("age", "weight", "css_params", "fit_params", "C_ext"),
  overwrite = FALSE,
  rate_extra_cols = NULL,
  expos_mean = NULL,
  expos_sd = NULL,
  max_mult = 1.5
)
}
\arguments{
\item{GT}{GeoTox object.}

\item{vary}{Variable to vary. One of "age", "weight", "css_params",
"fit_params", or "C_ext".}

\item{overwrite}{Logical indicating whether to overwrite existing sensitivity
analysis results in the GeoTox database.}

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

\item{expos_mean}{Column name of exposure concentration mean in the
'exposure' table (default "mean").}

\item{expos_sd}{Column name of exposure concentration standard deviation in
the 'exposure' table (default "sd").}

\item{max_mult}{Upper bound multiplier for max response (default 1.5).}
}
\value{
The updated GeoTox object, invisibly.
}
\description{
Compute risk by varying one variable while holding others fixed.
}
\details{
The sensitivity analysis makes use of the C\eqn{_{ss}} values stored in the
'fixed_css' table of the GeoTox database. These values are determined using
the pre-simulated C\eqn{_{ss}} values supplied to \code{\link[=set_simulated_css]{set_simulated_css()}} and
can be set using \code{\link[=set_fixed_css]{set_fixed_css()}} prior to running this function. This step
is automatically done when using \code{\link[=simulate_population]{simulate_population()}} with \code{sample_css = TRUE}.

There are five options for the \code{vary} argument:
\describe{
\item{age}{C\eqn{_{ss}} values from the 'age' column of the 'fixed_css' table
are used. For other cases, exposure rates are re-simulated using the median
age by location in the 'sample' table by calling \code{\link[=simulate_exposure_rate]{simulate_exposure_rate()}}
with \code{sensitivity = TRUE}.}
\item{weight}{C\eqn{_{ss}} values from the 'weight' column of the 'fixed_css'
table are used.}
\item{css_params}{C\eqn{_{ss}} values from the 'params' column of the
'fixed_css' table are used.}
\item{fit_params}{C\eqn{_{ss}} values from the 'other' column of the
'fixed_css' table are used. For other cases, the standard deviation of
dose-response model fit parameters are set to zero by calling \code{\link[=calc_risk]{calc_risk()}}
with \code{fixed = TRUE}.}
\item{C_ext}{C\eqn{_{ss}} values from the 'other' column of the 'fixed_css'
table are used. For other cases, external concentrations are re-simulated
with standard deviations set to zero by calling \code{\link[=simulate_exposure]{simulate_exposure()}} with
\code{sensitivity = TRUE}.}
}
In all cases above, the resulting risk table is named
'risk_sensitivity_~vary~' (e.g., 'risk_sensitivity_age') in the GeoTox
database.

Inputs \code{rate_extra_cols}, \code{expos_mean}, and \code{expos_sd} do not need to be
specified again if they were already provided in a previous call and are set
in the GeoTox parameters (\code{GT$par}).
}
\examples{
# Example setup is shown below in \dontrun().
# Pre-generated results will be loaded instead to avoid long example runtime.

\dontrun{
# Setup required tables
sample_df <- tibble::tribble(
  ~FIPS, ~age, ~weight,
  10000, 25, "Normal",
  10000, 35,  "Obese",
  20000, 50, "Normal"
)
exposure_df <- tibble::tribble(
  ~FIPS, ~casn, ~route, ~mean, ~sd,
  10000, "00-00-1", "inhalation", 10, 1,
  10000, "00-00-2", "inhalation", 20, 1,
  20000, "00-00-1", "inhalation", 30, 1,
  20000, "00-00-2", "inhalation", 40, 1
)
css_df <- tibble::tribble(
  ~casn, ~age_lb, ~age_ub, ~weight, ~css,
  "00-00-1",  0, 49, "Normal", 21,
  "00-00-1", 50, 99, "Normal", 22,
  "00-00-1",  0, 49,  "Obese", 61,
  "00-00-1", 50, 99,  "Obese", 62,
  "00-00-2",  0, 49, "Normal", 11,
  "00-00-2", 50, 99, "Normal", 12,
  "00-00-2",  0, 49,  "Obese", 31,
  "00-00-2", 50, 99,  "Obese", 32
)
hill_df <- tibble::tribble(
  ~assay, ~model, ~casn, ~logc, ~resp,
  "a1", "human", "00-00-1",    0,  10,
  "a1", "human", "00-00-1",    1,  20,
  "a1", "human", "00-00-1",    2,  80,
  "a1", "human", "00-00-1",    3, 100,
  "a1", "human", "00-00-2", -0.5,   5,
  "a1", "human", "00-00-2",  0.5,  20,
  "a1", "human", "00-00-2",  1.5,  55,
  "a1", "human", "00-00-2",  2.5,  60,
  "a2",   "rat", "00-00-1",   -1,   0,
  "a2",   "rat", "00-00-1",    0,  10,
  "a2",   "rat", "00-00-1",    1,  30,
  "a2",   "rat", "00-00-1",    2,  40
)
set.seed(1234)
GT <- GeoTox() |>
  set_sample(sample_df) |>
  set_simulated_css(css_df) |>
  add_exposure_rate_params() |>
  add_hill_params(fit_hill(
    hill_df, assay = c(name = "assay", model = "model"), substance = "casn"
  )) |>
  simulate_population(exposure = exposure_df) |>
  calc_response()

# Calculate sensitivity to age
GT <- GT |> calc_sensitivity("age")
}

# Load results from pre-generated database for this example
temp_dir <- tempdir()
zip::unzip(
  system.file("extdata", "sensitivity.duckdb.zip", package = "GeoTox"),
  junkpaths = TRUE,
  exdir = temp_dir
)
GT <- GeoTox(paste0(temp_dir, "/sensitivity.duckdb"))

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

# Look at relevant table

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

# Compared to baseline risk table
dplyr::tbl(con, "risk") |> dplyr::collect()

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