# Custom value sets

## Introduction

New EQ-5D value sets are published regularly. Rather than waiting for a package update, `eq5dsuite` allows you to add your own value sets using `eqvs_add()`. Custom value sets work with all scoring and analysis functions in the package.

## Adding a custom value set

A custom value set must be a data frame with two columns:

- `state` — the EQ-5D health state code (integer)
- A column named after the VS_code containing utility values

    # Generate all valid 3L health state codes
    states <- make_all_EQ_indexes(version = "3L")

    # Create a custom value set (random values for illustration)
    set.seed(42)
    custom_vs <- data.frame(
      state  = states,
      MY_VS  = runif(243, min = -0.5, max = 1.0)
    )

    head(custom_vs)
    #>   state      MY_VS
    #> 1 11111  0.8722091
    #> 2 11112  0.9056131
    #> 3 11113 -0.0707907
    #> 4 11121  0.7456714
    #> 5 11122  0.4626183
    #> 6 11123  0.2786439

    # Register for current session only (saveOption = 1)
    eqvs_add(
      custom_vs,
      version     = "3L",
      country     = "My Country",
      countryCode = "MC",
      VSCode      = "MY_VS",
      description = "Custom value set — demonstration",
      saveOption  = 1
    )

    # Verify it appears in the list
    eqvs_display(version = "3L")

    # Use it for value calculation
    eq5d3l(c(11111, 12321), country = "MY_VS")

## Saving a custom value set permanently

To persist a custom value set across R sessions, use `saveOption = 2`:

    eqvs_add(
      custom_vs,
      version     = "3L",
      country     = "My Country",
      countryCode = "MC",
      VSCode      = "MY_VS",
      description = "Custom value set — permanent",
      saveOption  = 2  # saves to user cache
    )

Load it in a new session with:

    eqvs_load(country = "MY_VS", version = "3L")

## Removing a custom value set

    eqvs_drop(
      country    = "MY_VS",
      version    = "3L",
      saveOption = 1  # remove from current session only
    )

## Validation

`eqvs_add()` validates the value set before registration:

- For 3L: checks all 243 health states are present
- For 5L: checks all 3125 health states are present
- Checks values are numeric with no duplicates

## Using custom value sets with crosswalk methods

Custom value sets are fully compatible with all crosswalk functions:

    # Use custom 3L value set with original crosswalk
    eqxw(
      eq5d5l_data,
      country   = "MY_VS",
      dim.names = c("mo", "sc", "ua", "pd", "ad")
    )

## Keeping value sets up to date

Use `update_value_sets()` to automatically check for and install newly published value sets from the eq5dsuite online repository:

    update_value_sets()

See `vignette("update-value-sets")` for full details.