Package {eq5dsuite}

Type:	Package
Title:	Handling and Analysing 'EQ-5D' Data
Version:	2.1.0
Maintainer:	Kim Rand <krand@mathsinhealth.com>
Description:	The EQ-5D is a widely-used standardised instrument for measuring Health Related Quality Of Life (HRQOL), developed by the EuroQol group https://euroqol.org/. It assesses five dimensions; mobility, self-care, usual activities, pain/discomfort, and anxiety/depression, using either a three-level (EQ-5D-3L) or five-level (EQ-5D-5L) scale. Scores from these dimensions are commonly converted into a single utility index using country-specific value sets, which are critical in clinical and economic evaluations of healthcare and in population health surveys. The eq5dsuite package enables users to calculate utility index values for the EQ-5D instruments, including crosswalk utilities using the original crosswalk developed by van Hout et al. (2012) <doi:10.1016/j.jval.2012.02.008> (mapping EQ-5D-5L responses to EQ-5D-3L index values), or the recently developed reverse crosswalk by van Hout et al. (2021) <doi:10.1016/j.jval.2021.03.009> (mapping EQ-5D-3L responses to EQ-5D-5L index values). Users are allowed to add and/or remove user-defined value sets. Additionally, the package provides tools to analyse EQ-5D data according to the recommended guidelines outlined in "Methods for Analyzing and Reporting EQ-5D data" by Devlin et al. (2020) <doi:10.1007/978-3-030-47622-9>.
URL:	https://github.com/MathsInHealth/eq5dsuite-r, https://github.com/MathsInHealth/eq5dsuite
BugReports:	https://github.com/MathsInHealth/eq5dsuite-r/issues
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding:	UTF-8
LazyData:	true
Depends:	R (≥ 4.1.0)
Imports:	curl, ggplot2, moments, RColorBrewer, rlang, scales, rappdirs
Suggests:	shiny, DT, bslib, readxl, spelling, testthat (≥ 3.0.0), withr, knitr, rmarkdown, writexl, zip
VignetteBuilder:	knitr
Config/testthat/edition:	3
Language:	en-GB
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-10-22 09:48:02 UTC; aeste
Author:	Kim Rand [aut, cre], Oliver Rivero-Arias [aut], Iryna Schlackow [aut], Anabel Estévez-Carrillo [aut]
Repository:	CRAN
Date/Publication:	2026-10-22 10:40:14 UTC

eq5dsuite: Standardised Tools for EQ-5D Analysis

Description

The eq5dsuite package provides a comprehensive set of functions for calculating EQ-5D preference-based values and analysing EQ-5D data following the recommendations of Devlin et al. (2020).

The package supports three EQ-5D instruments:

• EQ-5D-3L

• EQ-5D-5L

• EQ-5D-Y-3L

Value calculation

Functions for calculating EQ-5D preference-based values:

• eq5d — Generic calculator for all instruments

• eq5d3l — EQ-5D-3L value calculation

• eq5d5l — EQ-5D-5L value calculation

• eq5dy3l — EQ-5D-Y-3L value calculation

• eqxw — Original crosswalk method (van Hout et al., 2012)

• eqxwr — Reverse crosswalk method (van Hout and Shaw, 2021)

• eqxwr_UK — UK mapping from EQ-5D-3L responses to values on the UK EQ-5D-5L value set (NICE Decision Support Unit; Hernández Alava et al., 2023). This is the mapping NICE's interim methods statement of 27 August 2026 specifies when only EQ-5D-3L data are available

• eqxw_UK — UK mapping in the opposite direction, from EQ-5D-5L responses to values on the UK EQ-5D-3L value set (Hernández Alava et al., 2023). Under NICE's interim methods statement of 27 August 2026, EQ-5D-5L data collected in a study should instead be valued directly with eq5d5l(country = "GB"); eqxw_UK remains for topics started before that date, for which NICE says 5L data should still be mapped to 3L utility values, and for reproducing earlier analyses

Value set management

Functions for managing country-specific value sets:

• eqvs_display — List all available value sets

• eqvs_add — Add a custom value set

• eqvs_drop — Remove a custom value set

• eqvs_load — Load a saved custom value set into the current session

• update_value_sets — Check for and install new value sets from the online repository

Profile analysis

Functions for analysing EQ-5D health state profiles, including cross-sectional summaries, longitudinal change analyses, and severity metrics:

• eq5d_profile_level_summary — Cross-sectional frequency summary by dimension

• eq5d_profile_level_summary_by_group — Stratified frequency summary by subgroup

• eq5d_profile_top_states — Most frequently observed health state profiles

• eq5d_profile_change_summary — Dimension-level frequencies at two time points

• eq5d_profile_dimension_change_table — Changes in levels per dimension as percentages of total and of type of change

• eq5d_profile_pchc_table — Paretian Classification of Health Change table

• eq5d_profile_pchc_with_no_problems_table — PCHC table with no-problems category

• eq5d_profile_pchc_by_group_plot — PCHC bar chart by subgroup

• eq5d_profile_better_dimensions_by_group_plot — Dimensions improved among Better patients

• eq5d_profile_worse_dimensions_by_group_plot — Dimensions worsened among Worse patients

• eq5d_profile_mixed_dimensions_by_group_plot — Dimensions changed among Mixed patients

• eq5d_profile_health_profile_grid — Health Profile Grid of individual transitions

• eq5d_profile_lss_utility_summary — Descriptive statistics by Level Sum Score

• eq5d_profile_lss_utility_plot — EQ-5D values plotted against LSS

• eq5d_profile_lfs_distribution — Level Frequency Score distribution table

• eq5d_profile_lfs_mean_utility — Mean EQ-5D values by LFS category

• eq5d_profile_lfs_utility_summary — Descriptive statistics by Level Frequency Score

• eq5d_profile_lfs_utility_plot — EQ-5D values plotted against LFS

• eq5d_profile_density_curve — Health State Density Curve

• eq5d_profile_shannon — Shannon's informativity indices H' and J', by dimension and for the health state

EQ-5D value analysis

Functions for analysing EQ-5D preference-based values across time points, subgroups, and population norms:

• eq5d_utility_summary — Descriptive statistics at each time point

• eq5d_utility_summary_by_group — Descriptive statistics stratified by subgroup

• eq5d_utility_norms_comparison — Comparison with population norms by age and sex

• eq5d_utility_over_time_plot — Mean values with confidence intervals over time

• eq5d_utility_by_group_plot — Mean values with confidence intervals by subgroup

• eq5d_utility_change_by_group_plot — Longitudinal change by subgroup

• eq5d_utility_distribution_plot — Histogram of EQ-5D value distribution

• eq5d_utility_vas_scatter_plot — Scatter plot of EQ-5D values against EQ VAS

EQ VAS analysis

Functions for analysing EQ VAS self-rated health scores:

• eq5d_vas_summary — Descriptive statistics at each time point

• eq5d_vas_distribution_table — Frequency distribution in pre-defined ranges

• eq5d_vas_histogram — Histogram of EQ VAS scores

• eq5d_vas_grouped_distribution_plot — Bar chart of grouped EQ VAS frequencies

Helper functions

Utility functions for preparing EQ-5D data:

• toEQ5Dindex — Combine dimension columns into a 5-digit profile code

• toEQ5Ddims — Split a 5-digit profile code into separate dimension columns

• make_all_EQ_indexes — Generate all valid EQ-5D state codes as a vector

• make_all_EQ_states — Generate all valid EQ-5D states as a data frame

• make_dummies — Create dummy variables from EQ-5D dimension columns

Data

• example_data — A sample of EQ-5D-3L data from the NHS Patient Reported Outcome Measures (PROMs) programme, used throughout the examples and vignettes. Missing values are recorded as 9 in the five dimensions and 999 in the EQ VAS

Interactive application

A Shiny application providing point-and-click access to the same analytical workflow without requiring R coding:

• run_app — Launch the Shiny application

Cross-platform suite

eq5dsuite is part of a cross-platform suite also available in Stata and Excel:

• Full suite: https://github.com/MathsInHealth/eq5dsuite

• R package: https://github.com/MathsInHealth/eq5dsuite-r

• Value sets repository: https://github.com/MathsInHealth/eq5dsuite-value-sets

Author(s)

Maintainer: Kim Rand krand@mathsinhealth.com (ORCID)

Authors:

• Kim Rand krand@mathsinhealth.com (ORCID)

• Oliver Rivero-Arias (ORCID)

• Iryna Schlackow (ORCID)

• Anabel Estévez-Carrillo (ORCID)

References

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

van Hout B, Janssen MF, Feng YS, et al. (2012). Interim scoring for the EQ-5D-5L: mapping the EQ-5D-5L to EQ-5D-3L value sets. Value in Health, 15(5), 708–715. doi:10.1016/j.jval.2012.02.008

van Hout B, Shaw JW (2021). Mapping EQ-5D-3L to EQ-5D-5L. Value in Health, 24(9), 1285–1293. doi:10.1016/j.jval.2021.03.009

Hernández Alava M, Pudney S, Wailoo A (2023). Estimating the relationship between EQ-5D-5L and EQ-5D-3L: results from a UK population study. PharmacoEconomics, 41(2), 199–207. doi:10.1007/s40273-022-01218-7

Rowen D, Mukuria C, Bray N, et al. (2026). A UK value set for the EQ-5D-5L. Value in Health. doi:10.1016/j.jval.2026.03.008

National Institute for Health and Care Excellence (2026). Interim methods statement: implementing the EQ-5D-5L value set (PMG51). Published 27 August 2026. https://www.nice.org.uk/process/pmg51

See Also

Useful links:

• https://github.com/MathsInHealth/eq5dsuite-r

• https://github.com/MathsInHealth/eq5dsuite

• Report bugs at https://github.com/MathsInHealth/eq5dsuite-r/issues

.EQxwrprob

Description

Takes a matrix of parameters for reverse crosswalk model, returns 243 x 25 matrix of state/level transition probabilities.

Usage

.EQxwrprob(par = NULL)

Arguments

Value

An 243 * 25 matrix with probabilities for state level transitions.

Add utility values to a data frame

Description

This function adds utility values to a data frame based on a specified version of EQ-5D and a country name.

Usage

.add_utility(df, eq5d_version, country)

Arguments

Value

A data frame with an additional column named 'utility' containing the calculated utility values. If the input country name is not found in the country_codes dataset, a list of available codes is printed, and subsequently an error message is displayed and the function stops.

Apply a result's filter in the app

Description

Apply a result's filter in the app

Usage

.apply_filter(df, filter)

Arguments

Value

df, restricted.

Check that the columns an analysis function needs are present

Description

Every analysis function resolves its column arguments – filling any left NULL with a default – and then checks that the named columns exist. That check used to say only "Provided column names not in dataframe", naming neither the missing column nor the argument it came from. Since the defaults are supplied silently, the commonest cause was a default the caller never chose: a frame with the five EQ-5D columns and nothing else fails because name_fu defaulted to "fu".

Usage

.check_columns(df, ...)

Arguments

Value

Invisibly TRUE. Called for its side effect of stopping when a column is missing.

Write a function call as R source

Description

Write a function call as R source

Usage

.deparse_call(fn, args, indent = 2L, width = 72L, close = ")")

Arguments

Value

A single string.

The R code restricting a data frame to the rows of one group

Description

The app applies a result's filter by evaluating exactly this code (see .apply_filter()), and the script writes it out, so the two select the same rows by construction. which() leaves out a row whose group is missing; indexing with the comparison itself would return such a row as a row of NAs.

Usage

.filter_code(filter, data = "analysis_data")

Arguments

Value

A single string.

Helper function for frequency of levels by dimensions tables

Description

Helper function for frequency of levels by dimensions tables

Usage

.freqtab(
  df,
  names_eq5d = NULL,
  name_fu = NULL,
  levels_fu = NULL,
  eq5d_version = NULL,
  add_summary_problems_change = TRUE
)

Arguments

Value

Summary data frame.

Generate colours for PCHC figures

Description

This internal function generates a vector of colours based on the specified base colour. Currently only green and orange colours are implemented. The wrapper is used in Figures 2.2-2.4.

Usage

.gen_colours(col, n)

Arguments

Value

A vector of colours generated based on the specified base colour and number of colours.

Calculate the Level Frequency Score (LFS)

Description

This function calculates the Level Frequency Score (LFS) for a given EQ-5D state and a specified version of EQ-5D. If at least one domain contains a missing entry, the whole LFS is set to be NA.

Usage

.get_lfs(s, eq5d_version)

Arguments

Value

A character vector representing the calculated LFS.

Replace NULL names with default values

Description

This function takes in a list of parameters, which would be column names of the input data frame, and checks if they are null. Any nulls are replaced with default values, and the updated list of parameters is returned.

Usage

.get_names(df = NULL, ...)

Arguments

Value

a list of parameters with null entries replaced with default values.

Get the mode of a vector.

Description

This function calculates the mode of a numeric or character vector. If there are multiple modes, the first one is returned. The code is taken from an R help page.

Usage

.getmode(v)

Arguments

Value

The mode of 'v'.

Modify ggplot2 theme

Description

Modify ggplot2 theme

Usage

.modify_ggplot_theme(p)

Arguments

Value

ggplot2 plot with modified theme

Wrapper to determine Paretian Classification of Health Change

Description

This internal function determines Paretian Classification of Health Change (PCHC) for each combination of the variables specified in the 'group_by' argument. It is used in the code for eq5d_profile_pchc_table, eq5d_profile_pchc_with_no_problems_table, eq5d_profile_dimension_change_table, and the eq5d_profile_*_by_group_plot functions. An EQ-5D health state is deemed to be 'better' than another if it is better on at least one dimension and is no worse on any other dimension. An EQ-5D health state is deemed to be 'worse' than another if it is worse in at least one dimension and is no better in any other dimension.

Usage

.pchc(df, level_fu_1, add_noprobs = FALSE)

Arguments

Value

A data frame with PCHC value for each combination of the grouping variables. If 'add_noprobs' is TRUE, a separate classification for those without problems is also included.

Wrapper to generate Paretian Classification of Health Change plot by dimension

Description

This internal function plots Paretian Classification of Health Change (PCHC) by dimension. The input is a data frame containing the information to plot, and the plot will contain bars representing the proportion of the total data that falls into each dimension, stacked by covariate. The wrapper is used in Figures 2.2-2.4.

Usage

.pchc_plot_by_dim(plot_data, ylab, title, cols, text_rotate = FALSE)

Arguments

Value

A ggplot object containing the PCHC plot.

Data checking/preparation: EQ-5D variables

Description

This function prepares a data frame for analysis by extracting, processing, and adding columns for EQ-5D variables, including state, LSS (Level Sum Score), LFS (Level Frequency Score) and utility.

Usage

.prep_eq5d(
  df,
  names,
  add_state = FALSE,
  add_lss = FALSE,
  add_lfs = FALSE,
  add_utility = FALSE,
  eq5d_version = NULL,
  country = NULL
)

Arguments

Value

a modified data frame with EQ-5D domain columns renamed to default names, and, if necessary, with added columns for state, LSS, LFS, and/or utility. If any of the checks fail (e.g. EQ-5D columns are not in an integer format), an error message is displayed and the function is stopping.

Data checking/preparation: follow-up variable

Description

This function prepares the follow-up (FU) variable for analysis by giving it a default name ('fu') and factorising

Usage

.prep_fu(df, name = NULL, levels = NULL)

Arguments

Value

A data frame with the follow-up variable renamed as "fu" and factorised.

Data checking/preparation: EQ-5D value variable

Description

Prepares a column of pre-calculated EQ-5D values for the eq5d_utility_* analyses. Those functions take the values as they are: nothing here recalculates them from the dimensions, and no value set is involved.

Usage

.prep_utility(df, name)

Arguments

Details

No range check is applied at the lower end: EQ-5D values are negative for states regarded as worse than dead, and how negative depends on the value set. The upper end is fixed, though – full health is 1 by construction – so values above 1 are reported as a warning. They are kept rather than discarded, because the likeliest cause is the wrong column, which the user should see and fix rather than have silently emptied.

Value

A modified data frame with the EQ-5D value column renamed to "utility", held as a numeric vector. The function does not stop on invalid input; it coerces and warns.

Data checking/preparation: VAS variable

Description

The function prepares the data for VAS (Visual Analogue Scale) analyses.

Usage

.prep_vas(df, name)

Arguments

Value

A modified data frame with the VAS score renamed to "vas", held as an integer vector. The function does not stop on invalid input; it coerces and warns.

.pstate3t5

Description

Takes a N x 25 matrix with probabilities per level/dimension, and creates an N * 3125 matrix with probabilities per state

Usage

.pstate3t5(PPP)

Arguments

Value

An N * 3125 matrix with probabilities per state

.pstate5t3

Description

Takes a 15 x 5 matrix with probabilities per level/dimension, and creates an 3125x243 matrix with probabilities per state

Usage

.pstate5t3(probs = .EQxwprob)

Arguments

Value

An 3125x243 matrix with probabilities per state

A string as an R string literal that is valid everywhere

Description

The literal is plain ASCII: backslashes, both quote characters and control characters are escaped, and every character outside ASCII is written as \uXXXX (or \UXXXXXXXX beyond the Basic Multilingual Plane). deparse() gets the escaping of backslashes and quotes right but leaves non-ASCII characters as they are, and how those survive being written to a file and read back depends on the platform's encoding – on Windows before R 4.2 it is not UTF-8. An ASCII script parses the same everywhere, and parse(text = .r_string(x)) gives back x.

Usage

.r_string(x)

Arguments

Details

This is the one way the package writes a string into R code; the test suite uses it too, to put a file path into a generated script.

Value

A single string.

Shannon's indices for one categorical variable

Description

Computes Shannon's index H', its maximum, and Shannon's evenness index J', as described in chapter 4 of Devlin et al. (2020).

Usage

.shannon(x, n_categories)

Arguments

Details

H' = -\sum_{i} p_i \log_2 p_i

summed over the categories that occur, where p_i is the proportion of observations in category i. Categories with no observations contribute nothing, since 0 \log_2 0 = 0.

H'_{max} = \log_2 L, where L is the number of categories the instrument allows – not the number observed. J' = H' / H'_{max} therefore runs from 0, when every observation falls in one category, to 1, when they are spread evenly over all L.

Value

A numeric vector of three elements, H, Hmax and J. All three are NA when there is no observation to summarise.

Wrapper to summarise a continuous variable by follow-up (FU)

Description

This function summarizes a continuous variable for each follow-up (FU) and calculates various statistics such as mean, standard deviation, median, mode, kurtosis, skewness, minimum, maximum, range, and number of observations. It also reports the total sample size and the number (and proportion) of missing values for each FU. The input 'df' must contain an ordered FU variable and the continuous variable of interest. The name of the continuous variable must be specified using 'name_v'. The wrapper is used in Table 3.1 (for VAS) or Table 4.2 (for EQ-5D utility)

Usage

.summary_cts_by_fu(df, name_v)

Arguments

Details

Skewness and kurtosis are the population (biased) estimators m_3 / m_2^{3/2} and m_4 / m_2^2, as returned by moments::skewness() and moments::kurtosis().

The kurtosis is **non-excess**: a normal distribution gives 3, not 0. The row is labelled "Kurtosis (non-excess)" so that the output says which convention it uses. Stata's summarize, detail reports the same quantity. Excel's KURT() reports *excess* kurtosis with a sample-bias correction, so it is roughly 3 lower for the same data.

Value

Data frame with one row for each statistic and one column for each FU.

Wrapper to calculate summary mean with 95% confidence interval

Description

This internal function calculates summary mean and 95% confidence interval of the utility variable, which can also be grouped. The function is used in Figures 4.2-4.4.

Usage

.summary_mean_ci(df, group_by)

Arguments

Value

A data frame with the mean, lower bound, and upper bound of the 95

Wrapper for the repetitive code in function_table_2_1. Data frame summary

Description

This internal function summarises a data frame by grouping it based on the variables specified in the 'group_by' argument and calculates the frequency of each group. The output is used in Table 2.1

Usage

.summary_table_2_1(df, group_by)

Arguments

Value

A summarised data frame with groups defined by 'eq5d' and 'fu' variables, the count of observations in each group, and the frequency of each group.

Summary wrapper for Table 4.3

Description

This internal function creates a summary of the data frame for Table 4.3. It groups the data by the variables specified in 'group_by' and calculates various summary statistics.

Usage

.summary_table_4_3(df, group_by)

Arguments

Value

A data frame with the summary statistics.

Summary wrapper for Table 4.4

Description

This internal function creates a summary of the data frame for Table 4.4. It groups the data by the variables specified in 'group_by' and calculates various summary statistics.

Usage

.summary_table_4_4(df, group_by)

Arguments

Value

A data frame with the summary statistics.

Apply pending value set migrations

Description

Fetches the migrations index from the repository and applies any renames that have not yet been applied locally. This ensures that value set codes remain consistent when a country publishes a second value set and the original code needs to be disambiguated with a year suffix.

Usage

apply_pending_migrations(ask = TRUE)

Arguments

Details

Migrations are applied before checking for new value sets in update_value_sets(), ensuring the local state is consistent before any new installations.

A migration is recorded as applied only when its outcome is verified: the old code is gone and the new one is there, or there was nothing to rename. When both codes are installed – the target already exists – nothing is renamed or deleted, the migration is a conflict, and it stays pending: two different value sets cannot be merged without a policy that says how. Codes are compared without regard to case, as lookups are.

A rename that was made but whose record (applied_migrations.rds) could not be saved is kept, and the status is "unrecorded". The migration stays pending; on the next run its old code is gone, so it is recorded without renaming anything again.

Value

Invisibly, a list: status ("ok", "conflict", "failed", "unrecorded" or "postponed"), applied (migration ids whose outcome holds now), recorded (those of them saved as applied), conflicts and failed (ids left pending), and reason (why the whole step failed, or NULL). A list that could not be downloaded, or is malformed, is "failed"; an empty list is "ok".

Check for conflicts between user-defined and built-in value sets

Description

After applying migrations or installing new value sets, checks whether any built-in value sets share a VS_code with a migration that has been applied. If conflicts are found, warns the user that the built-in value set still exists and will be removed in the next package release.

Usage

check_builtin_conflicts(version)

Arguments

Value

Invisibly returns a character vector of conflicting VS_codes, or character(0) if none found.

Drop a value set from the installed library

Description

Removes a value set from the installed library using eqvs_drop(). Only user-added value sets can be removed — built-in value sets are protected.

Usage

drop_value_set(vs_code, version, ask = TRUE)

Arguments

Value

Logical. TRUE if successful, FALSE otherwise.

eq5d

Description

Get EQ-5D values for the -3L, -5L, crosswalk (-3L value set applied to -5L health states), reverse crosswalk (-5L value set applied to -3L health states), and -Y-3L

Usage

eq5d(
  x,
  country = NULL,
  version = "5L",
  dim.names = c("mo", "sc", "ua", "pd", "ad")
)

Arguments

Value

A numeric vector of values, or a data.frame with one column for each value set requested. The result is an unnamed numeric vector, one element per element or row of x and in the same order.

Missing and invalid responses

Each health state is checked before it is scored, and a state that cannot be scored gives NA for that element or row; the others are scored as usual.

• A missing response (NA in any dimension, or an NA state index) gives NA without a warning.

• An invalid response gives NA with a warning, which gives the number of such states and examples. Invalid means a level the instrument does not have (for example 4 in the EQ-5D-3L, or a missing-value code such as 9), a level or index that is not a whole, finite number, or an index that is not five digits long. Each problem is reported once, however many value sets are requested.

• State indexes and levels given as text or as factors are read through their labels, so "21111" and factor(2) are scored as 21111 and 2.

Recode missing-value codes to NA first if the warning is not wanted.

Examples

# US -3L value set
eq5d(c(11111, 12321, 32123, 33333), 'US', '3L') 
# Danish and US -5L value sets applied to -3L descriptives, i.e. reverse crosswalk
eq5d(make_all_EQ_states('3L'), c('DK', 'US'), 'XWR') 
# US -5L value set
eq5d(c(11111, 12321, 32153, 55555), 'US', '5L') 

eq5d3l

Description

Get EQ-5D-3L index values from individual responses to the five dimensions of the EQ-5D-3L.

Usage

eq5d3l(x, country = NULL, dim.names = c("mo", "sc", "ua", "pd", "ad"))

Arguments

Value

A numeric vector of EQ-5D-3L values, or a data.frame with one column for each requested value set. The result is an unnamed numeric vector, one element per element or row of x and in the same order.

Missing and invalid responses

Each health state is checked before it is scored, and a state that cannot be scored gives NA for that element or row; the others are scored as usual.

• A missing response (NA in any dimension, or an NA state index) gives NA without a warning.

• An invalid response gives NA with a warning, which gives the number of such states and examples. Invalid means a level the instrument does not have (for example 4 in the EQ-5D-3L, or a missing-value code such as 9), a level or index that is not a whole, finite number, or an index that is not five digits long. Each problem is reported once, however many value sets are requested.

• State indexes and levels given as text or as factors are read through their labels, so "21111" and factor(2) are scored as 21111 and 2.

Recode missing-value codes to NA first if the warning is not wanted.

Examples

# Example 1: utility values from EQ-5D-3L profile codes
eq5d3l(c(11111, 12321, 32123, 33333), country = "US")

# Example 2: request multiple value sets
eq5d3l(make_all_EQ_states("3L"), country = c("DK", "CA"))

# Example 3: use a data.frame with dimension columns
df3l <- data.frame(
  mo = c(1, 2, 3),
  sc = c(1, 2, 2),
  ua = c(1, 3, 1),
  pd = c(2, 2, 3),
  ad = c(1, 1, 2)
)
eq5d3l(df3l, country = "US")

# Example 4: use custom dimension column names
df3l_named <- data.frame(
  mobility = c(1, 2, 3),
  self_care = c(1, 2, 2),
  usual_activities = c(1, 3, 1),
  pain_discomfort = c(2, 2, 3),
  anxiety_depression = c(1, 1, 2)
)
eq5d3l(
  df3l_named,
  country = "US",
  dim.names = c(
    "mobility", "self_care", "usual_activities",
    "pain_discomfort", "anxiety_depression"
  )
)

eq5d5l

Description

Get EQ-5D-5L index values from individual responses to the five dimensions of the EQ-5D-5L.

Usage

eq5d5l(x, country = NULL, dim.names = c("mo", "sc", "ua", "pd", "ad"))

Arguments

Value

A numeric vector of EQ-5D-5L values, or a data.frame with one column for each requested value set. The result is an unnamed numeric vector, one element per element or row of x and in the same order.

Missing and invalid responses

Each health state is checked before it is scored, and a state that cannot be scored gives NA for that element or row; the others are scored as usual.

• A missing response (NA in any dimension, or an NA state index) gives NA without a warning.

• An invalid response gives NA with a warning, which gives the number of such states and examples. Invalid means a level the instrument does not have (for example 4 in the EQ-5D-3L, or a missing-value code such as 9), a level or index that is not a whole, finite number, or an index that is not five digits long. Each problem is reported once, however many value sets are requested.

• State indexes and levels given as text or as factors are read through their labels, so "21111" and factor(2) are scored as 21111 and 2.

Recode missing-value codes to NA first if the warning is not wanted.

Examples

# Example 1: utility values from EQ-5D-5L profile codes
eq5d5l(c(11111, 12321, 32423, 55555), country = "IT")

# Example 2: request multiple value sets
eq5d5l(make_all_EQ_states("5L"), country = c("ES", "DE"))

# Example 3: use a data.frame with dimension columns
df5l <- data.frame(
  mo = c(1, 2, 5),
  sc = c(1, 2, 4),
  ua = c(1, 3, 3),
  pd = c(2, 4, 2),
  ad = c(1, 5, 1)
)
eq5d5l(df5l, country = "ES")

# Example 4: use custom dimension column names from a real-world style dataset
df5l_named <- data.frame(
  mobility = c(1, 5, 3),
  self_care = c(2, 4, 2),
  usual_activities = c(3, 3, 1),
  pain_discomfort = c(4, 2, 2),
  anxiety_depression = c(5, 1, 3)
)
eq5d5l(
  df5l_named,
  country = "ES",
  dim.names = c(
    "mobility", "self_care", "usual_activities",
    "pain_discomfort", "anxiety_depression"
  )
)

The midpoint of each age band

Description

Turns a column of age bands – "30 to 39", "30-39", "65+", "under 20" – into the age at the middle of each band, for use where an analysis needs a number and the data hold a band. The NICE Decision Support Unit's mapping between the EQ-5D-3L and EQ-5D-5L (eqxwr_UK, eqxw_UK) is the case this exists for.

Usage

eq5d_age_band_midpoint(x)

Arguments

Details

Age is recorded in completed years, so the band "30 to 39" covers the continuous interval [30, 40) and its midpoint is 35, not 34.5. The distinction decides the band a respondent is mapped into: the DSU's age bands begin at 35, 45, 55 and 65, which are exactly those midpoints, so a band that straddles one of those boundaries is placed in the upper one.

No midpoint is invented for a label that cannot identify a single band. A band open at the top, such as "65+", resolves to its lower bound, because every age in it falls in the same band; one open at the bottom, such as "under 20", or spanning a boundary, such as "50+", returns NA with a warning naming the label. Supply an exact age in that case.

Using a midpoint makes the result an approximation. Where exact ages are available, use them.

Value

A numeric vector of the same length as x, with two attributes: banded, TRUE when x held bands rather than numbers, and straddles, a logical vector marking the values whose band crosses one of the DSU's boundaries.

See Also

eqxwr_UK, eqxw_UK

The app as an object, for a server to run

Description

Returns the Shiny application rather than starting it, which is what a server such as Shiny Server, Posit Connect or shinyapps.io needs: each runs the application directory itself, so an app.R that called run_app would be a runApp() inside a runApp(), which Shiny refuses.

Usage

eq5d_app(online = NULL)

Arguments

Details

Use run_app to start the app on your own machine, and this to deploy it.

A whole app.R for a server is one line:

eq5dsuite:::eq5d_app(online = TRUE)

Three colons, because eq5d_app() is internal: with two the server cannot find it. DEPLOY.md says the same.

The settings this puts in force – the upload limit and error sanitising – stay in force for the R process that serves the app, which is what a deployment wants. run_app() restores them when it returns, which is what an interactive session wants.

See DEPLOY.md in the installed package (system.file("shiny", "DEPLOY.md", package = "eq5dsuite")).

Value

A Shiny application object, as shinyAppDir returns.

See Also

run_app, eq5d_online_config

Rename a data frame's columns to the names the analyses expect

Description

The analysis functions take their columns by name. This renames the columns a user has identified to the canonical names those functions use – "mo", "sc", "ua", "pd", "ad" for the dimensions, and "fu", "groupvar", "id", "vas" and "utility" for the optional ones – and coerces the dimensions to integer and the EQ VAS to numeric.

Usage

eq5d_apply_mapping(df, mapping)

Arguments

Value

df with the mapped columns renamed and coerced. Columns not named in mapping are left untouched.

See Also

eq5d_validate, which checks the same mapping.

Check an uploaded dataset against the online limits

Description

Applied by the Shiny app after a file has been read, so the limits hold whatever the browser allowed through. Returns the reason the file cannot be used, in words the person who uploaded it can act on, or NULL when there is nothing wrong.

Usage

eq5d_check_upload(df, type, config = eq5d_online_config())

Arguments

Value

A single string explaining the problem, or NULL.

See Also

eq5d_online_config

Format an analysis table for display

Description

Presents the output of an analysis function the way the Shiny app does: proportions as percentages, counts with a thousands separator and no decimals, other numbers to a fixed number of places, and column headings with the underscores removed.

Usage

eq5d_format_table(df, percent_digits = 1L, digits = 2L, tidy_names = TRUE)

Arguments

Details

The analysis functions return proportions, whatever the column is called: Percentage in eq5d_profile_top_states holds 0.225, and so does % in eq5d_profile_lfs_distribution. A column is treated as a proportion when it is named freq_*; when it is a *_p column whose matching *_n is also present, which is the shape the PCHC tables produce; when it ends in "% Total" or "% Type"; or when it is one of p, cum_p, Percentage, Cumulative percentage, % or Cum (%).

Every column becomes character, so the result is for reading, not for further computation. The table passed in is not modified.

Value

A data frame of character columns.

Settings for the app's online mode

Description

The Shiny app runs in one of two modes. Locally – the default – it behaves as it always has. Deployed on a public server it limits what can be uploaded, keeps every file it writes inside a per-session folder, ends idle sessions, and tells the user what happens to their data.

Usage

eq5d_online_config(online = NULL)

Arguments

Details

Online mode is off unless it is asked for, by run_app(online = TRUE) or by setting EQ5DSUITE_ONLINE=true in the environment the app starts in. The argument wins over the environment variable.

Each limit can be set with an R option or an environment variable, the option taking precedence:

The defaults are 10 MB, 50,000 rows, 200 columns, 30 minutes, and CSV and Excel files. .rds is deliberately not accepted online: reading a serialised R object from an untrusted source is not a safe operation. It remains accepted locally.

See DEPLOY.md in the installed package (system.file("shiny", "DEPLOY.md", package = "eq5dsuite")) for what the server itself has to be told.

Value

A list: enabled, max_upload_mb, max_rows, max_cols, idle_minutes and allowed_types. The limits are reported whether or not online mode is on, so a deployment can check what it would apply.

See Also

eq5d_check_upload, eq5d_online_notice, run_app

What the app tells users about their data online

Description

The wording of the notices shown in online mode, in one place so that it can be changed without touching the app. Each can be overridden with an option, which is how a deployment adopts its own organisation's wording.

Usage

eq5d_online_notice(which = c("data", "upload", "local"))

Arguments

Details

Set options(eq5dsuite.online.notice.data = "..."), and likewise ...notice.upload and ...notice.local, to replace the wording.

Value

A single string.

See Also

eq5d_online_config

eq5d_profile_better_dimensions_by_group_plot: Percentage of Respondents Who Improved in Each EQ-5D Dimension, by Group This function calculates how many respondents improved in each dimension between two time points and summarizes the results for each group. It then produces a dimension-focused chart illustrating improvement percentages by dimension.

Description

eq5d_profile_better_dimensions_by_group_plot: Percentage of Respondents Who Improved in Each EQ-5D Dimension, by Group This function calculates how many respondents improved in each dimension between two time points and summarizes the results for each group. It then produces a dimension-focused chart illustrating improvement percentages by dimension.

Usage

eq5d_profile_better_dimensions_by_group_plot(
  df,
  name_id,
  name_groupvar = NULL,
  names_eq5d = NULL,
  name_fu = NULL,
  levels_fu = NULL
)

Arguments

Value

A list containing:

Pairing records

Each respondent's records are compared in timepoint order, using only the timepoints in levels_fu. The function stops, naming the respondents, if a respondent has more than one record at the same timepoint: it cannot tell which to compare, and does not choose. Where the analysis is split by name_groupvar, it also stops if a respondent is not in the same group at every timepoint (a missing group at one timepoint counts as a change), because the change is attributed to the respondent's group.

Examples

result <- eq5d_profile_better_dimensions_by_group_plot(
  df = example_data,
  name_id = "id",
  name_groupvar = "procedure",
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
  name_fu = "time",
  levels_fu = c("Pre-op","Post-op")
)
result$p
result$plot_data

eq5d_profile_change_summary: Frequency of levels by dimensions, by follow-up

Description

eq5d_profile_change_summary: Frequency of levels by dimensions, by follow-up

Usage

eq5d_profile_change_summary(
  df,
  names_eq5d = NULL,
  name_fu = NULL,
  levels_fu = NULL,
  eq5d_version = NULL
)

Arguments

Details

Counts are made against the number of non-missing responses on each dimension at each follow-up. Where that number is positive, every level of the instrument has a row and every count is a number: a level, or a problem, that nobody reported is 0. Where it is zero – nobody recorded at that follow-up, or everyone missing on that dimension – the counts are NA, because the data say nothing about them.

The change in the number reporting problems is between consecutive levels of levels_fu, and is NA where either count is. The relative change is NA where the earlier count is 0. These are counts at each follow-up, not changes within respondents; for those, see eq5d_profile_pchc_table and eq5d_profile_dimension_change_table.

Value

Summary data frame.

Examples

eq5d_profile_change_summary(
  df = example_data,
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
  name_fu = "time",
  levels_fu = c("Pre-op" , "Post-op"),
  eq5d_version = "3L"
)

eq5d_profile_density_curve: Generate a Health State Density Curve (HSDC) for EQ-5D Data

Description

Calculates and plots the Health State Density Curve (HSDC) and the Health State Density Index (HSDI) of Zamora et al. (2018), which describe how evenly the observations are spread over the health state profiles that occur in the data. Profiles are formed from the five dimensions; a row whose profile is not valid for the instrument is excluded with a warning.

Usage

eq5d_profile_density_curve(df, names_eq5d, eq5d_version)

Arguments

Details

The curve. The S distinct profiles observed are ranked from the most to the least frequent. For i = 1, \dots, S, x_i is the cumulative proportion of observations in the first i profiles and y_i = i / S the cumulative proportion of profiles. The HSDC plots y against x, from (0, 0) to (1, 1). The diagonal is perfect evenness, every profile equally frequent; the further the curve lies below it, the more the observations are concentrated in a few profiles.

The index. Following Zamora et al. (2018, equation 1),

HSDI = \sum_{i=1}^{S} (x_i - x_{i-1})(y_i + y_{i-1}),

with x_0 = y_0 = 0: twice the area under the curve. It is analogous to the Gini coefficient, but runs the other way: the HSDI is 1 - G, where G is twice the area between the curve and the diagonal.

Direction. Higher is more even. The HSDI is 1 when every observed profile is equally frequent, including the case of a single profile, and falls as the observations concentrate in fewer of the observed profiles. Profiles of equal frequency may be ranked in either order without changing it.

Attainable bounds. With N observations over S observed profiles, the HSDI lies in

1/S + (S - 1)/N \le HSDI \le 1.

The lower bound is reached when one profile holds N - S + 1 observations and each of the others one. The HSDI is therefore never below 1/S, and never 0: the 0 of "total inequality" in Zamora et al. is a limit, approached only as S and N/S both grow. With two profiles it cannot fall below 0.5.

What it is relative to. Only the profiles that occur in these data count: y_i is i / S for the S profiles observed, not for the 243 (EQ-5D-3L, EQ-5D-Y-3L) or 3,125 (EQ-5D-5L) the instrument allows, and a profile nobody reported does not enter. The index describes how evenly observations are spread over the profiles that appear. Because its attainable range depends on S and N, compare it between samples with care. Repeating a whole distribution over more profiles leaves it exactly unchanged (Zamora et al.'s independence of S), but samples whose distributions differ in shape are not on a common scale.

Worked values. Two profiles observed equally often: 1. Frequencies 9 and 1: 0.9 \times 0.5 + 0.1 \times 1.5 = 0.6. Frequencies 999 and 1: 0.501, the paper's "0.5" for this case. Frequencies 2, 1 and 1: (0.5 \times 1 + 0.25 \times 3 + 0.25 \times 5) / 3 = 5/6, the lower bound for N = 4, S = 3.

Value

A list containing:

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 18/03. London: Office of Health Economics. https://www.ohe.org/publications/new-methods-analysing-distribution-eq-5d-observations/

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

Examples

figure <- eq5d_profile_density_curve(
            df = example_data, 
            names_eq5d = c("mo", "sc", "ua", "pd", "ad"), 
            eq5d_version = "3L"
          )
figure$plot_data
figure$hsdi
figure$p

eq5d_profile_dimension_change_table: Changes in levels in each dimension, percentages of total and of type of change

Description

eq5d_profile_dimension_change_table: Changes in levels in each dimension, percentages of total and of type of change

Usage

eq5d_profile_dimension_change_table(
  df,
  name_id,
  names_eq5d = NULL,
  name_fu = NULL,
  levels_fu = NULL
)

Arguments

Value

Summary data frame

Pairing records

Each respondent's records are compared in timepoint order, using only the timepoints in levels_fu. The function stops, naming the respondents, if a respondent has more than one record at the same timepoint: it cannot tell which to compare, and does not choose. Where the analysis is split by name_groupvar, it also stops if a respondent is not in the same group at every timepoint (a missing group at one timepoint counts as a change), because the change is attributed to the respondent's group.

Examples

eq5d_profile_dimension_change_table(
  df = example_data,
  name_id = "id",
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
  name_fu = "time",
  levels_fu = c("Pre-op" , "Post-op")
)

eq5d_profile_health_profile_grid: Health Profile Grid (HPG) for Two Time Points

Description

This function creates a Health Profile Grid (HPG) for EQ-5D data, plotting each individual's change in health states (ranked from best to worst) between two time points. A diagonal reference line indicates no change; points above the line reflect improvement, and points below indicate deterioration.

Usage

eq5d_profile_health_profile_grid(
  df,
  names_eq5d,
  name_fu,
  levels_fu = NULL,
  name_id,
  eq5d_version,
  country
)

Arguments

Details

The ranking is over every health state the instrument allows, not only those the data contain: all 243 states for the EQ-5D-3L and the EQ-5D-Y-3L, and all 3,125 for the EQ-5D-5L. Each is valued with the value set named by country and eq5d_version, and ordered best to worst, so the best possible state is rank 1 and the worst is rank 243 or 3,125. A rank therefore means the same thing in every dataset valued with the same value set, and the axes span the whole classification system rather than the part of it a particular sample happens to occupy.

This is why the function takes a value set rather than a column of pre-calculated values: the states that do not occur in the data still have to be valued in order to place the states that do.

Value

A list with components:

Pairing records

Each respondent's records are compared in timepoint order, using only the timepoints in levels_fu. The function stops, naming the respondents, if a respondent has more than one record at the same timepoint: it cannot tell which to compare, and does not choose. Where the analysis is split by name_groupvar, it also stops if a respondent is not in the same group at every timepoint (a missing group at one timepoint counts as a change), because the change is attributed to the respondent's group.

Examples

tmp <- eq5d_profile_health_profile_grid(
           df = example_data,
           names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
           name_fu = "time",
           levels_fu = c("Pre-op", "Post-op"),
           name_id = "id",
           eq5d_version = "3L",
           country = "GB"
       )

eq5d_profile_level_summary: Frequency of levels by dimensions, cross-sectional

Description

eq5d_profile_level_summary: Frequency of levels by dimensions, cross-sectional

Usage

eq5d_profile_level_summary(df, names_eq5d = NULL, eq5d_version = NULL)

Arguments

Value

Summary data frame.

Examples

eq5d_profile_level_summary(
 df = example_data[example_data$time == "Pre-op",],
 names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
 eq5d_version = "3L"
)

eq5d_profile_level_summary_by_group: Frequency of levels by dimensions, separated by category

Description

eq5d_profile_level_summary_by_group: Frequency of levels by dimensions, separated by category

Usage

eq5d_profile_level_summary_by_group(
  df,
  names_eq5d = NULL,
  name_cat = NULL,
  levels_cat = NULL,
  eq5d_version = NULL
)

Arguments

Value

Summary data frame.

Examples

eq5d_profile_level_summary_by_group(
 df = example_data[example_data$time == "Pre-op",],
 names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
 name_cat = "procedure",
 levels_cat = c("Hip Replacement", "Knee Replacement"),
 eq5d_version = "3L"
)

eq5d_profile_lfs_distribution: Distribution of the EQ-5D states by LFS (Level Frequency Score)

Description

eq5d_profile_lfs_distribution: Distribution of the EQ-5D states by LFS (Level Frequency Score)

Usage

eq5d_profile_lfs_distribution(df, names_eq5d = NULL, eq5d_version = NULL)

Arguments

Value

Summary data frame

Examples

eq5d_profile_lfs_distribution(
  example_data, 
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"), 
  eq5d_version = "3L"
)

eq5d_profile_lfs_mean_utility: Number of observations in the LFS (Level Frequency Score) according to the EQ-5D values

Description

eq5d_profile_lfs_mean_utility: Number of observations in the LFS (Level Frequency Score) according to the EQ-5D values

Usage

eq5d_profile_lfs_mean_utility(
  df,
  names_eq5d = NULL,
  name_utility = NULL,
  eq5d_version = NULL
)

Arguments

Value

Summary data frame

Examples

example_data$value <- eq5d3l(example_data[, c("mo", "sc", "ua", "pd", "ad")],
                             country = "GB")
eq5d_profile_lfs_mean_utility(
  example_data, 
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"), 
  name_utility = "value",
  eq5d_version = "3L"
)

eq5d_profile_lfs_utility_plot: EQ-5D values plotted against LFS

Description

eq5d_profile_lfs_utility_plot: EQ-5D values plotted against LFS

Usage

eq5d_profile_lfs_utility_plot(
  df,
  names_eq5d = NULL,
  name_utility = NULL,
  eq5d_version = NULL
)

Arguments

Value

Summary plot and data used for plotting

Examples

example_data$value <- eq5d3l(example_data[, c("mo", "sc", "ua", "pd", "ad")],
                             country = "GB")
tmp <- eq5d_profile_lfs_utility_plot(
 example_data, 
 names_eq5d = c("mo", "sc", "ua", "pd", "ad"), 
 name_utility = "value",
 eq5d_version = "3L"
)
tmp$p
tmp$plot_data

eq5d_profile_lfs_utility_summary: Summary statistics of EQ-5D values by LFS (Level Frequency Score)

Description

eq5d_profile_lfs_utility_summary: Summary statistics of EQ-5D values by LFS (Level Frequency Score)

Usage

eq5d_profile_lfs_utility_summary(
  df,
  names_eq5d = NULL,
  name_utility = NULL,
  eq5d_version = NULL
)

Arguments

Value

Summary data frame

Examples

example_data$value <- eq5d3l(example_data[, c("mo", "sc", "ua", "pd", "ad")],
                             country = "GB")
eq5d_profile_lfs_utility_summary(
  example_data, 
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"), 
  name_utility = "value",
  eq5d_version = "3L"
)

eq5d_profile_lss_utility_plot: EQ-5D values plotted against LSS

Description

eq5d_profile_lss_utility_plot: EQ-5D values plotted against LSS

Usage

eq5d_profile_lss_utility_plot(
  df,
  names_eq5d = NULL,
  name_utility = NULL,
  eq5d_version = NULL
)

Arguments

Value

Summary plot and data used for plotting

Examples

df <- data.frame(make_all_EQ_states(version = "5L"))
df$value <- eq5d5l(df[, c("mo", "sc", "ua", "pd", "ad")], country = "US")
tmp <- eq5d_profile_lss_utility_plot(
 df, 
 names_eq5d = c("mo", "sc", "ua", "pd", "ad"), 
 name_utility = "value",
 eq5d_version = "5L"
)
tmp$p
tmp$plot_data

eq5d_profile_lss_utility_summary: Summary statistics for the EQ-5D values by all the different LSSs (Level Sum Scores)

Description

eq5d_profile_lss_utility_summary: Summary statistics for the EQ-5D values by all the different LSSs (Level Sum Scores)

Usage

eq5d_profile_lss_utility_summary(
  df,
  names_eq5d = NULL,
  name_utility = NULL,
  eq5d_version = NULL
)

Arguments

Value

Summary data frame

Examples

df <- data.frame(make_all_EQ_states(version = "5L"))
df$value <- eq5d5l(df[, c("mo", "sc", "ua", "pd", "ad")], country = "US")
eq5d_profile_lss_utility_summary(
  df, 
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"), 
  name_utility = "value",
  eq5d_version = "5L"
)

eq5d_profile_mixed_dimensions_by_group_plot: Percentage of Respondents Who Had a Mixed Change Overall, by Dimension Improved or Worsened, Grouped by Procedure (or Other Grouping)

Description

This function focuses on patients classified as having "Mixed change" overall (i.e., some dimensions improved, others worsened). It then examines which dimensions improved vs. worsened for each subject. Results are summarized by a grouping variable (e.g., procedure) and time points. The final output is a table plus a ggplot object.

Usage

eq5d_profile_mixed_dimensions_by_group_plot(
  df,
  name_id,
  name_groupvar = NULL,
  names_eq5d = NULL,
  name_fu = NULL,
  levels_fu = NULL
)

Arguments

Value

A list with two elements:

Pairing records

Each respondent's records are compared in timepoint order, using only the timepoints in levels_fu. The function stops, naming the respondents, if a respondent has more than one record at the same timepoint: it cannot tell which to compare, and does not choose. Where the analysis is split by name_groupvar, it also stops if a respondent is not in the same group at every timepoint (a missing group at one timepoint counts as a change), because the change is attributed to the respondent's group.

Examples

result <- eq5d_profile_mixed_dimensions_by_group_plot(
  df = example_data,
  name_id = "id",
  name_groupvar = "procedure",
  names_eq5d = c("mo","sc","ua","pd","ad"),
  name_fu = "time",
  levels_fu = c("Pre-op","Post-op")
)
result$plot_data
result$p

eq5d_profile_pchc_by_group_plot: Paretian Classification of Health Change (PCHC) by Group This function computes PCHC categories between two time points for each subject, stratifies them by a grouping variable, and produces a single bar chart with side-by-side bars showing the distribution of PCHC categories.

Description

eq5d_profile_pchc_by_group_plot: Paretian Classification of Health Change (PCHC) by Group This function computes PCHC categories between two time points for each subject, stratifies them by a grouping variable, and produces a single bar chart with side-by-side bars showing the distribution of PCHC categories.

Usage

eq5d_profile_pchc_by_group_plot(
  df,
  name_id,
  name_groupvar = NULL,
  names_eq5d = NULL,
  name_fu = NULL,
  levels_fu = NULL
)

Arguments

Value

A list with two elements:

Pairing records

Each respondent's records are compared in timepoint order, using only the timepoints in levels_fu. The function stops, naming the respondents, if a respondent has more than one record at the same timepoint: it cannot tell which to compare, and does not choose. Where the analysis is split by name_groupvar, it also stops if a respondent is not in the same group at every timepoint (a missing group at one timepoint counts as a change), because the change is attributed to the respondent's group.

Examples

result <- eq5d_profile_pchc_by_group_plot(
  df = example_data,
  name_id = "id",
  name_groupvar = "procedure",
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
  name_fu = "time",
  levels_fu = c("Pre-op", "Post-op")
)
result$p        # shows the plot
result$plot_data  # shows the summary table

eq5d_profile_pchc_table: Changes in health according to the PCHC (Paretian Classification of Health Change)

Description

eq5d_profile_pchc_table: Changes in health according to the PCHC (Paretian Classification of Health Change)

Usage

eq5d_profile_pchc_table(
  df,
  name_id,
  name_groupvar = NULL,
  names_eq5d = NULL,
  name_fu = NULL,
  levels_fu = NULL
)

Arguments

Value

Summary data frame

Pairing records

Each respondent's records are compared in timepoint order, using only the timepoints in levels_fu. The function stops, naming the respondents, if a respondent has more than one record at the same timepoint: it cannot tell which to compare, and does not choose. Where the analysis is split by name_groupvar, it also stops if a respondent is not in the same group at every timepoint (a missing group at one timepoint counts as a change), because the change is attributed to the respondent's group.

Examples

eq5d_profile_pchc_table(
  df = example_data,
  name_id = "id",
  name_groupvar = "procedure",
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
  name_fu = "time",
  levels_fu = c("Pre-op" , "Post-op")
)

eq5d_profile_pchc_with_no_problems_table: Changes in health according to the PCHC, taking account of those with no problems

Description

eq5d_profile_pchc_with_no_problems_table: Changes in health according to the PCHC, taking account of those with no problems

Usage

eq5d_profile_pchc_with_no_problems_table(
  df,
  name_id,
  name_groupvar = NULL,
  names_eq5d = NULL,
  name_fu = NULL,
  levels_fu = NULL
)

Arguments

Value

Summary data frame. For each group and later timepoint, _n is a count and _p a proportion: of everyone for "No problems" and "Total with problems", and of those with problems for the four change categories. Where nobody in a group had problems at a timepoint, those four proportions are NA, as they have no denominator.

Pairing records

Each respondent's records are compared in timepoint order, using only the timepoints in levels_fu. The function stops, naming the respondents, if a respondent has more than one record at the same timepoint: it cannot tell which to compare, and does not choose. Where the analysis is split by name_groupvar, it also stops if a respondent is not in the same group at every timepoint (a missing group at one timepoint counts as a change), because the change is attributed to the respondent's group.

Examples

eq5d_profile_pchc_with_no_problems_table(
  df = example_data,
  name_id = "id",
  name_groupvar = "procedure",
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
  name_fu = "time",
  levels_fu = c("Pre-op" , "Post-op")
)

eq5d_profile_shannon: Shannon's informativity indices

Description

Reports Shannon's index H', its maximum H'max, and Shannon's evenness index J', for each EQ-5D dimension and for the health state as a whole. These are the informativity measures of chapter 4 of Devlin et al. (2020): how much of the classification system a sample actually uses.

Usage

eq5d_profile_shannon(
  df,
  names_eq5d = NULL,
  eq5d_version = NULL,
  name_fu = NULL,
  levels_fu = NULL
)

Arguments

Details

For a variable with categories i holding proportions p_i of the observations,

H' = -\sum_{i} p_i \log_2 p_i,\quad H'_{max} = \log_2 L,\quad J' = H' / H'_{max}

where L is the number of categories the instrument allows. For a dimension that is 3 (EQ-5D-3L, EQ-5D-Y-3L) or 5 (EQ-5D-5L); for the health state it is 3^5 = 243 or 5^5 = 3125. L is what the instrument allows, not what the sample happens to contain, so J' is comparable between samples.

H' is in bits and rises with both the number of categories used and how evenly they are used. J' is H' as a fraction of its maximum, from 0 when every observation falls in one category to 1 when they are spread evenly over all L. Reporting both is the recommendation: H' alone cannot be compared between instruments with different numbers of categories.

Each dimension is computed over its own non-missing responses. The health state row uses complete profiles only, since a profile with any dimension missing is not a health state.

Value

A data frame with one row per EQ-5D dimension and a final row for the health state, and three columns per follow-up level: H_<level>, Hmax_<level> and J_<level>. Without name_fu there is a single set of columns, suffixed All.

References

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

Examples

eq5d_profile_shannon(
  example_data,
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
  eq5d_version = "3L"
)

# By time point
eq5d_profile_shannon(
  example_data,
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
  eq5d_version = "3L",
  name_fu = "time",
  levels_fu = c("Pre-op", "Post-op")
)

eq5d_profile_top_states: Prevalence of the 10 most frequently observed self-reported health states

Description

eq5d_profile_top_states: Prevalence of the 10 most frequently observed self-reported health states

Usage

eq5d_profile_top_states(df, names_eq5d = NULL, eq5d_version = NULL, n = 10)

Arguments

Value

Summary data frame

Examples

eq5d_profile_top_states(
  df = example_data[example_data$time == "Pre-op",],
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
  eq5d_version = "3L",
  n = 10
)

This function identifies respondents with a "Worsen" PCHC state (i.e., overall health state got worse between levels_fu[1] and levels_fu[2]), checks dimension-specific changes (e.g., mo_diff < 0), and summarizes by a grouping variable (e.g., procedure) and time points. It returns a data table and a ggplot object.

Description

This function identifies respondents with a "Worsen" PCHC state (i.e., overall health state got worse between levels_fu[1] and levels_fu[2]), checks dimension-specific changes (e.g., mo_diff < 0), and summarizes by a grouping variable (e.g., procedure) and time points. It returns a data table and a ggplot object.

Usage

eq5d_profile_worse_dimensions_by_group_plot(
  df,
  name_id,
  name_groupvar = NULL,
  names_eq5d = NULL,
  name_fu = NULL,
  levels_fu = NULL
)

Arguments

Value

A list containing:

Pairing records

Each respondent's records are compared in timepoint order, using only the timepoints in levels_fu. The function stops, naming the respondents, if a respondent has more than one record at the same timepoint: it cannot tell which to compare, and does not choose. Where the analysis is split by name_groupvar, it also stops if a respondent is not in the same group at every timepoint (a missing group at one timepoint counts as a change), because the change is attributed to the respondent's group.

Examples

result <- eq5d_profile_worse_dimensions_by_group_plot(
  df = example_data,
  name_id = "id",
  name_groupvar = "procedure",
  names_eq5d = c("mo", "sc", "ua", "pd", "ad"),
  name_fu = "time",
  levels_fu = c("Pre-op","Post-op")
)
result$p        # shows the plot
result$plot_data  # shows the summary table

Read a data file of EQ-5D responses

Description

Reads a CSV, Excel or RDS file, choosing by the file's extension unless type says otherwise. This is what the Shiny app's upload uses, and what the R script it generates calls, so a script reproduces what the app read.

Usage

eq5d_read_data(
  path,
  type = NULL,
  sep = ",",
  dec = ".",
  fileEncoding = "",
  sheet = 1,
  ...
)

Arguments

Value

A data frame. Character columns are not converted to factors and column names are left as they are in the file.

See Also

eq5d_apply_mapping for naming the columns an analysis needs, and eq5d_validate for checking them.

eq5d_utility_by_group_plot: Mean EQ-5D values and 95% confidence intervals: all vs by groupvar

Description

eq5d_utility_by_group_plot: Mean EQ-5D values and 95% confidence intervals: all vs by groupvar

Usage

eq5d_utility_by_group_plot(df, name_utility = NULL, name_groupvar = NULL)

Arguments

Value

Summary plot and data used for plotting

Confidence intervals

The 95% confidence interval of a mean is the mean plus or minus 1.96 standard errors, the standard error being the standard deviation divided by the square root of the number of values: a normal approximation, which is less accurate for small groups.

Examples

example_data$value <- eq5d3l(example_data[, c("mo", "sc", "ua", "pd", "ad")],
                             country = "GB")
tmp <- eq5d_utility_by_group_plot(
 example_data,
 name_utility = "value",
 name_groupvar = "procedure"
)
tmp$p
tmp$plot_data

eq5d_utility_change_by_group_plot: EQ-5D values: smoothed lines and confidence intervals by groupvar

Description

eq5d_utility_change_by_group_plot: EQ-5D values: smoothed lines and confidence intervals by groupvar

Usage

eq5d_utility_change_by_group_plot(
  df,
  name_utility = NULL,
  name_fu = NULL,
  levels_fu = NULL,
  name_groupvar = NULL
)

Arguments

Value

Summary plot and data used for plotting

Confidence intervals

The 95% confidence interval of a mean is the mean plus or minus 1.96 standard errors, the standard error being the standard deviation divided by the square root of the number of values: a normal approximation, which is less accurate for small groups.

Examples

example_data$value <- eq5d3l(example_data[, c("mo", "sc", "ua", "pd", "ad")],
                             country = "GB")
tmp <- eq5d_utility_change_by_group_plot(
 example_data,
 name_utility = "value",
 name_fu = "time",
 levels_fu = c('Pre-op', 'Post-op'),
 name_groupvar = "procedure"
)
tmp$p
tmp$plot_data

eq5d_utility_distribution_plot: EQ-5D values: smoothed lines and confidence intervals by groupvar

Description

eq5d_utility_distribution_plot: EQ-5D values: smoothed lines and confidence intervals by groupvar

Usage

eq5d_utility_distribution_plot(df, name_utility = NULL)

Arguments

Value

Summary plot and data used for plotting

Examples

example_data$value <- eq5d3l(example_data[, c("mo", "sc", "ua", "pd", "ad")],
                             country = "GB")
tmp <- eq5d_utility_distribution_plot(
 example_data,
 name_utility = "value"
)
tmp$p
tmp$plot_data

eq5d_utility_norms_comparison:EQ-5D values: by age and groupvar

Description

eq5d_utility_norms_comparison:EQ-5D values: by age and groupvar

Usage

eq5d_utility_norms_comparison(
  df,
  name_utility = NULL,
  name_fu = NULL,
  levels_fu = NULL,
  name_groupvar = NULL,
  name_age
)

Arguments

Details

The comparison with population norms describes the sample at baseline: only records at the first timepoint in levels_fu are used, so each respondent counts once, and a message says which timepoint that is. Records at other timepoints, or with a missing timepoint, are not included.

Value

Summary data frame

Examples

example_data$ageband <- factor(
  example_data$ageband,
  levels = c("20 to 29", "30 to 39", "40 to 49", "50 to 59", "60 to 69", "70 to 79", "80 to 89")
)
example_data <- example_data[example_data$gender %in% c("Male", "Female"),]
example_data$value <- eq5d3l(example_data[, c("mo", "sc", "ua", "pd", "ad")],
                             country = "GB")
eq5d_utility_norms_comparison(
  example_data,
  name_utility = "value",
  name_fu = "time",
  levels_fu = c('Pre-op', 'Post-op'),
  name_groupvar = "gender",
  name_age = "ageband"
)

eq5d_utility_over_time_plot: EQ-5D values by timepoints: mean values and 95% confidence intervals

Description

eq5d_utility_over_time_plot: EQ-5D values by timepoints: mean values and 95% confidence intervals

Usage

eq5d_utility_over_time_plot(
  df,
  name_utility = NULL,
  name_fu = NULL,
  levels_fu = NULL
)

Arguments

Value

Summary plot and data used for plotting

Confidence intervals

The 95% confidence interval of a mean is the mean plus or minus 1.96 standard errors, the standard error being the standard deviation divided by the square root of the number of values: a normal approximation, which is less accurate for small groups.

Examples

example_data$value <- eq5d3l(example_data[, c("mo", "sc", "ua", "pd", "ad")],
                             country = "GB")
tmp <- eq5d_utility_over_time_plot(
 example_data,
 name_utility = "value",
 name_fu = "time",
 levels_fu = c('Pre-op', 'Post-op')
)
tmp$p
tmp$plot_data

eq5d_utility_summary: EQ-5D values: by timepoints

Description

eq5d_utility_summary: EQ-5D values: by timepoints

Usage

eq5d_utility_summary(df, name_utility = NULL, name_fu = NULL, levels_fu = NULL)

Arguments

Details

Skewness and kurtosis are the population (biased) estimators m_3 / m_2^{3/2} and m_4 / m_2^2, as returned by moments::skewness() and moments::kurtosis().

The kurtosis is **non-excess**: a normal distribution gives 3, not 0. The row is labelled "Kurtosis (non-excess)" so that the output says which convention it uses. Stata's summarize, detail reports the same quantity. Excel's KURT() reports *excess* kurtosis with a sample-bias correction, so it is roughly 3 lower for the same data.

Value

Summary data frame with one row per statistic and one column per follow-up level, in the order given by levels_fu. "Missing (%)" is a percentage, from 0 to 100, of the rows at that follow-up (the "Total sample" row) with no usable value; it is NA for a follow-up with no rows. Before 2.1.0 it was a proportion.

Examples

example_data$value <- eq5d3l(example_data[, c("mo", "sc", "ua", "pd", "ad")],
                             country = "GB")
eq5d_utility_summary(
  example_data,
  name_utility = "value",
  name_fu = "time",
  levels_fu = c('Pre-op', 'Post-op')
)

eq5d_utility_summary_by_group:EQ-5D values: by groupvar

Description

eq5d_utility_summary_by_group:EQ-5D values: by groupvar

Usage

eq5d_utility_summary_by_group(df, name_utility = NULL, name_groupvar = NULL)

Arguments

Value

Summary data frame

Examples

example_data$value <- eq5d3l(example_data[, c("mo", "sc", "ua", "pd", "ad")],
                             country = "GB")
eq5d_utility_summary_by_group(
  example_data,
  name_utility = "value",
  name_groupvar = "procedure"
)

eq5d_utility_vas_scatter_plot: EQ-5D values: smoothed lines and confidence intervals by groupvar

Description

eq5d_utility_vas_scatter_plot: EQ-5D values: smoothed lines and confidence intervals by groupvar

Usage

eq5d_utility_vas_scatter_plot(df, name_utility = NULL, name_vas = NULL)

Arguments

Value

Summary plot and data used for plotting

Examples

example_data$value <- eq5d3l(example_data[, c("mo", "sc", "ua", "pd", "ad")],
                             country = "GB")
tmp <- eq5d_utility_vas_scatter_plot(
   example_data,
   name_utility = "value",
   name_vas = "vas"
 )
tmp$p
tmp$plot_data

Check a data frame of EQ-5D responses against its column mapping

Description

Runs the checks the Shiny app's Validation page runs: that the dimension columns are there, that their values are levels the instrument allows, how much is missing, whether patient IDs repeat in a way the timepoint column explains, and whether EQ VAS scores are in range.

Usage

eq5d_validate(df, mapping, stop_on_error = FALSE, quiet = FALSE)

Arguments

Details

Each finding is reported as it is found – with message() for a check that passed, warning() for one that found something, and for a problem that stops the analysis either stop() or a warning, according to stop_on_error. The findings are also returned, so a caller that wants to present them itself can.

Value

Invisibly, a data frame with one row per finding and the columns type ("ok", "warning" or "error") and message. The messages are plain text. Attribute "details" is a list with one element per finding: NULL, or a list with summary and records (data frames: the values found and their counts, and the records affected, by row number and, where those are selected, patient ID and timepoint), notes, emphasis and denominator (text). The details describe the data and change nothing.

See Also

eq5d_apply_mapping

eq5d_vas_distribution_table: EQ VAS Scores frequency of mid-points

Description

eq5d_vas_distribution_table: EQ VAS Scores frequency of mid-points

Usage

eq5d_vas_distribution_table(df, name_vas = NULL, add_na_total = TRUE)

Arguments

Value

Summary data frame

Examples

eq5d_vas_distribution_table(
  example_data,
  name_vas = 'vas', 
  add_na_total =  TRUE
  )

eq5d_vas_grouped_distribution_plot: Mid-point EQ VAS scores

Description

eq5d_vas_grouped_distribution_plot: Mid-point EQ VAS scores

Usage

eq5d_vas_grouped_distribution_plot(df, name_vas = NULL)

Arguments

Value

Summary plot and data used for plotting

Examples

tmp <- eq5d_vas_grouped_distribution_plot(example_data, name_vas = 'vas')
tmp$p
tmp$plot_data

eq5d_vas_histogram: EQ VAS scores

Description

eq5d_vas_histogram: EQ VAS scores

Usage

eq5d_vas_histogram(df, name_vas = NULL)

Arguments

Value

Summary plot and data used for plotting

Examples

tmp <- eq5d_vas_histogram(example_data, name_vas = 'vas')
tmp$p
tmp$plot_data

eq5d_vas_summary: EQ VAS Score by timepoints

Description

eq5d_vas_summary: EQ VAS Score by timepoints

Usage

eq5d_vas_summary(df, name_vas = NULL, name_fu = NULL, levels_fu = NULL)

Arguments

Details

Skewness and kurtosis are the population (biased) estimators m_3 / m_2^{3/2} and m_4 / m_2^2, as returned by moments::skewness() and moments::kurtosis().

The kurtosis is **non-excess**: a normal distribution gives 3, not 0. The row is labelled "Kurtosis (non-excess)" so that the output says which convention it uses. Stata's summarize, detail reports the same quantity. Excel's KURT() reports *excess* kurtosis with a sample-bias correction, so it is roughly 3 lower for the same data.

Value

Summary data frame with one row per statistic and one column per follow-up level, in the order given by levels_fu. "Missing (%)" is a percentage, from 0 to 100, of the rows at that follow-up (the "Total sample" row) with no usable value; it is NA for a follow-up with no rows. Before 2.1.0 it was a proportion.

Examples

eq5d_vas_summary(
  example_data,
  name_vas = 'vas', 
  name_fu = 'time', 
  levels_fu = c('Pre-op', 'Post-op')
)

eq5dy3l

Description

Get EQ-5D-Y-3L index values from individual responses to the five dimensions of the EQ-5D-Y-3L.

Usage

eq5dy3l(x, country = NULL, dim.names = c("mo", "sc", "ua", "pd", "ad"))

Arguments

Value

A numeric vector of EQ-5D-Y-3L values, or a data.frame with one column for each requested value set. The result is an unnamed numeric vector, one element per element or row of x and in the same order.

Missing and invalid responses

Each health state is checked before it is scored, and a state that cannot be scored gives NA for that element or row; the others are scored as usual.

• A missing response (NA in any dimension, or an NA state index) gives NA without a warning.

• An invalid response gives NA with a warning, which gives the number of such states and examples. Invalid means a level the instrument does not have (for example 4 in the EQ-5D-3L, or a missing-value code such as 9), a level or index that is not a whole, finite number, or an index that is not five digits long. Each problem is reported once, however many value sets are requested.

• State indexes and levels given as text or as factors are read through their labels, so "21111" and factor(2) are scored as 21111 and 2.

Recode missing-value codes to NA first if the warning is not wanted.

Examples

# Example 1: utility values from EQ-5D-Y-3L profile codes
eq5dy3l(x = c(11111, 12321, 33333), country = "SI")

# Example 2: request multiple value sets
eq5dy3l(make_all_EQ_states("3L"), country = c("ES", "DE"))

# Example 3: use a data.frame with dimension columns
dfy3l <- data.frame(
  mo = c(1, 2, 3),
  sc = c(1, 1, 2),
  ua = c(1, 2, 3),
  pd = c(2, 2, 3),
  ad = c(1, 3, 2)
)
eq5dy3l(dfy3l, country = "SI")

# Example 4: use custom dimension column names
dfy3l_named <- data.frame(
  mobility = c(1, 2, 3),
  self_care = c(1, 1, 2),
  usual_activities = c(1, 2, 3),
  pain_discomfort = c(2, 2, 3),
  anxiety_depression = c(1, 3, 2)
)
eq5dy3l(
  dfy3l_named,
  country = "SI",
  dim.names = c(
    "mobility", "self_care", "usual_activities",
    "pain_discomfort", "anxiety_depression"
  )
)

eqvs_add

Description

Add user-defined EQ-5D value set and corresponding crosswalk option.

Usage

eqvs_add(
  df,
  version = "5L",
  country = NULL,
  countryCode = NULL,
  VSCode = NULL,
  description = NULL,
  saveOption = 1,
  savePath = NULL
)

Arguments

Details

Every check below is made before anything is changed, so a value set that fails one is not added, in part or in full, and nothing is saved.

• df, if a file name, must name an existing csv file, and must have exactly two columns.

• It must have exactly one row per health state of the instrument (3,125 for the EQ-5D-5L, 243 for the EQ-5D-3L and EQ-5D-Y-3L), and every state must be present exactly once. The rows may be in any order, and the states may be given as numbers, text or factors; they must be whole numbers, so 11111.9 is refused rather than read as 11111.

• The value set code (VSCode, or the name of the second column) must not be a built-in value set code, compared without regard to case and across all three instruments; this is an error. If it is the code of one of your own value sets for the same instrument, again without regard to case, the function warns and returns 0 without adding it.

• Every value must be numeric and finite: NA, NaN, text, Inf and -Inf are errors.

• With saveOption = 3, savePath must name an existing directory. With saveOption = 2 or 3, if the cache cannot be saved, the value set is removed again.

The values themselves are not checked further: nothing requires full health (11111) to be 1, or the values to fall as the levels worsen.

Value

Called for its side effect. When the value set is added, NULL, invisibly, with a message. When VSCode is already used by one of your own value sets for this instrument, 0, with a warning, and nothing is added.

Examples

# Make a nonsense value set. The values are a plain sequence rather than
# runif(), which would move the random seed of whoever runs the example.
new_df <- data.frame(state = make_all_EQ_indexes(),
                     TEST = seq(1, -0.5, length.out = 3125))
# Add as value set for Fantasia
eqvs_add(
   new_df,
   version = "5L",
   country = 'Fantasia',
   countryCode = "MyCountry",
   VSCode = "FAN",
   saveOption = 1
)
eq5d5l(55555,country = "FAN")
# Remove it again, so the example leaves no value set behind.
eqvs_drop(country = "FAN", version = "5L", saveOption = 1, ask = FALSE)

eqvs_display

Description

Display available value sets, which can also be used as (reverse) crosswalks. Built-in value sets are shown first, followed by any user-defined value sets added via eqvs_add().

Usage

eqvs_display(version = "5L", return_df = FALSE, show_citation = FALSE)

Arguments

Value

When return_df = FALSE, NULL invisibly, called for the printed output. When return_df = TRUE, a data.frame, returned visibly so that it still prints when the call is made at the console.

Examples

# Print the available EQ-5D-5L value sets.
eqvs_display(version = "5L")

# Get the same information as a data.frame, printing nothing.
vs <- eqvs_display(version = "5L", return_df = TRUE)
head(vs)

eqvs_drop

Description

Drop user-defined EQ-5D value set to reverse crosswalk options.

Usage

eqvs_drop(
  country = NULL,
  version = "5L",
  saveOption = 1,
  savePath = NULL,
  ask = TRUE
)

Arguments

Value

Invisibly TRUE if a value set was removed, and FALSE otherwise (for example if no matching value set exists, or the user declined the confirmation).

Examples

  # Make a nonsense value set, without moving the random seed.
  new_df <- data.frame(state = make_all_EQ_indexes(),
                       TEST = seq(1, -0.5, length.out = 3125))
  # Add as value set for Fantasia
  eqvs_add(
   new_df,
   version = "5L",
   country = 'Fantasia',
   countryCode = "MyCountry",
   VSCode = "FAN",
   saveOption = 1
  )
  # Test the new value set
  eq5d5l(55555,country = "FAN")
  # Drop value set for Fantasia, without asking for confirmation
  eqvs_drop(country = 'FAN', saveOption = 1, ask = FALSE)

eqvs_load

Description

Load cache data from a specified path.

Usage

eqvs_load(loadPath)

Arguments

Details

loadPath is the *directory* a cache was written to with eqvs_add(saveOption = 3, savePath = ...) or eqvs_drop(saveOption = 3, savePath = ...), not a single value set. Everything saved there is restored at once.

A cache written with saveOption = 2 goes to the package's user cache directory and is read back automatically when the package loads, so it needs no call to eqvs_load().

Value

TRUE if loading is successful, FALSE otherwise.

See Also

eqvs_add, eqvs_drop

Examples

# Save a custom value set to a directory of your choosing, then read it
# back. tempdir() is used here so the example leaves nothing behind.
path <- file.path(tempdir(), "eq5d-value-sets")
dir.create(path, showWarnings = FALSE)

my_vs <- data.frame(state = make_all_EQ_indexes("3L"),
                    MY_VS = round(seq(1, -0.5, length.out = 243), 4))
eqvs_add(my_vs, version = "3L", country = "My Country",
         countryCode = "MC", VSCode = "MY_VS",
         saveOption = 3, savePath = path)

# In a later session, restore it from that directory.
eqvs_load(loadPath = path)
eq5d3l(c(11111, 33333), country = "MY_VS")

# Tidy up.
eqvs_drop(country = "MY_VS", version = "3L", ask = FALSE)
unlink(path, recursive = TRUE)

eqxw

Description

Get crosswalk values

Usage

eqxw(x, country = NULL, dim.names = c("mo", "sc", "ua", "pd", "ad"))

Arguments

Value

A numeric vector of crosswalk values, or a data.frame with one column per crosswalk set requested. The result is an unnamed numeric vector, one element per element or row of x and in the same order.

Missing and invalid responses

Each health state is checked before it is scored, and a state that cannot be scored gives NA for that element or row; the others are scored as usual.

• A missing response (NA in any dimension, or an NA state index) gives NA without a warning.

• An invalid response gives NA with a warning, which gives the number of such states and examples. Invalid means a level the instrument does not have (for example 4 in the EQ-5D-3L, or a missing-value code such as 9), a level or index that is not a whole, finite number, or an index that is not five digits long. Each problem is reported once, however many value sets are requested.

• State indexes and levels given as text or as factors are read through their labels, so "21111" and factor(2) are scored as 21111 and 2.

Recode missing-value codes to NA first if the warning is not wanted.

Examples

eqxw(c(11111, 12521, 32123, 55555), 'US')
eqxw(make_all_EQ_states('5L'), c('DK', 'US'))

eqxw_UK

Description

Map EQ-5D-5L health states, or mean EQ-5D-5L values, to EQ-5D values based on the UK EQ-5D-3L value set (Dolan 1997), using the mapping published by the NICE Decision Support Unit (Hernández Alava et al. 2023).

Usage

eqxw_UK(x, age, male, dim.names = c("mo", "sc", "ua", "pd", "ad"), bwidth = 0)

Arguments

Details

NICE's interim methods statement of 27 August 2026 (NICE 2026, PMG51) makes the UK EQ-5D-5L value set the reference case: EQ-5D-5L data collected in a study should be valued directly with it, that is eq5d5l(x, country = "GB"). The statement applies to topics started after it was published – for technology appraisals, those whose invitation to participate was issued after that date. For topics started before it, NICE says EQ-5D-5L data should continue to be mapped to EQ-5D-3L utility values, which is what eqxw_UK() does; it also reproduces earlier analyses. (Checked against the statement on 4 October 2026; NICE's methods manuals PMG36 and PMG20 are to be updated to match it.)

The mapping is age- and sex-specific. It is not the crosswalk of van Hout et al. (2012) implemented in eqxw, and it is not the reverse crosswalk of van Hout and Shaw (2021) implemented in eqxwr; those take neither age nor sex. See eqxwr_UK for the opposite direction.

Two kinds of input

Health states, for individual respondents. Give x as 5-digit EQ-5D-5L state indexes, or as a matrix or data frame with one column per dimension. Each respondent's state, age and sex are looked up directly and bwidth is ignored. This is the usual case.

EQ-5D values, for a mean value such as one reported in a published study. Give x as values on the UK EQ-5D-5L value set. There is no unique health state behind a mean, so the mapped value is a weighted average of the mapped values of the states whose EQ-5D value lies near it, using an Epanechnikov kernel of half-width bwidth within the age band and sex given. Set bwidth = "default" to apply the DSU's recommended bandwidths for mean values: 0.1 for values above 0.6, and 0.4 for values at or below 0.6. This input is not intended for individual-level data; map individual respondents from their health states.

Age and sex

Both are required. Age is used in years and grouped into the five bands of the mapping: 16-34, 35-44, 45-54, 55-64 and 65 or over. There is no upper limit. Ages below 16 are outside the estimation sample and return NA with a warning; values of 1 to 5 are treated as ages, never as band numbers. Sex must be 1 for male and 0 for female; TRUE and FALSE are accepted. Any other value returns NA with a warning.

Invalid or missing health states, ages or sexes return NA.

Value

An unnamed numeric vector of mapped EQ-5D values, one per row of x and in the same order.

Source

The mapping tables are taken from the publicly available commands for mapping between the EQ-5D-3L and the EQ-5D-5L published by the NICE Decision Support Unit (April 2026 release, which uses the UK EQ-5D-5L value set of Rowen et al. 2026): https://sheffield.ac.uk/nice-dsu/methods-development/mapping-eq-5d-5l-3l

As the DSU requests, work using these mappings cites Hernández Alava, Pudney and Wailoo (2023) and, for the underlying model, Hernández-Alava and Pudney (2017). See file.show(system.file("COPYRIGHTS", package = "eq5dsuite")).

References

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

Hernández-Alava M, Pudney S (2017). 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. Journal of Health Economics 55:139-152. doi:10.1016/j.jhealeco.2017.06.013

Rowen D, Mukuria C, Bray N, et al. (2026). A UK value set for the EQ-5D-5L. Value in Health 29(5):858-869. doi:10.1016/j.jval.2026.03.008

National Institute for Health and Care Excellence (2026). Interim methods statement: implementing the EQ-5D-5L value set (PMG51). Published 27 August 2026. https://www.nice.org.uk/process/pmg51

See Also

eqxwr_UK for EQ-5D-3L to EQ-5D-5L, eqxw and eqxwr for the van Hout crosswalks, and eq5d5l() for direct valuation.

Examples

# health states, for individual respondents
eqxw_UK(c(11111, 12345, 32423, 55555),
        age = c(30, 40, 55, 70), male = c(1, 0, 1, 0))

# a mean EQ-5D-5L value from a published study, with the recommended bandwidth
eqxw_UK(0.72, age = 55, male = 1, bwidth = "default")

eqxwr

Description

Get reverse crosswalk values

Usage

eqxwr(x, country = NULL, dim.names = c("mo", "sc", "ua", "pd", "ad"))

Arguments

Details

This is the reverse crosswalk of van Hout and Shaw (2021), which maps EQ-5D-3L responses to EQ-5D-5L values for any available value set. It does not use age or sex. It is a different mapping from eqxwr_UK, which implements the NICE Decision Support Unit mapping for the United Kingdom only and is age- and sex-specific. Do not substitute one for the other.

Value

A numeric vector of reverse crosswalk values, or a data.frame with one column per reverse crosswalk set requested. The result is an unnamed numeric vector, one element per element or row of x and in the same order.

Missing and invalid responses

Each health state is checked before it is scored, and a state that cannot be scored gives NA for that element or row; the others are scored as usual.

• A missing response (NA in any dimension, or an NA state index) gives NA without a warning.

• An invalid response gives NA with a warning, which gives the number of such states and examples. Invalid means a level the instrument does not have (for example 4 in the EQ-5D-3L, or a missing-value code such as 9), a level or index that is not a whole, finite number, or an index that is not five digits long. Each problem is reported once, however many value sets are requested.

• State indexes and levels given as text or as factors are read through their labels, so "21111" and factor(2) are scored as 21111 and 2.

Recode missing-value codes to NA first if the warning is not wanted.

References

van Hout B, Shaw JW (2021). Mapping EQ-5D-3L to EQ-5D-5L. Value in Health 24(9):1285-1293. doi:10.1016/j.jval.2021.03.009

See Also

eqxwr_UK, eqxw

Examples

eqxwr(c(11111, 12321, 32123, 33333), 'US')
eqxwr(make_all_EQ_states('3L'), c('DK', 'US'))

eqxwr_UK

Description

Map EQ-5D-3L health states, or mean EQ-5D-3L values, to EQ-5D values based on the UK EQ-5D-5L value set (Rowen et al. 2026), using the mapping published by the NICE Decision Support Unit (Hernández Alava et al. 2023).

Usage

eqxwr_UK(x, age, male, dim.names = c("mo", "sc", "ua", "pd", "ad"), bwidth = 0)

Arguments

Details

This is the mapping NICE's interim methods statement of 27 August 2026 (NICE 2026, PMG51) specifies when EQ-5D-5L data from a relevant study are not available and EQ-5D-3L data are used instead: the 3L responses are mapped to utility values on the UK EQ-5D-5L value set, the reference case for topics started after that date. (Checked against the statement on 4 October 2026.)

The mapping is age- and sex-specific. It is not the reverse crosswalk of van Hout and Shaw (2021) implemented in eqxwr, which takes neither age nor sex and is available for many value sets; the two give different answers and are not interchangeable. See eqxw_UK for the opposite direction.

Two kinds of input

Health states, for individual respondents. Give x as 5-digit EQ-5D-3L state indexes, or as a matrix or data frame with one column per dimension. Each respondent's state, age and sex are looked up directly and bwidth is ignored. This is the usual case.

EQ-5D values, for a mean value such as one reported in a published study. Give x as values on the UK EQ-5D-3L value set. There is no unique health state behind a mean, so the mapped value is a weighted average of the mapped values of the states whose EQ-5D value lies near it, using an Epanechnikov kernel of half-width bwidth within the age band and sex given. Set bwidth = "default" to apply the DSU's recommended bandwidths for mean values: 0.1 for values above 0.6, and 0.4 for values at or below 0.6. This input is not intended for individual-level data; map individual respondents from their health states.

Age and sex

Both are required. Age is used in years and grouped into the five bands of the mapping: 16-34, 35-44, 45-54, 55-64 and 65 or over. There is no upper limit. Ages below 16 are outside the estimation sample and return NA with a warning; values of 1 to 5 are treated as ages, never as band numbers. Sex must be 1 for male and 0 for female; TRUE and FALSE are accepted. Any other value returns NA with a warning.

Invalid or missing health states, ages or sexes return NA.

Value

An unnamed numeric vector of mapped EQ-5D values, one per row of x and in the same order.

Source

The mapping tables are taken from the publicly available commands for mapping between the EQ-5D-3L and the EQ-5D-5L published by the NICE Decision Support Unit (April 2026 release, which uses the UK EQ-5D-5L value set of Rowen et al. 2026): https://sheffield.ac.uk/nice-dsu/methods-development/mapping-eq-5d-5l-3l

As the DSU requests, work using these mappings cites Hernández Alava, Pudney and Wailoo (2023) and, for the underlying model, Hernández-Alava and Pudney (2017). See file.show(system.file("COPYRIGHTS", package = "eq5dsuite")).

References

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

Hernández-Alava M, Pudney S (2017). 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. Journal of Health Economics 55:139-152. doi:10.1016/j.jhealeco.2017.06.013

Rowen D, Mukuria C, Bray N, et al. (2026). A UK value set for the EQ-5D-5L. Value in Health 29(5):858-869. doi:10.1016/j.jval.2026.03.008

National Institute for Health and Care Excellence (2026). Interim methods statement: implementing the EQ-5D-5L value set (PMG51). Published 27 August 2026. https://www.nice.org.uk/process/pmg51

See Also

eqxw_UK for EQ-5D-5L to EQ-5D-3L, and eqxwr for the van Hout and Shaw reverse crosswalk.

Examples

# health states, for individual respondents
eqxwr_UK(c(11111, 12321, 32123, 33333),
         age = c(30, 40, 55, 70), male = c(1, 0, 1, 0))

# a mean EQ-5D-3L value from a published study, with the recommended bandwidth
eqxwr_UK(0.54, age = 35, male = 0, bwidth = "default")

example_data

Description

A sample of patient-level EQ-5D-3L data from the NHS Patient Reported Outcome Measures (PROMs) programme, in long format: 5,000 patients, each with one pre-operative and one post-operative record.

Missing values in the EQ-5D dimensions and in the EQ VAS are recorded with numeric codes rather than NA: 9 in mo, sc, ua, pd and ad (1,323 cells across 497 records), and 999 in vas (671 records). Both the analysis functions and the value functions (eq5d3l(), eq5d(), eqxwr() and so on) treat these as invalid: they set them to NA, with a warning. Recode them to NA first to avoid the warning. ageband and gender use NA directly (970 records each).

Usage

data(example_data)

Format

A data frame with 10000 rows and 12 variables:

id

integer Patient id; each id appears twice

time

character Follow-up (Pre-op / Post-op)

mo

integer EQ-5D-3L Mobility dimension (1-3; 9 = missing)

sc

integer EQ-5D-3L Self-care dimension (1-3; 9 = missing)

ua

integer EQ-5D-3L Usual activities dimension (1-3; 9 = missing)

pd

integer EQ-5D-3L Pain/discomfort dimension (1-3; 9 = missing)

ad

integer EQ-5D-3L Anxiety/depression dimension (1-3; 9 = missing)

vas

integer EQ VAS score (0-100; 999 = missing)

procedure

character Type of surgery (Groin Hernia / Hip Replacement / Knee Replacement / Varicose Vein)

year

character Financial year of the operation, April to March (2013/14 to 2016/17)

ageband

character Age in pre-defined ranges (20 to 29, ..., 80 to 89; NA where not recorded)

gender

character Patient's gender (Female / Male / Not specified; NA where not recorded)

Fetch the index of available value sets from GitHub

Description

Fetch the index of available value sets from GitHub

Usage

fetch_available_value_sets(version)

Arguments

Value

A data frame with columns Version, Name, Name_short, Country_code, VS_code, doi. Returns NULL if fetch fails.

Fetch the migrations index from the repository

Description

Downloads the migrations.csv file from the eq5dsuite-value-sets repository, which records all historical value set renames. Returns NULL silently if the fetch fails.

Usage

fetch_migrations()

Value

A data frame with columns version, old_VS_code, new_VS_code, reason, date. Returns NULL if fetch fails.

Get the list of already-applied migrations

Description

Reads the locally cached list of migration IDs that have already been applied. Returns an empty character vector if no migrations have been applied yet.

Usage

get_applied_migrations()

Value

A character vector of migration IDs.

Get the eq5dsuite cache directory

Description

Returns the path to the user-specific cache directory used by eq5dsuite to store the date of the last value set check. The directory is created if it does not exist, unless create = FALSE.

Usage

get_cache_dir(create = TRUE)

Arguments

Value

A character string giving the path to the cache directory.

Get the VS_codes currently installed for a given instrument

Description

Returns all installed VS_codes for the specified instrument version, including both built-in value sets shipped with the package and any user-added value sets installed via eqvs_add() or update_value_sets().

Usage

get_installed_vs_codes(version)

Arguments

Details

Reads directly from the runtime package environment (getOption("eq.env")) to include user-added value sets without triggering the display side-effects of eqvs_display().

Value

A character vector of VS_codes.

Get the date of the last value set check

Description

Reads the cached date of the last value set update check from the user cache directory. Returns 1970-01-01 if no cache file exists (i.e., the check has never been run).

Usage

get_last_checked()

Value

A Date object.

Download and install a single value set

Description

Download and install a single value set

Usage

install_value_set(vs_code, version, meta_row)

Arguments

Value

Logical. TRUE if successful, FALSE otherwise.

Check whether a value set update check is due

Description

Compares the date of the last value set check (from the user cache) against Sys.Date(). Returns TRUE if more than threshold_days days have elapsed, indicating that the user should be prompted to run update_value_sets().

Usage

is_update_due(threshold_days = 60)

Arguments

Value

A single logical value.

make_all_EQ_indexes

Description

Make a vector containing all 5-digit EQ-5D indexes for -3L or -5L version.

Usage

make_all_EQ_indexes(
  version = "5L",
  dim.names = c("mo", "sc", "ua", "pd", "ad")
)

Arguments

Value

A vector with 5-digit state indexes for all 243 (-3L, -Y-3L) or 3125 (-5L) EQ-5D health states

Examples

make_all_EQ_indexes('3L')

make_all_EQ_states

Description

Make a data.frame with all health states defined by dimensions

Usage

make_all_EQ_states(
  version = "5L",
  dim.names = c("mo", "sc", "ua", "pd", "ad"),
  append_index = FALSE
)

Arguments

Value

A data.frame with 5 columns and 243 (-3L, -Y-3L) or 3125 (-5L) health states

Examples

make_all_EQ_states('3L')

EQ_dummies

Description

Make a data.frame of all EQ-5D dummies relevant for e.g. regression modelling.

Usage

make_dummies(
  df,
  version = "5L",
  dim.names = c("mo", "sc", "ua", "pd", "ad"),
  drop_level_1 = TRUE,
  add_intercept = FALSE,
  incremental = FALSE,
  prepend = NULL,
  append = NULL,
  return_df = TRUE
)

Arguments

Value

A data.frame of dummy variables, one row per row of df. Levels are read as the value functions read them: text and factors through their labels. A level the instrument does not have (fractional, 0, negative, non-finite or above the highest level) is not a level, so that dimension's dummies are NA, with a warning; a missing level gives NA dummies without one.

Examples

make_dummies(make_all_EQ_states('3L'), '3L')

make_dummies(df = make_all_EQ_states('3L'), 
             version =  '3L', 
             incremental = TRUE, 
             add_intercept = TRUE, 
             prepend = "d_")

Rename a value set

Description

Renames a user-defined value set, preserving its values and its metadata: only the identifier changes. The two tables are rebuilt as locals, checked, and committed together, so a rename that cannot complete leaves the session and the cache exactly as they were.

Usage

rename_value_set(old_vs_code, new_vs_code, version, ask = TRUE)

Arguments

Details

A built-in code is not renamed at runtime. It is part of the installed package's data, and changing it in one session would mean two installations of the same version disagreeing about what a code means. A built-in code change ships in a release; where backward compatibility is needed the old code is kept as a deprecated alias in .fixCountries(), as "UK" is for "GB". Asked to rename a built-in, this function explains that and returns FALSE without changing anything.

Value

Logical. TRUE if successful, FALSE otherwise.

Launch the eq5dsuite Shiny Application

Description

Opens an interactive Shiny application for uploading, validating, analysing and exporting EQ-5D data.

Usage

run_app(online = NULL, ...)

Arguments

Details

The app has seven pages, in the order the work is done:

Home

What the app does, what data it needs, and a button to load the bundled example_data.

Data

Upload a .csv, .xlsx or .rds file, set the instrument version, and select its variables ("Confirm variables"). Only the five EQ-5D dimensions are required; a timepoint, patient ID, group, EQ VAS score, age, sex and an existing EQ-5D value column are each optional and each unlock further analyses.

Validation

Range, missingness and duplicate-ID checks, then "Proceed", which fixes the working dataset.

Calculate EQ-5D values

Turn the responses into values and append them as a column. One Method selector covers every way the package has of doing it: a published value set directly, a crosswalk (eqxw, eqxwr), or the NICE Decision Support Unit's UK mapping (eqxw_UK, eqxwr_UK). The direction of a mapping follows the instrument version and is stated in the method's label and on the page: EQ-5D-3L responses give EQ-5D-5L values, and EQ-5D-5L responses give EQ-5D-3L values.

The DSU mapping depends on the respondent's age and sex as well as the health state, so choosing it asks for those columns. Where the age column holds bands rather than exact ages, the midpoint of each band is used and the page says so: the DSU's age bands begin at 35, 45, 55 and 65, which are exactly the midpoints of ten-year bands, so a band straddling a boundary is placed in the upper one. Supply exact ages where they are available.

Only the EQ-5D value analyses need a value column; the profile and EQ VAS analyses can be run without one. Several columns can be added and compared.

The working dataset can be downloaded from here, as CSV, XLSX or RDS, with every column added during the session. EQ-5D values are shown to three decimal places throughout the app, but written at full precision.

Analysis

All the analysis functions of Devlin et al. (2020), in one place. Pick a component (EQ-5D profiles, EQ-5D values or EQ VAS), then an output, then Run – or open "See catalogue of available analyses", which lists, in one tab per component, only what the data can support: a plain description of each and an example of its output on the bundled example data, with "Select this". An output whose variables are not selected says what it needs rather than failing. The EQ-5D value analyses take a Utility column, offering every value column in the dataset; the chosen one is passed to the analysis as name_utility and nothing is recalculated.

Results and export

Every analysis that has been run, numbered, each with controls to move it up or down or remove it, its own downloads (CSV for a table, PNG and PDF for a figure), and "View", which shows the table or figure and the eq5dsuite code that produced it. That order is the export order for all three exports: a Word report, one section per result with its title and its table or figure; an archive of CSV tables and PNG figures with a manifest.csv; and an R script that repeats the whole session. The Word report uses the template bundled with the package and needs Pandoc, which ships with RStudio.

The script loads the data, runs the same checks, calculates the same EQ-5D values and produces the same results in the same order. Apart from the analysis functions themselves it calls nothing from eq5dsuite: reading the file, renaming the columns, the checks, the age-band midpoints and the display formatting are all written out in the script, so it can be read, changed and run wherever eq5dsuite is installed, with no part of the app involved. It is built from a structured record of what was done, so every value is quoted safely.

Value

Called for its side effect of launching a Shiny application. Returns invisibly.

Running it on a server

run_app(online = TRUE), or EQ5DSUITE_ONLINE=true in the environment the app starts in, puts the app in online mode. That limits what can be uploaded, keeps every file the app writes inside a folder of its own that is deleted when the session ends, ends idle sessions, sanitises errors, and tells the user what happens to their data. Locally – the default – none of it applies and the app behaves as it always has.

The limits and the wording are set with options or environment variables. DEPLOY.md in the installed package (system.file("shiny", "DEPLOY.md", package = "eq5dsuite")) covers what the server itself has to be told.

The app does not attach eq5dsuite, so it needs no library() call first; run_app() is enough.

References

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

See Also

eq5d and eqxwr_UK for the EQ-5D values the app calculates, and eq5d_profile_level_summary for the analyses it runs.

eq5d for value calculation, eqxwr_UK and eqxw_UK for the UK mapping.

Examples

## Not run: 
  # Locally.
  eq5dsuite::run_app()

  # On a server, with the defaults.
  eq5dsuite::run_app(online = TRUE)

  # On a server, with its own limits.
  options(eq5dsuite.max_rows = 20000, eq5dsuite.idle_minutes = 15)
  eq5dsuite::run_app(online = TRUE)

## End(Not run)

Build an R script reproducing a Shiny session

Description

Build an R script reproducing a Shiny session

Usage

script_from_session(steps = list(), results = list(), title = "EQ-5D analysis")

Arguments

Value

A character vector of lines.

Save the list of applied migrations to cache

Description

Save the list of applied migrations to cache

Usage

set_applied_migrations(migrations)

Arguments

Value

Invisibly, TRUE if the list was saved and reads back as saved, FALSE (with a warning) otherwise.

Set the date of the last value set check

Description

Writes the given date to the user cache directory so that future calls to get_last_checked() and is_update_due() can determine how long ago the check was performed.

Usage

set_last_checked(date = Sys.Date())

Arguments

Value

Invisibly returns date.

Give the tables in a .docx borders and let Word size their columns

Description

Pandoc writes its tables with the reference document's "Table" style, which in the bundled template has no borders at all, and with the column widths fixed from the width of the Markdown source. Both are set right here, on the finished file: the style becomes "Table Grid", which the template already defines, and the layout becomes autofit so Word sizes each column to what is in it. Tables too wide to read at the body font are set smaller.

Usage

style_docx_tables(
  file,
  narrow_from = 8L,
  narrow_half_pt = 16L,
  landscape_from = 12L
)

Arguments

Details

A table of more than landscape_from columns is given a landscape page of its own. The level-frequency-by-timepoint table is 21 columns wide, which no amount of autofit will make readable across a 6.5-inch page.

Value

file, invisibly.

Tidy an analysis table's column headings for a Word document

Description

The analysis functions name columns for machines: freq_Post-op_mo, Knee Replacement_Post-op_n, mo_% Total. Word cannot break a line at an underscore, so each of those is one unbreakable token and the column is made wide enough to hold it – which is how a 21-column table ends up with nothing legible in it. Replacing the underscores lets Word wrap the heading over two or three lines and size the column to its contents instead.

Usage

tidy_table_headings(nm)

Arguments

Value

The names, tidied.

toEQ5Ddims

Description

Generate dimension vectors based on state index

Usage

toEQ5Ddims(x, dim.names = c("mo", "sc", "ua", "pd", "ad"))

Arguments

Value

A data.frame with 5 integer columns, one for each EQ-5D dimension, with names from the dim.names argument; the same layout as the output of make_all_EQ_states(). A code that is not a valid 5-digit state gives NA in every column, with a warning.

Examples

toEQ5Ddims(c(12345, 54321, 12321))

Convert EQ-5D dimension scores to a five-digit profile index

Description

Convert EQ-5D dimension scores to a five-digit profile index

Usage

toEQ5Dindex(
  x,
  dim.names = c("mo", "sc", "ua", "pd", "ad"),
  na.rm = FALSE,
  quiet = FALSE
)

Arguments

Value

An integer vector with one element per row (data.frame/matrix input) or a single integer (vector input). Works inside dplyr::mutate() without rowwise().

Examples

# Named vector — scalar usage unchanged
toEQ5Dindex(c(mo=1, sc=2, ua=3, pd=1, ad=2))

Update eq5dsuite value sets

Description

Connects to the eq5dsuite value sets repository and checks whether new value sets are available for any of the three EQ-5D instruments. Optionally drop or rename existing value sets before checking for updates.

Usage

update_value_sets(
  versions = c("3L", "5L", "Y3L"),
  ask = TRUE,
  drop = NULL,
  rename = NULL
)

Arguments

Details

This function requires an internet connection for checking and installing new value sets. Drop and rename operations work offline.

An instrument counts as checked only when its index was downloaded and is valid. One that could not be downloaded, or whose index is malformed, is reported as failed, with the reason, and is not reported as up to date. The date of the last check, which the reminder on loading the package uses, is moved on only when every requested instrument was checked and every new value set installed; otherwise the reminder stays due.

Value

Invisibly returns a list with elements checked (the instruments whose index was read and valid), failed (a named character vector: for each instrument that could not be checked, the reason), new, installed, install_failed (new value sets that could not be installed), migration_conflicts (renames not applied because both codes are installed; both value sets are kept), migrations_unrecorded (renames made, and kept, whose record could not be saved), dropped, and renamed. A list of renames that could not be downloaded, or is malformed, or renames that could not be recorded, appear in failed as "migrations"; that, or a conflict, leaves the check incomplete, so the date of the last check is not moved on. A rename made but not recorded is recorded by the next run, without being made again.

Examples

## Not run: 
# Check for new value sets interactively
update_value_sets()

# Check specific instrument only
update_value_sets(versions = "5L")

# Drop a value set
update_value_sets(drop = "NL:3L")

# Rename a value set
update_value_sets(rename = c("NL:3L" = "NL_2006"))

# Drop and rename in one call
update_value_sets(
  drop   = "DE:3L",
  rename = c("NL:3L" = "NL_2006", "SI:3L" = "SI_TTO")
)

# Non-interactive update
update_value_sets(ask = FALSE)

## End(Not run)

Write the saved Shiny results to a Word document

Description

Produces one section per saved result, in the order given, each with the result's title and its table or figure. The document is rendered through Pandoc with inst/shiny/template.docx as the reference document, so it takes that file's styles, header and footer; the template's own text is not carried over.

Usage

write_results_docx(
  results,
  file,
  template = system.file("shiny", "template.docx", package = "eq5dsuite"),
  title = "EQ-5D results",
  format_table = NULL
)

Arguments

Details

The order of results is the order of the report. The Shiny app lets the user reorder and remove saved results on the Results page, and passes whatever is left, so a removed result is simply absent from the list and therefore from the document.

Value

file, invisibly.