Package {rxref}

rxref: Tidy RxNorm utilities

Description

rxref provides tidy, API-first tools for working with RxNorm and RxClass data in R. The package helps users resolve drug names and identifiers, inspect RxNorm concepts, map between RxCUIs and NDCs, expand ingredients to product-level concepts, retrieve drug class information, and derive clinically useful product attributes.

Details

Common workflows include:

• Resolving drug names or identifiers with resolve() and search_drug().

• Retrieving concept metadata with get_properties().

• Building product-level medication lists with find_ingredients(), ingredients_for_rxcui(), and products_for_ingredients().

• Mapping between RxCUIs and NDCs with map_to(), map_ndc_to_rxcui(), and map_rxcui_to_ndc().

• Retrieving therapeutic class information with get_classes(), find_classes(), get_class_members(), get_atc(), get_epc(), and get_va().

• Deriving clinical product attributes with get_clinical_attributes() and filter_products_by_route().

Configure package behavior with rxref_conf().

Author(s)

Maintainer: Steven Smith ssmith@cop.ufl.edu

Authors:

• Steven Smith ssmith@cop.ufl.edu

See Also

Useful links:

• https://github.com/ssmithm/rxref

• https://www.stevenmsmith.org/rxref/

• Report bugs at https://github.com/ssmithm/rxref/issues

Default RxNorm product term types

Description

Returns the default RxNorm term types used by rxref when identifying drug products.

Usage

default_product_ttys()

Details

The default set is intentionally focused on product-level concepts: semantic clinical drugs, semantic branded drugs, generic packs, and branded packs.

Value

A character vector of RxNorm term type abbreviations.

Examples

default_product_ttys()

Exclude products containing specified ingredients

Description

Remove all rows for products that contain one or more user-specified ingredients. This is useful when broad ingredient-based product searches return fixed-dose combination products that contain an ingredient of interest but are not clinically relevant to a specific study definition.

Usage

exclude_products_with_ingredients(
  data,
  ingredients = NULL,
  ingredient_rxcuis = NULL,
  product_id_col = "product_rxcui",
  ingredient_name_col = "ingredient_name",
  ingredient_rxcui_col = "ingredient_rxcui",
  return_excluded = FALSE
)

Arguments

Details

Exclusions are applied at the product level. If any ingredient in a product matches the exclusion list, all rows for that product are removed.

Value

If return_excluded = FALSE, a data frame of the same general shape as data, with excluded product rows removed.

If return_excluded = TRUE, a list with:

data

The filtered data frame.

excluded

Rows from the input data belonging to excluded products.

resolved_ingredients

The ingredient names/RxCUIs used for exclusion.

Examples

## Not run: 
antihtn_clean <- antihtn_products |>
  exclude_products_with_ingredients(ingredients = "sacubitril")

antihtn_audit <- antihtn_products |>
  exclude_products_with_ingredients(
    ingredients = "sacubitril",
    return_excluded = TRUE
  )

antihtn_audit$data
antihtn_audit$excluded
antihtn_audit$resolved_ingredients

## End(Not run)

Extended RxNorm product term types

Description

Returns an extended set of RxNorm term types that includes the default product term types plus dose-form and dose-form-group concepts.

Usage

extended_product_ttys()

Details

This can be useful when a broader set of product-related RxNorm concepts is desired.

Value

A character vector of RxNorm term type abbreviations.

Examples

extended_product_ttys()

Extended RxNorm term types

Description

Returns an extended set of RxNorm term types that includes the default and extended product term types plus drug component, brand name, and ingredient concepts. This list includes essentially all term types that capture a specific ingredient, thus it excludes dose form, dose form group, prescribable name, synonyms, and others that are not associated with a specific ingredient.

Usage

extended_ttys()

Details

This can be useful when the broadest set of RxNorm concepts that still capture an ingredient is desired.

Value

A character vector of RxNorm term type abbreviations.

Examples

extended_ttys()

Filter RxNorm product concepts by route of administration.

Description

Filters a product-level rxref table using route information from get_clinical_attributes(). Useful when a drug or class includes products across multiple routes, such as oral tablets, ophthalmic solutions, injectables, patches, or topical formulations.

Usage

filter_products_by_route(
  products,
  route = "ORAL",
  keep_route_info = TRUE,
  include_historical = FALSE,
  show_progress = interactive()
)

Arguments

Value

A tibble containing only rows whose product_rxcui has at least one matching route.

Examples

## Not run: 
ing <- find_ingredients("metoprolol")

prods <- products_for_ingredients(
  ing$rxcui,
  include_combos = TRUE
)

filter_products_by_route(prods, route = "ORAL")

# Historical/current products can also be route-filtered
prods_hist <- products_for_ingredients(
  ing$rxcui,
  include_combos = TRUE,
  concept_status = "active_and_historical"
)

filter_products_by_route(prods_hist, route = "ORAL")

## End(Not run)

Find RxClass drug classes by class name

Description

Find RxClass drug classes by class name

Usage

find_classes(query, class_types = NULL)

Arguments

Value

A tibble of matching class concepts.

Resolve a free-text drug name to ingredient CUIs (IN/PIN)

Description

Uses RxNav approximateTerm, then fetches properties for each candidate and filters to ingredient-type concepts (TTY IN and, optionally, PIN).

Usage

find_ingredients(
  term,
  max_entries = 10,
  include_pin = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble with columns: input, rxcui, name, tty, score.

Examples

if (identical(Sys.getenv("RXREF_ONLINE"), "1")) {
  find_ingredients("metformin")
}

Get ATC classes for RxNorm drugs

Description

get_atc() is a convenience wrapper for get_classes() that returns Anatomical Therapeutic Chemical (ATC) class assertions for RxNorm drugs.

Usage

get_atc(
  x,
  by = c("rxcui", "name"),
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble of ATC class assertions.

Get ATC product-level classes for RxNorm drugs

Description

get_atc() is a convenience wrapper for get_classes() that returns Anatomical Therapeutic Chemical (ATC) product-level class assertions for RxNorm drugs.

Usage

get_atcprod(
  x,
  by = c("rxcui", "name"),
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble of ATCPROD class assertions.

Get chemical-structure assertions

Description

get_chemical_structure() is a convenience wrapper for get_classes() that returns chemical-structure assertions for RxNorm drugs.

Usage

get_chemical_structure(
  x,
  by = c("rxcui", "name"),
  rela_source = c("FDASPL", "DAILYMED", "MEDRT"),
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble of chemical-structure assertions.

Get RxNorm members of an RxClass class

Description

get_class_members() queries the RxClass API to identify members of a specific drug class. Typically, this would be used to identify all ingredient RxCUIs in a class, which can then be combined with other search functions to extract related product RxCUIs or NDCs.

Usage

get_class_members(
  class_id,
  rela_source,
  rela = NULL,
  include_indirect = TRUE,
  ttys = NULL
)

Arguments

Value

A tibble of RxNorm drug members.

Get RxClass assertions for RxNorm drugs

Description

get_classes() returns RxClass assertions for RxNorm concepts or drug names. These include drug-class relationships from sources such as ATC, FDASPL, DAILYMED, MEDRT, SNOMEDCT, and VA. Depending on the source and relationship, returned assertions may represent pharmacologic classes, chemical structures, mechanisms of action, physiologic effects, indications, contraindications, VA classes, ATC classes, or SNOMED CT dispositions/structures.

Because different sources use different classification logic, this function preserves class type, relationship, and relationship source rather than collapsing results into a single class label.

Usage

get_classes(
  x,
  by = c("rxcui", "name"),
  rela_source = NULL,
  relas = NULL,
  class_types = NULL,
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble with one row per RxClass assertion.

Clinical attributes from the concept (SCD/SBD) or related SCD/SBD

Description

If rxcui is already a clinical drug (TTY = SCD or SBD), parse attributes directly from its own name. Otherwise, query /rxcui/{id}/related?tty=SCD,SBD and parse.

Usage

get_clinical_attributes(
  rxcui,
  include_historical = FALSE,
  show_progress = interactive()
)

Arguments

Details

In addition to strength and dose form, this returns route, dose-form group (DFG), brand/generic flags, ingredient summaries, and a simple active/inactive status.

Note there is a fair amount of parsing of the RxNorm STR value to try to extract relevant information (e.g., strength, dose_form), so check closely before trusting. There may be edge cases that are not correctly parsed.

For combination products, ingredient-related columns may contain multiple semicolon-delimited values, such as "amlodipine; valsartan".

Value

A tibble with columns:

rxcui

Input RxCUI

related_rxcui

Clinical drug RxCUI (SCD/SBD) used for attributes

name

Clinical drug name

tty

Term type (SCD/SBD, etc.)

strength

Parsed strength string (e.g. "500 MG")

dose_form

Parsed dose form (e.g. "Extended Release Oral Tablet")

route

Route parsed from dose form / DFG (e.g. "ORAL", "INJECTION")

dose_form_group

Dose form group (DFG), if available

is_brand

Logical; TRUE for branded clinical concepts (SBD/BPCK)

is_generic

Logical; TRUE for generic clinical concepts (SCD/GPCK)

ingredient_count

Number of distinct ingredients

ingredient_rxcui

Ingredient RxCUI. For combination products, multiple values are returned as semicolon-delimited strings.

ingredient_name

Ingredient name. For combination products, multiple values are returned as semicolon-delimited strings.

ingredient_tty

Ingredient term type (IN/PIN/MIN). For combination products, multiple values are returned as semicolon-delimited strings.

is_multi_ingredient

Logical; TRUE if >1 ingredient

suppress

Raw RxNorm suppress flag from properties

status

Simple status derived from suppress: "ACTIVE" vs "INACTIVE"

Examples

## Not run: 
get_clinical_attributes(c("861007","860975")) |>
  dplyr::select(rxcui, related_rxcui, name, strength, dose_form, route, tty) |>
  head()

## End(Not run)

Get contraindication assertions from MED-RT

Description

get_contraindications() is a convenience wrapper for get_medrt() that returns only contraindication MED-RT assertions for RxNorm drugs.

Usage

get_contraindications(
  x,
  by = c("rxcui", "name"),
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble of MED-RT contraindication assertions.

Get class-like RxClass assertions for RxNorm drugs

Description

get_drug_classes() is an experimental convenience function that returns RxClass assertions that are likely to behave like drug-class labels.

It combines selected assertions from ATC, ATCPROD, FDA/SPL EPC, VA, and SNOMED CT disposition relationships. It intentionally excludes relationship types that usually describe contraindications, indications, physiologic effects, chemical structures, or other non-class assertions.

For a more compact and ingredient-oriented output, rely on defaults for include_sources. For extended list of product-level sources, consider adding "ATCPROD" and "VA".

This function is experimental because "drug class" is not a single native RxClass concept. Different sources use different classification logic, and this helper applies an opinionated filter to return class-like assertions. For source-specific results, use get_classes(), get_atc(), get_epc(), get_va(), or related functions directly.

Usage

get_drug_classes(
  x,
  by = c("rxcui", "name"),
  include_sources = c("ATC", "EPC", "SNOMEDCT"),
  collapse = TRUE,
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble of class-like RxClass assertions.

Get FDA/SPL established pharmacologic classes

Description

get_epc() is a convenience wrapper for get_classes() that returns FDA labeling class assertions for RxNorm drugs.

Usage

get_epc(
  x,
  by = c("rxcui", "name"),
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble of established pharmacologic class assertions.

Get indication/treatment assertions from MED-RT

Description

get_may_treat() is a convenience wrapper for get_medrt() that returns indications (disease assertions) from MED-RT for RxNorm drugs, when available. Note that absence of a row (or an empty table altogether) should not necessarily be interpreted as absence of an indication.

Usage

get_may_treat(
  x,
  by = c("rxcui", "name"),
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble of MED-RT may-treat assertions.

Get MED-RT assertions for RxNorm drugs

Description

get_medrt() is a convenience wrapper for get_classes() that returns MED-RT assertions for RxNorm drugs. These include, for example, asserted mechanisms of action, contraindications, physiologic effects (including adverse side effects), etc.

Usage

get_medrt(
  x,
  by = c("rxcui", "name"),
  relas = NULL,
  class_types = NULL,
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble of MED-RT assertions.

Get MED-RT mechanism-of-action assertions

Description

get_medrt_moa() is a convenience wrapper for get_medrt() that returns MED-RT mechanism-of-action assertions when available. Not all drugs have MED-RT has_moa assertions; for some drugs, mechanism-like or class-like information may instead be available from FDA/SPL EPC via get_epc() or as physiologic effects via get_medrt_pe().

Usage

get_medrt_moa(
  x,
  by = c("rxcui", "name"),
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble of MED-RT mechanism-of-action assertions.

Get MED-RT physiologic-effect assertions

Description

get_medrt_pe() is a convenience wrapper for get_medrt() that returns only physiologic effect MED-RT assertions for RxNorm drugs.

Usage

get_medrt_pe(
  x,
  by = c("rxcui", "name"),
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble of MED-RT physiologic-effect assertions.

Get core RxNorm properties for one or more RxCUIs

Description

Get core RxNorm properties for one or more RxCUIs

Usage

get_properties(rxcui, show_progress = interactive())

Arguments

Value

tibble with rxcui, name, synonym, tty, language, suppress, umlscui.

Examples

if (identical(Sys.getenv("RXREF_ONLINE"), "1")) {
get_properties(c("860975","1049630"))
}

Get VA drug classes for RxNorm drugs

Description

get_va() is a convenience wrapper for get_classes() that returns VA drug class assertions for RxNorm drugs.

Usage

get_va(
  x,
  by = c("rxcui", "name"),
  extended = TRUE,
  keep_input = TRUE,
  show_progress = interactive()
)

Arguments

Value

A tibble of VA class assertions.

Get ingredient concepts for RxCUIs

Description

Maps one or more RxCUIs to related ingredient concepts, returning ingredient RxCUIs, names, and term types. This is useful when the input is already a specific RxNorm product concept rather than a free-text drug name.

Usage

ingredients_for_rxcui(
  rxcui,
  include_pin = TRUE,
  include_min = FALSE,
  show_progress = interactive()
)

Arguments

Value

A tibble with columns rxcui, ingredient_rxcui, ingredient_name, and ingredient_tty.

Map NDCs to RxCUIs

Description

Convenience wrapper around map_to() for mapping National Drug Codes (NDCs) to RxNorm Concept Unique Identifiers (RxCUIs).

Usage

map_ndc_to_rxcui(x, show_progress = interactive())

Arguments

Details

NDCs may be supplied as 10-digit, 11-digit, or hyphenated values. Input NDCs are normalized to 11-digit format before querying RxNorm.

Value

A tibble with columns:

input

Original input NDC.

ndc11

Normalized 11-digit NDC.

rxcui

Mapped RxCUI, if found.

Examples

## Not run: 
map_ndc_to_rxcui("00093-7424-56")

## End(Not run)

Map RxCUIs to NDCs

Description

Convenience wrapper around map_to() for mapping RxNorm Concept Unique Identifiers (RxCUIs) to National Drug Codes (NDCs).

Usage

map_rxcui_to_ndc(
  x,
  status = NULL,
  history = c("active", "direct", "all"),
  show_progress = interactive()
)

Arguments

Details

By default, this function retrieves currently active NDCs associated with the supplied RxCUIs. Use history = "direct" or history = "all" to retrieve historical NDC associations.

status = NULL means that no status filter is applied after NDCs are retrieved. It does not, by itself, request historical NDCs. To retrieve historical NDCs, set history = "direct" or history = "all".

Value

A tibble with one row per RxCUI/NDC mapping.

For history = "active", returns columns:

rxcui

Input RxCUI.

ndc11

Mapped NDC.

ndc_status

NDC status returned by RxNorm, when available.

For history = "direct" or "all", the output may also include:

related_rxcui

RxCUI associated with the historical NDC record. This may differ from the input RxCUI when historical or indirect associations are retrieved.

ndc_start_date

Start date of the NDC association, when available.

ndc_end_date

End date of the NDC association, when available.

Examples

## Not run: 
# Current active NDCs
map_rxcui_to_ndc("1049630")

# NDCs ever directly associated with this RxCUI
map_rxcui_to_ndc("1049630", history = "direct")

# All historical NDCs, retaining obsolete NDCs only
map_rxcui_to_ndc(
  "1049630",
  history = "all",
  status = "OBSOLETE"
)

## End(Not run)

Map between NDCs and RxCUIs

Description

map_to() maps identifiers between National Drug Codes (NDCs) and RxNorm Concept Unique Identifiers (RxCUIs).

Usage

map_to(
  x,
  to = c("rxcui", "ndc"),
  status = NULL,
  history = NULL,
  show_progress = interactive()
)

Arguments

Details

When mapping from NDC to RxCUI, NDCs may be supplied as 10-digit, 11-digit, or hyphenated values. Input NDCs are normalized to 11-digit format before querying RxNorm.

When mapping from RxCUI to NDC, the history argument controls whether only currently active NDCs are retrieved or whether historical NDC associations are also included.

RxNorm distinguishes between currently active NDCs and historical NDC associations. The default behavior, history = "active", uses RxNorm's active NDC endpoint and preserves the earlier behavior of map_to().

To retrieve obsolete, discontinued, or otherwise historical NDCs, use history = "direct" or history = "all". Setting status = NULL does not by itself request historical NDCs; it only means that no status filter is applied after NDCs are retrieved.

Value

A tibble.

For to = "rxcui", returns one row per input NDC/RxCUI mapping with columns:

input

Original input NDC.

ndc11

Normalized 11-digit NDC.

rxcui

Mapped RxCUI, if found.

For to = "ndc" and history = "active", returns one row per RxCUI/NDC mapping with columns:

rxcui

Input RxCUI.

ndc11

Mapped NDC.

ndc_status

NDC status returned by RxNorm, when available.

For to = "ndc" and history equal to "direct" or "all", the output may also include:

related_rxcui

RxCUI associated with the historical NDC record. This may differ from the input RxCUI when historical or indirect associations are retrieved.

ndc_start_date

Start date of the NDC association, when available.

ndc_end_date

End date of the NDC association, when available.

Examples

## Not run: 
# Map an NDC to RxCUI
map_to("00093-7424-56", to = "rxcui")

# Map an RxCUI to currently active NDCs
map_to("1049630", to = "ndc")

# Map an RxCUI to all directly associated historical NDCs
map_to("1049630", to = "ndc", history = "direct")

# Map an RxCUI to all historical NDCs and retain obsolete NDCs only
map_to("1049630", to = "ndc", history = "all", status = "OBSOLETE")

## End(Not run)

Get RxNav status for NDCs

Description

ndc_status() requests the status of an NDC entry for one or more user-supplied NDC numbers. The returned status will be one "ACTIVE", "OBSOLETE", or "UNSPECIFIED". On occasion, a NULL value may be pulled (resulting in an NA in the returned tibble), when RxNorm has no status for a given NDC, or if an invalid NDC is supplied.

Usage

ndc_status(ndc, show_progress = interactive())

Arguments

Value

A tibble with three columns: ndc_input, ndc11, ndc_hyph, status

RxNorm product term type sets

Description

Returns common RxNorm term type sets used by rxref.

Usage

product_ttys(set = c("default", "extended_product", "extended"))

Arguments

Value

A character vector of RxNorm term type abbreviations.

Examples

product_ttys()
product_ttys("extended")

Expand ingredient CUIs to product CUIs that truly contain the ingredient

Description

Tries multiple RxNav endpoints and verifies candidates truly contain the queried ingredient or one of its acceptable related ingredient concepts. The function unions candidates from multiple sources, verifies ingredient containment, and reports the number of ingredients represented by each product concept.

Usage

products_for_ingredients(
  ingredient_rxcui,
  ttys = .rxref_default_ttys,
  route = NULL,
  include_combos = TRUE,
  concept_status = c("active", "active_and_historical"),
  historical_status = c("Obsolete", "Remapped", "Quantified", "NotCurrent"),
  show_progress = interactive()
)

Arguments

Value

A tibble with one row per matched ingredient/product concept pair. For concept_status = "active", columns include ingredient_rxcui, product_rxcui, name, tty, and n_ingredients. When concept_status = "active_and_historical", additional columns include concept_status, active_start_date, active_end_date, release_start_date, and release_end_date.

Resolve free text, RxCUI, or NDC to RxCUI and preferred name

Description

Vectorized over x. For free text, uses RxNorm approximateTerm. For NDC, uses findRxcuiById. For RxCUI, validates and returns properties.

Usage

resolve(
  x,
  type = c("auto", "name", "rxcui", "ndc"),
  max_entries = 1,
  show_progress = interactive()
)

Arguments

Value

A tibble with columns: input, type, rxcui, name, tty, score (if name), ndc11 (if ndc input), matched_term (if name input)

Get RxClass relationship sources

Description

Get RxClass relationship sources

Usage

rxclass_rela_sources()

Value

A tibble of RxClass relationship sources.

Get RxClass relationship types

Description

rxclass_relas() is a helper function that queries the RxClass API for generally valid relationships within the data. Note that just because a relationship is generally valid within a rela_source, not every drug or RxCUI will have a corresponding relationship asserted.

Usage

rxclass_relas(rela_source)

Arguments

Value

A tibble of relationship names for the selected source.

Summarize RxClass relationship types for drugs

Description

rxclass_relationships() is a diagnostic helper that evaluates the type(s) of relationship (rela) asserted in RxNorm MED-RT data and the number within each relationship asserted. In some cases, get_medrt() or its various convenience wrappers may return empty or shorter-than-expected tibbles because some relationships expected by the user are not asserted in RxNorm (for example, an MOA may not be asserted by MED-RT).

Usage

rxclass_relationships(
  x,
  by = c("rxcui", "name"),
  rela_source = NULL,
  show_progress = interactive()
)

Arguments

Value

A tibble summarizing available relationship/class-type combinations.

Configure rxref

Description

Configure rxref

Usage

rxref_conf(
  base_url = getOption("rxref.base_url"),
  rate_delay = getOption("rxref.rate_delay"),
  cache = getOption("rxref.cache")
)

Arguments

Value

A named list of current settings

Search free-text drug name and return product CUIs and/or NDCs

Description

High-level convenience: free text -> ingredient(s) (IN/PIN) -> verified product CUIs, and optionally expand to NDCs with status filtering.

Usage

search_drug(
  term,
  return = c("rxcui", "ndc", "both"),
  ndc_status = NULL,
  ttys = .rxref_default_ttys,
  route = NULL,
  show_progress = interactive(),
  ...
)

Arguments

Value

If return="rxcui": tibble of products. If "ndc": tibble of NDCs with ingredient_rxcui, product_rxcui, ndc11, ndc_status. If "both": list(products=…, ndcs=…).

Catalogue of RxNorm TTY (Term Types)

Description

Returns a tibble describing common RxNorm TTYs you may want to use when expanding ingredients to products. Includes whether each TTY typically maps cleanly to NDCs and whether it's included in the package's default or extended TTY sets.

Usage

tty_catalogue()

Details

Columns:

• tty: RxNorm term type code.

• label: Short, human-friendly name.

• description: What the TTY represents in RxNorm.

• maps_to_ndc: Logical; whether CUIs of this TTY usually map to NDCs via ⁠/rxcui/{rxcui}/ndcs⁠.

• typical_role: How it’s commonly used (product, component, group, name).

• include_default: Logical; included in .rxref_default_ttys.

• include_extended: Logical; included in .rxref_extended_ttys.

Value

A tibble with metadata for key TTYs.

Examples

tty_catalogue()

# TTYs that map to NDCs
subset(tty_catalogue(), maps_to_ndc)$tty

# See what your defaults and extended sets contain
subset(tty_catalogue(), include_default)$tty
subset(tty_catalogue(), include_extended)$tty

# Pick a custom set: products + components
with(tty_catalogue(),
     tty[tty %in% c("SCD","SBD","GPCK","BPCK","SCDC","SBDC")])