Package 'qalytools'

Coerce to an EQ5D object

Description

We define an ⁠<EQ5D>⁠ object as a data frame meeting the following criteria:

• It contains columns that represent dimensions from the EQ5D survey specification as well as a column representing the Visual Analogue Score.

• It contains a column that acts as a unique respondent identifier and another that identifies different surveys over time. Together these should uniquely identify a response and no combination should be duplicated within the data frame.

⁠<EQ5D3L>⁠, ⁠<EQ5D5L>⁠ and ⁠<EQ5DY3L>⁠ objects are defined as a subclass of EQ5D objects with the additional restriction that the corresponding dimension columns in x are either NA or whole numbers bounded below by 1 and above by 3 or 5 (depending on the survey type).

Usage

as_eq5d5l(
  x,
  respondentID,
  surveyID,
  mobility,
  self_care,
  usual,
  pain,
  anxiety,
  vas,
  ...
)

as_eq5d3l(
  x,
  respondentID,
  surveyID,
  mobility,
  self_care,
  usual,
  pain,
  anxiety,
  vas,
  ...
)

as_eq5dy3l(
  x,
  respondentID,
  surveyID,
  mobility,
  self_care,
  usual,
  pain,
  anxiety,
  vas,
  ...
)

Arguments

x	A data frame like object.
respondentID	⁠[character]⁠ The name of a variable in x that uniquely identifies respondents.
surveyID	⁠[character]⁠ Name of variable x that uniquely identifies surveys over time.
mobility	⁠[character]⁠ Name of the 'mobility' dimension in x.
self_care	⁠[character]⁠ Name of the 'self-care' dimension in x.
usual	⁠[character]⁠ Name of the 'usual activities' dimension in x.
pain	⁠[character]⁠ Name of the 'pain / discomfort' dimension in x.
anxiety	⁠[character]⁠ Name of the 'anxiety / depression' dimension in x.
vas	⁠[character]⁠ Name of the 'visual analogue score' variable in x.
...	Not currently used.

Value

A tibble like ⁠<EQ5D3L>⁠, ⁠<EQ5D5L>⁠ or ⁠<EQ5DY3L>⁠ object.

Examples

data(eq5d3l_example)
as_eq5d3l(
    eq5d3l_example,
    respondentID = "respondentID",
    surveyID = "surveyID",
    mobility = "MO",
    self_care = "SC",
    usual = "UA",
    pain = "PD",
    anxiety = "AD",
    vas = "vas"
)

---

Coerce to a utility object

Description

Coerce data frames to utility objects

A utility object contains is a data frame that meets the following criteria:

• It contains a column that acts as a unique respondent identifier and another that identifies different surveys over time.

• It contains additional columns that represent the country, type and value of a utility that has previously been calculated.

• Together, Each combination of respondent identifier, survey identifier, utility country and utility type should be unique and not duplicated across rows.

Usage

as_utility(x, respondentID, surveyID, country, type, value)

Arguments

x	⁠[data.frame]⁠.
respondentID	⁠[character]⁠ Unique respondent identifier. The name of a variable in x that uniquely identifies respondents.
surveyID	⁠[character]⁠ Name of variable in x that uniquely identifies surveys over time. To avoid ambiguity the specified variable must be either numeric or a factor (in which case the order will be taken as that given by the factor levels).
country	⁠[character]⁠ Name of variable in x representing the utility country.
type	⁠[character]⁠ Name of variable in x representing the utility country.
value	⁠[character]⁠ Name of variable in x representing the utility value.

Value

A tibble like ⁠<utility>⁠ object.

---

Available value sets

Description

Generic function that lists value sets available.

Usage

available_valuesets(x, ...)

## Default S3 method:
available_valuesets(x, ...)

## S3 method for class 'EQ5D5L'
available_valuesets(x, ...)

## S3 method for class 'EQ5D3L'
available_valuesets(x, ...)

## S3 method for class 'EQ5DY3L'
available_valuesets(x, ...)

## S3 method for class 'character'
available_valuesets(x, ...)

Arguments

x	An R object.
...	Further arguments passed to or from other methods.

Details

available_valuesets() returns the available valuesets from the eq5d package. It is an s3 generic that wraps the eq5d::valuesets() function providing additional methods for eq5d and character objects.

For character objects, the input is expected to be the survey type with various forms permitted:

• "eq5d5l", "EQ5D5L", "eq-5d-5l", "EQ-5D-5L", "5L", "5l"

• "eq5d3l", "EQ5D3L", "eq-5d-3l", "EQ-5D-3L", "3L", "3l"

• "eq5dy3l" , "EQ5DY3L" , "eq-5d-y-3l" , "EQ-5D-Y-3L" , "Y3L" , "y3l"

If called with no arguments value sets for all available version, type and country combination are returned.

Value

A tibble containing the available value sets for the given object or survey type.

Examples

data(eq5d3l_example)
dat <- as_eq5d3l(
    eq5d3l_example,
    respondentID = "respondentID",
    surveyID = "surveyID",
    mobility = "MO",
    self_care = "SC",
    usual = "UA",
    pain = "PD",
    anxiety = "AD",
    vas = "vas"
)
available_valuesets(dat)
available_valuesets("eq5d5l")

---

Calculate limitation

Description

Generic function that calculates the limitation of survey responses across response dimensions. Here we define a limitation to be a dimension value not equal to 1. Methods are provided for EQ5D objects.

Usage

calculate_limitation(x, ...)

## Default S3 method:
calculate_limitation(x, ...)

## S3 method for class 'EQ5D'
calculate_limitation(x, ...)

Arguments

x	An R object.
...	Further arguments passed to or from other methods.

Value

A tibble of the fraction of individuals without limitation.

Examples

data(eq5d3l_example)
dat <- as_eq5d3l(
    eq5d3l_example,
    respondentID = "respondentID",
    surveyID = "surveyID",
    mobility = "MO",
    self_care = "SC",
    usual = "UA",
    pain = "PD",
    anxiety = "AD",
    vas = "vas"
)
calculate_limitation(dat)

---

Calculate the Paretian Classification of Health Change

Description

calculate_pchc() calculates the Paretian Classification of Health Change (PCHC) in an individuals health state between two surveys. It wraps the eq5d::pchc() function providing methods for EQ5D objects.

Usage

calculate_pchc(pre, post, no.problems = TRUE, by.dimension = FALSE)

Arguments

pre	An EQ5D object for a single survey.
post	An EQ5D object for a single survey.
no.problems	boolean. Summarise 11111 "No change" subjects in a "No problems" group.
by.dimension	boolean. Summarise results by each EQ-5D dimension rather than by the whole dataset.

Value

For by.dimension = FALSE:

• A data frame with columns 'Change', 'Number' and 'Percent'.

For by.dimension = TRUE:

• A data frame with columns 'Dimension', 'Change', 'Number' and 'Percent'.

Examples

data(eq5d3l_example)
dat <- as_eq5d3l(
    eq5d3l_example,
    respondentID = "respondentID",
    surveyID = "surveyID",
    mobility = "MO",
    self_care = "SC",
    usual = "UA",
    pain = "PD",
    anxiety = "AD",
    vas = "vas"
)
grp1 <- subset(dat, Group == "Group1")
grp2 <- subset(dat, Group == "Group2")
calculate_pchc(grp1, grp2)
calculate_pchc(grp1, grp2, by.dimension = TRUE)

---

Calculate quality of life years

Description

Generic for calculating quality of life years (QALY) metrics for EQ5D survey respondents.

Usage

calculate_qalys(x, ...)

## Default S3 method:
calculate_qalys(x, ...)

## S3 method for class 'EQ5D'
calculate_qalys(
  x,
  time_index,
  type,
  country,
  units = c("days", "weeks", "months", "quarters", "years"),
  baseline_survey = NULL,
  ...
)

## S3 method for class 'utility'
calculate_qalys(
  x,
  time_index,
  units = c("days", "weeks", "months", "quarters", "years"),
  baseline_survey = NULL,
  ...
)

Arguments

x	An R object.
...	Further arguments passed to or from other methods.
time_index	⁠[character]⁠ Name of variable in x representing the relative time within the survey framework.
type	⁠[character]⁠ Method type(s) used for calculating the value sets. For EQ5D3L inputs this can be: "TTO", the time trade-off valuation technique; "VAS", the visual analogue scale valuation technique; "RCW", a reverse crosswalk conversion to EQ5D5L values; or "DSU", the NICE Decision Support Unit's model that allows mappings on to EQ5D5L values accounting for both age and sex. For EQ5D5L inputs this can be: "VT", value sets generated via a EuroQol standardised valuation study protocol; "CW", a crosswalk conversion EQ5D3L values; or "DSU", the NICE Decision Support Unit's model that allows mappings on to EQ5D5L values accounting for both age and sex.
country	⁠[character]⁠ Value set countries to use.
units	character The units of the time_index column of x. Can be one of "days", "weeks", "months", "quarters" or "years". Note that the output will always be a QALY (i.e years) irrespective of the unit input.
baseline_survey	(optional) Either a character string specifying the surveyID, to use as a baseline or a data frame. If a data frame, it must have at least two columns; one for the respondentID (with name matching that in x input) and another (of any name) for the associated utility values. If desired you can also specify columns that match on the utility and country type columns of the input x.

Details

The methods provided for utility and EQ5D objects, return two metrics by default:

• Firstly, a raw QALY. This is the area under the utility curve scaled to the proportion of the year it corresponds to.

• Secondly, a loss_v_fullhealth value. This represents the loss from perfect health which is calculated by assuming all dimensions are 1 to calculate a full health QALY value.

• Optionally, a third metric can also be returned, loss_v_baseline. This represents the loss from a specified baseline utility value.

Value

A tibble.

Note

If a character string baseline_survey argument is given then this must match a surveyID to match against. In this situation the survey is still included in the unadjusted, raw, calculation, prior to the calculation of loss.

Alternatively the baseline_survey argument can be specified as a data frame with a column corresponding to the respondentID and another representing the associated utility. Optionally columns corresponding to the utility country and utility type can be included to allow more granular comparisons. For this specification of baseline, it is not included in the unadjusted, raw, calculation.

Examples

data(EQ5D5L_surveys)
dat <- as_eq5d5l(
    EQ5D5L_surveys,
    surveyID = "surveyID",
    respondentID = "respondentID",
    mobility = "mobility",
    self_care = "self_care",
    usual = "usual",
    pain = "pain",
    anxiety = "anxiety",
    vas = "vas"
)
calculate_qalys(
    dat,
    time_index = "time_index",
    type = "VT",
    country = c("Denmark", "France")
)

---

Calculate utility

Description

Generic function that calculates EQ5D index scores for given value sets.

Usage

calculate_utility(x, type, country, ...)

## Default S3 method:
calculate_utility(x, type, country, ...)

## S3 method for class 'EQ5D5L'
calculate_utility(
  x,
  type = "VT",
  country = "England",
  drop = TRUE,
  age = NULL,
  sex = NULL,
  ...
)

## S3 method for class 'EQ5D3L'
calculate_utility(
  x,
  type = "VT",
  country = "England",
  drop = TRUE,
  age = NULL,
  sex = NULL,
  ...
)

## S3 method for class 'EQ5DY3L'
calculate_utility(
  x,
  type = "VT",
  country = "England",
  drop = TRUE,
  age = NULL,
  sex = NULL,
  ...
)

add_utility(x, type, country, ...)

## Default S3 method:
add_utility(x, type, country, ...)

## S3 method for class 'EQ5D5L'
add_utility(x, type = "VT", country = "England", age = NULL, sex = NULL, ...)

## S3 method for class 'EQ5D3L'
add_utility(x, type = "VT", country = "England", age = NULL, sex = NULL, ...)

## S3 method for class 'EQ5DY'
add_utility(x, type = "VT", country = "England", age = NULL, sex = NULL, ...)

Arguments

x	An R object.
type	⁠[character]⁠ Method type(s) used for calculating the value sets. For EQ5D3L inputs this can be: "TTO", the time trade-off valuation technique; "VAS", the visual analogue scale valuation technique; "RCW", a reverse crosswalk conversion to EQ5D5L values; or "DSU", the NICE Decision Support Unit's model that allows mappings on to EQ5D5L values accounting for both age and sex. For EQ5D5L inputs this can be: "VT", value sets generated via a EuroQol standardised valuation study protocol; "CW", a crosswalk conversion EQ5D3L values; or "DSU", the NICE Decision Support Unit's model that allows mappings on to EQ5D5L values accounting for both age and sex.
country	⁠[character]⁠ Value set countries to use.
...	Further arguments passed to or from other methods.
drop	⁠[logical]⁠ If TRUE (default), only columns corresponding to the surveyID and respondentID are kept from the input x.
age	⁠[character]⁠ Column in x representing the age, in years, of the respondent. Only used if type = "DSU".
sex	⁠[character]⁠ Column in x representing the sex, in years, of the respondent. Only used if type = "DSU". Column entries must be one of "Male", "M", "Female" or "F" (case insensitive).

Details

• calculate_utility() returns the utility index scores for a given object and value set combination. Methods that wrap functionality of the eq5d package are provided for EQ5D objects.

• add_utility() is a wrapper around calculate_utility() which keeps all columns of the input data x.

Value

A data frame of utility values linked to responses.

Note

The methods for EQ5D objects expect type and country to be of the same length but will recycle those of length one to a common size.

See Also

available_valuesets() for the method / country combinations available for each survey type.

Examples

data(eq5d3l_example)
dat <- as_eq5d3l(
    eq5d3l_example,
    respondentID = "respondentID",
    surveyID = "surveyID",
    mobility = "MO",
    self_care = "SC",
    usual = "UA",
    pain = "PD",
    anxiety = "AD",
    vas = "vas"
)
calculate_utility(dat, type = "TTO", country = c("UK", "Germany"))

---

Coerce an EQ5D object

Description

Methods to convert an EQ5D object to a data frame, tibble or data.table.

Usage

## S3 method for class 'EQ5D'
as.data.frame(x, row.names, optional, ...)

## S3 method for class 'EQ5D'
as.data.table(x, keep.rownames, ...)

## S3 method for class 'EQ5D'
as_tibble(x, ..., .rows, .name_repair, rownames)

Arguments

x	An EQ5D object.
row.names	Not used.
optional	Not used.
...	Not used.
keep.rownames	Not used.
.rows	Not used.
.name_repair	Not used.
rownames	Not used.

Value

An appropriate representation of the data frame underlying the EQ5D object. Only column names are preserved with all other attributes, including row names, dropped.

Note

Apart from x no other parameters are used and they are only present in the method signatures for compatibility with the underlying generic.

---

EQ-5D-3L example data

Description

A dataset containing dimensions and grouping for 200 observations. Data was obtained from the eq5d package on 2022-06-15, with additional variables added for package compatibility.

Usage

eq5d3l_example

Format

A tibble with 200 rows and 6 variables:

respondentID

Unique respondent identifier

surveyID

Unique survey identifier

MO

Mobility dimension valuea

SC

Self-care dimension values

UA

Usual activities dimension values

PD

Pain/discomfort dimension values

AD

Anxiety/depression dimension values

Group

Observation group

vas

VAS score

time

Relative time within survey framework

Source

https://github.com/fragla/eq5d/raw/master/inst/extdata/eq5d3l_example.xlsx

---

EQ-5D-5L multiple survey example data

Description

A dataset containing dimension values and vas score for 1000 respondents across 10 surveys. Data was synthetically generated.

Usage

EQ5D5L_surveys

Format

A tibble with 10000 rows and 11 variables:

surveyID

Survey ID

respondentID

Respondent ID

sex

Respondent sex

age

Respondent age

mobility

Mobility dimension

self_care

Self-care dimension

usual

Usual activities dimension

pain

Pain/discomfort dimension

anxiety

Anxiety/depression dimension

vas

VAS score

time_index

Relative time within survey framework

dummy

Random roolean variable

---

Summary method for eq5d objects

Description

Provides a summary of dimension values by survey ID.

Usage

## S3 method for class 'EQ5D'
summary(object, ..., tidy = FALSE)

Arguments

object	An EQ5D object.
...	Not currently used.
tidy	⁠[logical]⁠ Should results be returned as single, "tidy", table in long format? If FALSE, output will be a list of frequency / proportion tables split by survey ID.

---