doseconvert: Convert a Set of Dosage Texts to Structured Dosage...

Description Usage Arguments Details Value Note Author(s) References See Also Examples

View source: R/algorithm.R

Description

Calls interpret on each individual dose string, to extract structured information such as quantity, frequency and units.

Usage

1
2
3
4
doseconvert(text, textid = seq_along(text), dosage_mg = NULL,
    simplify = TRUE, singlewords = NULL, multiwords = NULL,
    patterns = NULL, maxifchoice = TRUE, usebuiltinlookups = TRUE,
    customlookups = NULL, cores = 1, noisy = FALSE)

Arguments

text

Dosage strings to be interpreted.

textid

Optional vector of text or numeric identifiers for the dosage strings.

dosage_mg

Optional vector of numeric milligram dose quantities for each prescription item.

simplify

FALSE if multiple periods with different doses should be returned as separate doses; TRUE if they should be combined into a single dose (default), thus returning one row per original dosage text.

singlewords

A drugdose_singlewords object or file path to the singlewords dictionary. If NULL it is loaded from the package data directory.

multiwords

A drugdose_multiwords object or file path to the multiwords dictionary. If NULL it is loaded from the package data directory.

patterns

A drugdose_patterns object or file path to the patterns dictionary. If NULL it is loaded from the package data directory.

maxifchoice

Whether to return the maximum dose if there is a choice of dose (e.g. 1 or 2 tablets daily). If FALSE, the average is returned.

usebuiltinlookups

Whether to use the lookup table of exact dose strings and their conversion included in the package.

customlookups

A drugdose_lookups object or file path to the a custom lookups table. This may consist of errors that you have found and corrected, for which you would like the algorithm to use the correct interpretation in the future. This lookup table is in the same format as the output

cores

Number of cores to use, for multiprocessor machines running R on Linux. The 'parallel' package must be loaded in order to use more than one core.

noisy

TRUE or FALSE - whether to print debug information to console.

Details

This function calls interpret repeatedly to analyse individual dosage texts. First it compiles a list of unique dosage texts to be analysed, so that each is interpreted only once. If usebuiltinlookups = TRUE and a text is found in the lookups table, or if it is in the customlookups table, the pre-analysed output is returned, otherwise the interpret function is called to analyse the text.

Value

Data frame with the following columns:

textid

numeric or character; text identifier

order

numeric; if simplify = TRUE, this column contains '1'. If simplify = FALSE, there may be multiple result lines per text entry, and this column states the order of the result lines.

qty

numeric; dose quantity

units

numeric; dose units

units

character; dose units

freq

numeric; dose frequency per time period

tot

numeric; total dose per time period

max

factor with 3 levels: max, average, exact

time

numeric; time interval in number of days

change

factor with 3 levels: first, second, nochange, combined. If doses for different time periods combined using simplify = TRUE, change states which dose contributes to the output.

choice

factor with 3 levels: choice, asneeded, nochoice

duration

numeric; duration of prescription

daily_dose

numeric; calculated daily dose (0 = missing)

If simplify = TRUE, the row.names are the ids if supplied, or equal to the row numbers otherwise. If simplify = FALSE, the row.names are ids.X where X (=1, 2, 3 etc.) is the order of the partial dose if ids are supplied, or equal to the row numbers otherwise.

Note

Converted from the original Visual Basic algorithm.

Author(s)

Anoop Shah

References

Shah AD, Martinez C. An algorithm to derive a numerical daily dose from unstructured text dosage instructions. Pharmacoepidemiol Drug Saf 2006; 15(3): 161-166. doi: 10.1002/pds.1151 http://onlinelibrary.wiley.com/doi/10.1002/pds.1151/

See Also

interpret, testdoseconvert

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# Using default dictionaries (loaded each time by function)
doseconvert(c('2 tab twice daily',
    'one daily for 1 week then two daily'),
    textid = 1:2, simplify = FALSE)
doseconvert(c('2 tab twice daily', '2 drops in left eye qds',
    '5mcg daily'), textid = 1:3, dosage_mg = c(5, 5, 5))
doseconvert('one daily for 1 week then two daily',
    textid = 2, simplify = TRUE)

# Timing test
system.time(doseconvert(text = '2 tablets daily', textid = 3))
    
# Pre-loading dictionaries for faster analysis
# This is particularly useful when running in server mode for on-demand
# dosage text conversion
data(singlewords)
the_singlewords <- as.drugdose_singlewords(singlewords)
data(multiwords)
the_multiwords <- as.drugdose_multiwords(multiwords)
data(patterns)
the_patterns <- as.drugdose_patterns(patterns)
data(lookups)
the_lookups <- as.drugdose_lookups(lookups)

# Write a function to use pre-loaded dictionaries
doseconvert_fast <- function(text, textid){
    doseconvert(text = text, textid = textid, simplify = TRUE,
    singlewords = the_singlewords, multiwords = the_multiwords,
    patterns = the_patterns, usebuiltinlookups = FALSE,
    customlookups = the_lookups, cores = 1)
}

system.time(doseconvert_fast(text = '2 tablets daily', textid = 3))

CALIBERdrugdose documentation built on Aug. 5, 2020, 3 p.m.