Skip to contents

Getting started with ComptoxR

Source: vignettes/articles/getting-started.Rmd
getting-started.Rmd

ComptoxR provides R functions for querying the U.S. EPA CompTox Chemical Dashboard and related services. This guide assumes that you are new to R packages or API-based data access.

Install ComptoxR

Run this once in the R console:

install.packages("pak")
pak::pkg_install("seanthimons/ComptoxR")

Load the package whenever you start a new R session:

Configure access

Some services require an API key. Request one by emailing ccte_api@epa.gov with the subject API Key Request.

For a persistent setup, open your user .Renviron file:

file.edit("~/.Renviron")

Add the following line, replacing the placeholder with your key:

ctx_api_key=YOUR_KEY_HERE

Save the file and restart R. Then check the setup:

Do not put an API key directly in a script that you share or commit.

Retrieve your first chemical record

Many functions accept a DTXSID, CAS number, chemical name, or another chemical identifier. For example:

benzene <- ct_chemical_detail_search("DTXSID7020182")
dplyr::glimpse(benzene)

The DTXSID is the stable join key for the workflows in this series. For several identifiers, use the bulk function:

chemicals <- ct_chemical_detail_search_bulk(
  query = c("DTXSID7020182", "DTXSID9020243")
)
dplyr::glimpse(chemicals)

The returned object is normally a tibble. Use standard R tools to inspect the columns and rows:

head(chemicals)

Use ct_chemical_detail_search() when you need one chemical record. Use ct_chemical_detail_search_bulk() for a vector of identifiers.

Continue with Building a CCD Chemical Profile to add properties, fate, hazard, exposure, and bioactivity evidence.

Find the right function

The reference lists all exported functions. The function names use prefixes to show the service family:

  • ct_ functions query CompTox Chemical Dashboard services.
  • chemi_ functions query cheminformatics and chemical-service APIs.
  • dss_, eco_, and toxval_ functions work with local EPA databases.
  • epi_ and genra_ functions access prediction services.

Start with a single chemical and a small result. Then move to batch functions when the single-query version works for your data.

Troubleshooting

Use verbose mode to see progress:

Use debug mode to inspect a request without sending it:

run_debug(TRUE)

Both settings apply only to the current R session.