Manually specified decodings

decode is a generic S3-function that accepts R-object of different kinds. The default method takes an atomic vector with codes and a specification of how to translate these codes (see ?decode).

# the package is automatically attached by the rcc package.
# Use 'library(rcc)' if you have the rcc package installed or
# attach only the decoder package by:
library(decoder)

decode(incadata$KON_VALUE, "kon")

## [1] "Kvinna" "Kvinna" "Kvinna" "Kvinna" "Man"    "Man"

decode(incadata$a_tstad, "t_rtr")

## [1] "T0"  "T1"  "T1a" "T1b" "T1c" "T2"

See ?key_value_data for a list of all available keyvalue objects included in the package.

The whole data.frame at once

There is also a method for data.frames, where translations are made automatically for columns with recognised names.

incadata_decoded <- decode(incadata)

## 
## New decoded columns added: 
## * KON_VALUE_beskrivning
## * region_beskrivning

knitr::kable(incadata_decoded)

All the original columns from incadata are preserved but are now accompanied by some additional columns with identical names suffixed by “_beskrivning“. (”_Beskrivning" with capital “B” will be used if there are already some column names with suffixes “_Beskrivning" or “_Värde" in the data, otherwise lower case variable names are generally preffered in all the rcc packages).

Several keyvalues for the same code

Note that the same coded variable might be decoded by more than one keyvalue-object, for example the “a_icdo3”-variable is automatically decoded by the “icdo3” keyvalue object (see ?icdo3) with a dictionary from Rockan. ICD-O3 however, can also be seen as a “developed subset” of ICD10, wherefore:

decode(incadata$a_icdo3, "icd10")

## [1] "Malign tumör i huden på övre extremiteten inklusive skuldran"                  
## [2] "Icke specificerad lokalisation av malign tumör i binjure"                      
## [3] "Icke specificerad lokalisation av malign tumör i esofagus"                     
## [4] "Icke specificerad lokalisation av malign tumör i centrala nervsystemets hinnor"
## [5] "Malign tumör i perifera nerver i bäckenet"                                     
## [6] "Malign tumör i glottis"

“icd10”, can also decode non oncological desease codes:

decode(c("D448A", "T009", "F182", "S134C", "C131"), "icd10")

## [1] "Tumör med multiglandulär lokalisation, Typ I"                                                  
## [2] "Multipla ytliga skador, ospecificerade"                                                        
## [3] "Psykiska störningar och beteendestörningar orsakade av flyktiga lösningsmedel, beroendesyndrom"
## [4] "Whiplash-skada, WAD III"                                                                       
## [5] "Malign tumör i aryepiglottiska vecket, hypofaryngeala delen"

Exact versus non exact decoding

So far, we have looked only on cases where the code can be littaraly translated by the keyvalue object. There is however a third argument to the decode function, exact, which is FALSE by default. It is often useful to allow some automatic transformation for variables that we know are coded values but that are not exactly the same as in the keyvalue object. The most common application is probably when we want to extract the municipality names from an LKF-variable. This can obviosly be done by:

x <- c(178405, 138408, 108202, 128706, 048005)
y <- as.numeric(substring(as.character(x), 1, 4))
decode(y, "kommun", exact = TRUE)

## Warning: Some codes could not be translated using "kommun" as keyvalue
## object (4800)

## [1] "Arvika"     "Kungsbacka" "Karlshamn"  "Trelleborg" NA

But it is also possible to use the original six digit code as is:

decode(x, "kommun")

## Warning in format_as_key(x, keyvalue, name_x, name_keyvalue): x has been
## transformed to match the code for kommun: Only the first 4 characters are
## used.

## Warning: Some codes could not be translated using "kommun" as keyvalue
## object (48005)

## [1] "Arvika"     "Kungsbacka" "Karlshamn"  "Trelleborg" NA

Note here that the last value decodes to NA in both cases. It would be preffered to have the original codes stored as character, since that preserves the leading 0 in “048005”:

decode("048005", "kommun")

## Warning in format_as_key(x, keyvalue, name_x, name_keyvalue): "048005" has
## been transformed to match the code for kommun: Only the first 4 characters
## are used.

## [1] "Nyköping"

This can also be taken care of by reading data through the use_incadata function (see ?incadata::use_incadata), which always classifies numbers with leading zeros as characters (and not numeric) (but this will not be covered in this vignette).

Note that use of exact = FALSE (which is the default for convenience) always produce warnings when some transformations are done. It is always recommended to manually confirm that these transformations are in fact accurate. Unexpected results might otherwise occur!

More than one decoded variable from the same code

Using non exact decoding, the same code might be simultaneously decoded by more that one keyvalue object using the data.frame method:

df <- data.frame(LKF = c("149804", "147104", "012704", "143505", "126502", "232602"))
knitr::kable(suppressWarnings(decode(df)))

## 
## New decoded columns added: 
## * LKF_forsamling_beskrivning
## * LKF_hemort_beskrivning
## * LKF_kommun_beskrivning
## * LKF_lan_beskrivning

Consult ?hemort and ?forsamling to invest the differnce between these two variables (hint: a lot have happened with Swedish administrative geography since 1958).

Extra functions

The atomic vector method has an additional argument extra_functions that can be used to modify the outcome of the decoded variable. Read the man page (?decode) for more details and a complete list of available extra functions.

The default regional names used from INCA are used by default by the “region” keyvalue:

decode(1:6, "region")

## [1] "Region Sthlm/Gotland"  "Region Uppsala/Örebro" "Region Sydöstra"      
## [4] "Region Syd"            "Region Väst"           "Region Norr"

Sometimes it is however more convenient to use an abbriviated form of these names such as:

decode(1:6, "region", "short_region_names")

## [1] "Sthlm/Gotland"  "Uppsala/Örebro" "Sydöstra"       "Syd"           
## [5] "Väst"           "Norr"

This could also be achieved by an additional keyvalue object containing the hard coded short names but an additional advantage with the “extra_function” method is that several extra functions can be chained:

munic_west <- c("1382", "1419", "1441", "1460", "1472", "1488", "1496")
decode(munic_west, "sjukvardsomrade", c("kungalv2Storgoteborg", "real_names"))

## [1] "Norra Halland"  "Storgöteborg"   "Södra Älvsborg" "Fyrbodal"      
## [5] "Skaraborg"      "Fyrbodal"       "Skaraborg"