Select Single Column Name

Safely extracts a single column name from a data frame using tidyselect syntax. Validates and ensures that exactly one column is selected. Useful for parameter validation in functions that require single-column inputs.

Usage

select_single_col_name(data, col, alt_null = FALSE)

Arguments

data

A data frame from which to select the column.

col

A column selection specified using:

• An unquoted column name (e.g., col_name)

• A quoted column name (e.g., "col_name")

• A numeric index (e.g., 1)

• A tidyselect helper (e.g., starts_with("prefix"))

alt_null

Logical. If TRUE, NULL is allowed and the function returns NA_character_ instead of throwing an error. This is useful for optional column arguments such as a weight column, where NULL can later be handled by using default weights of 1.

Value

A character string containing the name of the selected column. If alt_null = TRUE and col is NULL, returns NA_character_.

Details

The function will error in the following cases:

• The column selection is missing

• No columns are selected

• Multiple columns are selected

• The specified column doesn't exist

By default, passing NULL is treated as an invalid column specification and raises an error. Set alt_null = TRUE when NULL is an allowed input and should be translated to NA_character_ for easier downstream handling.

Examples

# This function is meant to be used inside other functions to validate column selection
# parameters. For example:

my_function <- function(data, id_col) {
  # Validates and extracts the column name
  id_col_name <- select_single_col_name(data, {{ id_col }})
  # Use the validated column name
  data[[id_col_name]]
}

df <- data.frame(id = 1:3, response = 4:6)

# The function can then be called with different column specifications:
my_function(df, id)              # Using unquoted name
#> [1] 1 2 3
my_function(df, "response")      # Using quoted name
#> [1] 4 5 6
my_function(df, starts_with("resp"))  # Using tidyselect helper
#> [1] 4 5 6

# Optional columns can be handled with alt_null = TRUE:
select_single_col_name(df, NULL, alt_null = TRUE)
#> [1] NA

weighted_values <- function(data, value_col, weight_col = NULL) {
  value_col_name <- select_single_col_name(data, {{ value_col }})
  weight_col_name <- select_single_col_name(data, {{ weight_col }}, alt_null = TRUE)

  if (is.na(weight_col_name)) {
    weights <- rep(1, nrow(data))
  } else {
    weights <- data[[weight_col_name]]
  }
  g6tr.ui::check_weight(weights)

  data[[value_col_name]] * weights
}

df2 <- data.frame(value = c(10, 20, 30), weight = c(0.5, 1, 2))
weighted_values(df2, value)
#> [1] 10 20 30
weighted_values(df2, value, weight)
#> [1]  5 20 60

# These will raise errors:
if (FALSE) { # \dontrun{
my_function(df, c(id, response))      # Error: selects multiple columns
my_function(df, nonexistent)          # Error: column doesn't exist
my_function(df, starts_with("xyz"))   # Error: no columns selected
my_function(df)                       # Error: parameter is missing
select_single_col_name(df, NULL)      # Error unless alt_null = TRUE
} # }