fix factor to integer bug (#543)

**What changes are proposed in this pull request?**

Fixed bug in `rename_ard_columns()` whereby factor variables were
getting converted to integers and added param `fct_as_chr` as is used in
`unlist_ard_columns()` (#542 , @alanahjonas95 )

Provide more detail here as needed.

**Reference GitHub issue associated with pull request.** _e.g., 'closes
#<issue number>'_

closes #542 


--------------------------------------------------------------------------------

Pre-review Checklist (if item does not apply, mark is as complete)
- [x] **All** GitHub Action workflows pass with a ✅
- [x] PR branch has pulled the most recent updates from master branch:
`usethis::pr_merge_main()`
- [x] If a bug was fixed, a unit test was added.
- [x] Code coverage is suitable for any new functions/features
(generally, 100% coverage for new code): `devtools::test_coverage()`
- [x] Request a reviewer

Reviewer Checklist (if item does not apply, mark is as complete)

- [ ] If a bug was fixed, a unit test was added.
- [ ] Run `pkgdown::build_site()`. Check the R console for errors, and
review the rendered website.
- [ ] Code coverage is suitable for any new functions/features:
`devtools::test_coverage()`

When the branch is ready to be merged:
- [ ] Update `NEWS.md` with the changes from this pull request under the
heading "`# cards (development version)`". If there is an issue
associated with the pull request, reference it in parentheses at the end
update (see `NEWS.md` for examples).
- [ ] **All** GitHub Action workflows pass with a ✅
- [ ] Approve Pull Request
- [ ] Merge the PR. Please use "Squash and merge" or "Rebase and merge".

_Optional Reverse Dependency Checks_:

Install `checked` with `pak::pak("Genentech/checked")` or
`pak::pak("checked")`

```shell
# Check dev versions of `cardx`, `gtsummary`, and `tfrmt` which are in the `ddsjoberg` R Universe
Rscript -e "options(checked.check_envvars = c(NOT_CRAN = TRUE)); checked::check_rev_deps(path = '.', n = parallel::detectCores() - 2L, repos = c('https://ddsjoberg.r-universe.dev', 'https://cloud.r-project.org'))"

# Check CRAN reverse dependencies but run tests skipped on CRAN
Rscript -e "options(checked.check_envvars = c(NOT_CRAN = TRUE)); checked::check_rev_deps(path = '.', n = parallel::detectCores() - 2, repos = 'https://cloud.r-project.org')"

# Check CRAN reverse dependencies in a CRAN-like environment
Rscript -e "options(checked.check_envvars = c(NOT_CRAN = FALSE), checked.check_build_args = '--as-cran'); checked::check_rev_deps(path = '.', n = parallel::detectCores() - 2, repos = 'https://cloud.r-project.org')"
```

---------

Co-authored-by: Becca Krouse <14199771+bzkrouse@users.noreply.github.com>

Author: alanahjonas95

NEWS.md

@@ -1,3 +1,7 @@
+# cards (development version)
+
+* Fixed bug in `rename_ard_columns()` whereby factor variables were getting converted to integers and added parameter `fct_as_chr` as is used in `unlist_ard_columns()` (#542)
+
 # cards 0.7.1.9007
 
 * Adding `ard_tabulate_rows()` function to tabulate the number of rows in a data frame. (#531)

R/rename_ard_columns.R

@@ -16,6 +16,11 @@
 #'   where the `colname` element is available to inject into the string,
 #'   e.g. `'Overall {colname}'` may resolve to `'Overall AGE'` for an AGE column.
 #'   Default is `'{colname}'`.
+#' @param fct_as_chr (scalar `logical`)\cr
+#'   When `TRUE`, factor elements will be converted to character before unlisting.
+#'   When the column being unlisted contains mixed types of classes, the
+#'   factor elements are often converted to the underlying integer value instead
+#'   of retaining the label. Default is `TRUE`.
 #' @param unlist `r lifecycle::badge("deprecated")`
 #'
 #' @return data frame
@@ -37,7 +42,9 @@
 #'   unlist_ard_columns()
 rename_ard_columns <- function(x,
                                columns = c(all_ard_groups("names"), all_ard_variables("names")),
-                               fill = "{colname}", unlist = NULL) {
+                               fill = "{colname}",
+                               fct_as_chr = TRUE,
+                               unlist = NULL) {
   # check inputs ---------------------------------------------------------------
   if (!missing(unlist)) {
     lifecycle::deprecate_warn(
@@ -52,6 +59,8 @@ rename_ard_columns <- function(x,
   check_class(x, "card")
   process_selectors(x, columns = {{ columns }})
   check_scalar(fill)
+  check_scalar_logical(fct_as_chr)
+
   if (!is_empty(setdiff(columns, dplyr::select(x, all_ard_groups("names"), all_ard_variables("names")) |> names()))) {
     bad_columns <-
       setdiff(columns, dplyr::select(x, all_ard_groups("names"), all_ard_variables("names")) |> names())
@@ -125,6 +134,13 @@ rename_ard_columns <- function(x,
     dplyr::select(-"...ard_row_order...") |>
     dplyr::mutate(
       # replace NULL values with NA, then unlist
-      across(all_of(all_new_names), ~ map(., \(value) value %||% NA) |> unlist())
+      across(
+        all_of(all_new_names),
+        ~ map(., \(value){
+          if (isTRUE(fct_as_chr) && inherits(value, "factor")) value <- as.character(value)
+          value %||% NA
+        }) |>
+          unlist()
+      )
     )
 }

man/rename_ard_columns.Rd

@@ -53,3 +53,36 @@ test_that("rename_ard_columns(unlist) lifecycle", {
       rename_ard_columns(unlist = "stat")
   )
 })
+
+
+test_that("rename_ard_columns(fct_as_chr)", {
+  adsl_ <- ADSL |>
+    dplyr::mutate(
+      RACE = factor(RACE)
+    )
+
+  # check fct_to_chr = TRUE
+  res <- ard_tabulate(
+    data = adsl_,
+    by = TRT01A,
+    variables = c(RACE, ETHNIC)
+  ) |>
+    rename_ard_columns()
+
+  # Check that 'race' is a character vector
+  expect_type(res$RACE, "character")
+
+  # Check that it contains the actual level string, not an integer "1", "2", etc.
+  expect_true("WHITE" %in% res$RACE)
+
+  # check fct_to_chr = FALSE
+  res <- ard_tabulate(
+    data = adsl_,
+    by = TRT01A,
+    variables = c(RACE, ETHNIC)
+  ) |>
+    rename_ard_columns(fct_as_chr = FALSE)
+
+  # Check that 'race' is an interger vector
+  expect_type(res$RACE, "integer")
+})