Package amended to use "Y3L" rather than "Y" for youth EQ-5D question…

…airre to be consistent with new EuroQol convention.

DESCRIPTION

@@ -51,7 +51,8 @@ Suggests:
     PMCMRplus,
     knitr,
     rmarkdown,
-    covr
+    covr,
+    lifecycle
 URL: https://github.com/fragla/eq5d
 BugReports: https://github.com/fragla/eq5d/issues
 RoxygenNote: 7.3.2

NAMESPACE

@@ -19,7 +19,7 @@ export(RCW)
 export(TTO)
 export(VAS)
 export(VT)
-export(Y)
+export(Y3L)
 export(eq5d)
 export(eq5d3l)
 export(eq5d5l)
@@ -29,6 +29,7 @@ export(eq5dds)
 export(eq5dmap)
 export(eq5drcw)
 export(eq5dy)
+export(eq5dy3l)
 export(getDimensionsFromHealthStates)
 export(getHealthStates)
 export(getHealthStatesFromDimensions)

R/data.R

@@ -214,9 +214,9 @@
 #' @export
 "VT"
 
-#' EQ-5D-Y value set data
+#' EQ-5D-Y-3L value set data
 #'
-#' EQ-5D-Y value set calculation data for Belgium, China, Germany, Hungary, 
+#' EQ-5D-Y-3L value set calculation data for Belgium, Brazil, China, Germany, Hungary, 
 #' Indonesia, Japan, Netherlands, Slovenia and Spain.
 #'
 #' @source
@@ -233,6 +233,6 @@
 #'     \item{\strong{Spain}: Ramos-Goñi JM, Oppe M, Estévez-Carrillo A, Rivero-Arias O; IMPACT HTA HRQoL Group. Accounting for Unobservable Preference Heterogeneity and Evaluating Alternative Anchoring Approaches to Estimate Country-Specific EQ-5D-Y Value Sets: A Case Study Using Spanish Preference Data. Value in Health. 2021 Dec 04. doi: 10.1016/j.jval.2021.10.013.}
 #'   }
 #'
-#' @name Y
+#' @name Y3L
 #' @export
-"Y"
+"Y3L"

R/eq5d.R

@@ -1,15 +1,15 @@
 #' Calculate EQ-5D index scores
 #'
-#' Wrapper for \code{eq5d3l}, \code{eq5d5l} and \code{eq5dy}. Calculate EQ-5D index scores for
-#' EQ-5D-3L, EQ-5D-5L and EQ-5D-Y. Available value sets can be viewed using the function
+#' Wrapper for \code{eq5d3l}, \code{eq5d5l} and \code{eq5dy3l}. Calculate EQ-5D index scores for
+#' EQ-5D-3L, EQ-5D-5L and EQ-5D-Y-3L. Available value sets can be viewed using the function
 #' \code{valuesets}.
 #'
 #' @param scores numeric or data.frame with names/colnames MO, SC, UA, PD and AD
 #'   representing Mobility, Self-care, Usual activities, Pain/discomfort and
 #'   Anxiety/depression. Alternatively EQ-5D scores can be provided in
 #'   five digit format e.g. 12321. If five digit scores are used in a data.frame
 #'   the default column name look for by the function is "State".
-#' @param version string of value "3L", "5L" or "Y" to indicate instrument
+#' @param version string of value "3L", "5L" or "Y3L" to indicate instrument
 #'   version.
 #' @param type string specifying method type used in deriving value set scores.
 #'   Options are TTO or VAS for EQ-5D-3L, VT for EQ-5D-5L, CW for EQ-5D-5L
@@ -146,9 +146,14 @@ eq5d.matrix <- function(scores, version=NULL, type=NULL, country=NULL, ignore.in
 
 #' @export
 eq5d.default <- function(scores, version=NULL, type=NULL, country=NULL, ignore.invalid=FALSE, ...){
-
-  if(!version %in% c("3L", "5L", "Y"))
-    stop("EQ-5D version not one of 3L, 5L or Y.")
+
+  if (version == "Y") {
+    lifecycle::deprecate_warn("0.16.0", I('Setting `version = "Y"`'), I('`version = "Y3L"`'))
+    version <- "Y3L"
+  }
+
+  if(!version %in% c("3L", "5L", "Y3L"))
+    stop("EQ-5D version not one of 3L, 5L or Y3L.")
 
   .length = length(scores)
   if(!is.null(type) && type=="DSU") {
@@ -258,8 +263,8 @@ eq5d.default <- function(scores, version=NULL, type=NULL, country=NULL, ignore.i
     } else {
       stop("EQ-5D-3L valueset type not recognised. Must be one of 'TTO', 'VAS', 'RCW' or 'DSU'.")
     }
-  } else if (version=="Y") {
-    eq5dy(scores, country=country)
+  } else if (version=="Y3L") {
+    eq5dy3l(scores, country=country)
   }
   else {
     if(!is.null(type) && type=="VT") {
@@ -281,7 +286,7 @@ eq5d.default <- function(scores, version=NULL, type=NULL, country=NULL, ignore.i
 #'     in the \code{eq5d} package.
 #'
 #' @param type string EQ-5D value set type. TTO or VAS for EQ-5D-3L, VT for EQ-5D-5L,
-#'   cTTO for EQ-5D-Y, CW for EQ-5D-5L crosswalk conversion dataset, or DSU for NICE Decision Support
+#'   cTTO for EQ-5D-Y-3L, CW for EQ-5D-5L crosswalk conversion dataset, or DSU for NICE Decision Support
 #'   Unit's EQ-5D-5L to EQ-5D-3L and EQ-5D-3L to EQ-5D-5L mappings.
 #' @param version string either 3L, 5L or Y.
 #' @param country string one of the countries for which there is a value set.
@@ -296,17 +301,24 @@ eq5d.default <- function(scores, version=NULL, type=NULL, country=NULL, ignore.i
 #' valuesets(type="TTO")
 #' valuesets(version="5L")
 #' valuesets(country="UK")
-#' valuesets(version="Y", references=c("DOI", "PubMed"))
+#' valuesets(version="Y3L", references=c("DOI", "PubMed"))
 #' @export
 valuesets <- function(type=NULL, version=NULL, country=NULL, references=c("PubMed", "DOI", "ISBN", "ExternalURL")) {
+
+  if (!is.null(version) && version == "Y") {
+    lifecycle::deprecate_warn("0.16.0", I('Setting `version = "Y"`'), I('`version = "Y3L"`'))
+    version <- "Y3L"
+  }
+
+  if(!is.null(version) && version == "Y3L") version <- "Y-3L"
   if(!is.null(version)) version <- paste0("EQ-5D-", version)
 
   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))
   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", Type="cTTO", Country=colnames(Y))
+  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)

R/eq5dds.R

@@ -41,9 +41,14 @@ eq5dds <- function(data, version, counts=FALSE, by=NULL, ignore.invalid=TRUE, ..
 
   if(!is.null(args$dimensions)) {dimensions <- args$dimensions}
   if(!is.null(args$five.digit)) {five.digit <- args$five.digit}
+
+  if (version == "Y") {
+    lifecycle::deprecate_warn("0.16.0", I('Setting `version = "Y"`'), I('`version = "Y3L"`'))
+    version <- "Y3L"
+  }
 
-  if(!version %in% c("3L", "5L", "Y"))
-    stop("EQ-5D version not one of 3L, 5L or Y.")
+  if(!version %in% c("3L", "5L", "Y3L"))
+    stop("EQ-5D version not one of 3L, 5L or Y3L.")
 
   if(all(dimensions %in% names(data))) {
     colnames(data)[match(dimensions, colnames(data))] <- .get_dimension_names()

R/eq5dlfs.R

@@ -4,7 +4,7 @@
 #' 
 #' @param scores data.frame with names MO, SC, UA, PD and AD representing
 #'   Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression.
-#' @param version string of value "3L", "5L" or "Y" to indicate instrument version.
+#' @param version string of value "3L", "5L" or "Y3L" to indicate instrument version.
 #' @param ignore.invalid whether to ignore invalid scores. TRUE returns NA, FALSE throws an 
 #' error.
 #' @param ... character vector, specifying "dimensions" column names. Defaults 
@@ -55,8 +55,13 @@ lfs.matrix <- function(scores, version=NULL, ignore.invalid=FALSE, ...) {
 #' @export
 lfs.default <- function(scores, version=NULL, ignore.invalid=FALSE, ...){
 
-  if(!version %in% c("3L", "5L", "Y"))
-    stop("EQ-5D version not one of 3L, 5L or Y.")
+  if (version == "Y") {
+    lifecycle::deprecate_warn("0.16.0", I('Setting `version = "Y"`'), I('`version = "Y3L"`'))
+    version <- "Y3L"
+  }
+
+  if(!version %in% c("3L", "5L", "Y3L"))
+    stop("EQ-5D version not one of 3L, 5L or Y3L.")
 
   .length = length(scores)
 

R/eq5dlss.R

@@ -55,8 +55,13 @@ lss.matrix <- function(scores, version=NULL, ignore.invalid=FALSE, ...) {
 #' @export
 lss.default <- function(scores, version=NULL, ignore.invalid=FALSE, ...){
 
-  if(!version %in% c("3L", "5L", "Y"))
-    stop("EQ-5D version not one of 3L, 5L or Y.")
+  if (version == "Y") {
+    lifecycle::deprecate_warn("0.16.0", I('Setting `version = "Y"`'), I('`version = "Y3L"`'))
+    version <- "Y3L"
+  }
+
+  if(!version %in% c("3L", "5L", "Y3L"))
+    stop("EQ-5D version not one of 3L, 5L or Y3L.")
 
   .length = length(scores)
 

R/eq5dy.R → R/eq5dy3l.R

@@ -1,30 +1,30 @@
-#' Calculate EQ-5D-Y index scores
+#' Calculate EQ-5D-Y-3L index scores
 #'
-#' Calculate indices for EQ-5D-Y value sets. Available value sets can be viewed
+#' Calculate indices for EQ-5D-Y-3L value sets. Available value sets can be viewed
 #'   using the function \code{valuesets}.
 #'
 #' @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.
 #' @return calculated utility index score.
 #' @examples
-#' eq5dy(scores=c(MO=3,SC=3,UA=3,PD=3,AD=3), country="Slovenia")
+#' eq5dy3l(scores=c(MO=3,SC=3,UA=3,PD=3,AD=3), country="Slovenia")
 #'
 #' @export
-eq5dy <- function(scores, country=NULL) {
+eq5dy3l <- function(scores, country=NULL) {
 
   if(!all(.get_dimension_names() %in% names(scores)))
     stop("Unable to identify EQ-5D dimensions in scores.")
 
   if(!all(scores %in% 1:3)) {
-    message <- "Scores must be coded as 1, 2 or 3 for EQ-5D-Y."
+    message <- "Scores must be coded as 1, 2 or 3 for EQ-5D-Y-3L."
     if(all(scores %in% 1:5)) {
       message <- paste(message, "Are you using EQ-5D-5L?")
     }
     stop(message)
   }
 
-  survey <- Y
+  survey <- Y3L
 
   if(is.null(country) || !country %in% colnames(survey))
     stop(paste("Country must be one of:", paste(colnames(survey), collapse=", ")))
@@ -37,6 +37,26 @@ eq5dy <- function(scores, country=NULL) {
   return(round(sum(values, na.rm = TRUE), digits=3))
 }
 
+#' Calculate EQ-5D-Y index scores
+#'
+#' @description 
+#'  `r lifecycle::badge("deprecated")
+#'
+#' `eq5dy` was renamed to `eq5dy3l` to be consistent with the new EuroQol
+#' naming convention.
+#' 
+#' @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.
+#' @return calculated utility index score.
+#'
+#' @export
+#' 
+eq5dy <- function(scores, country=NULL) {
+  lifecycle::deprecate_warn("0.16.0", "eq5dy()", "eq5dy3l()")  
+  eq5dy3l(scores, country)
+}
+
 .intercept <- function(scores, survey) {
   ##at least one mobility, care, activity, pain, anxiety > 1
   if(sum(scores) > 5 && !is.na(survey["Intercept"])) {

R/eqpchc.R

@@ -35,8 +35,13 @@
 #' @export
 pchc <- function(pre, post, version=NULL, no.problems=TRUE, totals=TRUE, by.dimension=FALSE, ignore.invalid=TRUE, dimensions=.get_dimension_names(), summary=TRUE) {
 
-  if(is.null(version) || !version %in% c("3L", "5L", "Y"))
-    stop("EQ-5D version not one of 3L, 5L or Y.")
+  if (version == "Y") {
+    lifecycle::deprecate_warn("0.16.0", I('Setting `version = "Y"`'), I('`version = "Y3L"`'))
+    version <- "Y3L"
+  }
+
+  if(is.null(version) || !version %in% c("3L", "5L", "Y3L"))
+    stop("EQ-5D version not one of 3L, 5L or Y3L.")
 
   if(is.character(pre) || is.numeric(pre)) {
     pre <- get_dimensions_from_health_states(pre, version=version, ignore.invalid=ignore.invalid)

R/helpers.R

@@ -3,33 +3,39 @@
 }
 
 .get_number_levels <- function(version) {
-  if(!version %in% c("3L", "5L", "Y"))
-    stop("Version must be either 3L, 5L or Y.")
+  if(!version %in% c("3L", "5L", "Y3L"))
+    stop("Version must be either 3L, 5L or Y3L.")
 
-  levels <- ifelse(version=="Y", 3, as.numeric(sub("L", "", version)))
+  levels <- ifelse(version=="Y3L", 3, as.numeric(sub("L", "", version)))
 
   return(levels)
 }
 
 #' Get all five digit health state scores
 #' 
 #' Get all five digit health state scores for either EQ-5D-3L, EQ-5D-5L or
-#' EQ-5D-Y
+#' EQ-5D-Y3L
 #' 
 #' @param version the EQ-5D version. Either 3L or 5L.
 #' @return A character vector of five digit health states.
 #' @aliases getHealthStates
 #' @examples
 #' get_all_health_states("3L")
 #' get_all_health_states("5L")
-#' get_all_health_states("Y")
+#' get_all_health_states("Y3L")
 #' 
 #' @export getHealthStates get_all_health_states
 get_all_health_states <- function(version) {
-  if(!version %in% c("3L", "5L", "Y"))
-    stop("Version must be either 3L, 5L or Y.")
 
-  if(version %in% c("3L", "Y")) {
+  if (version == "Y") {
+    lifecycle::deprecate_warn("0.16.0", I('Setting `version = "Y"`'), I('`version = "Y3L"`'))
+    version <- "Y3L"
+  }
+
+  if(!version %in% c("3L", "5L", "Y3L"))
+    stop("Version must be either 3L, 5L or Y3L.")
+
+  if(version %in% c("3L", "Y3L")) {
     return(STATES[["3L"]])
   } else {
     return(STATES[["5L"]])

README.Rmd

@@ -23,7 +23,7 @@ knitr::opts_chunk$set(
 
 EQ-5D is a popular health related quality of life instrument used in the clinical and economic evaluation of health care. Developed by the [EuroQol](https://euroqol.org/) group, the instrument consists of two components: health state description and evaluation. 
 
-For the description component a subject self-rates their health in terms of five dimensions; mobility, self-care, usual activities, pain/discomfort, and anxiety/depression using either a three-level ([EQ-5D-3L](https://euroqol.org/information-and-support/euroqol-instruments/eq-5d-3l/) and [EQ-5D-Y](https://euroqol.org/information-and-support/euroqol-instruments/eq-5d-y-3l/)) or a five-level ([EQ-5D-5L](https://euroqol.org/information-and-support/euroqol-instruments/eq-5d-5l/)) scale. 
+For the description component a subject self-rates their health in terms of five dimensions; mobility, self-care, usual activities, pain/discomfort, and anxiety/depression using either a three-level ([EQ-5D-3L](https://euroqol.org/information-and-support/euroqol-instruments/eq-5d-3l/) and [EQ-5D-Y-3L](https://euroqol.org/information-and-support/euroqol-instruments/eq-5d-y-3l/)) or a five-level ([EQ-5D-5L](https://euroqol.org/information-and-support/euroqol-instruments/eq-5d-5l/)) scale. 
 
 The evaluation component requires a patient to record their overall health status using a visual analogue scale (EQ-VAS).
 
@@ -74,8 +74,8 @@ eq5d(scores=scores, country="UK", version="3L", type="TTO")
 #Using five digit format
 eq5d(scores=12321, country="UK", version="3L", type="TTO")
 
-#EQ-5D-Y using the Slovenian cTTO value set
-eq5d(scores=13321, country="Slovenia", version="Y", type="cTTO")
+#EQ-5D-Y-3L using the Slovenian cTTO value set
+eq5d(scores=13321, country="Slovenia", version="Y3L", type="cTTO")
 
 #EQ-5D-5L crosswalk
 eq5d(scores=55555, country="Spain", version="5L", type="CW")

README.md

@@ -22,7 +22,7 @@ of five dimensions; mobility, self-care, usual activities,
 pain/discomfort, and anxiety/depression using either a three-level
 ([EQ-5D-3L](https://euroqol.org/information-and-support/euroqol-instruments/eq-5d-3l/)
 and
-[EQ-5D-Y](https://euroqol.org/information-and-support/euroqol-instruments/eq-5d-y-3l/))
+[EQ-5D-Y-3L](https://euroqol.org/information-and-support/euroqol-instruments/eq-5d-y-3l/))
 or a five-level
 ([EQ-5D-5L](https://euroqol.org/information-and-support/euroqol-instruments/eq-5d-5l/))
 scale.
@@ -116,8 +116,8 @@ eq5d(scores=scores, country="UK", version="3L", type="TTO")
 eq5d(scores=12321, country="UK", version="3L", type="TTO")
 #> [1] 0.329
 
-#EQ-5D-Y using the Slovenian cTTO value set
-eq5d(scores=13321, country="Slovenia", version="Y", type="cTTO")
+#EQ-5D-Y-3L using the Slovenian cTTO value set
+eq5d(scores=13321, country="Slovenia", version="Y3L", type="cTTO")
 #> [1] 0.295
 
 #EQ-5D-5L crosswalk
@@ -176,10 +176,10 @@ head(valuesets(type="TTO", references=c("PubMed","DOI")))
 #>    Version Type   Country   PubMed                              DOI
 #> 1 EQ-5D-3L  TTO Argentina 19900257 10.1111/j.1524-4733.2008.00468.x
 #> 2 EQ-5D-3L  TTO Australia 21914515       10.1016/j.jval.2011.04.009
-#> 3 EQ-5D-3L  TTO    Brazil 29702778       10.1016/j.vhri.2013.01.009
-#> 4 EQ-5D-3L  TTO    Canada 22328929     10.1371/journal.pone.0031115
-#> 5 EQ-5D-3L  TTO     Chile 22152184      10.1016/j.jval.2011.09.002.
-#> 6 EQ-5D-3L  TTO     China 25128053       10.1016/j.jval.2014.05.007
+#> 3 EQ-5D-3L  TTO   Bermuda 38982011       10.1007/s10198-024-01701-2
+#> 4 EQ-5D-3L  TTO    Brazil 29702778       10.1016/j.vhri.2013.01.009
+#> 5 EQ-5D-3L  TTO    Canada 22328929     10.1371/journal.pone.0031115
+#> 6 EQ-5D-3L  TTO     Chile 22152184      10.1016/j.jval.2011.09.002.
 
 # Return VAS value sets with ISBN and external URL (top 6 returned for brevity).
 head(valuesets(type="VAS", references=c("ISBN","ExternalURL")))
@@ -201,12 +201,12 @@ head(valuesets(type="VAS", references=c("ISBN","ExternalURL")))
 # Return EQ-5D-5L value sets (top 6 returned for brevity).
 head(valuesets(version="5L"))
 #>    Version Type     Country   PubMed                        DOI ISBN
-#> 1 EQ-5D-5L   CW     Denmark 22867780 10.1016/j.jval.2012.02.008 <NA>
-#> 2 EQ-5D-5L   CW      France 22867780 10.1016/j.jval.2012.02.008 <NA>
-#> 3 EQ-5D-5L   CW     Germany 22867780 10.1016/j.jval.2012.02.008 <NA>
-#> 4 EQ-5D-5L   CW       Japan 22867780 10.1016/j.jval.2012.02.008 <NA>
-#> 5 EQ-5D-5L   CW Netherlands 22867780 10.1016/j.jval.2012.02.008 <NA>
-#> 6 EQ-5D-5L   CW      Russia 33713323 10.1007/s11136-021-02804-6 <NA>
+#> 1 EQ-5D-5L   CW     Bermuda 38982011 10.1007/s10198-024-01701-2 <NA>
+#> 2 EQ-5D-5L   CW     Denmark 22867780 10.1016/j.jval.2012.02.008 <NA>
+#> 3 EQ-5D-5L   CW      France 22867780 10.1016/j.jval.2012.02.008 <NA>
+#> 4 EQ-5D-5L   CW     Germany 22867780 10.1016/j.jval.2012.02.008 <NA>
+#> 5 EQ-5D-5L   CW       Japan 22867780 10.1016/j.jval.2012.02.008 <NA>
+#> 6 EQ-5D-5L   CW Netherlands 22867780 10.1016/j.jval.2012.02.008 <NA>
 #>   ExternalURL
 #> 1        <NA>
 #> 2        <NA>