Recode according to controlled terminology

ct_map() recodes a vector following a controlled terminology.

Usage

ct_map(
  x,
  ct_spec = NULL,
  ct_clst = NULL,
  from = ct_spec_vars("from"),
  to = ct_spec_vars("to")
)

Arguments

x: A character vector of terms to be recoded following a controlled terminology.
ct_spec: A tibble providing a controlled terminology specification.
ct_clst: A character vector indicating a set of possible controlled terminology codelists codes to be used for recoding. By default (NULL) all codelists available in ct_spec are used.
from: A character vector of column names indicating the variables containing values to be matched against for terminology recoding.
to: A single string indicating the column whose values are to be recoded into.

Value

A character vector of terminology recoded values from x. If no match is found in the controlled terminology spec provided in ct_spec, then x values are returned in uppercase. If ct_spec is not provided x is returned unchanged.

Examples

# A few example terms.
terms <-
  c(
    "/day",
    "Yes",
    "Unknown",
    "Prior",
    "Every 2 hours",
    "Percentage",
    "International Unit"
  )

# Load a controlled terminology example
(ct_spec <- read_ct_spec_example("ct-01-cm"))
#> # A tibble: 33 × 8
#>    codelist_code term_code CodedData term_value collected_value    
#>    <chr>         <chr>     <chr>     <chr>      <chr>              
#>  1 C71113        C25473    QD        QD         QD (Every Day)     
#>  2 C71113        C64496    BID       BID        BID (Twice a Day)  
#>  3 C71113        C64499    PRN       PRN        PRN (As Needed)    
#>  4 C71113        C64516    Q2H       Q2H        Q2H (Every 2 Hours)
#>  5 C71113        C64530    QID       QID        QID (4 Times a Day)
#>  6 C66726        C25158    CAPSULE   CAPSULE    Capsule            
#>  7 C66726        C25394    PILL      PILL       Pill               
#>  8 C66726        C29167    LOTION    LOTION     Lotion             
#>  9 C66726        C42887    AEROSOL   AEROSOL    Aerosol            
#> 10 C66726        C42944    INHALANT  INHALANT   Inhalant           
#> # ℹ 23 more rows
#> # ℹ 3 more variables: term_preferred_term <chr>, term_synonyms <chr>,
#> #   raw_codelist <chr>

# Use all possible matching terms in the controlled terminology.
ct_map(x = terms, ct_spec = ct_spec)
#> [1] "QD"      "Y"       "UNKNOWN" "BEFORE"  "Q2H"     "%"       "IU"     

# Note that if the controlled terminology mapping is restricted to a codelist
# code, e.g. C71113, then only `"/day"` and `"Every 2 hours"` get mapped to
# `"QD"` and `"Q2H"`, respectively; remaining terms won't match given the
# codelist code restriction, and will be mapped to an uppercase version of
# the original terms.
ct_map(x = terms, ct_spec = ct_spec, ct_clst = "C71113")
#> [1] "QD"                 "YES"                "UNKNOWN"           
#> [4] "PRIOR"              "Q2H"                "PERCENTAGE"        
#> [7] "INTERNATIONAL UNIT"