Skip to contents

Revalue Data

Source: R/RevalueData.R
RevalueData.Rd

Revalues variables in a dataset using a VarTypes codebook.

Usage

RevalueData(
  data,
  codebook,
  missingVal = -999,
  splitchar = ";",
  on_error = c("stop", "warn"),
  DatatoRevalue = lifecycle::deprecated(),
  VarTypes = lifecycle::deprecated()
)

Arguments

data

A data.frame or tibble to be revalued.

codebook

A data.frame with columns: Variable, Recode, Code, Type, Label, MissingCode. Only Variable is required. (Backward compatible: if MissingCode is absent/NA, will fall back to Missing.)

missingVal

Default value to treat as missing when VarTypes$MissingCode is absent or NA.

splitchar

Separator used in VarTypes$Code between pairs (default ";").

on_error

Whether to stop at the first variable-level error (the default) or continue and record errors in the returned object.

DatatoRevalue

Deprecated (since 19.15.0). Use data instead.

VarTypes

Deprecated (since 19.15.0). Use codebook instead.

Value

A list with: RevaluedData (data), warninglist (character), recodedvars (character), not_in_data (character), and errors (data frame with Variable and Error columns). In the default on_error = "stop" mode, an error names the offending variable and preserves the underlying message.

What changes

In the raw extract sex is a bare 0/1 column and nothing carries a label. Afterwards it is a factor with real levels, and the labels are attached for every downstream table and plot to pick up automatically - which is what makes output readable without renaming anything by hand.

Anything the codebook could not act on is reported in warninglist rather than silently skipped, so a mistyped variable name or an unparseable Code string is visible instead of quietly leaving a variable unrecoded.

Examples

data(SampleData)
data(SampleVariableTypes)

# Before: no labels, and sex is stored as 0/1
sjlabelled::get_label(SampleData$age)   # NULL
#> NULL
class(SampleData$sex)                    # "integer"
#> [1] "integer"

# Revalue using the codebook
revalued <- RevalueData(SampleData, SampleVariableTypes)
Labelled <- revalued$RevaluedData

# After: labels attached, sex is a labelled factor
sjlabelled::get_label(Labelled$age)     # "Age"
#> [1] "Age"
levels(Labelled$sex)                     # "Female" "Male"
#> [1] "Female" "Male"  

# Recoded variables, and codebook entries not found in the data
revalued$recodedvars
#> [1] "sex"
revalued$not_in_data
#> [1] "Group"   "Race"    "Marital" "Height"  "Income"  "Smokes"  "Smoker" 

# \donttest{
# A side-by-side view of what changed
vars_Show <- c("Diagnosis", "age", "sex", "Genotype", "AXL")

df_Before <- utils::head(SampleData[, vars_Show], 6)
df_After <- utils::head(Labelled[, vars_Show], 6)

ShowTable <- function(x, caption) {
  htmltools::browsable(htmltools::HTML(as.character(
    kableExtra::kable_styling(
      knitr::kable(x, format = "html", caption = caption, row.names = FALSE),
      bootstrap_options = c("striped", "hover", "condensed"),
      full_width = FALSE
    )
  )))
}

ShowTable(df_Before, "Before: raw codes as imported")

Before: raw codes as imported
 
 Diagnosis 
    age 
    sex 
    Genotype 
    AXL 
  
 Control 
    52 
    0 
    E3E3 
    1.0983867 
  
 Control 
    61 
    0 
    E3E4 
    0.6832816 
  
 Control 
    77 
    1 
    E3E4 
    -0.1452763 
  
 Control 
    97 
    0 
    E3E4 
    0.6832816 
  
 Control 
    73 
    0 
    E3E3 
    0.1908902 
  
 Impaired 
    87 
    1 
    E4E4 
    -0.2223611 
  
ShowTable(df_After, "After: recoded and labelled")

After: recoded and labelled
 
 Diagnosis 
    age 
    sex 
    Genotype 
    AXL 
  
 Control 
    52 
    Female 
    E3E3 
    1.0983867 
  
 Control 
    61 
    Female 
    E3E4 
    0.6832816 
  
 Control 
    77 
    Male 
    E3E4 
    -0.1452763 
  
 Control 
    97 
    Female 
    E3E4 
    0.6832816 
  
 Control 
    73 
    Female 
    E3E3 
    0.1908902 
  
 Impaired 
    87 
    Male 
    E4E4 
    -0.2223611 
  

# The labels the codebook attached
df_Labels <- data.frame(
  Variable = vars_Show,
  Label = vapply(
    vars_Show,
    function(v) {
      lab <- sjlabelled::get_label(Labelled[[v]])
      if (is.null(lab) || is.na(lab)) v else lab
    },
    character(1)
  ),
  Class = vapply(vars_Show, function(v) class(Labelled[[v]])[1], character(1)),
  Levels = vapply(
    vars_Show,
    function(v) {
      lv <- levels(Labelled[[v]])
      if (is.null(lv)) "" else paste(lv, collapse = ", ")
    },
    character(1)
  ),
  row.names = NULL
)

htmltools::browsable(htmltools::HTML(as.character(
  FreezeTableHeader(df_Labels, full_width = TRUE)
)))

 Variable 
    Label 
    Class 
    Levels 
  
 Diagnosis 
    Diagnosis 
    factor 
    Control, Impaired 
  
 age 
    Age 
    numeric 
     
  
 sex 
    Sex 
    factor 
    Female, Male 
  
 Genotype 
    Genotype 
    factor 
    E2E2, E2E3, E2E4, E3E3, E3E4, E4E4 
  
 AXL 
    AXL receptor tyrosine kinase 
    numeric 
     
  

# Anything the codebook could not act on
revalued$warninglist
#> [1] "Variables listed in VarTypes but not found in data (ignored): Group, Race, Marital, Height, Income, Smokes, Smoker"
# }