% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sample_simulated_css.R
\name{sample_simulated_css}
\alias{sample_simulated_css}
\title{Sample from pre-simulated steady-state plasma concentrations}
\usage{
sample_simulated_css(GT, css_extra_cols = NULL, substance_order = NULL)
}
\arguments{
\item{GT}{GeoTox object.}

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

\item{substance_order}{Named list specifying order of substance evaluation
(default NULL).}
}
\value{
The updated GeoTox object, invisibly.
}
\description{
Sample steady-state plasma concentrations (C\eqn{_{ss}}) for individuals from
pre-simulated values stored in the 'simulated_css' table in a GeoTox
database.
}
\details{
The C\eqn{_{ss}} values are sampled from the 'simulated_css' table, which
must already exist in the GeoTox database; it can be created using
\code{\link[=set_simulated_css]{set_simulated_css()}}. The minimum characteristics that are used to match
individuals to sets of C\eqn{_{ss}} values are age and weight category
("Normal" or "Obese"). Additional columns (which must exist in both the
'simulated_css' and 'sample' tables) can be specified using the
\code{css_extra_cols} argument. If \code{css_exta_cols} is provided it will be added to
the GeoTox object parameter list, \code{GT$par}.

In addition to the 'simulated_css' table, both 'sample' and 'concentration'
tables must also exist in the GeoTox database. The 'sample' table must
contain the characteristics of individuals (age, weight category, and any
additional columns specified in \code{css_extra_cols}). One way to create this
'sample' table is by using \code{\link[=set_sample]{set_sample()}}. The 'concentration' table will
typically be created using \code{\link[=simulate_exposure]{simulate_exposure()}} and will be populated with
rows for each individual and substance combination where exposure data is
available. The sampled C\eqn{_{ss}} values will be stored in a new "C_ss"
column in the 'concentration' table.

The \code{substance_order} argument can be used to specify the order in which
substances are evaluated when sampling C\eqn{_{ss}} values. The default is to
evaluate substances in the order they appear in the 'substance' table.
However, if a different order is needed for some reason (e.g., replication of
results from a previous GeoTox implementation), the user can provide a named
list where the name is the column in the 'substance' table to use for
ordering (e.g., "casn") and the value is a vector of substance identifiers in
the desired order. If provided, the \code{substance_order} will be added to the
GeoTox object parameter list, \code{GT$par}.
}
\examples{
# Create 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
)
# 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
)
GT <- GeoTox() |>
  set_sample(sample_df) |>
  add_exposure(exposure_df) |>
  simulate_exposure() |>
  set_simulated_css(css_df)

# Sample simulated C_ss values
GT <- GT |> sample_simulated_css()

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

# Look at created tables. sample_simulated_css() generated the 'C_ss' column
# of the 'concentration' table.

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()

# Replace sample and css tables with new data including an extra column
# Limit to a single substance for simplicity
sample_df <- tibble::tribble(
  ~FIPS, ~age, ~weight, ~sign,
  10000, 25, "Normal", "+",
  10000, 35,  "Obese", "-",
  20000, 50, "Normal", "+"
)
css_df <- tibble::tribble(
  ~casn, ~age_lb, ~age_ub, ~weight, ~css, ~sign,
  "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-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, "-"
)
GT <- GT |>
 set_sample(sample_df, overwrite = TRUE) |>
 simulate_exposure() |>
 set_simulated_css(css_df, overwrite = TRUE)

# Sample simulated C_ss values with extra column
# Notice how the extra column name is added to GT$par
str(GT$par)
GT <- GT |> sample_simulated_css(css_extra_cols = "sign")
str(GT$par)

# Look at new 'concentration' table. Values will be missing for substance 2
# since it is not in the new css_df.
dplyr::tbl(con, "concentration") |> 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[=simulate_population]{simulate_population()}}
}
