In ready4-dev/scorz: Score Multi-Attribute Utility Instruments

Note: This vignette is illustrated with fake data. The dataset explored in this example should not be used to inform decision-making. Some of the methods illustrated in this EQ-5D vignette are described in more detail in a vignette about scoring AQoL-6D health utility. Furthermore, the synthetic data and model types used in this data have not been optimised for the purposes of this example (the models created below perform poorly as a result).

library(ready4)
library(scorz)

EQ-5D scoring

The eq5d package provides a toolkit for scoring EQ-5D health utility. The scorz package contains ready4 framework modules that integrate eq5d package tools with the readyforwhatsnext youth mental health economic model.

Ingest and describe data

To begin, we ingest an unscored dataset and its data dictionary as a Ready4useDyad. We then add additional details about the dataset (unique identifier and data-collection round variable name and values) by converting the ingested data to an instance of the (YouthvarsSeries module)[https://www.ready4-dev.com/docs/model/modules/using-modules/people/add-metadata/].

X <- ready4use::Ready4useRepos(dv_nm_1L_chr = "fakes",
                               dv_ds_nm_1L_chr = "https://doi.org/10.7910/DVN/W95KED",
                               dv_server_1L_chr = "dataverse.harvard.edu") %>%
  ingest(fls_to_ingest_chr = "ymh_eq5d_dyad_r4",
         metadata_1L_lgl = F) 
X <- youthvars::YouthvarsSeries(a_Ready4useDyad = X,
                                id_var_nm_1L_chr = "uid",
                                timepoint_var_nm_1L_chr = "Timepoint",
                                timepoint_vals_chr = unique(X@ds_tb$Timepoint))

We now use the data and meta-data we have created in the previous steps to create an instance of the ScorzEuroQol5 class. Important arguments to specify when creating a ScorzEuroQol5 instance are country_1L_chr (the country preference weights to use), instrument_version_1L_chr (instrument version) and the itm_var_nms_chr (item variable names - these must be in the exact order that corresponds to the Movement, Self-care, Usual Activities, Pain/Discomfort and Anxiety Depression domains).

Y <- ScorzEuroQol5(a_YouthvarsProfile = X,
                   country_1L_chr = "UK",
                   instrument_version_1L_chr = "5L",
                   itm_var_nms_chr = c("eq5dq_MO", "eq5dq_SC", "eq5dq_UA", "eq5dq_PD", "eq5dq_AD"))

Calculating scores

To calculate EQ-5D adolescent utility scores, use the renew method.

Y <- renew(Y)

Viewing the updated dataset

We can inspect our updated dataset using the exhibit method.

exhibit(Y,
        display_1L_chr = "head",
         scroll_box_args_ls = list(width = "100%"))

Creating summary plots

To create plots, we use the depict method, supplying the index number of the dimension we wish to plot.

depict(Y, type_1L_chr = "domain_by_time", var_idcs_int = 5L)

Total EQ-5D scores can also be plotted using the same approach, where var_idcs_int = 1L is used to plot the weighted total distribution.

depict(Y, type_1L_chr = "total_by_time", var_idcs_int = 1L)

A composite plot can also be generated.

depict(Y, type_1L_chr = "comp_domain_by_time")

Share output

We can now publicly share our scored dataset and its associated metadata, using Ready4useRepos and its share method as described in a vignette from the ready4use package.

Z <- ready4use::Ready4useRepos(gh_repo_1L_chr = "ready4-dev/scorz", # Replace with details of your repo.
                               gh_tag_1L_chr = "Documentation_0.0") # You must have write permissions.
Z <- share(Z,
           obj_to_share_xx = Y,
           fl_nm_1L_chr = "ymh_ScorzEuroQol5")