decoder (version 1.1.0)

code: Decode codes to plain text (and vice versa)

Description

Translate coded values into meaningful plain text (or reversed). Use list_keyvalues() to see a list of all keyvalue objects ("dictionaries") included in the package.

Usage

code(y, keyvalue, verbose = TRUE)
decode(x, ...)
"decode"(x, ...)
"decode"(x, keyvalue, extra_functions = NULL, exact = FALSE, ...)
list_keyvalues()

Arguments

y

value to be coded (to be matched againt the value element) in a keyvalue object.

keyvalue

either a name (as character string) of one of the keyvalue objects listed here: key_value_data, or a user defined keyvalue object (see as.keyvalue).

verbose

(only for code) can be set to FALSE to avoid a printed message to the console if an error occur (TRUE as default).

x

object to decode. Either a key vector to be matched againt the key column in keyvalue, or a data.frame (see section decode.data.frame). object.

...

ignored

extra_functions

is a list of functions (or names of functions as character vector) to be applied to the decoded data after decoding (see section "extra_functions" below).

exact

Should x have an exact match from the key? Default is FALSE. When FALSE, x might be transformed to fit the key (punctuation might be removed, upper case changed to lower case or vice versa and strings that are too long might be substringed). (code only accept excact matches.)

Value

• For default S3 method: A vector of the same length as x but with all cells decoded (or coded) to plain text (or code) as character.
• For S3 method for class 'data.frame': Data.frame x is returned, possibly with some extra columns (names ending in '_Beskrivning'), decoded from columns with names corresponding to attribute standard_var_names for keyvalue objects listed by list_keyvalues().

Vignette

See the vignette for a longer introduction to the package: vignette("decoder")

decode.data.frame

If x is a data.frame, all column names of x are matched to attribute standard_var_names for all keyvalue objects in the package (see list_keyvalues()). If the column name is a standard name used for a coding, the corresponding keyvalue object is used to decode the column and to add an extra column to x with its original name with suffix _Beskrivning. This is done for all identified columns. Please report additional suggestions of standard names to https://github.com/cancercentrum/decoder/issues.

extra_functions

The relationship betwen the key and the value in a keyvalue object is either 1:1 or m:1. The mapping is straight forward for 1:1 but with m:1, different applications might require slightly different groupings of the keys. One solution is to have several versions of the keyvalue object. Another (which we prefer) is to use the same keyvalue object (if possible) but to call one or several extra function(s) to further process the result. These functions are either built in package functions that should be called by quoted names or user defined functions that can be called by either quoted or unquoted names (if available in the current environment). Note that the order of the functions could matter since they are called in turn (the output from the first function is passed as input to the second function etc). Standard functions and how to use them: To use with sjukvardsomrade:

kungalv2Fyrbodal

The default classification used in sjukvardsomrade is to make Kungalv a region of its own. Use this function if Kungalv should be included in Fyrbodal. See example section below.

kungalv2Storgoteborg

As kungalv2Fyrbodal but classifies Kungalv as a part of Storgoteborg.

real_names

Give the area names with correct Swedish spelling (including spaces). This is not as default due to compability reasons and because names with spaces must be back-ticked when reffered to.

To use with region

short_region_names

Exclude the prefix 'Region' from the region names, hence 'Syd' instead of 'Region Syd' etcetera.

See Also

key_value_data, keyvalue, extra_functions

Examples

# We can start to list all available keyvalue objects included in the package:
list_keyvalues()

KON_VALUE <- sample(1:2, 20, replace = TRUE)
(kon <- decode(KON_VALUE, "kon"))
code(kon, "kon")

# Get a sample of Snomed-codes (in the real world we obviously avoid this step) ...
snomed2 <- sample(decoder:::snomed$key, 30, replace = TRUE)
# ... then decode them:
(snomed3 <- decode(snomed2, "snomed"))


# Health care regions can be defined in more than one way
# By default Kungalv define a region of its own:
set.seed(123456789)
healtcare_areas_west <- sample(unlist(decoder:::sjukvardsomrade), 100, replace = TRUE)
(areas <- decode(healtcare_areas_west, "sjukvardsomrade"))
table(areas)

# But if we want Kungalv to be a part of Storgoteborg
# (which is common practice for example with lung cancer data):
(areas2 <- decode(healtcare_areas_west, "sjukvardsomrade", "kungalv2Storgoteborg"))
table(areas2)

# We can also combine several extra_functions if we for example
# also want the area names with correct Swedish spelling.
(areas3 <- decode(healtcare_areas_west, "sjukvardsomrade", c("kungalv2Storgoteborg", "real_names")))


# The region names can be both with and without prefix:
regs <- sample(6, 10, replace = TRUE)
decode(regs, "region") # With prefix
decode(regs, "region", "short_region_names") # without prefix

# Note that only the first four digits of the LKF-code were used abowe?
# What if we use the full LKF-code?
lkfs <- sample(decoder:::forsamling$key, 100, replace = TRUE)
decode(lkfs, "sjukvardsomrade")
# That work's just as fine when argument exact = FALSE (which it is by default).

# decode can also be used for data.frames with recognised column names
d <- data.frame(
     kon = sample(1:2, 10, replace = TRUE), 
     sex = sample(1:2, 10, replace = TRUE),
     lkf = sample(decoder:::hemort$key, 10, replace = TRUE)
 )
 decode(d)

### --- code --- ###
# Sometimes we have keyvalue objects with some key-value pairs without a 1:1 relation.
# This is true for snomed
# Show all non 1:1 pairs:
summary(decoder:::snomed)$nonunique
# Save them for later:
non_unique_snomeds <- summary(decoder:::snomed)$nonunique$key

# Use these snomed codes for decoding and coding
# Decoding works fine (all keys are unique) ...
(a <- decode(non_unique_snomeds, "snomed"))
# ... but coding these values back to their key does not

code(a, "snomed")