R/eq5dsuite-package.R

In eq5dsuite: Handling and Analysing EQ-5d Data

#' eq5dsuite: Standardised Tools for EQ-5D Analysis
#'
#' @description
#' The \pkg{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:
#' \itemize{
#'   \item EQ-5D-3L
#'   \item EQ-5D-5L
#'   \item EQ-5D-Y-3L
#' }
#'
#' @section Value calculation:
#' Functions for calculating EQ-5D preference-based values:
#' \itemize{
#'   \item \code{\link{eq5d}} — Generic calculator for all
#'     instruments
#'   \item \code{\link{eq5d3l}} — EQ-5D-3L value calculation
#'   \item \code{\link{eq5d5l}} — EQ-5D-5L value calculation
#'   \item \code{\link{eq5dy3l}} — EQ-5D-Y-3L value calculation
#'   \item \code{\link{eqxw}} — Original crosswalk method
#'     (van Hout et al., 2012)
#'   \item \code{\link{eqxwr}} — Reverse crosswalk method
#'     (van Hout and Shaw, 2021)
#'   \item \code{\link{eqxw_UK}} — UK-specific NICE-recommended
#'     mapping (Hernandez Alava et al., 2023)
#' }
#'
#' @section Value set management:
#' Functions for managing country-specific value sets:
#' \itemize{
#'   \item \code{\link{eqvs_display}} — List all available
#'     value sets
#'   \item \code{\link{eqvs_add}} — Add a custom value set
#'   \item \code{\link{eqvs_drop}} — Remove a custom value set
#'   \item \code{\link{eqvs_load}} — Load a saved custom value
#'     set into the current session
#'   \item \code{\link{update_value_sets}} — Check for and
#'     install new value sets from the online repository
#' }
#'
#' @section Profile analysis:
#' Functions for analysing EQ-5D health state profiles,
#' including cross-sectional summaries, longitudinal change
#' analyses, and severity metrics:
#' \itemize{
#'   \item \code{\link{eq5d_profile_level_summary}} —
#'     Cross-sectional frequency summary by dimension
#'   \item \code{\link{eq5d_profile_level_summary_by_group}} —
#'     Stratified frequency summary by subgroup
#'   \item \code{\link{eq5d_profile_top_states}} —
#'     Most frequently observed health state profiles
#'   \item \code{\link{eq5d_profile_change_summary}} —
#'     Dimension-level frequencies at two time points
#'   \item \code{\link{eq5d_profile_dimension_change_table}} —
#'     Changes in levels per dimension as percentages of total
#'     and of type of change
#'   \item \code{\link{eq5d_profile_pchc_table}} —
#'     Paretian Classification of Health Change table
#'   \item \code{\link{eq5d_profile_pchc_with_no_problems_table}}
#'     — PCHC table with no-problems category
#'   \item \code{\link{eq5d_profile_pchc_by_group_plot}} —
#'     PCHC bar chart by subgroup
#'   \item \code{\link{eq5d_profile_better_dimensions_by_group_plot}}
#'     — Dimensions improved among Better patients
#'   \item \code{\link{eq5d_profile_worse_dimensions_by_group_plot}}
#'     — Dimensions worsened among Worse patients
#'   \item \code{\link{eq5d_profile_mixed_dimensions_by_group_plot}}
#'     — Dimensions changed among Mixed patients
#'   \item \code{\link{eq5d_profile_health_profile_grid}} —
#'     Health Profile Grid of individual transitions
#'   \item \code{\link{eq5d_profile_lss_utility_summary}} —
#'     Descriptive statistics by Level Sum Score
#'   \item \code{\link{eq5d_profile_lss_utility_plot}} —
#'     EQ-5D values plotted against LSS
#'   \item \code{\link{eq5d_profile_lfs_distribution}} —
#'     Level Frequency Score distribution table
#'   \item \code{\link{eq5d_profile_lfs_mean_utility}} —
#'     Mean EQ-5D values by LFS category
#'   \item \code{\link{eq5d_profile_lfs_utility_summary}} —
#'     Descriptive statistics by Level Frequency Score
#'   \item \code{\link{eq5d_profile_lfs_utility_plot}} —
#'     EQ-5D values plotted against LFS
#'   \item \code{\link{eq5d_profile_density_curve}} —
#'     Health State Density Curve
#' }
#'
#' @section EQ-5D value analysis:
#' Functions for analysing EQ-5D preference-based values
#' across time points, subgroups, and population norms:
#' \itemize{
#'   \item \code{\link{eq5d_utility_summary}} —
#'     Descriptive statistics at each time point
#'   \item \code{\link{eq5d_utility_summary_by_group}} —
#'     Descriptive statistics stratified by subgroup
#'   \item \code{\link{eq5d_utility_norms_comparison}} —
#'     Comparison with population norms by age and sex
#'   \item \code{\link{eq5d_utility_over_time_plot}} —
#'     Mean values with confidence intervals over time
#'   \item \code{\link{eq5d_utility_by_group_plot}} —
#'     Mean values with confidence intervals by subgroup
#'   \item \code{\link{eq5d_utility_change_by_group_plot}} —
#'     Longitudinal change by subgroup
#'   \item \code{\link{eq5d_utility_distribution_plot}} —
#'     Histogram of EQ-5D value distribution
#'   \item \code{\link{eq5d_utility_vas_scatter_plot}} —
#'     Scatter plot of EQ-5D values against EQ-VAS
#' }
#'
#' @section EQ-VAS analysis:
#' Functions for analysing EQ-VAS self-rated health scores:
#' \itemize{
#'   \item \code{\link{eq5d_vas_summary}} —
#'     Descriptive statistics at each time point
#'   \item \code{\link{eq5d_vas_distribution_table}} —
#'     Frequency distribution in pre-defined ranges
#'   \item \code{\link{eq5d_vas_histogram}} —
#'     Histogram of EQ-VAS scores
#'   \item \code{\link{eq5d_vas_grouped_distribution_plot}} —
#'     Bar chart of grouped EQ-VAS frequencies
#' }
#'
#' @section Helper functions:
#' Utility functions for preparing EQ-5D data:
#' \itemize{
#'   \item \code{\link{toEQ5Dindex}} — Combine dimension
#'     columns into a 5-digit profile code
#'   \item \code{\link{toEQ5Ddims}} — Split a 5-digit profile
#'     code into separate dimension columns
#'   \item \code{\link{make_all_EQ_indexes}} — Generate all
#'     valid EQ-5D state codes as a vector
#'   \item \code{\link{make_all_EQ_states}} — Generate all
#'     valid EQ-5D states as a data frame
#'   \item \code{\link{make_dummies}} — Create dummy variables
#'     from EQ-5D dimension columns
#' }
#'
#' @section Interactive application:
#' A Shiny application providing point-and-click access to
#' the same analytical workflow without requiring R coding:
#' \itemize{
#'   \item \code{\link{run_app}} — Launch the Shiny application
#' }
#'
#' @section Cross-platform suite:
#' eq5dsuite is part of a cross-platform suite also available
#' in Stata and Excel:
#' \itemize{
#'   \item Full suite:
#'     \url{https://github.com/MathsInHealth/eq5dsuite}
#'   \item R package:
#'     \url{https://github.com/MathsInHealth/eq5dsuite-r}
#'   \item Value sets repository:
#'     \url{https://github.com/MathsInHealth/eq5dsuite-value-sets}
#' }
#'
#' @references
#' Devlin N, Parkin D, Janssen B (2020).
#' \emph{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.
#' \emph{Value in Health}, 15(5), 708--715.
#' \doi{10.1016/j.jval.2012.02.008}
#'
#' @author
#' Anabel Estévez-Carrillo, Oliver Rivero-Arias,
#' Iryna Schlackow, Kim Rand
#'
#' Maintainer: Anabel Estévez-Carrillo
#' \email{aestevez@@mathsinhealth.com}
#'
#' @docType package
#' @name eq5dsuite-package
#' @aliases eq5dsuite
"_PACKAGE"