Unclear warnings and errors generated when setting levels for a factor generated from a character vector

[wtimmerman-fitp]

When I use fct_relevel with the levels argument, I receive a warning that does not clearly indicate what is going wrong. Similarly, when I use the levels argument in forcats::as_factor()'s, (on the assumptions that arguments in .../ellipsis will be passed on to methods), I receive an error "Arguments in ... must be used". Both of these are unexpected results for me based on my understanding of the function help text and base::factor().

For background, my intention is to convert a character column into a factor column using a pre-specified list of levels (the pre-specified list is somewhat important as a check and consistency for reasons that I won't get into here). I have reviewed the forcats issues and don't see an exact match for this problem:

• Using base:factor(), I can pass the vector of levels to the levels argument; this is fine, but it is not noisy enough if the levels provided do not match the character column I am mutating into a factor.
• Using forcats::as_factor(), when I pass the levels argument I receive the error "Arguments in ... must be used." I am not clear if I am misusing the function.
• Using forcats::fct_relevel(), I receive the warning "Outer names are only allowed for unnamed scalar atomic inputs". This comes from vctrs, and I also see it referenced in the fct_relevel() help, but it doesn't seem to apply in the reprex I've generated below.

My questions are:

• Should these forcats() functions be generating different/more-specific warnings?
• Should these forcats() functions behave differently when passed the levels argument?
• Should I be using these functions differently (or a different function altogether) given my use case?

Reprex

library(tidyverse)

mtcars2 <-
  mtcars %>% 
  tibble::rownames_to_column(var = "make_model") %>% 
  dplyr::filter(
    dplyr::row_number() <= 5
  )

use_levels <-
  mtcars2 %>% 
  dplyr::pull(make_model) 

# this works as expected, since the provided levels will by definition match the values in the make_model column.
mtcars2_factor <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = base::factor(
      make_model,
      levels = use_levels
    )
  )

# I don't understand why this is an error based on the as_factor() help.
mtcars2_as_factor <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = forcats::as_factor(
      make_model,
      levels = use_levels
    )
  )
#> Error in `dplyr::mutate()`:
#> ! Problem while computing `make_model = forcats::as_factor(make_model,
#>   levels = use_levels)`.
#> Caused by error:
#> ! Arguments in `...` must be used.
#> x Problematic argument:
#> * levels = use_levels

# I don't understand why this generates this warning since use_levels does not have names
mtcars2_fct_relevel <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = forcats::fct_relevel(
      make_model,
      levels = use_levels
    )
  )
#> Warning: Outer names are only allowed for unnamed scalar atomic inputs

# when i modify use_levels to have a value not present in the column, more challenges arise.
use_levels_mod <-
  c(use_levels, "Other Car")

# base::factor is not noisy enough that there are factor levels not present in the data.
mtcars2_mod_factor <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = base::factor(
      make_model,
      levels = use_levels_mod
    )
  )

# as_factor continus to error
mtcars2_mod_as_factor <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = forcats::as_factor(
      make_model,
      levels = use_levels_mod
    )
  )
#> Error in `dplyr::mutate()`:
#> ! Problem while computing `make_model = forcats::as_factor(make_model,
#>   levels = use_levels_mod)`.
#> Caused by error:
#> ! Arguments in `...` must be used.
#> x Problematic argument:
#> * levels = use_levels_mod

# fct_relevel generates an expected warning, but still has the 
# original warning that makes little sense in this case.

mtcars2_mod_fct_relevel <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = forcats::fct_relevel(
      make_model,
      levels = use_levels_mod
    )
  )
#> Warning: Outer names are only allowed for unnamed scalar atomic inputs
#> Warning: Unknown levels in `f`: Other Car

^{Created on 2022-08-09 by the reprex package (v2.0.1)}

Session info

``` r sessionInfo() #> R version 4.0.5 (2021-03-31) #> Platform: x86_64-w64-mingw32/x64 (64-bit) #> Running under: Windows 10 x64 (build 19043) #> #> Matrix products: default #> #> locale: #> [1] LC_COLLATE=English_United States.1252 #> [2] LC_CTYPE=English_United States.1252 #> [3] LC_MONETARY=English_United States.1252 #> [4] LC_NUMERIC=C #> [5] LC_TIME=English_United States.1252 #> #> attached base packages: #> [1] stats graphics grDevices utils datasets methods base #> #> other attached packages: #> [1] forcats_0.5.1 stringr_1.4.0 dplyr_1.0.9 purrr_0.3.4 #> [5] readr_2.1.2 tidyr_1.2.0 tibble_3.1.8 ggplot2_3.3.6 #> [9] tidyverse_1.3.2 #> #> loaded via a namespace (and not attached): #> [1] tidyselect_1.1.2 xfun_0.31 haven_2.5.0 #> [4] gargle_1.2.0 colorspace_2.0-3 vctrs_0.4.1 #> [7] generics_0.1.3 htmltools_0.5.3 yaml_2.3.5 #> [10] utf8_1.2.2 rlang_1.0.4 pillar_1.8.0 #> [13] glue_1.6.2 withr_2.5.0 DBI_1.1.3 #> [16] dbplyr_2.2.1 readxl_1.4.0 modelr_0.1.8 #> [19] lifecycle_1.0.1 munsell_0.5.0 gtable_0.3.0 #> [22] cellranger_1.1.0 rvest_1.0.2 evaluate_0.15 #> [25] knitr_1.39 tzdb_0.3.0 fastmap_1.1.0 #> [28] fansi_1.0.3 highr_0.9 broom_1.0.0 #> [31] backports_1.4.1 scales_1.2.0 googlesheets4_1.0.0 #> [34] jsonlite_1.8.0 fs_1.5.2 hms_1.1.1 #> [37] digest_0.6.29 stringi_1.7.8 grid_4.0.5 #> [40] cli_3.3.0 tools_4.0.5 magrittr_2.0.3 #> [43] crayon_1.5.1 pkgconfig_2.0.3 ellipsis_0.3.2 #> [46] xml2_1.3.3 reprex_2.0.1 googledrive_2.0.0 #> [49] lubridate_1.8.0 assertthat_0.2.1 rmarkdown_2.14 #> [52] httr_1.4.3 rstudioapi_0.13 R6_2.5.1 #> [55] compiler_4.0.5 ```

[jennybc]

Based on a quick read, I think you might be interested in fct()? More in #299.

[wtimmerman-fitp]

Oh, this is perfect! Thank you for the pointer! I think this will solve my issue. level named argument is there, no errors or warnings if an additional level is listed but not in data, errors (unlike base::factor) if one of the supplied levels is not in the data.

I'll close the issue and look forward to fct() getting into a future release.

(example below if anyone curious).

#setup ----
library(tidyverse)

fct <- function(x = character(), levels = NULL, na = character()) {
  if (!is.character(x)) {
    cli::cli_abort("{.arg x} must be a character vector")
  }
  if (!is.character(na)) {
    cli::cli_abort("{.arg na} must be a character vector")
  }

  x[x %in% na] <- NA

  if (is.null(levels)) {
    levels <- unique(x)
  } else if (!is.character(levels)) {
    abort("`{.arg levels} must be a character vector")
  }

  invalid <- setdiff(x, c(levels, NA))

  if (length(invalid) > 0 ) {
    cli::cli_abort(c(
      "Values of {.arg x} must be members of {.arg levels}", 
      i = "Invalid value{?s}: {.str {invalid}}"
    ))
  }
  factor(x, levels = levels, exclude = NULL)
}

mtcars2 <-
  mtcars %>% 
  tibble::rownames_to_column(var = "make_model") %>% 
  dplyr::filter(
    dplyr::row_number() <= 5
  )

# Match levels----
match_levels <-
  mtcars2 %>% 
  dplyr::pull(make_model) 

mtcars2_factor <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = base::factor(
      make_model,
      levels = match_levels
    )
  )

mtcars2_fct <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = fct(
      make_model,
      levels = match_levels
    )
  )

# Add Levels ----
add_levels <-
  c(match_levels, "Other Car")

mtcars2_add_factor <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = base::factor(
      make_model,
      levels = add_levels
    )
  )

mtcars2_add_fct <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = fct(
      make_model,
      levels = add_levels
    )
  )

levels(mtcars2_add_fct$make_model)
#> [1] "Mazda RX4"         "Mazda RX4 Wag"     "Datsun 710"       
#> [4] "Hornet 4 Drive"    "Hornet Sportabout" "Other Car"

# Miss Levels ----
miss_levels <-
  match_levels[-1]

mtcars2_miss_factor <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = base::factor(
      make_model,
      levels = miss_levels
    )
  )

mtcars2_miss_fct <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = fct(
      make_model,
      levels = miss_levels
    )
  )
#> Error in `dplyr::mutate()`:
#> ! Problem while computing `make_model = fct(make_model, levels =
#>   miss_levels)`.
#> Caused by error in `fct()`:
#> ! Values of `x` must be members of `levels`
#> i Invalid value: "Mazda RX4"

^{Created on 2022-08-09 by the reprex package (v2.0.1)}

[wtimmerman-fitp]

Also, if anyone runs into the same warning I got with fct_relevel (Warning: Outer names are only allowed for unnamed scalar atomic inputs), it's because you can't use the levels argument for that function; just pass the vector object of level names (in this case, use_levels) into the ellipsis on its own like:

mtcars2_fct_relevel <-
  mtcars2 %>% 
  dplyr::mutate(
    make_model = forcats::fct_relevel(
      make_model,
      use_levels
    )
  )