Skip to contents

Create a Mapping Table for Binary Variables

Source: R/createBinaryMapping.R
createBinaryMapping.Rd

Identifies binary variables and returns a deterministic mapping for 0/1 coding.

  • Factors with explicit order (ordered = TRUE) do NOT use heuristics; the highest (last) level is Positive.

  • Logicals map to Negative = "FALSE", Positive = "TRUE".

  • Numeric 0/1 (or any 2-value numeric) maps Positive to the numeric maximum.

  • Characters / unordered factors use minimal heuristics (no race/PWH/sex terms).

Usage

createBinaryMapping(
  data,
  CatVars,
  prefer = NULL,
  Data = lifecycle::deprecated()
)

Arguments

data

A dataframe.

CatVars

Character vector of candidate binary variables.

prefer

Optional named character vector of explicit positive levels, e.g., c(STATUS = "PWH", Smoker = "Yes"). This overrides other rules.

Data

Deprecated (since 19.15.0). Use data instead.

Value

A data.frame with columns: Variable, Label, PositiveLevel, NegativeLevel.

Details

Modelling a two-level variable means scoring one level against the other, and which level counts as "positive" decides the sign of every coefficient and odds ratio that follows. This resolves that choice once, explicitly, and returns it as a table so it can be checked rather than assumed.

The rules are applied in order: an explicit prefer entry always wins; an ordered factor uses its highest level; otherwise a short list of conventional affirmative labels ("Yes", "Present", "Case", and similar) is consulted, then the larger of two numbers, and finally the second level in sorted order. The heuristics deliberately exclude race, sex, and serostatus terms, because there is no defensible default "positive" level for those - name them through prefer.

See also

getBinaryVars() to find the candidates.

Examples

# \donttest{
data(SampleData)
data(SampleVariableTypes)

Labelled <- RevalueData(SampleData, SampleVariableTypes)$RevaluedData
vars_Binary <- getBinaryVars(Labelled)

# One row per variable, naming the level scored as positive
mapping <- createBinaryMapping(Labelled, vars_Binary)

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

 Variable 
    Label 
    PositiveLevel 
    NegativeLevel 
  
 Diagnosis 
    Diagnosis 
    Impaired 
    Control 
  
 sex 
    Sex 
    Male 
    Female 
  

# `prefer` overrides the choice, which is how to set a direction the
# heuristics will not guess at - `sex` is exactly that case.
createBinaryMapping(
  Labelled, vars_Binary,
  prefer = c(Diagnosis = "Control", sex = "Female")
)
#>    Variable     Label PositiveLevel NegativeLevel
#> 1 Diagnosis Diagnosis       Control      Impaired
#> 2       sex       Sex        Female          Male

# The rules on constructed variables: an ordered factor takes its highest
# level, a logical takes TRUE, a 0/1 numeric takes the larger number, and a
# conventional affirmative label is recognised.
df_Rules <- data.frame(
  Severity = factor(c("Mild", "Severe"), levels = c("Mild", "Severe"),
                    ordered = TRUE),
  Responded = c(TRUE, FALSE),
  Coded01 = c(0, 1),
  Smoker = c("Yes", "No")
)

createBinaryMapping(
  df_Rules, c("Severity", "Responded", "Coded01", "Smoker")
)
#>    Variable     Label PositiveLevel NegativeLevel
#> 1  Severity  Severity        Severe          Mild
#> 2 Responded Responded          TRUE         FALSE
#> 3   Coded01   Coded01             1             0
#> 4    Smoker    Smoker           Yes            No
# }