---
title: "Mapping between EQ-5D-5L and EQ-5D-3L using the NICE Decision Support Unit models"
author: "Fraser Morton"
date: "`r format(Sys.Date(), '%d %B %Y')`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Mapping between EQ-5D-5L and EQ-5D-3L using the NICE Decision Support Unit models}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
The NICE Decision Support Unit (DSU) provides models that enable mapping 
between EQ-5D-5L and EQ-5D-3L data. These models can be applied to health 
states, utility index scores and summarised utility values, allowing results 
obtained using different EQ-5D descriptive systems to be compared on a common 
basis.

The DSU models require age and sex in addition to EQ-5D responses and support 
mapping in both directions between EQ-5D-3L and EQ-5D-5L. In the UK, prior to 
the release of the 2026 EQ-5D-5L UK value set, NICE recommended the use of 
these models for reference-case analyses involving mapping between EQ-5D 
versions. The DSU models remain useful for mapping between EQ-5D versions and 
for the analysis of studies conducted under earlier NICE guidance.

This vignette demonstrates how the DSU models can be used from within the 
`eq5d` package.

### Available value sets

DSU value sets available in `eq5d` can be viewed using the `valuesets()` 
function. Results can be filtered by EQ-5D version, country or value set type.

```{r dsu_valuesets}
  library(eq5d)

  # DSU value sets for the UK
  valuesets(version = "5L", type = "DSU", country = "UK")

  ## All DSU EQ-5D-5L to EQ-5D-3L value sets
  head(valuesets(version = "5L", type = "DSU"))

```

### Mapping health states

Health states can be mapped using either individual EQ-5D dimensions or 
five-digit health-state codes. In addition to EQ-5D responses, age and sex must 
be supplied.

Age may be provided either as years or as an age category. Age categories range 
from 1 to 5, where 1 = 18-34, 2 = 35-44, 3 = 45-54, 4 = 55-64 and 5 = 65-100. 
Equivalent age values and age categories produce the same results (for example, 
age 47 and age category 3). Sex may be specified as "Male", "Female", "M", or 
"F" and matching is case-insensitive.

##### Single health states

```{r dsu_dimensions_1}

# Using age in years and sex as "m"
eq5d(c(MO=1, SC=2, UA=3, PD=4, AD=5), type = "DSU", country = "England_2018", age = 43, version = "5L", sex = "m")

# Using an age category and sex as "Male"
eq5d(12345, type = "DSU", country = "England_2018", age = 2, version = "5L", sex = "Male")

```

##### Multiple health states

```{r dsu_dimensions_2}

# get states and create data.frame
set.seed(12345)
dat1 <- data.frame(State = sample(get_all_health_states("5L"), 10), 
                   Age = sample(18:100, 10), 
                   Sex = sample(c("M","F"), replace = TRUE, 10))

print(dat1)

eq5d(dat1, version="5L", type="DSU", country="England_2018")

```

<br>

### Mapping utility scores

Utility scores can also be mapped between EQ-5D versions. Exact utility values 
are supplied in place of health states.

```{r dsu_exact_utility}

# Using utility score 0.322 (score for state 12345), an age category and sex as "Male"
eq5d(0.322, type = "DSU", country = "England_2018", age = 2, version = "5L", sex = "Male")


# Multiple states

# create data.frame of utility scores using the 2018 EQ-5D-5L value set for England for the states in dat1
dat2 <- data.frame(Utility = eq5d(dat1$State, version = "5L", type = "VT", country = "England"), 
                   Age = dat1$Age,
                   Sex = dat1$Sex)
                   
print(dat2)

eq5d(dat2, version="5L", type="DSU", country="England_2018")

```                   

### Mapping summarised utility scores

If approximate or summarised utility scores are being mapped, a bandwidth 
parameter needs to be provided in addition to the age and sex parameters. The 
bandwidth parameter specifies the neighbourhood and the rate at which the 
weight declines with distance. It is possible to provide a single bandwidth 
score that can be applied to all utility scores in a dataset. The DSU recommend 
bandwidth values of 0.2 for utilities below 0.8, 0.1 for utilities between 0.8 
and 0.951, and a small bandwidth sufficient to include 1.0 for utilities above 
0.951. Individual bandwidth values can also be supplied using a `bwidth` 
column. For more information please view the tutorial on the [NICE DSU website](https://sheffield.ac.uk/nice-dsu/methods-development/mapping-eq-5d-5l-3l).

```{r dsu_summary_utility}

# Get all utility scores from 2018 EQ‑5D‑5L value set for England 
exist.utils <- unique(DSU5L$England_2018)
min <- min(DSU5L$England_2018)
max <- max(DSU5L$England_2018)

# calculate range of values between min and max
poss.utils <- seq(from=min, to=max, by=0.001)

# create data.frame of 10 utility scores that aren't in the 2018 EQ‑5D‑5L value set for England 
set.seed(54321)
dat3 <- data.frame(Utility = sample(poss.utils[which(!poss.utils %in% exist.utils)], 10),
                   Age = sample(18:100, 10), 
                   Sex = sample(c("M","F"), replace = TRUE, 10))

print(dat3)

# map scores using a single bandwidth value for all scores
eq5d(dat3, version="5L", type="DSU", country="England_2018", bwidth=0.2)

# add bwidth column with values based on the DSU recommendations
dat3$bwidth <- c(0.2, 0.1, 0.2, 0.2, 0.1, 0.2, 0.2, 0.2, 0.2, 0.01)

eq5d(dat3, version="5L", type="DSU", country="England_2018")

```

Differences can be observed in the 2nd, 5th, and 10th mapped scores when the 
DSU recommended bandwidth values are used instead of a single bandwidth value 
of 0.2 for all utility scores.

### Further information

- Wailoo et al. (2021) discuss differences between EQ-5D-3L and EQ-5D-5L 
valuation and the development of the DSU mapping models:
  https://doi.org/10.1016/j.jval.2020.11.012

- NICE DSU mapping resources:
  https://sheffield.ac.uk/nice-dsu/methods-development/mapping-eq-5d-5l-3l

- Devlin et al. (2018) describe the England EQ-5D-5L value set:
  https://doi.org/10.1002/hec.3564

- Rowen et al. (2026) describe the UK EQ-5D-5L value set:
  https://doi.org/10.1016/j.jval.2026.03.008