% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/set_sample.R
\name{set_sample}
\alias{set_sample}
\title{Set sample data}
\usage{
set_sample(GT, df, location = "FIPS", overwrite = FALSE)
}
\arguments{
\item{GT}{GeoTox object.}

\item{df}{Data frame containing sample data.}

\item{location}{Column name(s) in \code{df} that contain location identifier(s)
(default "FIPS").}

\item{overwrite}{Logical indicating whether to overwrite existing 'sample'
table and remove existing 'concentration' and 'risk' tables (default
FALSE).}
}
\value{
The same GeoTox object, invisibly.
}
\description{
Create the 'sample' table in the GeoTox database.
}
\details{
The 'sample' table consists of individual characteristics and location
information. At a minimum, it must contain columns with information on age,
weight category, and location identifier(s).

When the \code{df} input contains information on age or weight category, the
column names must be "age" and "weight", respectively. The \code{location} input
(default "FIPS") can be a named vector to specify multiple identifier columns
in \code{df}. For example, \code{location = c(FIPS = "FIPS", state = "ST")} would
indicate that \code{df} contains both FIPS codes and state identifiers for
locations. The location column(s) will be added to the 'location' table and
replaced with a corresponding "location_id" column in the 'sample' table. The
\code{state = "ST"} part in the example above would rename the "ST" column in \code{df}
to "state" in the 'location' table.

There are several other functions that can be used to create or add to the
'sample' table: \code{\link[=simulate_age]{simulate_age()}} to generate age data, \code{\link[=simulate_obesity]{simulate_obesity()}}
to generate weight category data, and \code{\link[=simulate_population]{simulate_population()}}, which is a
wrapper function that can generate both age and weight category data along
with other fields. \code{set_sample()} can be used in combination with these
functions to first set some known sample data, e.g. age, and then simulate
any missing fields, e.g. weight category.

If \code{overwrite = TRUE}, any existing 'concentration' and 'risk' tables will be
dropped before creating the 'sample' table. This is because the existing
concentration and risk data would no longer be valid for the new sample data.
Further downstream tables are not dropped automatically, but can be updated
during subsequent simulation and analysis steps.
}
\examples{
# Example sample data
sample_df <- tibble::tribble(
  ~FIPS, ~age, ~weight,
  10000, 25, "Normal",
  10000, 35,  "Obese",
  20000, 50, "Normal"
)

# Set sample data
GT <- GeoTox() |> set_sample(sample_df)

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

# Look at created tables

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

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

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