# Getting started with eq5dsuite

## Introduction

The `eq5dsuite` package provides standardised tools for calculating EQ-5D preference-based values and analysing EQ-5D data following the recommendations of Devlin et al. (2020). This vignette introduces the core workflow: loading the package, exploring available value sets, and calculating EQ-5D values from profile data.

## Installation

Install the released version from CRAN:

    install.packages("eq5dsuite")

Install the development version from GitHub:

    remotes::install_github("MathsInHealth/eq5dsuite-r")

## Available value sets

The package includes country-specific value sets for the EQ-5D-3L, EQ-5D-5L, and EQ-5D-Y-3L instruments. Use `eqvs_display()` to see all available sets:

    # List all available EQ-5D-3L value sets
    eqvs_display(version = "3L")
    #> Available national value sets for 3L version:
    #>  Version          Name_short Country_code VS_code
    #>       3L           Argentina           AR  AR_TTO
    #>       3L     Argentina (VAS)           AR  AR_VAS
    #>       3L           Australia           AU      AU
    #>       3L       Belgium (VAS)           BE  BE_VAS
    #>       3L             Bermuda           BM      BM
    #>       3L              Brazil           BR      BR
    #>       3L              Canada           CA      CA
    #>       3L               Chile           CL      CL
    #>       3L               China           CN      CN
    #>       3L             Germany           DE  DE_TTO
    #>       3L       Germany (VAS)           DE  DE_VAS
    #>       3L             Denmark           DK      DK
    #>       3L               Spain           ES      ES
    #>       3L       Finland (VAS)           FI  FI_VAS
    #>       3L              France           FR      FR
    #>       3L             Hungary           HU      HU
    #>       3L                Iran           IR      IR
    #>       3L               Italy           IT      IT
    #>       3L              Jordan           JO      JO
    #>       3L               Japan           JP      JP
    #>       3L               Korea           KR      KR
    #>       3L           Sri Lanka           LK      LK
    #>       3L      Malaysia (VAS)           MY  MY_VAS
    #>       3L    Netherlands_2006           NL NL_2006
    #>       3L   New Zealand (VAS)           NZ  NZ_VAS
    #>       3L            Pakistan           PK      PK
    #>       3L              Poland           PL      PL
    #>       3L            Portugal           PT      PT
    #>       3L              Sweden           SE      SE
    #>       3L           Singapore           SG      SG
    #>       3L            Slovenia           SI  SI_TTO
    #>       3L      Slovenia (VAS)           SI  SI_VAS
    #>       3L            Thailand           TH      TH
    #>       3L             Tunisia           TN      TN
    #>       3L Trinidad and Tobago           TT      TT
    #>       3L              Taiwan           TW      TW
    #>       3L      United Kingdom           UK      UK
    #>       3L                 USA           US      US
    #>       3L            Zimbabwe           ZW      ZW
    #>       3L    Netherlands_2026           NL NL_2026
    #>                                  doi
    #>     10.1111/j.1524-4733.2008.00468.x
    #>     10.1111/j.1524-4733.2008.00468.x
    #>           10.1016/j.jval.2011.04.009
    #>            10.1007/s10198-009-0167-0
    #>           10.1007/s10198-024-01701-2
    #>             10.1177/0272989X15613521
    #>         10.1371/journal.pone.0031115
    #>          10.1016/j.jval.2011.09.002.
    #>           10.1016/j.jval.2014.05.007
    #>            10.1007/s10198-004-0264-z
    #>  https://eq-5dpublications.euroqol.o
    #>             10.1177/1403494809105287
    #>           10.1177/0272989X0102100102
    #>  https://eq-5dpublications.euroqol.o
    #>            10.1007/s10198-011-0351-x
    #>           10.1016/j.jval.2020.03.019
    #>                  10.5812/ircmj.21584
    #>           10.1016/j.jval.2013.04.008
    #>           10.1007/s10198-024-01712-z
    #>                      10.1002/hec.673
    #>     10.1111/j.1524-4733.2009.00579.x
    #>            10.1007/s11136-014-0906-2
    #>           10.1016/j.jval.2011.11.024
    #>                     10.1002/hec.1124
    #>                      10.1002/hec.741
    #>           10.1007/s41669-023-00437-8
    #>     10.1111/j.1524-4733.2009.00596.x
    #>            10.1007/s11136-013-0448-z
    #>            10.1007/s11136-013-0496-4
    #>            10.1007/s40273-014-0142-1
    #>               10.2478/sjph-2020-0002
    #>               10.2478/sjph-2020-0003
    #>           10.1016/j.jval.2011.06.005
    #>           10.1007/s11136-020-02730-z
    #>           10.1016/j.vhri.2016.07.010
    #>           10.1016/j.jfma.2012.12.015
    #>     10.1097/00005650-199711000-00002
    #>     10.1097/00005650-200503000-00003
    #>               10.1186/1478-7954-1-11
    #>           10.1007/s10198-025-01892-2
    #> No user-defined value sets available.

## Calculating EQ-5D values

### EQ-5D-3L

The most common workflow uses a data frame with one column per EQ-5D dimension. The `dim.names` argument maps your column names to the five dimensions in the standard order (mobility, self-care, usual activities, pain/discomfort, anxiety/depression):

    # Example data with EQ-5D-3L responses
    eq5d3l_data <- data.frame(
      id = 1:5,
      mo = c(1, 2, 1, 3, 2),
      sc = c(1, 1, 2, 2, 1),
      ua = c(1, 2, 1, 3, 2),
      pd = c(2, 2, 1, 3, 3),
      ad = c(1, 1, 2, 2, 1)
    )

    # Calculate EQ-5D-3L values using the UK value set
    eq5d3l_data$value <- eq5d3l(
      eq5d3l_data,
      country   = "UK",
      dim.names = c("mo", "sc", "ua", "pd", "ad")
    )

    eq5d3l_data
    #>   id mo sc ua pd ad      value
    #> 1  1  1  1  1  2  1  0.7960000
    #> 2  2  2  1  2  2  1  0.6910000
    #> 3  3  1  2  1  1  2  0.7440001
    #> 4  4  3  2  3  3  2 -0.3190000
    #> 5  5  2  1  2  3  1  0.1590000

### EQ-5D-5L

    eq5d5l_data <- data.frame(
      id = 1:5,
      mo = c(1, 2, 3, 1, 2),
      sc = c(1, 1, 2, 1, 3),
      ua = c(2, 1, 3, 1, 2),
      pd = c(2, 3, 2, 1, 4),
      ad = c(1, 2, 1, 3, 2)
    )

    eq5d5l_data$value <- eq5d5l(
      eq5d5l_data,
      country   = "IT",
      dim.names = c("mo", "sc", "ua", "pd", "ad")
    )

    eq5d5l_data
    #>   id mo sc ua pd ad value
    #> 1  1  1  1  2  2  1 0.903
    #> 2  2  2  1  1  3  2 0.817
    #> 3  3  3  2  3  2  1 0.779
    #> 4  4  1  1  1  1  3 0.891
    #> 5  5  2  3  2  4  2 0.446

### EQ-5D-Y-3L

    eq5dy3l_data <- data.frame(
      id = 1:5,
      mo = c(1, 2, 1, 2, 3),
      sc = c(1, 1, 2, 1, 2),
      ua = c(2, 1, 1, 3, 2),
      pd = c(1, 2, 3, 2, 1),
      ad = c(2, 1, 2, 1, 3)
    )

    eq5dy3l_data$value <- eq5dy3l(
      eq5dy3l_data,
      country   = "SI",
      dim.names = c("mo", "sc", "ua", "pd", "ad")
    )

    eq5dy3l_data
    #>   id mo sc ua pd ad value
    #> 1  1  1  1  2  1  2 0.777
    #> 2  2  2  1  1  2  1 0.755
    #> 3  3  1  2  1  3  2 0.374
    #> 4  4  2  1  3  2  1 0.433
    #> 5  5  3  2  2  1  3 0.163

## Custom value sets

If a value set is not yet included in the package, you can add your own using `eqvs_add()`:

    # Create a custom value set data frame
    custom_vs <- data.frame(
      state = make_all_EQ_indexes(version = "3L"),
      MY_VS = runif(243)
    )

    # Register it temporarily for this session
    eqvs_add(
      custom_vs,
      version     = "3L",
      country     = "My Country",
      countryCode = "MC",
      VSCode      = "MC",
      description = "Custom value set for demonstration",
      saveOption  = 1
    )

    # Use the custom value set
    eq5d3l(c(11111, 12321), country = "MC")

## Keeping value sets up to date

New EQ-5D value sets are published regularly. Use `update_value_sets()` to check for and install new value sets from the online repository:

    update_value_sets()

## Next steps

- `vignette("analysing-eq5d-data")` — complete analytical workflow using NHS PROMs data
- `vignette("crosswalk-methods")` — when and how to use crosswalk methods
- `vignette("custom-value-sets")` — adding and managing custom value sets
- `?eq5dsuite` — full package documentation