Package {eq5d}

Type: Package
Title: Methods for Analysing 'EQ-5D' Data and Calculating 'EQ-5D' Index Scores
Version: 0.17.0
Description: EQ-5D is a widely used health-related quality-of-life instrument developed by the EuroQol Group and used in the clinical and economic evaluation of health care. Health is described using five dimensions (mobility, self-care, usual activities, pain/discomfort, and anxiety/depression) rated on either a three-level (EQ-5D-3L and EQ-5D-Y-3L) or five-level (EQ-5D-5L) scale. Responses can be reported as EQ-5D health states or converted to utility index scores using country-specific value sets. The package provides methods for the valuation, reporting and analysis of EQ-5D data. Utility index scores can be calculated for EQ-5D-3L, EQ-5D-5L and EQ-5D-Y-3L data using a wide range of value sets and mapping approaches. Functionality is also provided for descriptive-system reporting, severity and distributional summaries, informativity measures, health-state distribution analysis, longitudinal change analysis, probability of superiority analysis and Health Profile Grid visualisation. Methods described in Devlin et al. (2020) <doi:10.1007/978-3-030-47622-9> are implemented where appropriate. A companion 'Shiny' application is included for interactive analysis and visualisation of EQ-5D datasets.
License: MIT + file LICENSE
Encoding: UTF-8
Depends: R (≥ 3.5.0), lifecycle, rlang
Suggests: testthat, shiny, DT, mime, readxl, ggplot2, ggiraph, ggiraphExtra, shinycssloaders, shinyWidgets, FSA, PMCMRplus, knitr, rmarkdown, covr
URL: https://github.com/fragla/eq5d
BugReports: https://github.com/fragla/eq5d/issues
RoxygenNote: 7.3.3
VignetteBuilder: knitr
Language: en-GB
NeedsCompilation: no
Packaged: 2026-08-28 17:01:01 UTC; fm78w
Author: Fraser Morton [aut, cre], Jagtar Singh Nijjar [aut]
Maintainer: Fraser Morton <fraser.morton@glasgow.ac.uk>
Repository: CRAN
Date/Publication: 2026-08-28 21:20:12 UTC

eq5d: Methods for Analysing 'EQ-5D' Data and Calculating 'EQ-5D' Index Scores

Description

EQ-5D is a widely used health-related quality-of-life instrument developed by the EuroQol Group and used in the clinical and economic evaluation of health care. Health is described using five dimensions (mobility, self-care, usual activities, pain/discomfort, and anxiety/depression) rated on either a three-level (EQ-5D-3L and EQ-5D-Y-3L) or five-level (EQ-5D-5L) scale. Responses can be reported as EQ-5D health states or converted to utility index scores using country-specific value sets. The package provides methods for the valuation, reporting and analysis of EQ-5D data. Utility index scores can be calculated for EQ-5D-3L, EQ-5D-5L and EQ-5D-Y-3L data using a wide range of value sets and mapping approaches. Functionality is also provided for descriptive-system reporting, severity and distributional summaries, informativity measures, health-state distribution analysis, longitudinal change analysis, probability of superiority analysis and Health Profile Grid visualisation. Methods described in Devlin et al. (2020) doi:10.1007/978-3-030-47622-9 are implemented where appropriate. A companion 'Shiny' application is included for interactive analysis and visualisation of EQ-5D datasets.

Author(s)

Maintainer: Fraser Morton fraser.morton@glasgow.ac.uk

Authors:

See Also

Useful links:

EQ-5D-5L Crosswalk data

Description

Crosswalk index value calculation table to calculate EQ-5D-3L indices from EQ-5D-5L data for Denmark, France, Germany, Japan, Netherlands, Russia, Spain, Thailand, UK, USA and Zimbabwe.

Usage

CW

Format

An object of class data.frame with 3125 rows and 13 columns.

Source

van Hout B, Janssen MF, et al. Interim scoring for the EQ-5D-5L: Mapping the EQ-5D-5L to EQ-5D-3L value sets. Value in Health 2012 Jul-Aug;15(5):708-15. doi:10.1016/j.jval.2012.02.008. PMID: 22867780.

Bailey H, Roudijk B, Brathwaite R. The EQ-5D-3L valuation study for Bermuda: using an on-line EQ-VT protocol. Eur J Health Econ. 2024 Jul 9. doi:10.1007/s10198-024-01701-2. Epub ahead of print. PMID: 38982011.

Al Rabayah A, Roudijk B, Purba FD, Rencz F, Jaddoua S, Siebert U. Valuation of the EQ-5D-3L in Jordan. Eur J Health Econ. 2024 Sep 3. doi:10.1007/s10198-024-01712-z. Epub ahead of print. PMID: 39225720.

Omelyanovskiy V, Musina N, Ratushnyak S, Bezdenezhnykh T, Fediaeva V, Roudijk B, Purba FD. Valuation of the EQ-5D-3L in Russia. Qual Life Res. 2021 Mar 13. doi:10.1007/s11136-021-02804-6. Epub ahead of print. PMID: 33713323.

EQ-5D-5L Crosswalk Index Value Sets

DSU mapping from EQ-5D-3L to EQ-5D-5L

Description

Data for age and sex based mapping from EQ-5D-3L dimensions or utility index score to EQ-5D-5L for China, Germany, Japan, Netherlands, South Korea, Spain and UK.

Usage

DSU3L

Format

An object of class data.frame with 2430 rows and 60 columns.

Source

Hernández Alava M, Pudney S, Wailoo A. Estimating the Relationship Between EQ-5D-5L and EQ-5D-3L: Results from a UK Population Study. Pharmacoeconomics. 2023 Feb;41(2):199-207. doi:10.1007/s40273-022-01218-7. Epub 2022 Nov 30. PMID: 36449173.

Hernández-Alava M, Pudney S. Econometric modelling of multiple self-reports of health states: The switch from EQ-5D-3L to EQ-5D-5L in evaluating drug therapies for rheumatoid arthritis. J Health Econ. 2017 Sep;55:139-152. doi:10.1016/j.jhealeco.2017.06.013. Epub 2017 Jul 4. PMID: 28778350.

NICE DSU mapping website.

DSU mapping from EQ-5D-5L to EQ-5D-3L

Description

Data for age and sex based mapping from EQ-5D-5L dimensions or utility index score to EQ-5D-3L for China, Germany, Japan, Netherlands, South Korea, Spain and UK.

Usage

DSU5L

Format

An object of class data.frame with 31250 rows and 60 columns.

Source

Hernández Alava M, Pudney S, Wailoo A. Estimating the Relationship Between EQ-5D-5L and EQ-5D-3L: Results from a UK Population Study. Pharmacoeconomics. 2023 Feb;41(2):199-207. doi:10.1007/s40273-022-01218-7. Epub 2022 Nov 30. PMID: 36449173.

Hernández-Alava M, Pudney S. Econometric modelling of multiple self-reports of health states: The switch from EQ-5D-3L to EQ-5D-5L in evaluating drug therapies for rheumatoid arthritis. J Health Econ. 2017 Sep;55:139-152. doi:10.1016/j.jhealeco.2017.06.013. Epub 2017 Jul 4. PMID: 28778350.

NICE DSU mapping website.

EQ-5D-3L Reverse Crosswalk data (deprecated)

Description

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 published on the EuroQol analysis tools webpage based on reverse engineering of van Hout et al (2012)

Usage

RCW

Format

An object of class data.frame with 243 rows and 4 columns.

Source

Reverse crosswalk datasets

EQ-5D-3L Reverse Crosswalk data

Description

Reverse Crosswalk index value table to calculate EQ-5D-5L indices from EQ-5D-3L data using the van Hout et al (2021) method.

Usage

RCWVH

Format

An object of class matrix (inherits from array) with 243 rows and 50 columns.

Source

doi:10.1016/j.jval.2021.03.009

EQ-5D-3L TTO value set data

Description

Coefficients for the estimation of the EQ-5D-3L index values based on TTO valuation studies for Argentina, Australia, Brazil, Canada, Chile, China, Denmark, Ecuador, France, Germany, Hungary, Italy, Japan, Netherlands (2006), Netherlands (2026), Pakistan, Poland, Portugal, Russia, Singapore, SouthKorea, Spain, SriLanka, Sweden, Taiwan, Thailand, Trinidad and Tobago, Tunisia, UK, USA and Zimbabwe.

Usage

TTO

Format

An object of class data.frame with 63 rows and 33 columns.

Source

Szende, A., Oppe, M., & de Charro, F. (2007), Comparative review of Time Trade-Off value sets. In Szende, A., Oppe, M., & Devlin, N. (Ed.), EQ-5D Value Sets: Inventory, Comparative Review and User Guide (pp. 27-28). Dordrecht, The Netherlands: Springer.

Janssen, B., Szende, A., & Ramos-Goñi JM. (2014), Data and Methods. Szende, A., Janssen, B., & Cabasés, J. (Ed.), In Self-Reported Population Health: An International Perspective based on EQ-5D (p 13). Dordrecht, The Netherlands: Springer.

EQ-5D-3L VAS value set data

Description

Coefficients for the estimation of the EQ-5D-3L index values based on VAS valuation studies for Belgium, Denmark, Europe, Finland, Germany, Iran, Malaysia, New Zealand, Slovenia, Spain and UK.

Usage

VAS

Format

An object of class data.frame with 21 rows and 11 columns.

Source

Oppe, M., Szende, A., & de Charro, F. (2007), Comparative review of Visual Analogue Scale value sets. In Szende, A., Oppe, M., & Devlin, N. (Ed.), EQ-5D Value Sets: Inventory, Comparative Review and User Guide (pp. 37-38). Dordrecht, The Netherlands: Springer.

EQ-5D-5L VT value set data

Description

EQ-5D-5L VT value set calculation data for Australia, Belgium, Canada, China, Denmark, Egypt, England, Ethiopia, France, Germany, Ghana, HongKong, Hungary, India, Indonesia, Iran, Ireland, Italy, Japan, Malaysia, Mexico, Morocco, Netherlands, NewZealand, Norway, Peru, Philippines, Poland, Portugal, Romania, SaudiArabia, Slovenia, SouthKorea, Spain, Sweden, Taiwan, Thailand, Uganda, UAE, Uruguay, USA, Vietnam and Western Preference Pattern (WePP).

Usage

VT

Format

An object of class data.frame with 37 rows and 50 columns.

Source

EQ-5D-Y-3L value set data

Description

EQ-5D-Y-3L value set calculation data for Australia, Belgium, Brazil, China, Germany, Hungary, Indonesia, Japan, Netherlands, Slovenia and Spain.

Usage

Y3L

Format

An object of class data.frame with 14 rows and 13 columns.

Source

Generate descriptive system data for EQ-5D

Description

Creates a tidy data.frame representing the EQ-5D descriptive system, suitable for plotting and tabular presentation. The output contains explicit columns for dimension, level, metric (count or percent), and optional grouping variables.

Usage

descriptive_data(
  data,
  version,
  metric = c("percent", "count"),
  group = NULL,
  dimensions = c("MO", "SC", "UA", "PD", "AD"),
  ignore.invalid = TRUE
)

Arguments

data

A data.frame containing EQ-5D responses.

version

EQ-5D version ("3L", "5L", or "Y3L").

metric

Character string, one of "percent" (default) or "count".

group

Optional character scalar giving the name of a grouping variable.

dimensions

Character vector of EQ-5D dimension names.

ignore.invalid

Logical; whether to ignore invalid responses.

Details

This function is designed as a canonical internal representation and may be used by plotting and table-generation functions. It does not return Stata-style summary tables; for those see eq5dds.

Value

A tidy data.frame with columns:

References

Ramos-Goñi JM, Ramallo-Fariña Y (2016). eq5dds: A command to analyze the descriptive system of the EQ-5D quality-of-life instrument. The Stata Journal, 16(3), 691–701. doi:10.1177/1536867X1601600309

See Also

eq5dds, plot_descriptive

Examples

## Load example EQ-5D-3L data included with the package
dat <- read.csv(
  system.file("extdata", "eq5d3l_example.csv", package = "eq5d")
)

## Descriptive system for the full sample
dd <- descriptive_data(
  data = dat,
  version = "3L"
)

dd

## Descriptive system stratified by group
dd_group <- descriptive_data(
  data = dat,
  version = "3L",
  group = "Group"
)

dd_group

Calculate EQ-5D index scores

Description

Wrapper for eq5d3l, eq5d5l and 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 valuesets.

Usage

eq5d(scores, version, type, country, ignore.invalid, ...)

Arguments

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".

version

string of value "3L", "5L" or "Y3L" to indicate instrument version.

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 crosswalk conversion valuesets, RCW for EQ-5D-3L reverse crosswalk conversion valuesets and DSU for the NICE Decision Support Unit's EEPRU age-sex based EQ-5D-3L to EQ-5D-5L and EQ-5D-5L to EQ-5D-3L mappings. Not required for EQ-5D-Y-3L.

country

string of value set country name used.

ignore.invalid

logical to indicate whether to ignore dimension data with invalid, incomplete or missing data.

...

character vectors for column names when using a data.frame. Use "dimensions" (default c("MO", "SC", "UA", "PD" and "AD")), "five.digit" (default "State") or "utility", "age", "sex" and "bwidth" (defaults "Utility", "Age", "Sex" and "bwidth") for NICE DSU mapping. bwidth can also 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 eq5dmap for valid options. "digits" can also be used to return scores with more precision.

Value

a numeric vector of utility index scores.

Examples


#EQ-5D-5L single utility score by dimension
eq5d(scores=c(MO=1,SC=2,UA=3,PD=4,AD=5), type="VT",
 country="Indonesia", version="5L")
 
#EQ-5D-3L single utility score by dimension
eq5d(scores=c(MO=3,SC=2,UA=3,PD=2,AD=3),
 type="TTO", version="3L", country="Germany")

#Mapping an EQ-5D-5L utility score to EQ-5D-3L using NICE DSU method
eq5d(0.922, country="UK", version="5L", type="DSU",
 age=18, sex="male")

#Calculation of multiple EQ-5D-5L utility scores from a data.frame of dimensions
scores.df <- data.frame(
  MO=c(1,2,3,4,5), SC=c(1,5,4,3,2),
  UA=c(1,5,2,3,1), PD=c(1,3,4,3,4), AD=c(1,2,NA,2,1)
)

eq5d(scores.df, country="Canada", version="5L", type="VT", ignore.invalid=TRUE)

#Calculation of a utility score using five digit state
eq5d(scores=12321, type="TTO", version="3L", country="UK")

scores.df2 <- data.frame(
  state=c(11111,12121,23232,33333)
)

#Calculation of utility scores using a data.frame with five digit states
eq5d(scores=scores.df2, type="TTO", version="3L", country="UK", five.digit="state")

#Calculation of utility scores from a vector of five digit states
eq5d(scores=scores.df2$state, type="TTO", version="3L", country="UK")

#Mapping multiple utility scores from EQ-5D-5L to EQ-5D-3L using NICE DSU method
scores.df3 <- data.frame(
  Utility=c(0.715,0.435,0.95),
  Age=c(50,30,70),
  Sex=c("m","f","m"),
  bwidth=c(0.2,0.2,0.1)
)

#using bwidth column values (one per observation)
eq5d(scores.df3, type="DSU", version="5L", country="UK")

#using single bwidth value for whole dataset
eq5d(scores.df3, type="DSU", version="5L", country="UK", bwidth=0.1)

Calculate EQ-5D-3L index scores

Description

Calculate indices for EQ-5D-3L value sets. Available value sets can be viewed using the function valuesets.

Usage

eq5d3l(scores, type = "TTO", country = "UK", digits = 3)

Arguments

scores

numeric with names MO, SC, UA, PD and AD representing Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression.

type

3L values set type. Either TTO or VAS.

country

value set country.

digits

number of decimal places to return.

Value

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")

Calculate EQ-5D-5L index scores

Description

Calculate indices for EQ-5D-5L value sets. Available value sets can be viewed using the function valuesets.

Usage

eq5d5l(scores, country = "England", digits = 3)

Arguments

scores

numeric with names MO, SC, UA, PD and AD representing Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression.

country

value set country.

digits

number of decimal places to return.

Value

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")

eq5d plotting theme

Description

Default ggplot2 theme matching the academic style used in Methods for Analysing and Reporting EQ-5D Data (Devlin et al., 2020).

Usage

eq5d_theme(base_size = 11, base_family = "")

Arguments

base_size

Base font size, in points.

base_family

Base font family.

Value

A ggplot2 theme.

Calculate the cumulative frequency distribution of EQ-5D health states

Description

Computes the frequency, proportion, and cumulative distribution of EQ-5D health states in a dataset. The function accepts EQ-5D data supplied either as dimension-level columns (MO, SC, UA, PD, AD) or as a single column of five-digit EQ-5D health states.

Usage

eq5dcf(scores, version, ignore.invalid = TRUE, digits = 1, ...)

Arguments

scores

EQ-5D health states supplied as:

  • a vector of 5-digit EQ-5D health states (character or numeric), or

  • a data.frame containing either dimension columns (MO, SC, UA, PD, AD) or a single health-state column named "state" (case-insensitive).

version

Character string identifying the EQ-5D version: one of "3L", "5L", or "Y3L".

ignore.invalid

Logical. If TRUE, invalid health states are replaced with NA. If FALSE, invalid values trigger an error.

digits

Integer specifying the number of decimal places used when rounding percentages. Defaults to 1.

...

Additional arguments reserved for future use.

Details

The output is a tidy data.frame containing frequencies and cumulative proportions, suitable for computing informativity indices (e.g. HSDI) or for plotting Health State Density Curves (HSDC).

Value

A data.frame with one row per observed health state and columns:

Examples

dat <- read.csv(system.file("extdata", "eq5d3l_example.csv", package="eq5d"))
eq5dcf(dat, "3L")

Calculate EQ-5D-5L crosswalk index scores

Description

Calculate indices for EQ-5D-5L indices by mapping them onto EQ-5D-3L value sets. Available value sets can be viewed using the function valuesets.

Usage

eq5dcw(scores, country = "UK")

Arguments

scores

numeric with names MO, SC, UA, PD and AD representing Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression.

country

value set country.

Value

calculated utility index score.

Examples

eq5dcw(scores=c(MO=1,SC=2,UA=5,PD=1,AD=3), country="UK")
eq5dcw(scores=c(MO=3,SC=5,UA=5,PD=2,AD=3), country="Germany")

Analyse the descriptive system of an EQ-5D dataset

Description

Analyses the descriptive components of an EQ-5D dataset producing summary information either as counts or as percentages.

Usage

eq5dds(
  data,
  version,
  counts = FALSE,
  by = NULL,
  ignore.invalid = TRUE,
  digits = 1,
  ...
)

Arguments

data

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 an EQ-5D score can be provided in five digit format e.g. 12321.

version

string of value "3L" or "5L" to indicate instrument version.

counts

logical show absolute counts in the summary table. Default is FALSE, which shows percentages for each EQ-5D dimension.

by

character specifying the column in the data.frame by which to group the results.

ignore.invalid

boolean whether to ignore invalid scores. TRUE returns NA, FALSE throws an error.

digits

Integer specifying the number of decimal places used when reporting percentages. Set to NULL to suppress rounding.

...

character vector, specifying "dimensions" column names. Defaults are "MO", "SC", "UA", "PD" and "AD".

Value

a data.frame or list of data.frames of counts/percentages. Columns contain dimensions names and rows the EQ-5D score.

Examples

dat <- data.frame(
         matrix(
           sample(1:3,5*12, replace=TRUE),12,5, 
           dimnames=list(1:12,c("MO","SC","UA","PD","AD"))
         ),
         Sex=rep(c("Male", "Female"))
       )

eq5dds(dat, version="3L")
eq5dds(dat, version="3L", counts=TRUE)

eq5dds(dat, version="3L", by="Sex")

Calculate utility index scores by mapping between EQ-5D-3L and EQ-5D-5L

Description

Conditional prediction of the utility values of 5L scores onto 3L value sets and 3L scores onto 5L value sets from observed or specified values conditional on age and gender using the NICE Decision Support Unit's EEPRU funded models (see NICE DSU's website for more information).

Usage

eq5dmap(scores, country, version, age, sex, bwidth = 0, digits = 3)

Arguments

scores

numeric with names MO, SC, UA, PD and AD representing Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression. or a utility index score

country

value set country. The original DSU mapping used the England EQ-5D-5L value set, available as "England_2018". The newer UK EQ-5D-5L value set is available as "UK_2026". "UK" is retained as an alias for "England_2018". For backwards compatibility, "UK" is treated as an alias for "England_2018".

version

string of value "3L" or "5L" to indicate starting instrument version.

age

age in years (18-100), or age category (1: 18-34, 2: 35-44, 3: 45-54, 4: 55-64, 5: 65-100)

sex

Male or Female

bwidth

bandwidth score for approximate scores (< 0.8: 0.2, 0.8-0.951: 0.1, 0.951-1: small, but large enough to include 1)

digits

number of decimal places to return

Details

Available value sets can be viewed using the function valuesets.

Mapping may be performed from either EQ-5D dimension scores or an existing utility index score. When a utility score is supplied, exact lookup is used when bwidth = 0 (default); otherwise an Epanechnikov kernel smoother is applied. Utility values in the package lookup tables are stored rounded to 3 decimal places, consistent with standard reporting of EQ-5D index scores. Exact lookup is therefore generally intended for utility values reported to 3 decimal places.

Value

calculated utility index score.

Examples

eq5dmap(c(MO=1,SC=2,UA=3,PD=4,AD=5), "UK_2026", "5L", 30, "female")
eq5dmap(0.848, "UK_2026", "3L", 70, "male")
eq5dmap(0.715, "England_2018", "5L", 50, "male", bwidth = 0.0001)
eq5dmap(0.715, "England_2018", "5L", 50, "male", bwidth = 0.0001, digits = 8)

Calculate EQ-5D-3L reverse crosswalk index scores

Description

Calculate indices for EQ-5D-3L indices by mapping them onto EQ-5D-5L value sets. Available value sets can be viewed using the function valuesets.

Usage

eq5drcw(scores, country = "UK", method = "VH", digits = 3)

Arguments

scores

numeric with names MO, SC, UA, PD and AD representing Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression.

country

value set country.

method

crosswalk values to use. Either "VH" (Van Hout, 2021) or "EQ" (EuroQol 2019 values). The van Hout method is recommended.

digits

number of decimal places to return.

Value

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")

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.

Usage

eq5dy(scores, country = NULL)

Arguments

scores

numeric with names MO, SC, UA, PD and AD representing Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression.

country

value set country.

Value

calculated utility index score.

Calculate EQ-5D-Y-3L index scores

Description

Calculate indices for EQ-5D-Y-3L value sets. Available value sets can be viewed using the function valuesets.

Usage

eq5dy3l(scores, country = NULL, digits = 3)

Arguments

scores

numeric with names MO, SC, UA, PD and AD representing Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression.

country

value set country.

digits

number of decimal places to return.

Value

calculated utility index score.

Examples

eq5dy3l(scores=c(MO=3,SC=3,UA=3,PD=3,AD=3), country="Slovenia")

Get all five digit health state scores

Description

Get all five digit health state scores for either EQ-5D-3L, EQ-5D-5L or EQ-5D-Y3L

Usage

get_all_health_states(version)

Arguments

version

the EQ-5D version. Either 3L or 5L.

Value

A character vector of five digit health states.

Examples

get_all_health_states("3L")
get_all_health_states("5L")
get_all_health_states("Y3L")

Get individual dimension scores from their five digit health states

Description

Get a data.frame of individual dimension scores from their five digit health states.

Usage

get_dimensions_from_health_states(
  scores,
  version = "5L",
  ignore.invalid = TRUE
)

Arguments

scores

a vector of five digit scores

version

3L, 5L or Y. Used for validating scores when ignore.invalid is FALSE.

ignore.invalid

whether to ignore invalid scores. TRUE returns NA, FALSE throws an error.

Value

A data.frame of individual dimension scores.

Examples

get_dimensions_from_health_states(c("12345", "54321"), version="5L")

Get five digit health states from dimension scores

Description

Merge MO, SC, UA, PD and AD dimension scores to get five digit health states.

Usage

get_health_states_from_dimensions(
  scores,
  version = "5L",
  ignore.invalid = TRUE,
  dimensions = .get_dimension_names()
)

Arguments

scores

a data.fram containing each dimension in a column

version

3L, 5L or Y. Used for validating scores when ignore.invalid is FALSE.

ignore.invalid

whether to ignore invalid scores. TRUE returns NA, FALSE throws an error.

dimensions

character vector specifying "dimensions" column names. Defaults are "MO", "SC", "UA", "PD" and "AD".

Value

A character vector of individual dimension scores.

Examples

scores <- data.frame(MO=c(1,1,1,1,1),SC=c(1,2,1,2,1),
                     UA=c(1,2,3,2,1),PD=c(3,2,1,2,3),AD=c(3,3,3,3,3))
get_health_states_from_dimensions(scores, version="5L")

Health Profile Grid (HPG) for EQ-5D

Description

Computes the Health Profile Grid (HPG) for two sets of EQ-5D health states. The HPG displays pre- and post-intervention utility ranks and the associated PCHC category for each subject.

Two input interfaces are supported:

1. Wide-form input (default method) hpg(pre, post) where pre and post are EQ-5D health states represented either as:

2. Long-form input (formula method) hpg(formula, data) where the formula has left-hand side forms:

and right-hand side of the form time | id, where:

For formula methods the time variable must contain exactly two observable levels unless the user specifies pre.level and post.level. When not supplied, the ordering of pre- and post-measurements is determined automatically as follows:

Usage

hpg(
  pre,
  post = NULL,
  country = NULL,
  version = NULL,
  type = NULL,
  ignore.invalid = TRUE,
  dimensions = NULL,
  pre.level = NULL,
  post.level = NULL,
  no.problems = TRUE,
  data = NULL
)

## Default S3 method:
hpg(
  pre,
  post,
  country = NULL,
  version = NULL,
  type = NULL,
  ignore.invalid = TRUE,
  dimensions = NULL,
  pre.level = NULL,
  post.level = NULL,
  no.problems = TRUE,
  data = NULL
)

## S3 method for class 'formula'
hpg(
  formula,
  post = NULL,
  country = NULL,
  version = NULL,
  type = NULL,
  ignore.invalid = TRUE,
  dimensions = NULL,
  pre.level = NULL,
  post.level = NULL,
  no.problems = TRUE,
  data = NULL
)

Arguments

pre

For the wide-form interface, pre-intervention EQ-5D values (5-digit profiles or dimension data.frame). For the formula interface, a formula describing EQ-5D variables on the left-hand side and a time variable (and optionally an ID variable) on the right-hand side, e.g. profile ~ visit | id.

post

For the wide-form interface, post-intervention EQ-5D values. Ignored for the formula interface.

country

Country name passed to eq5d().

version

EQ-5D version: "3L", "5L", or "Y3L".

type

EQ-5D valuation method supplied to eq5d().

ignore.invalid

Logical; if TRUE, invalid EQ-5D values are replaced with NA. If FALSE, invalid values trigger an error.

dimensions

Optional named character vector mapping canonical dimension names (MO, SC, UA, PD, AD) to alternative column names. Only used in formula methods with multiple dimension columns.

pre.level

Optional value of the time variable representing the pre-intervention visit.

post.level

Optional value of the time variable representing the post-intervention visit.

no.problems

Logical; passed to pchc() to classify 11111 -> 11111 transitions as "No problems".

data

Long-form dataset used with the formula interface. Ignored for the wide-form interface.

formula

A formula describing EQ‑5D variables on the left‑hand side and a time variable (and optionally an ID variable) on the right‑hand side, separated by |. Used only with the formula interface.

Value

A data.frame with columns:

Examples

## Not run: 
## Load example EQ-5D-3L data included with the package
dat <- read.csv(
  system.file("extdata", "eq5d3l_example.csv", package = "eq5d")
)

## Wide-form usage (illustrative row-wise pairing)
pre  <- dat[dat$Group == "Group1", ][1:50, ]
post <- dat[dat$Group == "Group2", ][1:50, ]

res <- hpg(pre, post,
           country = "UK",
           version = "3L",
           type    = "TTO")

head(res)

## Long-form usage via formula interface
## (requires data in long format with subject identifiers)

## Using a 5-digit EQ-5D profile column
hpg(profile ~ visit | id, data = df,
    country = "UK", version = "3L", type = "TTO")

## Using EQ-5D dimension columns
hpg(MO + SC + UA + PD + AD ~ visit | id, data = df,
    country = "UK", version = "3L", type = "TTO")

## Explicit time ordering
hpg(profile ~ time | id, data = df, version = "3L",
    pre.level  = "baseline",
    post.level = "followup")

## End(Not run)

Calculate the Health State Density Index

Description

Calculate the Health State Density Index (HSDI) for an EQ-5D dataset.

Usage

hsdi(scores, version = NULL, ignore.invalid = TRUE, digits = 2, ...)

Arguments

scores

scores data.frame, numeric or character. For data.frame default column names should be MO, SC, UA, PD and AD representing Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression. Vector using five digit format can also be used.

version

string of value "3L" or "5L" to indicate instrument version.

ignore.invalid

booloean whether to ignore invalid scores. TRUE returns NA, FALSE throws an error.

digits

numeric specifying the number of decimal places for percentages. Defaults to 1, use NULL to skip rounding.

...

character vector, specifying "dimensions" column names. Defaults are "MO", "SC", "UA", "PD" and "AD".

Value

numeric containing the HSDI value.

Examples

## Load example EQ-5D-3L data included with the package
dat <- read.csv(
  system.file("extdata", "eq5d3l_example.csv", package = "eq5d")
)

## Health State Density Index (HSDI)
hsdi(dat, version = "3L")

Calculate the Level Frequency Score for an EQ-5D profile

Description

Calculate the Levels Frequency Score for one or more EQ-5D profiles

Usage

lfs(scores, version, ignore.invalid, ...)

Arguments

scores

EQ-5D health states supplied as:

  • a named numeric vector of dimension levels (MO, SC, UA, PD, AD),

  • a 5-digit EQ-5D health state (character or numeric),

  • a vector of 5-digit health states,

  • or a data.frame containing either dimension columns or a single health state column.

version

string of value "3L", "5L" or "Y3L" to indicate instrument version.

ignore.invalid

whether to ignore invalid scores. TRUE returns NA, FALSE throws an error.

...

Optional arguments.

dimensions

Character vector giving names of EQ-5D dimension columns.

five.digit

Name of the column containing 5-digit EQ-5D health states when 'scores' is a data.frame (default: "State"). Matching is case-insensitive.

Value

a character vector of Level Frequency Scores.

Examples

lfs(c(MO=1,SC=2,UA=3,PD=2,AD=1), version="3L")
lfs(55555, version="5L")
lfs(c(11111, 12345, 55555), version="5L")
lfs(data.frame(state = c("11111", "12345")), version = "5L")

Calculate the Level Sum Score for an EQ-5D profile

Description

Calculate the Levels Sum Score for one or more EQ-5D profiles

Usage

lss(scores, version, ignore.invalid, ...)

Arguments

scores

EQ-5D health states supplied as:

  • a named numeric vector of dimension levels (MO, SC, UA, PD, AD),

  • a 5-digit EQ-5D health state (character or numeric),

  • a vector of 5-digit health states,

  • or a data.frame containing either dimension columns or a single health state column.

version

string of value "3L", "5L" or "Y3L" to indicate instrument version.

ignore.invalid

whether to ignore invalid scores. TRUE returns NA, FALSE throws an error.

...

Optional arguments.

dimensions

Character vector giving names of EQ-5D dimension columns.

five.digit

Name of the column containing 5-digit EQ-5D health states when 'scores' is a data.frame (default: "State"). Matching is case-insensitive.

are "MO", "SC", "UA", "PD" and "AD".

Value

an integer vector of Level Sum Scores.

Examples

lss(c(MO=1,SC=2,UA=3,PD=2,AD=1), version="3L")
lss(55555, version="5L")
lss(c(11111, 12345, 55555), version="5L")

Generate Health State Density Curve (HSDC) data by group

Description

Computes health-state cumulative frequency distributions separately for each level of a grouping variable and returns a combined data frame suitable for Health State Density Curve (HSDC) plotting.

This function is a lightweight orchestration helper: it performs explicit data splitting and applies eq5dcf to each subgroup, but does not alter the definition or interpretation of the underlying distributional summaries.

Usage

make_hsdc_by_group(data, group, version)

Arguments

data

A data.frame containing EQ-5D descriptive-system data.

group

Character scalar specifying the name of the grouping variable in data.

version

EQ-5D instrument version. One of "3L", "5L", or "Y3L".

Value

A data.frame containing cumulative frequency distributions for each group. The returned data are suitable for direct use with plot_hsdc.

See Also

eq5dcf, hsdi, plot_hsdc, make_hsdi_by_group

Examples

dat <- read.csv(
  system.file("extdata", "eq5d3l_example.csv", package = "eq5d")
)

## Grouped HSDC data by treatment group
hsdc_by_group <- make_hsdc_by_group(
  dat,
  group = "Group",
  version = "3L"
)

plot_hsdc(hsdc_by_group)

Compute Health State Density Index (HSDI) by group

Description

Computes the Health State Density Index (HSDI) separately for each level of a grouping variable. This function is a lightweight orchestration helper that performs explicit data splitting prior to computation and does not alter the definition or interpretation of HSDI.

Usage

make_hsdi_by_group(data, group, version)

Arguments

data

A data.frame containing EQ-5D descriptive-system data.

group

Character scalar giving the name of the grouping variable in data.

version

EQ-5D instrument version. One of "3L", "5L", or "Y3L".

Value

A named numeric vector of HSDI values, with one entry per group.

See Also

eq5dcf, hsdi, make_hsdc_by_group

Examples

dat <- read.csv(
  system.file("extdata", "eq5d3l_example.csv", package = "eq5d")
)

## HSDI by group
hsdi_by_group <- make_hsdi_by_group(
  dat,
  group = "Group",
  version = "3L"
)

Paretian Classification of Health Change (PCHC)

Description

Computes the Paretian Classification of Health Change (PCHC) for EQ‑5D data. PCHC classifies change between two EQ‑5D health states into:

The method applied depends on the class of the first argument:

Computes the Paretian Classification of Health Change from wide-form EQ-5D data where pre- and post-intervention states are supplied as separate objects.

Computes the Paretian Classification of Health Change from long-form EQ-5D data using a formula interface.

Usage

pchc(
  pre,
  post = NULL,
  version = NULL,
  id = NULL,
  pre.level = NULL,
  post.level = NULL,
  duplicates = c("error", "first", "last"),
  no.problems = TRUE,
  totals = TRUE,
  by.dimension = FALSE,
  ignore.invalid = TRUE,
  dimensions = NULL,
  summary = TRUE,
  data = NULL
)

## Default S3 method:
pchc(
  pre,
  post,
  version = NULL,
  id = NULL,
  pre.level = NULL,
  post.level = NULL,
  duplicates = c("error", "first", "last"),
  no.problems = TRUE,
  totals = TRUE,
  by.dimension = FALSE,
  ignore.invalid = TRUE,
  dimensions = NULL,
  summary = TRUE,
  data = NULL
)

## S3 method for class 'formula'
pchc(
  formula,
  post = NULL,
  version = NULL,
  id = NULL,
  pre.level = NULL,
  post.level = NULL,
  duplicates = c("error", "first", "last"),
  no.problems = TRUE,
  totals = TRUE,
  by.dimension = FALSE,
  ignore.invalid = TRUE,
  dimensions = NULL,
  summary = TRUE,
  data = NULL
)

Arguments

pre

A data.frame of EQ-5D dimensions or a vector of 5-digit EQ-5D profiles.

post

Same format as pre, representing post-intervention states.

version

EQ-5D instrument version: "3L", "5L", or "Y3L".

id

Optional character string naming the subject identifier column when it is not supplied in the formula.

pre.level

Optional value of the time variable identifying the pre‑intervention visit. Required when the time variable has more than two levels or when automatic inference would be incorrect.

post.level

Optional value of the time variable identifying the post‑intervention visit.

duplicates

How to handle duplicate observations per subject and time point in long‑form data. One of "error", "first", or "last".

no.problems

Logical; classify 11111 to 11111 as "No problems".

totals

Logical; include total rows in the summary table.

by.dimension

Logical; compute PCHC separately for each EQ-5D dimension.

ignore.invalid

Logical; if TRUE, invalid or missing values yield NA rows; if FALSE, an error is thrown.

dimensions

Character vector naming EQ-5D dimension columns.

summary

Logical; return summary table or individual classifications.

data

A long‑form data.frame used with the formula interface.

formula

A formula specifying EQ‑5D variables on the left‑hand side and a time variable (and optionally an ID variable) on the right‑hand side. This argument is used only in the formula interface.

Details

When summary = FALSE, the function returns individual‑level PCHC classifications, one per subject. When summary = TRUE, it returns a tabular summary reporting counts and percentages by PCHC category, suitable for reporting.

The totals argument applies only when summary = TRUE; it is ignored otherwise. Missing or invalid EQ‑5D values are handled consistently across all methods via the ignore.invalid argument.

For formula methods the time variable must contain exactly two observable levels unless the user specifies pre.level and post.level. When not supplied, the ordering of pre‑ and post‑measurements is determined automatically as follows:

Value

When summary = FALSE and by.dimension = FALSE, a character vector of individual-level PCHC classifications.

When summary = TRUE and by.dimension = FALSE, a data.frame summarising PCHC categories with counts and percentages.

When by.dimension = TRUE, a named list is returned with one element per EQ-5D dimension. Each element is a character vector (when summary = FALSE) or a data.frame (when summary = TRUE).

Examples

## Load example EQ-5D-3L data included with the package
dat <- read.csv(
  system.file("extdata", "eq5d3l_example.csv", package = "eq5d")
)

## Wide form (explicit pre/post data)
pre  <- dat[dat$Group == "Group1", ][1:50, ]
post <- dat[dat$Group == "Group2", ][1:50, ]

pchc(pre, post, version = "3L", no.problems = FALSE, totals = FALSE)

## Long form (formula interface)
## Not run: 
pchc(profile ~ visit | id, data = eq_long)
pchc(MO + SC + UA + PD + AD ~ visit | id, data = eq_long)

## End(Not run)

Plot EQ-5D Descriptive System

Description

Creates bar charts summarising the EQ-5D descriptive system by dimension and level using pre-computed descriptive data. Bars representing EQ-5D response levels are displayed side-by-side within each dimension. When grouped data are supplied, separate panels are created using faceting.

Usage

plot_descriptive(
  descriptive_data,
  alpha = 1,
  theme = eq5d_theme(),
  xlab = "Dimension",
  ylab = NULL,
  dimension_labels = NULL
)

Arguments

descriptive_data

A data.frame produced by descriptive_data.

alpha

Numeric transparency for bars.

theme

A ggplot2 theme, defaults to the internal eq5d_theme().

xlab

Character string for the x-axis label.

ylab

Character string for the y-axis label. If NULL, it is inferred from the Metric column ("Percentage" or "Count").

dimension_labels

Optional named character vector mapping EQ-5D dimension codes (MO, SC, UA, PD, AD) to display labels.

Details

This function performs no analytical computation. It visualises the output of descriptive_data, which serves as the canonical representation of the EQ-5D descriptive system.

The descriptive system summarises the distribution of response levels within each EQ-5D dimension. Bars are shown side-by-side to facilitate comparison across response levels. When grouped data are supplied, the plot uses faceting to aid comparison across groups while avoiding overplotting and excessive use of colour.

Value

A ggplot object.

References

Ramos-Goñi JM, Ramallo-Fariña Y (2016). eq5dds: A command to analyze the descriptive system of the EQ-5D quality-of-life instrument. The Stata Journal, 16(3), 691–701. doi:10.1177/1536867X1601600309

See Also

descriptive_data

Examples

## Load example EQ-5D-3L data included with the package
dat <- read.csv(
  system.file("extdata", "eq5d3l_example.csv", package = "eq5d")
)

## Create canonical descriptive data (percentages)
dd <- descriptive_data(dat, version = "3L")

## Basic descriptive system plot
plot_descriptive(dd)

## Grouped descriptive system plot
dd_grp <- descriptive_data(dat, version = "3L", group = "Group")
plot_descriptive(dd_grp)

## Descriptive system using counts
dd_count <- descriptive_data(dat, version = "3L", metric = "count")
plot_descriptive(dd_count)

## Descriptive system with full dimension labels
plot_descriptive(
  dd,
  dimension_labels = c(
    MO = "Mobility",
    SC = "Self care",
    UA = "Usual activities",
    PD = "Pain & Discomfort",
    AD = "Anxiety & Depression"
  )
)

Plot Health Profile Grid (HPG)

Description

Visualises paired changes in EQ-5D health states using a Health Profile Grid (HPG). Each point represents an individual pre–post transition in EQ-5D index space, with a diagonal reference line indicating no change.

Usage

plot_hpg(
  hpg_data,
  version,
  include_no_problems = TRUE,
  xlab = "Post",
  ylab = "Pre",
  colours = NULL,
  shapes = NULL,
  theme = eq5d_theme()
)

Arguments

hpg_data

A data.frame returned by hpg, containing at least the columns Pre, Post, and PCHC.

version

EQ-5D version ("3L", "5L", or "Y3L").

include_no_problems

Logical; if FALSE, transitions corresponding to full health to full health (11111 to 11111) are excluded from the plot. This affects only the visualisation and does not modify the underlying hpg() results.

xlab

Character string giving the x-axis label. Defaults to "Post".

ylab

Character string giving the y-axis label. Defaults to "Pre".

colours

Optional named character vector overriding the default colours for transition classes present in the data.

shapes

Optional named numeric vector overriding the default shapes for transition classes present in the data.

theme

A ggplot2 theme applied to the plot. Defaults to the internal eq5d_theme().

Details

This function is a pure visualisation layer and expects the output of hpg. No analytical computation is performed.

The input to plot_hpg() is the result of hpg(), which may be generated using paired pre- and post-measurement data (for example as vectors or data frames), or via an alternative formula interface supported by hpg().

Transition classes follow the terminology and ordering used in the reference book: Improve, Mixed change, No change, Worsen, and No problems. Only transition classes present in the plotted data are shown in the legend.

The Health Profile Grid is intended for paired data and illustrates how individuals move between health states over time. Points on the diagonal indicate no change, while points above the diagonal represent improvement and points below the diagonal represent deterioration.

Value

A ggplot object.

References

Devlin N, Parkin D, Janssen B (2020). Methods for Analysing and Reporting EQ-5D Data. Springer Open. doi:10.1007/978-3-030-47622-9

See Also

hpg

Examples

## Not run: 
res <- hpg(pre, post, country = "UK", version = "3L", type = "TTO")

## Default labels
plot_hpg(res, version = "3L")

## Custom axis labels
plot_hpg(
  res,
  version = "3L",
  xlab = "Post-treatment",
  ylab = "Pre-treatment"
)

## End(Not run)

Plot Health State Density Curve (HSDC)

Description

Visualises the distribution of EQ-5D health profiles using the Health State Density Curve (HSDC) as described by Zamora et al (2018) and Devlin et al. (2020) The HSDC plots the cumulative proportion of observed health states against the cumulative proportion of observations, analogous to a Lorenz curve.

Usage

plot_hsdc(
  data,
  group = NULL,
  hsdi = NULL,
  diagonal = TRUE,
  colours = NULL,
  linewidth = 1,
  alpha = 1,
  theme = eq5d_theme(),
  xlab = "Cumulative percentage of observations",
  ylab = "Cumulative percentage of health states"
)

Arguments

data

A data.frame containing cumulative distribution data with at least the columns CumulativeProp and CumulativeState, as returned by eq5dcf.

group

Optional character scalar giving the name of a grouping column for plotting multiple HSDCs on the same axes.

hsdi

Optional numeric value, or named numeric vector for grouped data, giving Health State Density Index (HSDI) values to annotate on the plot.

diagonal

Logical; if TRUE, draw the 45-degree reference line.

colours

Optional named character vector specifying colours for grouped curves.

linewidth

Numeric line width for plotted curves.

alpha

Numeric transparency level for plotted curves.

theme

A ggplot2 theme. Defaults to the internal eq5d_theme().

xlab

Character string for the x-axis label.

ylab

Character string for the y-axis label.

Details

The input data must be a pre-computed cumulative distribution, typically returned by eq5dcf or make_hsdc_by_group. This function performs no analytical computation; it only visualises the supplied data.

Axes are displayed as cumulative percentages (0–100%). A 45-degree reference line indicates a perfectly even distribution of health states.

Curves that lie close to the diagonal indicate an even distribution of health profiles. Curves that lie further below the diagonal indicate increasing concentration of observations on a small number of health states.

Value

A ggplot object.

References

Zamora B, Parkin D, Feng Y, Bateman A, Herdman M, Devlin N (2018). New methods for analysing the distribution of EQ-5D observations. OHE Research Paper.

Devlin N, Parkin D, Janssen B (2020). Methods for Analysing and Reporting EQ-5D Data. Springer Open. doi:10.1007/978-3-030-47622-9

See Also

eq5dcf, hsdi, make_hsdc_by_group

Examples

dat <- read.csv(system.file("extdata", "eq5d3l_example.csv", package = "eq5d"))

cf <- eq5dcf(dat, version = "3L")
plot_hsdc(cf)

## Grouped Health State Density Curves
## Generate cumulative distributions by group
hsdc_grp <- make_hsdc_by_group(dat, group = "Group", version = "3L")

## Compute HSDI by group
hsdi_grp <- make_hsdi_by_group(dat, group = "Group", version = "3L")

## Plot grouped HSDCs with HSDI annotation
plot_hsdc(
  data  = hsdc_grp,
  group = "Group",
  hsdi  = hsdi_grp
)

Plot EQ-5D Severity Summary

Description

Summarises EQ-5D index values by severity category using the Level Frequency Score (LFS) or Level Sum Score (LSS). For each severity category, the lowest, median, and highest EQ-5D index values are shown using a range marker and horizontal ticks.

Usage

plot_severity_summary(
  data,
  country,
  version,
  type,
  severity = c("LFS", "LSS"),
  tick_width = 0.12,
  theme = eq5d_theme()
)

Arguments

data

A data.frame containing EQ-5D responses.

country

Country value set used for EQ-5D index calculation.

version

EQ-5D version ("3L", "5L", or "Y3L").

type

EQ-5D valuation type.

severity

Severity metric to use; either "LFS" or "LSS".

tick_width

Width of horizontal ticks in severity category units.

theme

A ggplot2 theme applied to the plot. Defaults to the internal eq5d_theme().

Details

This plot corresponds to severity summary figures in the Devlin book, where EQ-5D index values are examined across severity strata rather than plotting severity measures themselves. LFS and LSS are treated as alternative severity definitions and are not plotted together.

Value

A ggplot object.

References

Devlin N, Parkin D, Janssen B (2020). Methods for Analysing and Reporting EQ-5D Data. Springer Open. doi:10.1007/978-3-030-47622-9

See Also

lfs, lss, eq5d

Probability of Superiority (PS) for EQ‑5D

Description

Computes the Probability of Superiority (PS) for each EQ‑5D dimension based on the Paretian Classification of Health Change (PCHC).

PS quantifies whether post‑intervention EQ‑5D states tend to be superior to pre‑intervention states:

PS = \frac{\text{Improve} + 0.5 \times \text{No change}}{\text{Total}}

Interpretation:

Two interfaces are supported:

1. Wide‑form input (default) ps(pre, post) where pre and post are EQ‑5D states in 5‑digit form or data frames containing EQ‑5D dimension columns.

2. Long‑form + formula interface ps(formula, data) mirroring the interface of pchc().

For formula methods, the time variable must contain exactly two observable levels unless the user specifies pre.level and post.level. When not supplied, the ordering of pre‑ and post‑measurements is determined automatically as follows:

Computes the Probability of Superiority from wide‑form EQ‑5D data where pre‑ and post‑intervention states are supplied as separate objects.

Computes the Probability of Superiority from long‑form EQ‑5D data using a formula interface.

Usage

ps(
  pre,
  post = NULL,
  version = NULL,
  ignore.invalid = TRUE,
  dimensions = NULL,
  digits = 2,
  pre.level = NULL,
  post.level = NULL,
  data = NULL
)

## Default S3 method:
ps(
  pre,
  post,
  version = NULL,
  ignore.invalid = TRUE,
  dimensions = NULL,
  digits = 2,
  pre.level = NULL,
  post.level = NULL,
  data = NULL
)

## S3 method for class 'formula'
ps(
  formula,
  post = NULL,
  version = NULL,
  ignore.invalid = TRUE,
  dimensions = NULL,
  digits = 2,
  pre.level = NULL,
  post.level = NULL,
  data = NULL
)

Arguments

pre

For the wide‑form interface, pre‑intervention EQ‑5D states (5‑digit character/numeric vector or data frame of EQ‑5D dimensions). For the formula interface, a formula describing EQ‑5D variables on the left‑hand side and a time variable (and optionally an ID variable) on the right‑hand side, e.g. profile ~ visit | id.

post

For the wide‑form interface, post‑intervention EQ‑5D states. Ignored for the formula interface.

version

EQ‑5D instrument version. One of "3L" or "5L".

ignore.invalid

Logical; if TRUE, invalid scores are converted to NA; if FALSE, invalid scores trigger an error.

dimensions

Character vector specifying EQ‑5D dimension column names. Defaults to c("MO", "SC", "UA", "PD", "AD").

digits

Numeric specifying the number of decimal places. Defaults to 2.

pre.level

Optional value identifying the pre‑intervention visit in the formula interface.

post.level

Optional value identifying the post‑intervention visit in the formula interface.

data

A long‑form data frame used with the formula interface. Ignored for the wide‑form interface.

formula

A formula describing EQ‑5D variables on the left‑hand side and a time variable (and optionally an ID variable) on the right‑hand side, separated by |. Used only with the formula interface.

Value

A named numeric vector (or list) of Probability of Superiority scores by EQ‑5D dimension.

Examples

dat <- read.csv(system.file("extdata", "eq5d3l_example.csv", package="eq5d"))

## Wide form
pre <- dat[dat$Group=="Group1",][1:50,]
post <- dat[dat$Group=="Group2",][1:50,]
ps(pre, post, version="3L")

## Long form
## Not run: 
ps(profile ~ visit | id, data=eq_long)
ps(MO + SC + UA + PD + AD ~ visit | id, data=eq_long)

## End(Not run)

Calculate Shannon's Index

Description

Calculate Shannon's H' (diversity) index, H' max and Shannon's J' (evenness) index for an EQ-5D data set. This can be calculated both by dimension and for health states as a whole.

Usage

shannon(
  scores,
  version = NULL,
  by.dimension = TRUE,
  ignore.invalid = TRUE,
  dimensions = NULL,
  base = 2,
  digits = 2,
  permutations = TRUE
)

Arguments

scores

data.frame, numeric or character. For data.frame default column names should be MO, SC, UA, PD and AD representing Mobility, Self-care, Usual activities, Pain/discomfort and Anxiety/depression. Vector using five digit format can also be used.

version

string of value "3L" or "5L" to indicate instrument version.

by.dimension

boolean whether to calculate scores by EQ-5D dimensions or for the whole dataset. Defaults to TRUE.

ignore.invalid

boolean whether to ignore invalid scores. TRUE returns NA, FALSE throws an error.

dimensions

character vector, specifying "dimension" column names. Defaults are "MO", "SC", "UA", "PD" and "AD".

base

numeric base of logarithm to use. Defaults to base 2.

digits

numeric specifying the number of decimal places. Defaults to 2.

permutations

boolean whether to use maximum number of permutations for H' max or the number of observed unique profiles. Default is TRUE.

Value

a single list or list of dimensions containing H' H' max and J' scores.

Examples

dat <- read.csv(system.file("extdata", "eq5d3l_example.csv", package="eq5d"))

shannon(dat, version="3L", by.dimension=FALSE)
shannon(dat, version="3L", by.dimension=TRUE)

Launch shiny EQ-5D interface

Description

shiny_eq5d launches a shiny interface for browser based EQ-5D calculations.

Usage

shiny_eq5d(display.mode = "normal")

Arguments

display.mode

The display mode to be passed to runApp

Examples

## Not run: 
shiny_eq5d()
shiny_eq5d(display.mode="normal")

## End(Not run)

Descriptive System Tables for EQ-5D

Description

Formats EQ-5D descriptive system summaries into publication-ready tables. This function is the reporting-layer companion to descriptive_data, and mirrors the tabular presentation recommended in the EQ-5D reference literature and implemented by the Stata eq5dds command.

Tables contain either percentages or counts, depending on the metric supplied to descriptive_data. No analytical computation is performed by this function.

Usage

table_descriptive(dd, digits = 1, include_total = TRUE, group_order = NULL)

Arguments

dd

A data.frame returned by descriptive_data, containing the columns Dimension, Level, Value, and Metric. Grouped descriptive data are supported via a Group column.

digits

Integer specifying the number of decimal places used when rounding percentages. Ignored for count tables.

include_total

Logical; if TRUE, include a "Total" row.

group_order

Optional character vector specifying the order in which groups should be displayed when dd contains a Group column. Must match the levels of dd$Group. If NULL (default), groups are ordered according to the factor levels of Group as produced by descriptive_data.

Details

This function operates on the output of descriptive_data, which returns tidy descriptive-system summaries with one row per Dimension–Level–Metric combination. Values are reshaped into wide tables for reporting.

Counts and percentages are generated via separate calls to descriptive_data, consistent with the presentation in the EQ-5D reference literature.

When descriptive data are grouped, table_descriptive() returns a named list of tables, one per group, consistent with the behaviour of eq5dds when used with subgroup reporting.

Value

If descriptive data are ungrouped, a data.frame. If grouped, a named list of data.frames, one per group.

References

Devlin N, Parkin D, Janssen B (2020). Methods for Analysing and Reporting EQ-5D Data. Springer Open. doi:10.1007/978-3-030-47622-9

Ramos-Goñi JM, Ramallo-Fariña Y (2016). eq5dds: A command to analyze the descriptive system of the EQ-5D quality-of-life instrument. The Stata Journal, 16(3), 691–701.

Examples

dat <- read.csv(
  system.file("extdata", "eq5d3l_example.csv", package = "eq5d")
)

dat1 <- subset(dat, Group == "Group1")

## Percentage table
dd_pct <- descriptive_data(dat1, version = "3L", metric = "percent")
table_descriptive(dd_pct)

## Count table
dd_cnt <- descriptive_data(dat1, version = "3L", metric = "count")
table_descriptive(dd_cnt)

## Grouped percentage tables
dd_grp <- descriptive_data(dat, version = "3L", metric = "percent", group = "Group")
table_descriptive(dd_grp)

Probability of Superiority Tables

Description

Formats output from ps into a tabular representation suitable for reporting.

The function does not compute Probability of Superiority values; it restructures the numeric output of ps() into a data.frame with explicit dimension labels.

Usage

table_ps(ps_out, digits = 2)

Arguments

ps_out

Output from ps: a named list of numeric Probability of Superiority values by EQ‑5D dimension, or a named list of such lists for grouped output.

digits

Integer specifying the number of decimal places used when rounding PS values. Defaults to 2.

Value

If ps_out is ungrouped, a data.frame with columns Dimension and PS.

If ps_out is grouped, a named list of such data.frames.

Examples

dat <- read.csv(
  system.file("extdata", "eq5d3l_example.csv", package = "eq5d")
)

pre  <- dat[dat$Group == "Group1", ][1:50, ]
post <- dat[dat$Group == "Group2", ][1:50, ]

ps_res <- ps(pre, post, version = "3L")
table_ps(ps_res)

Get the available EQ-5D value sets.

Description

valuesets returns a data.frame of the available EQ-5D value sets in the eq5d package.

Usage

valuesets(
  type = NULL,
  version = NULL,
  country = NULL,
  references = c("PubMed", "DOI", "ISBN", "ExternalURL")
)

Arguments

type

string EQ-5D value set type. TTO or VAS for EQ-5D-3L, VT for EQ-5D-5L, IVP (International Valuation Protocol of Ramos-Goñi et al (2020)) 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.

version

string either 3L, 5L or Y3L.

country

string one of the countries for which there is a value set.

references

character vector of reference columns. One or more of PubMed, DOI, ISBN or ExternalURL. Default is all. Reference columns can be removed by setting argument to NULL.

Value

A data.frame containing the EQ-5D version, the value set type and country, along with PubMed IDs, DOIs, ISBNs and external URLs where available.

Examples

valuesets()
valuesets(type="TTO")
valuesets(version="5L")
valuesets(country="UK")
valuesets(version="Y3L", references=c("DOI", "PubMed"))