Merge pull request #28 from fragla/crosswalk

van Hout (2021) reverse crosswalk models merged into main.

Author: fragla

DESCRIPTION

@@ -24,11 +24,11 @@ Description: EQ-5D is a popular health related quality of life instrument used
     <doi:10.1007/978-94-007-7596-1>, 47 EQ-5D-5L EQ-VT value sets, the 
     EQ-5D-5L crosswalk value sets developed by van Hout et al. (2012) 
     <doi:10.1016/j.jval.2012.02.008>, the crosswalk value sets for Bermuda, Jordan and 
-    Russia and the reverse crosswalk value sets. 10 EQ-5D-Y value sets are also 
-    included as are the NICE 'DSU' age-sex based EQ-5D-3L to EQ-5D-5L and 
-    EQ-5D-5L to EQ-5D-3L mappings. Methods are also included for the analysis 
-    of EQ-5D profiles, including those from the book "Methods for Analyzing and 
-    Reporting EQ-5D data" by Devlin et al. (2020) 
+    Russia and the van Hout (2021) reverse crosswalk value sets. 10 EQ-5D-Y 
+    value sets are also included as are the NICE 'DSU' age-sex based EQ-5D-3L 
+    to EQ-5D-5L and EQ-5D-5L to EQ-5D-3L mappings. Methods are also included 
+    for the analysis of EQ-5D profiles, including those from the book "Methods 
+    for Analyzing and Reporting EQ-5D data" by Devlin et al. (2020) 
     <doi:10.1007/978-3-030-47622-9>. Additionally a shiny web tool is included 
     to enable the calculation, visualisation and automated statistical analysis 
     of EQ-5D data via a web browser using EQ-5D dimension scores stored in CSV 

NAMESPACE

@@ -16,6 +16,7 @@ export(CW)
 export(DSU3L)
 export(DSU5L)
 export(RCW)
+export(RCWVH)
 export(TTO)
 export(VAS)
 export(VT)

NEWS.Rmd

@@ -11,6 +11,14 @@ knitr::opts_chunk$set(echo = TRUE)
 
 - Moroccan EQ-5D-5L value set added.
 
+- "digits" argument added to eq5d3l, eq5d5l and eq5dy3l functions to enable 
+scores to be returned with more precision.
+
+- van Hout (2021) reverse crosswalk method added to eq5drcw function. This is 
+now the default and recommended option for mapping EQ-5D-3L to EQ-5D-5L. The 
+previous EuroQol (2019) mappings can be accessed by specifying the 
+`method = "EQ"` argument.
+
 # eq5d 0.15.7 (2025-02-28)
 
 - United Arab Emirates EQ-5D-5L value set added.

NEWS.md

@@ -5,6 +5,14 @@
 
 - Moroccan EQ-5D-5L value set added.
 
+- “digits” argument added to eq5d3l, eq5d5l and eq5dy3l functions to
+  enable scores to be returned with more precision.
+
+- van Hout (2021) reverse crosswalk method added to eq5drcw function.
+  This is now the default and recommended option for mapping EQ-5D-3L to
+  EQ-5D-5L. The previous EuroQol (2019) mappings can be accessed by
+  specifying the `method = "EQ"` argument.
+
 # eq5d 0.15.7 (2025-02-28)
 
 - United Arab Emirates EQ-5D-5L value set added.

R/data.R

@@ -63,11 +63,12 @@
 #' @export
 "DSU5L"
 
-#' EQ-5D-3L Reverse Crosswalk data
+#' EQ-5D-3L Reverse Crosswalk data (deprecated)
 #'
 #' Reverse Crosswalk index value table to calculate EQ-5D-5L indices from EQ-5D-3L data
-#'   for England, Germany, Netherlands and USA. Table uses the values of van Hout et al
-#'   from the EuroQol analysis tools webpage.
+#'   for England, Germany, Netherlands and USA. Table uses the values published 
+#'   on the EuroQol analysis tools webpage based on reverse engineering of
+#'   van Hout et al (2012)
 #'
 #' @source
 #' \href{https://euroqol.org/information-and-support/resources/value-sets/}{Reverse crosswalk datasets}
@@ -76,6 +77,18 @@
 #' @export
 "RCW"
 
+#' EQ-5D-3L Reverse Crosswalk data
+#'
+#' Reverse Crosswalk index value table to calculate EQ-5D-5L indices from EQ-5D-3L data
+#'   using the van Hout et al (2021) method.
+#'
+#' @source
+#' \doi{10.1016/j.jval.2021.03.009}
+#'
+#' @name RCWVH
+#' @export
+"RCWVH"
+
 #' EQ-5D-3L TTO value set data
 #'
 #' Coefficients for the estimation of the EQ-5D-3L index values based on TTO valuation studies

R/eq5d.R

@@ -26,7 +26,7 @@
 #'   be a number which is applied to the whole dataset. When a single
 #'   NICE DSU score is being calculated "age", "sex" and "bwidth" are also
 #'   used. See \code{\link{eq5dmap}} for valid options. "digits" can also be 
-#'   used to return NICE DSU mapping scores with more precision.
+#'   used to return scores with more precision.
 #' @return a numeric vector of utility index scores.
 #' @examples
 #' 
@@ -255,20 +255,25 @@ eq5d.default <- function(scores, version=NULL, type=NULL, country=NULL, ignore.i
 
   if(version=="3L") {
     if(!is.null(type) && type %in% c("TTO", "VAS")) {
-      eq5d3l(scores, type=type, country=country)
+      eq5d3l(scores, type=type, country=country, digits = digits)
     } else if(!is.null(type) && type=="RCW") {
-      eq5drcw(scores, country=country)
+      if(is.null(args$method)) {
+        method <- "VH"
+      } else {
+        method <- args$method
+      }
+      eq5drcw(scores, country=country, method=method, digits = digits)
     } else if(!is.null(type) && type=="DSU") {
       eq5dmap(scores, country, version, args$age, args$sex, bwidth, digits)
     } else {
       stop("EQ-5D-3L valueset type not recognised. Must be one of 'TTO', 'VAS', 'RCW' or 'DSU'.")
     }
   } else if (version=="Y3L") {
-    eq5dy3l(scores, country=country)
+    eq5dy3l(scores, country=country, digits = digits)
   }
   else {
     if(!is.null(type) && type=="VT") {
-      eq5d5l(scores, country=country)
+      eq5d5l(scores, country=country, digits = digits)
     } else if(!is.null(type) && type=="CW") {
       eq5dcw(scores, country=country)
     } else if(!is.null(type) && type=="DSU") {
@@ -316,20 +321,24 @@ valuesets <- function(type=NULL, version=NULL, country=NULL, references=c("PubMe
   tto <- data.frame(Version="EQ-5D-3L", Type="TTO", Country=colnames(TTO))
   vas <- data.frame(Version="EQ-5D-3L", Type="VAS", Country=colnames(VAS))
   rcw <- data.frame(Version="EQ-5D-3L", Type="RCW", Country=colnames(RCW))
+  rcwvh <- data.frame(Version="EQ-5D-3L", Type="RCW", Country=colnames(RCWVH))
   vt <- data.frame(Version="EQ-5D-5L", Type="VT", Country=colnames(VT))
   cw <- data.frame(Version="EQ-5D-5L", Type="CW", Country=colnames(CW))
   y <- data.frame(Version="EQ-5D-Y-3L", Type="cTTO", Country=colnames(Y3L))
   dsu3l <- data.frame(Version="EQ-5D-3L", Type="DSU", Country=sub("Copula", "", grep("Copula", sort(colnames(DSU3L)), value=TRUE)))
   dsu5l <- data.frame(Version="EQ-5D-5L", Type="DSU", Country=sub("Copula", "", grep("Copula", sort(colnames(DSU5L)), value=TRUE)))
-  vs <- rbind(tto, vas, rcw, vt, cw, y, dsu3l, dsu5l)
 
+  vs1 <- rbind(tto, vas, rcw, vt, cw, y, dsu3l, dsu5l)
+  vs1 <- merge(vs1, REFERENCES, by = c("Version", "Type", "Country"))
+  
+  vs2 <- cbind(rcwvh, REFERENCES[REFERENCES$Type=="RCW" & is.na(REFERENCES$Country),!names(REFERENCES) %in% c("Country", "Version", "Type")], row.names = NULL)
+  vs <- rbind(vs1, vs2)
+  
   if(!is.null(type)) vs <- vs[vs$Type==type,]
   if(!is.null(version)) vs <- vs[vs$Version==version,]
   if(!is.null(country)) vs <- vs[grep(paste0("^",country), vs$Country),]
   rownames(vs) <- NULL
 
-  vs <- merge(vs, REFERENCES, by = c("Version", "Type", "Country"))
-  
   if(is.null(references)) {
     vs <- vs[,c("Version", "Type", "Country")]
   } else if (all(references %in% c("PubMed", "DOI", "ISBN", "ExternalURL"))) {

R/eq5d3l.R

@@ -7,13 +7,14 @@
 #'   Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression.
 #' @param type 3L values set type. Either TTO or VAS.
 #' @param country value set country.
+#' @param digits number of decimal places to return.
 #' @return calculated utility index score.
 #' @examples
 #' eq5d3l(scores=c(MO=1,SC=2,UA=3,PD=1,AD=3), type="VAS", country="UK")
 #' eq5d3l(scores=c(MO=3,SC=2,UA=3,PD=2,AD=3), type="TTO", country="Germany")
 #'
 #' @export
-eq5d3l <- function(scores, type="TTO", country="UK") {
+eq5d3l <- function(scores, type="TTO", country="UK", digits=3) {
 
   if(!all(.get_dimension_names() %in% names(scores))) {
     stop("Unable to identify EQ-5D dimensions in scores.")
@@ -49,7 +50,7 @@ eq5d3l <- function(scores, type="TTO", country="UK") {
     index <- .eq5d3l.add(values)
   }
 
-  return(round(index, digits=3))
+  return(round(index, digits=digits))
 }
 
 .eq5d3l.add <- function(values) {

R/eq5d5l.R

@@ -6,13 +6,14 @@
 #' @param scores numeric with names MO, SC, UA, PD and AD representing
 #'   Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression.
 #' @param country value set country.
+#' @param digits number of decimal places to return.
 #' @return calculated utility index score.
 #' @examples
 #' eq5d5l(scores=c(MO=1,SC=2,UA=3,PD=4,AD=5), country="England")
 #' eq5d5l(scores=c(MO=3,SC=2,UA=5,PD=2,AD=3), country="Netherlands")
 #'
 #' @export
-eq5d5l <- function(scores, country="England") {
+eq5d5l <- function(scores, country="England", digits = 3) {
 
   if(!all(.get_dimension_names() %in% names(scores)))
     stop("Unable to identify EQ-5D dimensions in scores.")
@@ -35,7 +36,7 @@ eq5d5l <- function(scores, country="England") {
               .N4(scores,survey),
               .N5(scores,survey))
 
-    return(round(sum(values, na.rm = TRUE), digits=3))
+    return(round(sum(values, na.rm = TRUE), digits=digits))
 }
 
 .level4Or5 <- function(scores, survey) {

R/eq5drcw.R

@@ -6,24 +6,36 @@
 #' @param scores numeric with names MO, SC, UA, PD and AD representing
 #'   Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression.
 #' @param country value set country.
+#' @param method crosswalk values to use. Either "VH" (Van Hout, 2021) or "EQ" 
+#' (EuroQol 2019 values). The van Hout method is recommended.
+#' @param digits number of decimal places to return.
 #' @return calculated utility index score.
 #' @examples
 #' eq5drcw(scores=c(MO=1,SC=2,UA=3,PD=2,AD=1), country="Netherlands")
 #' eq5drcw(scores=c(MO=3,SC=3,UA=3,PD=3,AD=3), country="Germany")
 #'
 #' @export
-eq5drcw <- function(scores, country="UK") {
+eq5drcw <- function(scores, country="UK", method="VH", digits = 3) {
   if(!all(.get_dimension_names() %in% names(scores))) {
     stop("Unable to identify EQ-5D dimensions in scores.")
   }
+  
+  if(!method %in% c("VH", "EQ")) {
+    stop("Unable to identify reverse crosswalk values to use.")
+  }
 
   if(!all(scores %in% 1:3))
     stop("Scores must be coded as 1, 2, or 3 for EQ-5D-3L Reverse Crosswalk.")
-
-  survey <- RCW
-
+  
+  if(method == "VH") {
+    survey <- RCWVH
+  } else {
+    survey <- RCW
+  }
+  
   if(is.null(country) || !country %in% colnames(survey))
     stop(paste("For EQ-5D-3L reverse crosswalk value sets country must be one of:", paste(colnames(survey), collapse=", ")))
 
-  return(survey[paste(scores, collapse=""), country])
+  return(round(survey[paste(scores, collapse=""), country], digits))
 }
+

R/eq5dy3l.R

@@ -6,12 +6,13 @@
 #' @param scores numeric with names MO, SC, UA, PD and AD representing
 #'   Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression.
 #' @param country value set country.
+#' @param digits number of decimal places to return.
 #' @return calculated utility index score.
 #' @examples
 #' eq5dy3l(scores=c(MO=3,SC=3,UA=3,PD=3,AD=3), country="Slovenia")
 #'
 #' @export
-eq5dy3l <- function(scores, country=NULL) {
+eq5dy3l <- function(scores, country=NULL, digits=3) {
 
   if(!all(.get_dimension_names() %in% names(scores)))
     stop("Unable to identify EQ-5D dimensions in scores.")
@@ -34,7 +35,7 @@ eq5dy3l <- function(scores, country=NULL) {
   values <- c(survey["FullHealth"],
               .intercept(scores, survey), .power(scores, survey), .all3(scores, survey))
 
-  return(round(sum(values, na.rm = TRUE), digits=3))
+  return(round(sum(values, na.rm = TRUE), digits=digits))
 }
 
 #' Calculate EQ-5D-Y index scores