Package 'decoder' reference manual

Title:	Decode Coded Variables to Plain Text and the Other Way Around
Description:	Main function "decode" is used to decode coded key values to plain text. Function "code" can be used to code plain text to code if there is a 1:1 relation between the two. The concept relies on 'keyvalue' objects used for translation. There are several 'keyvalue' objects included in the areas of geographical regional codes, administrative health care unit codes, diagnosis codes and more. It is also easy to extend the use by arbitrary code sets.
Authors:	Erik Bulow [aut, cre]
Maintainer:	Erik Bulow <[email protected]>
License:	GPL-2
Version:	1.2.2
Built:	2024-11-01 11:39:47 UTC
Source:	CRAN

Coerce to key or value in objects in a key-value pair

Description

Functions to check if an object is a valid key or value in a keyvalue pair, or coerce it if possible.

Usage

as.key(x)

is.key(x)

as.value(x)

is.value(x)
as.key(x)

is.key(x)

as.value(x)

is.value(x)

Arguments

x

a vector

Value

as.value returns a value-object (currently the vector itself but with class "value"). as.key returns a key-object (building on value but with unique entries and as character).

Coerce a list to keyvalue object

Description

x should be a list with properties described in section "Details".

Usage

## S3 method for class 'list'
as.keyvalue(x, ...)
## S3 method for class 'list'
as.keyvalue(x, ...)

Arguments

`x`	a `list` with properties described in the details section.
`...`	further arguments passed to `as.keyvalue`.

Details

All names of the list elements should be unique.
All elements of the list should be named.
All keys should be unique (a key should only be mappad to one value).
All elements of the list should be atomic vectors.

Value

The function returns an object of class keyvalue (and list.

Examples


ex <- list(
 fruit  = c("banana", "orange", "kiwi"),
 car    = c("SAAB", "Volvo", "taxi", "truck"),
 animal = c("elephant")
)
as.keyvalue(ex)
is.keyvalue(ex)

ex <- list(
 fruit  = c("banana", "orange", "kiwi"),
 car    = c("SAAB", "Volvo", "taxi", "truck"),
 animal = c("elephant")
)
as.keyvalue(ex)
is.keyvalue(ex)

Anatomical Therapeutic Chemical (ATC) Classification System codes

Description

Key-value codes for ATC from the Swedish Medical Products Agency (2020-04-07).

Source

https://nsl.mpa.se/

Decode codes to plain text (and vice versa)

Description

Translate coded values into meaningful plain text (or reversed).

Usage

code(y, keyvalue, verbose = TRUE)

decode(x, ...)

## S3 method for class 'data.frame'
decode(x, ...)

## Default S3 method:
decode(x, keyvalue, extra_functions = NULL, exact = FALSE, ...)
code(y, keyvalue, verbose = TRUE)

decode(x, ...)

## S3 method for class 'data.frame'
decode(x, ...)

## Default S3 method:
decode(x, keyvalue, extra_functions = NULL, exact = FALSE, ...)

Arguments

`y`	value to be coded (to be matched against the `value` element) in a keyvalue object.
`keyvalue`	either a name (as character string) of a package internal keyvalue object, 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 against 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 exact 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.

extra_functions

The relationship between 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 compatibility reasons and because names with spaces must be back-ticked when referred to.

To use with region

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

Author(s)

Erik Bulow

Examples


KON_VALUE <- sample(1:2, 20, replace = TRUE)
(kon <- decode(KON_VALUE, decoder::kon))
code(kon, decoder::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)
KON_VALUE <- sample(1:2, 20, replace = TRUE)
(kon <- decode(KON_VALUE, decoder::kon))
code(kon, decoder::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)

Swedish district codes

Description

Key-value codes for the Swedish districts (introduced 2016-01-01).

Source

https://www.scb.se/hitta-statistik/regional-statistik-och-kartor/regionala-indelningar/distrikt/

Extra functions to apply to decoded variables using decode

Description

See section "extra_functions" at the decode help page!

Usage

kungalv2Storgoteborg(x)

kungalv2Fyrbodal(x)

real_names(x)

short_region_names(x)
kungalv2Storgoteborg(x)

kungalv2Fyrbodal(x)

real_names(x)

short_region_names(x)

Arguments

`x`	The decoded variable to be further processed. This argument should not be set by the user. It is used only internally by the function from which it is called.

FIGO-stadium

Description

Key-value codes for FIGO-stadium (Tumorutbredning enl FIGO, sep 2003). Data from Rockan (Rocen).

Swedish parish codes

Description

Key-value codes for the Swedish parishes (forsamlingar). All six digits in the LKF code.

Source

https://www.scb.se/hitta-statistik/regional-statistik-och-kartor/regionala-indelningar/lan-och-kommuner/

hemort and hemort2 codes (geographical codes)

Description

Both hemort and hemort2 combines regional codes for lan, kommun and forsamling. hemort is the official (but rather old) code used within RCC. hemort2 is an updated version combining lan, kommun and forsamling

HSN code (Hälso- och sjukvårdsnamnd)

Description

Key-value codes for the HSN:s in VGR valid from 2015. Based on municipality codes (kommun). Data from 2014-12-17.

Details

Categorization:

Norra: Lysekil, Munkedal, Orust, Sotenäs, Strömstad, Tanum, Bengtsfors, Dals-Ed, Färgelanda, Mellerud, Åmål, Trollhättan, Uddevalla och Vänersborg
Västra: Lilla Edet, Ale, Kungälv, Stenungsund, Tjörn, Öckerö, Härryda, Mölndal, Partille, Lerum och Alingsås
Södra: Herrljunga, Vårgårda, Bollebygd, Borås, Mark, Svenljunga, Tranemo och Ulricehamn
Göteborg: Göteborg
Östra: Essunga, Falköping, Grästorp, Götene, Lidköping, Skara, Vara, Gullspång, Hjo, Karlsborg, Mariestad, Skövde, Tibro, Tidaholm och Töreboda

ICD-10-CM code

Description

Key-value codes for ICD-10-CM 2020. Note that key codes are given without dots, i e C569, not C56.9.

Source

ftp://ftp.cdc.gov/pub/Health_Statistics/NCHS/Publications/ICD10CM/2020/

ICD-10-SE code

Description

Key-value codes for ICD-10-SE 2020 (Swedish version). Note that key codes are given without dots, i e C569, not C56.9.

Source

https://www.socialstyrelsen.se/utveckla-verksamhet/e-halsa/klassificering-och-koder/kodtextfiler/

ICD-7

Description

Key-value codes for ICD-7. Data from Rockan (Rocen).

ICD-7 Grov

Description

Key-value codes for just the first three digits of the ICDO-7 code. This gives broader grouping.

ICD-9

Description

Key-value codes for ICD-9. Data from Rockan (Rocen).

ICD-9-CM diagnosis and procedure codes

Description

Key-value codes for ICD-9-CM diagnostics (icd9cmd) and procedure (icd9cmp) codes (version 32).

Source

https://www.cms.gov/Medicare/Coding/ICD9ProviderDiagnosticCodes/codes

ICD-O

Description

Key-value codes for ICD-O. Data from Rockan (Rocen).

ICD-O3

Description

Key-value codes for ICD-O3. Data from Rockan (Rocen).

ICD-O3 Grov

Description

Key-value codes for just the first two digits of the ICDO-3 code. This gives broader grouping. Based on the table of contents from: http://www.socialstyrelsen.se/Lists/Artikelkatalog/Attachments/19446/2014-5-12.pdf

Coerce to a keyvalue object

Description

Functions to check if an object is a keyvalue object, or coerce it if possible.

Usage

as.keyvalue(x, ...)

## S3 method for class 'data.frame'
as.keyvalue(x, standard_var_names = NULL, ...)

## Default S3 method:
as.keyvalue(x, y, ...)

is.keyvalue(x)
as.keyvalue(x, ...)

## S3 method for class 'data.frame'
as.keyvalue(x, standard_var_names = NULL, ...)

## Default S3 method:
as.keyvalue(x, y, ...)

is.keyvalue(x)

Arguments

`x`	object to test for, or coerce to, keyvalue (see the details).
`...`	arguments passed between methods
`standard_var_names`	a character vector with standard names for variables decoded with this key-values.
`y`	a value vector if `x` is an unnamed vector (argument must be named 'y = .')

Details

x can be of:

a name of a package internal (or external) keyvalue object (character of length one)
a data.frame with two columns "key" (with unique cells) and "value".
a list as described in as.keyvalue.list
a named vector with all names unique
an unnamed vector with unique cells if supplemented by additional vector (y)

Value

as.keyvalue returns a data.frame with additional class keyvalue that fulfills the requirements for a keyvalue object and with the key column as character. It also has two extra attributes standard_var_names as described above and keyvalue11 which is TRUE for keyvalue objects with a 1:1 relation between its keys and values (otherwise FALSE).

Examples

snomed2 <- as.keyvalue(snomed)
is.keyvalue(snomed2)
summary(snomed2)
snomed2 <- as.keyvalue(snomed)
is.keyvalue(snomed2)
summary(snomed2)

Clinic codes

Description

Key-value codes for the Swedish clinic types. Data mainly from url below (taken from the PDF). Some extra codes are added from Rockan (290, 291, 292, 446, 921 and 999 for unknown).

Swedish municipality codes

Description

Key-value codes for the Swedish municipalities. First four digits in the LKF code. Data from 2014-08-12.

Source

https://www.scb.se/hitta-statistik/regional-statistik-och-kartor/regionala-indelningar/lan-och-kommuner/

Gender code (kon)

Description

Key-value codes for gender (1 = man (Male) and 2 = Kvinna (female)). Be aware of the spelling ("kon")!

Klassifikation av vardatgarder (KVA)

Description

Key-value codes for KVA (for surgery and medicine.

Source

https://www.socialstyrelsen.se/utveckla-verksamhet/e-halsa/klassificering-och-koder/kva/

Swedish county codes

Description

Key-value codes for the Swedish counties (lan). Two first digits of the LKF code. Be aware of the spelling ("lan")!

M-stadium

Description

Key-value codes for M-stadium (sep-03). Data from Rockan (Rocen).

N-stadium

Description

Key-value codes for N-stadium (sep-03). Data from Rockan (Rocen).

PAD (C24) code

Description

Key-value codes for PAD (C24) Data from Rockan 2012-09-18.

Pad leading zeros to character

Description

Pad leading zeros to character

Usage

pad0(x, n)
pad0(x, n)

Arguments

`x`	character or object that can be coerced to such
`n`	desired length of outcome vector

Value

Character vector of length n

Pathology department codes

Description

Key-value codes for the Swedish "laboratories". Data is combined from two sources.

The official list from SOFS 2006:15 (see url below). This is the primary source for codes appearing in both sources.
Extra codes are also added from the old Rockan registry for historical reasons.

Swedish health care regional codes

Description

Key-value codes for the Swedish health care regions (1-6).

Help tables from Rockan

Description

Key-value codes from old help tables used with Rockan (by Swedish regional cancer centers)

Sida

Description

Key-value codes for sida (Sida, 1 = Hoger, 2 = Vanster, 9 = Okant). Data from Rockan (Rocen).

Hospital codes

Description

Key-value codes for Swedish hospitals and some primary health care units.

Details

Data from 'Rockan'. Note that this is an old version of the classification! See the reference link below for the new version. The old version should be used of historical reasons. One difference is for example that the Sahlgrenska university hospital is one hospital in the new version of the classification but the Swedish regional cancer centers still classify it as three different hospitals. Note also that primary health care units did receive their own codes until 1992 (?) but not later!

Hospital codes used by INCA

Description

Codes taken from INCA's organizational register 2017-02-03.

Hospital codes used by Socialstyrelsen and the National Patient Register

Description

Codes taken from Excel sheets 2014 from link below.

Geographical health care areas

Description

Key-value codes for health care areas.

Details

Key: the first four digits from the LKF-code
Value: A geographical area (sub area of county/lan) with special interest

The object currently only applies to the Western health care region

Storgoteborg
Fyrbodal
Sodra_Alvsborg
Skaraborg
Norra_Halland

Updates for other regions needs to be requested (please do!).

Kungalv

Kungalv is an independent area by default. There are situations when Kungalv should be dealt with as an independent health care region or as a part of greater Gothenburg. See section "extra_functions" in decode to handle this.

Snomed code

Description

Key-value codes for Snomed. Data from Rockan 2012-10-05. Note tht this variable is the same as snomed from Rockan. It should not be confused with the later version snomed3!

Snomed 3

Description

Key-value codes for Snomed3 (fr 2005). Data from Rockan (Rocen).

Object summary for keyvalue objects

Description

Objects of type keyvalue11 are summarized as data.frames with an additional display of possible standard_var_names. Objects of type keyvalue also gives a list of non 1:1 key-value pairs.

Usage

## S3 method for class 'keyvalue'
summary(object, ...)
## S3 method for class 'keyvalue'
summary(object, ...)

Arguments

`object`	a keyvalue object
`...`	ignored

Value

A list with three elements: a summary of the underlying data.frame, the standard_var_names and possibly a data.frame with all non 1:1 relations.

T-stadium

Description

Key-value codes for T-stadium (sep 2003). Data from Rockan (Rocen).

Grund till TNM (patologisk/klinisk)

Description

Key-value codes for TNM-grund (Grund till TNM, 1=patologisk, 2=klinisk). Data from Rockan (Rocen).

Package 'decoder'

Help Index

Coerce to key or value in objects in a key-value pair

Description

Usage

Arguments

Value

Coerce a list to keyvalue object

Description

Usage

Arguments

Details

Value

See Also

Examples

Anatomical Therapeutic Chemical (ATC) Classification System codes

Description

Source

See Also

Decode codes to plain text (and vice versa)

Description

Usage

Arguments

Value

Vignette

decode.data.frame

extra_functions

Author(s)

See Also

Examples

Swedish district codes

Description

Source

See Also

Extra functions to apply to decoded variables using decode

Description

Usage

Arguments

FIGO-stadium

Description

See Also

Swedish parish codes

Description

Source

See Also

hemort and hemort2 codes (geographical codes)

Description

See Also

HSN code (Hälso- och sjukvårdsnamnd)

Description

Details

See Also

ICD-10-CM code

Description

Source

See Also

ICD-10-SE code

Description

Source

See Also

ICD-7

Description

See Also

ICD-7 Grov

Description

See Also

ICD-9

Description

See Also

ICD-9-CM diagnosis and procedure codes

Description

Source

See Also

ICD-O

Description

See Also

ICD-O3

Description

See Also

ICD-O3 Grov