build_epistats: Statistical Models for Act Rates, Condom Use, and Starting...

In EpiModel/ARTnet: Epidemic and Network Model Parameterization with the ARTnet Dataset

Statistical Models for Act Rates, Condom Use, and Starting HIV Prevalence

Description

Builds statistical models governing act rates and probability of condom use among main, casual and one-time sexual partnerships, and the probability of diagnosed HIV infection, for use in the EpiModelHIV workflow.

Usage

build_epistats(
  geog.lvl = NULL,
  geog.cat = NULL,
  race = TRUE,
  race.level = list("black", "hispanic", c("white", "other")),
  age.limits = c(15, 65),
  age.breaks = c(25, 35, 45, 55),
  age.sexual.cessation = NULL,
  init.hiv.prev = NULL,
  time.unit = 7,
  browser = FALSE
)

Arguments

geog.lvl	Specifies geographic level for ARTnet statistics.
geog.cat	Specifies one or more geographic strata within the level to base ARTnet statistics on. If the vector is of length 2+, data from the strata will be combined into one analysis.
race	If TRUE, stratify model estimates by race/ethnic grouping.
age.limits	Lower and upper limit of age range to include in model. Minimum of 15 and maximum of 100 allowed. Lower limit is inclusive boundary and upper boundary is exclusive boundary.
age.breaks	Ages that define the upper closed boundary of the age categories. Default is c(25, 35, 45, 55), which corresponds to ⁠(0, 25], (25, 35], (35, 45], (45, 55], (55, 65]⁠ with age.limits = c(15, 65).
age.sexual.cessation	Age of cessation of sexual activity, while aging process continues through the upper age limit. Maximum allowed value of 66.
init.hiv.prev	Initial HIV prevalence to be used in epidemic model estimated model, with a numerical vector of size 3 corresponding to starting prevalence in three race/ethnic groups (Black, Hispanic, and White/Other, respectively). If init.hiv.prev = NULL, build_epistats will estimate a logistic regression model to predict starting prevalence as a function of estimated prevalence in ARTnet as a function of race/ethnicity and age.
time.unit	Specifies time unit for time-dependent ARTnet statistics. Default is 7, corresponding to a weekly time unit. Allowed inputs range from 1 for a daily time unit to 30 for a monthly time unit.
browser	If TRUE, run build_epistats in interactive browser mode.

Details

The build_epistats function provides a way to input of geographic, age, and racial parameters necessary to build statistical models predicting sexual activity and condom use in sexual partnerships among men who have sex with men (MSM). Estimation of these models is performed using data from the ARTnetData package, containing the results of the ARTnet study.

Explanation of Parameter Values

• geog.lvl: level of geographic stratification desired. Acceptable values are "city", "county", "state", "region", and "division" corresponding to the metropolitan statistical area, county, state, census region, and census division, respectively. Default value is NULL, indicating no geographic stratification.

• geog.cat: given a geographic level above, "geog.cat" is a vector comprising the desired feature(s) of interest. Acceptable values are based on the chosen geographic level:

  • city: "Atlanta", "Boston", "Chicago", "Dallas", "Denver", "Detroit", "Houston", "Los Angeles", "Miami", "New York City", "Philadelphia", "San Diego", "San Francisco", "Seattle", "Washington DC".

  • county: FIPS codes for the county or county equivalents to be included. Selecting a single county or a set of smaller counties may lead to insufficient data used to estimate the models; an error may result.

  • state: Two-letter postal code for each state.

  • division: "1" (New England), "2" (Middle Atlantic), "3" (East North Central), "4" (West North Central), "5" (South Atlantic), "6" (East South Central), "7" (West South Central), "8" (Mountain) "9" (Pacific).

  • region: "1" (Northeast), "2" (Midwest), "3" (South), "4" (North)

• race: whether to introduce modeling by racial stratification. TRUE or FALSE.

• age.limits: a vector giving the lower and upper limit for the age of interest. Set to c(15, 65) by default. The lower boundary is inclusive, meaning persons may be initialized into the model at age 15.0; the upper boundary is exclusive, meaning exit from the population will occur on turning 65.0 years. Although the ARTnet data include respondents from age 15 to 65, this may be set to restricted values within that range (for example, c(25, 40)) for a subsetted data analysis. The upper boundary may be set up to age 100 (that is, c(15, 100)), which may be used in models where sexual activity ceases before mortality.

• age.breaks: a vector giving the upper age breaks to categorize data by age. Must be within the bounds specified by age.limits. These should be the interior age breaks only (that is, there is no need to include the age limit boundaries). If an age of sexual cessation is added, then this age is also added to the age breaks if it is not explicitly specified.

• age.sexual.cessation: a numerical value for the age of cessation of sexual activity. This may be by assumption or given data constraints (ARTnet eligibility were through age 65, so the maximum value here is 66). This specification is useful for models in which the HIV transmission process stops at a certain age but aging and other demographic features should continue through natural mortality.

• time.unit: a number between 1 and 30 that specifies time units for ARTnet statistics. Set to 7 by default.

• race.level: a list of race and ethnicity categories from ARTnet that can be used for race stratification in EpiModel. Values must match those in ARTnet, so options include "black", "hispanic", "white", "other", "asian", "ai/an", "mult", "nh/pi". Race categories may be combined (for example, c("white", "other")).

Examples

# Age and geographic stratification, for the Atlanta metropolitan statistical area
epistats1 <- build_epistats(geog.lvl = "city",
                            geog.cat = "Atlanta",
                            age.limits = c(20, 50),
                            age.breaks = c(24, 34, 44))

# Default age stratification
epistats2 <- build_epistats(geog.lvl = "state", geog.cat = "WA")

# Default age stratification, multiple states
epistats3 <- build_epistats(geog.lvl = "state", geog.cat = c("ME", "NH", "VT"))

# No race stratification
epistats4 <- build_epistats(geog.lvl = "state", geog.cat = "GA", race = FALSE)

# Age and race stratification, for the municipality (not metro) of New York City
# geog.cat values are FIPS codes for the 5 boroughs of NYC
epistats5 <- build_epistats(geog.lvl = "county",
                            geog.cat = c(36005, 36047, 36061, 36081, 36085),
                            age.limits = c(20, 50),
                            age.breaks = c(24, 34, 44))

# Use broader age range (to age 100) but with sexual cessation at age 66
epistats6 <- build_epistats(geog.lvl = "city",
                            geog.cat = "Atlanta",
                            race = TRUE,
                            age.limits = c(15, 100),
                            age.breaks = c(25, 35, 45, 55),
                            age.sexual.cessation = 66)

EpiModel/ARTnet documentation built on June 12, 2025, 4:23 p.m.