simulate_population: Simulate population characteristics and exposures
In GeoTox: Spatiotemporal Mixture Risk Assessment

simulate_population

R Documentation

Simulate population characteristics and exposures

Description

Simulate age, weight category, exposure rates, and external exposures. Sample from pre-simulated steady-state plasma concentrations.

Usage

simulate_population(
  GT,
  age = NULL,
  obesity = NULL,
  exposure = NULL,
  simulate_rate = TRUE,
  sample_css = TRUE,
  ...
)

Arguments

`GT`	GeoTox object.
`age`	Data frame with age data.
`obesity`	Data frame with obesity data.
`exposure`	Data frame with exposure data.
`simulate_rate`	Logical indicating whether to simulate exposure rates. This requires that exposure rate parameters have been added using `add_exposure_rate_params()`.
`sample_css`	Logical indicating whether to sample steady-state plasma concentrations (C`_{ss}`). This requires that a table of simulated C`_{ss}` values has been set using `set_simulated_css()`. In addition, `set_fixed_css()` will be called after sampling to prepare C`_{ss}` values for sensitivity analysis.
`...`	Additional arguments passed to wrapped functions (see 'Additional arguments' section of 'Details').

Details

This is a wrapper around several other functions:

add_age() and simulate_age() for age simulation.
add_obesity() and simulate_obesity() for weight category simulation.
add_exposure() and simulate_exposure() for external exposure concentration simulation (C_{ext}).
simulate_exposure_rate() for exposure rate simulation.
sample_simulated_css() for sampling steady-state plasma concentrations (C_{ss}).
set_fixed_css() to prepare C_{ss} values for sensitivity analysis.

The user can provide data frames for age, obesity, and exposure data; if any of these are provided, the corresponding add and simulate functions will be called. The user can also specify whether to simulate exposure rates and sample C_{ss} values using the simulate_rate and sample_css arguments, respectively. If simulate_rate is TRUE, exposure rate parameters must have been added using add_exposure_rate_params(). If sample_css is TRUE, a table of simulated C_{ss} values must already exist using set_simulated_css().

Additional arguments:

n: Number of samples to simulate (default 1000). Used in simulate_age(), simulate_obesity(), and simulate_exposure(). Ignored if the 'sample' table already exists, in which case the existing sample sizes are used.
location: Column name for location ID (default "FIPS"). Used in add_age(), add_obesity(), and add_exposure().
overwrite: Logical indicating whether to overwrite existing values (default FALSE). Used in simulate_age(), simulate_obesity(), simulate_exposure_rate(), and simulate_exposure().
substance: Column name for substance ID (default "casn"). Used in add_exposure().
route: Column name for exposure route (default "route"). Used in add_exposure().
rate_extra_cols: Additional columns to include in exposure_rate table. Used in simulate_exposure_rate().
obes_prev, obes_sd: Column names for obesity prevalence and standard deviation (default "OBESITY_CrudePrev" and "OBESITY_SD", respectively). Used in simulate_obesity().
expos_mean, expos_sd: Column names for exposure concentration mean and standard deviation (default "mean" and "sd", respectively). Used in simulate_exposure().
css_extra_cols: Additional columns to include in simulated_css table. Used in sample_simulated_css().
substance_order: Named list specifying order of substances. Used in sample_simulated_css() and set_fixed_css().

Value

The updated GeoTox object, invisibly.

Examples

# Example simulation data

age_df <- data.frame(
  FIPS = rep(c(10000, 20000), each = 19),
  AGEGRP = rep(0:18, times = 2),
  TOT_POP = 0
)
# FIPS 10000, populate age group 40-44
age_df$TOT_POP[c(1, 10)] = 100
# FIPS 20000, populate age groups 50-59
age_df$TOT_POP[c(1, 12, 13) + 19] = c(200, 100, 100)

obesity_df <- data.frame(
  FIPS = c(10000, 20000),
  OBESITY_CrudePrev = c(20, 80),
  OBESITY_SD = 5
)

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
)

# Note: normally the css_df would have many more rows for each combination of
# the non-'css' columns to allow for sampling.
css_df <- tibble::tribble(
  ~casn, ~age_lb, ~age_ub, ~weight, ~css,
  "00-00-1",  0, 49, "Normal",  1,
  "00-00-1", 50, 99, "Normal",  2,
  "00-00-1",  0, 49,  "Obese", 11,
  "00-00-1", 50, 99,  "Obese", 12,
  "00-00-2",  0, 49, "Normal", 21,
  "00-00-2", 50, 99, "Normal", 22,
  "00-00-2",  0, 49,  "Obese", 31,
  "00-00-2", 50, 99,  "Obese", 32
)

# Simulate population
GT <- GeoTox() |>
  add_exposure_rate_params() |>
  set_simulated_css(css_df) |>
  simulate_population(
    age = age_df,
    obesity = obesity_df,
    exposure = exposure_df,
    n = 3
  )

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

# Look at created tables

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

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

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

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

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

# Note: the 'age', 'weight', 'params', and 'other' columns of the
# 'fixed_css' table contain the C_ss values for sensitivity analysis.
# For example, the 'age' column doesn't contain ages, but C_ss values.
dplyr::tbl(con, "fixed_css") |> dplyr::collect()

# Clean up example
DBI::dbDisconnect(con)
file.remove(GT$db_info$dbdir)

GeoTox documentation built on May 20, 2026, 1:07 a.m.