Skip to contents

Retrieve STI surveillance data from CDC AtlasPlus

Source: R/get_atlas.R
get_atlas.Rd

get_atlas() provides a programmatic interface to the CDC AtlasPlus platform, returning case counts, population denominators, and rate estimates for sexually transmitted infection (STI) surveillance. The function submits a payload to the AtlasPlus data endpoint and parses the response into a tidy tibble.

Usage

get_atlas(
  disease,
  geography,
  year,
  stratify_by = NULL,
  extrapolate_to_tract = FALSE
)

Arguments

disease

A single disease name (e.g. "gonorrhea"). Multiple diseases are not currently supported in a single request.

geography

Character scalar. One of "national", "region", "state", "county", or "msa".

year

Integer vector of years. Valid values are from 2000 to 2023. Can be a single year (e.g., 2022) or a sequence (e.g., 2018:2022).

stratify_by

Optional character vector. Zero, one, or two of "age", "race", "sex". If NULL, totals (unstratified) are returned.

extrapolate_to_tract

Logical scalar. If FALSE, return the AtlasPlus results for the requested geography. If TRUE, pass the returned data to the package's tract extrapolation workflow. Extrapolation requires that the geography be set to county.

Value

A tibble with the following columns:

indicator

Disease/condition name (factor)

year

Calendar year (numeric)

geography

Geographic unit name (factor)

data_status

Data quality flags (factor)

race_ethnicity

Race/ethnicity category (factor, if stratified)

sex

Sex category (factor, if stratified)

age

Age group (factor, if stratified)

transmission

Transmission category (factor)

rate100000

Incidence rate per 100,000 (numeric)

cases

Case count (numeric)

population

Population denominator (numeric)

lowerci_rate, upperci_rate

95\% CI bounds for rate (numeric)

rse

Relative standard error (numeric)

lowerci_cases, upperci_cases

95\% CI bounds for cases (numeric)

FIPS code (character)

Columns and naming conventions may differ depending on CDC schema changes. The function attempts to standardize but does not guarantee historical compatibility for all years.

Details

The function supports multiple diseases, geographic levels, year ranges, and optional stratification. Stratified queries expand results into all requested combinations (e.g., age by race). When possible, numeric fields are returned as double and identifiers as character.

By default, the function returns data directly from the requested AtlasPlus geography. If extrapolate_to_tract = TRUE, county-level results are post-processed into census tract-level estimates using helper functions in this package. These tract estimates are derived estimates and are not directly returned by CDC AtlasPlus.

Supported diseases

  • "chlamydia"

  • "gonorrhea"

  • "adult syphilis"

  • "congenital syphilis"

  • "tuberculosis"

  • "hiv" (will provide confirmed diagnoses)

  • "estimate" (estimated HIV counts)

  • "hepatitis"

Geography

  • "national"

  • "region"

  • "state"

  • "county"

  • "msa" (metropolitan statistical area)

Stratification The CDC AtlasPlus API supports stratification by one or two dimensions:

  • "age"

  • "race"

  • "sex"

Stratification increases the number of returned rows. For example, stratify_by = c("race", "sex") returns all race × sex combinations for each geography-year pair.

This function is a reverse-engineered wrapper around the AtlasPlus public query system. The CDC does not publish an official API specification, and internal identifiers may change without notice. If the CDC modifies the backend schema, requests may fail. Please report issues via GitHub.

See also

cdc_atlas_meta() for metadata lookup and variable dictionaries.

Examples

if (FALSE) {
# National gonorrhea rates for 2018–2022
get_atlas(disease = "gonorrhea", geography = "national", year = 2018:2022)

# State-level chlamydia, stratified by race
get_atlas(
  disease = "chlamydia",
  geography = "state",
  year = 2022,
  stratify_by = "race"
)

get_atlas(
  disease = "gonorrhea",
  geography = "county",
  year = 2022,
  extrapolate_to_tract = TRUE
)
}