Refine REDCap metadata handling and package documentation

.Rbuildignore

@@ -40,3 +40,4 @@ inst/testdata/create_test_data.R
 ^CRAN-SUBMISSION$
 ^updating-mocks\.md$
 ^vignettes/articles$
+^air\.toml$

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Create a report to help us improve the `REDCapExploreR` package!
+title: "[BUG]"
+labels: bug
+assignees: ''
+
+---
+
+# Expected Behavior
+A clear and concise description of what you expected to happen.
+
+# Current Behavior
+A clear and concise description of the bug.
+
+## How to Reproduce the Bug:
+Numbered steps to reproduce the bug behavior.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+## Failure Logs
+
+If applicable, submit any failure logs or error messages here.
+
+### Checklist
+Before submitting this issue, please check and verify below that the submission meets the below criteria:
+
+- [ ] The issue is atomic
+- [ ] The issue description is documented
+- [ ] The issue title describes the problem succinctly
+- [ ] Developers are assigned to the issue
+- [ ] Labels are assigned to the issue

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,28 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[FEATURE]"
+labels: enhancement
+assignees: ''
+
+---
+
+# Feature Request Description
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]; It would be great to have [...], etc.
+
+# Proposed Solution
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+## Additional Context
+Add any other context or screenshots about the feature request here.
+
+### Checklist
+
+- [ ] The issue is atomic
+- [ ] The issue description is documented
+- [ ] The issue title describes the problem succinctly
+- [ ] Developers are assigned to the issue
+- [ ] Labels are assigned to the issue

.github/pull_request_template.md

@@ -0,0 +1,40 @@
+# Description
+Provide a description of the PR
+
+# Proposed Changes 
+List changes below in bullet format:
+
+- Change 1
+- Change 2
+- Change 3
+
+**Screenshots**
+If applicable, add screenshots to help explain the proposed changes
+
+### Issue Addressed
+**Closes #[provide issue number to link here]**
+
+### PR Checklist
+Before submitting this PR, please check and verify below that the submission meets the below criteria:
+
+- [ ] New/revised functions have associated tests
+- [ ] New/revised functions that update downstream outputs have associated static testing files (`.RDS`) updated under `inst/testdata/create_test_data.R`
+- [ ] New/revised functions use appropriate naming conventions
+- [ ] New/revised functions don't repeat code
+- [ ] Code changes are less than **250** lines total
+- [ ] Issues linked to the PR using [GitHub's list of keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
+- [ ] The appropriate reviewer is assigned to the PR
+- [ ] The appropriate developers are assigned to the PR
+- [ ] Pre-release package version incremented using `usethis::use_version()`
+
+# Code Review
+This section to be used by the reviewer and developers during Code Review after PR submission
+
+### Code Review Checklist
+
+- [ ] I checked that new files follow naming conventions and are in the right place
+- [ ] I checked that documentation is complete, clear, and without typos
+- [ ] I added/edited comments to explain "why" not "how"
+- [ ] I checked that all new variable and function names follow naming conventions
+- [ ] I checked that new tests have been written for key business logic and/or bugs that this PR fixes
+- [ ] I checked that new tests address important edge cases

.github/workflows/pkgdown.yaml

@@ -46,6 +46,6 @@ jobs:
         if: github.event_name != 'pull_request'
         uses: JamesIves/github-pages-deploy-action@4.1.4
         with:
-          clean: false
+          clean: true
           branch: gh-pages
-          folder: docs
+          folder: docs

.lintr

@@ -0,0 +1,13 @@
+linters: linters_with_defaults(
+    line_length_linter = line_length_linter(140),
+    object_length_linter = object_length_linter(45),
+    object_name_linter = NULL,
+    object_usage_linter = NULL,
+    indentation_linter = NULL,
+    commented_code_linter = NULL,
+    commas_linter = NULL,
+    pipe_consistency_linter = pipe_consistency_linter("auto")
+  )
+exclusions: list(
+    "tests/testthat/fixtures"
+  )

DESCRIPTION

@@ -19,7 +19,7 @@ LazyData: true
 Imports: 
     cli,
     DT,
-    dplyr,
+    dplyr (>= 1.1.0),
     ggplot2,
     htmltools,
     purrr,
@@ -28,12 +28,12 @@ Imports:
     stats,
     stringr,
     tibble,
-    tidyr,
     tidyselect
 Suggests: 
     knitr,
     rmarkdown,
-    testthat (>= 3.0.0)
+    testthat (>= 3.0.0),
+    tidyr
 Config/testthat/edition: 3
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.3

NAMESPACE

@@ -4,7 +4,7 @@ S3method(print,redcap_codebook)
 S3method(print,redcap_quality_report)
 export(build_codebook)
 export(build_quality_report)
-export(get_record_status_data)
+export(build_record_status_data)
 export(plot_record_status)
 export(pull_redcap_project)
 export(view_codebook)
@@ -17,45 +17,35 @@ importFrom(REDCapR,redcap_instruments)
 importFrom(REDCapR,redcap_metadata_read)
 importFrom(REDCapR,redcap_project_info_read)
 importFrom(REDCapR,redcap_read_oneshot)
-importFrom(REDCapR,sanitize_token)
 importFrom(cli,cli_abort)
-importFrom(cli,cli_fmt)
 importFrom(cli,cli_progress_bar)
 importFrom(cli,cli_progress_done)
 importFrom(cli,cli_progress_update)
-importFrom(cli,cli_text)
-importFrom(cli,cli_vec)
 importFrom(cli,cli_warn)
-importFrom(cli,qty)
 importFrom(cli,symbol)
 importFrom(dplyr,across)
 importFrom(dplyr,arrange)
-importFrom(dplyr,bind_cols)
 importFrom(dplyr,bind_rows)
 importFrom(dplyr,case_when)
 importFrom(dplyr,count)
+importFrom(dplyr,cross_join)
 importFrom(dplyr,distinct)
 importFrom(dplyr,filter)
-importFrom(dplyr,first)
 importFrom(dplyr,group_by)
-importFrom(dplyr,if_any)
 importFrom(dplyr,if_else)
 importFrom(dplyr,left_join)
 importFrom(dplyr,mutate)
 importFrom(dplyr,n)
 importFrom(dplyr,n_distinct)
 importFrom(dplyr,pull)
-importFrom(dplyr,recode)
 importFrom(dplyr,relocate)
 importFrom(dplyr,rename)
 importFrom(dplyr,right_join)
 importFrom(dplyr,row_number)
-importFrom(dplyr,rowwise)
 importFrom(dplyr,select)
 importFrom(dplyr,slice)
 importFrom(dplyr,summarise)
 importFrom(dplyr,transmute)
-importFrom(dplyr,ungroup)
 importFrom(ggplot2,aes)
 importFrom(ggplot2,element_blank)
 importFrom(ggplot2,element_text)
@@ -67,71 +57,27 @@ importFrom(ggplot2,scale_x_discrete)
 importFrom(ggplot2,scale_y_discrete)
 importFrom(ggplot2,theme)
 importFrom(ggplot2,theme_minimal)
-importFrom(htmltools,HTML)
 importFrom(htmltools,browsable)
-importFrom(htmltools,save_html)
+importFrom(htmltools,htmlDependency)
 importFrom(htmltools,tagList)
 importFrom(htmltools,tags)
 importFrom(purrr,flatten_chr)
 importFrom(purrr,map)
-importFrom(purrr,map2)
-importFrom(purrr,map2_chr)
 importFrom(purrr,map_chr)
-importFrom(purrr,map_int)
 importFrom(purrr,map_lgl)
-importFrom(purrr,pluck)
-importFrom(purrr,pmap)
-importFrom(purrr,pmap_chr)
-importFrom(purrr,reduce)
 importFrom(rlang,"!!!")
 importFrom(rlang,":=")
 importFrom(rlang,.data)
 importFrom(rlang,.env)
-importFrom(rlang,abort)
-importFrom(rlang,as_closure)
-importFrom(rlang,as_label)
-importFrom(rlang,caller_arg)
-importFrom(rlang,caller_env)
-importFrom(rlang,catch_cnd)
-importFrom(rlang,check_installed)
-importFrom(rlang,cnd_muffle)
-importFrom(rlang,current_call)
-importFrom(rlang,current_env)
-importFrom(rlang,enexpr)
-importFrom(rlang,enquo)
-importFrom(rlang,env_poke)
-importFrom(rlang,eval_tidy)
-importFrom(rlang,expr)
-importFrom(rlang,get_env)
-importFrom(rlang,global_env)
-importFrom(rlang,is_atomic)
-importFrom(rlang,is_bare_formula)
-importFrom(rlang,is_bare_list)
-importFrom(rlang,is_installed)
-importFrom(rlang,new_environment)
-importFrom(rlang,quo_get_expr)
-importFrom(rlang,quo_name)
-importFrom(rlang,sym)
-importFrom(rlang,syms)
-importFrom(rlang,try_fetch)
-importFrom(rlang,zap)
 importFrom(stats,IQR)
 importFrom(stats,quantile)
 importFrom(stats,setNames)
 importFrom(stringr,str_detect)
-importFrom(stringr,str_ends)
-importFrom(stringr,str_replace)
-importFrom(stringr,str_replace_all)
 importFrom(stringr,str_squish)
 importFrom(stringr,str_trim)
 importFrom(stringr,str_trunc)
 importFrom(tibble,as_tibble)
 importFrom(tibble,tibble)
-importFrom(tidyr,pivot_longer)
-importFrom(tidyr,pivot_wider)
 importFrom(tidyselect,all_of)
 importFrom(tidyselect,any_of)
-importFrom(tidyselect,ends_with)
-importFrom(tidyselect,eval_select)
 importFrom(tidyselect,everything)
-importFrom(tidyselect,starts_with)

R/REDCapExploreR-package.R

@@ -1,33 +1,23 @@
 #' @keywords internal
 #' @aliases REDCapExploreR-package
-#' @importFrom cli cli_abort cli_fmt cli_progress_bar cli_progress_done
-#' cli_progress_update cli_text cli_vec cli_warn qty symbol
+#' @importFrom cli cli_abort cli_progress_bar cli_progress_done
+#' cli_progress_update cli_warn symbol
 #' @importFrom DT datatable
-#' @importFrom dplyr across arrange bind_rows case_when count distinct filter
-#' group_by if_any if_else n n_distinct left_join mutate pull recode relocate
-#' rename right_join row_number rowwise select slice summarise transmute ungroup
-#' bind_cols first
+#' @importFrom dplyr across arrange bind_rows case_when count cross_join distinct
+#' filter group_by if_else left_join mutate n n_distinct pull relocate rename
+#' right_join row_number select slice summarise transmute
 #' @importFrom ggplot2 aes element_blank element_text geom_tile ggplot labs
 #' scale_fill_gradientn scale_x_discrete scale_y_discrete theme theme_minimal
-#' @importFrom htmltools browsable HTML save_html tagList tags
-#' @importFrom purrr map map2 map_chr map_int map_lgl pluck pmap_chr pmap
-#' flatten_chr map2_chr reduce
+#' @importFrom htmltools browsable htmlDependency tagList tags
+#' @importFrom purrr flatten_chr map map_chr map_lgl
 #' @importFrom REDCapR redcap_arm_export redcap_event_instruments
 #' redcap_instruments redcap_event_read redcap_instrument_repeating
 #' redcap_metadata_read redcap_project_info_read redcap_read_oneshot
-#' sanitize_token
-#' @importFrom rlang .data .env !!! abort as_closure caller_arg caller_env
-#' catch_cnd check_installed cnd_muffle current_call current_env enexpr enquo
-#' env_poke eval_tidy get_env global_env is_atomic is_bare_formula
-#' is_bare_list quo_name is_installed new_environment quo_get_expr try_fetch
-#' zap as_label sym syms expr :=
+#' @importFrom rlang .data .env !!! :=
 #' @importFrom stats IQR quantile setNames
-#' @importFrom stringr str_detect str_replace str_replace_all str_squish
-#' str_trunc str_trim str_ends
+#' @importFrom stringr str_detect str_squish str_trim str_trunc
 #' @importFrom tibble as_tibble tibble
-#' @importFrom tidyr pivot_longer pivot_wider
-#' @importFrom tidyselect all_of any_of ends_with eval_select everything
-#' starts_with
+#' @importFrom tidyselect all_of any_of everything
 "_PACKAGE"
 
 ## usethis namespace: start

R/choices.R

@@ -0,0 +1,64 @@
+#' Parse REDCap choices
+#'
+#' @description
+#' Converts explicit and implicit choices for choice-capable fields into one row
+#' per coded value. Calculated fields and other uses of the shared REDCap
+#' metadata column are excluded.
+#'
+#' @param metadata Standardized REDCap field metadata.
+#'
+#' @returns A tibble with field, form, choice type, order, value, and label
+#'   columns.
+#'
+#' @noRd
+get_choice_rows <- function(metadata) {
+  if (!"field_order" %in% names(metadata)) {
+    metadata$field_order <- NA_integer_
+  }
+
+  metadata <- metadata |>
+    mutate(
+      choice_definition = case_when(
+        tolower(.data$field_type) == "yesno" ~ "1, Yes | 0, No",
+        tolower(.data$field_type) == "truefalse" ~ "1, True | 0, False",
+        TRUE ~ as.character(.data$select_choices_or_calculations)
+      )
+    ) |>
+    filter(
+      tolower(.data$field_type) %in%
+        c("checkbox", "dropdown", "radio", "yesno", "truefalse"),
+      !get_is_missing(.data$choice_definition)
+    )
+
+  if (nrow(metadata) == 0) {
+    return(tibble(
+      field_order = integer(),
+      field_name = character(),
+      form_name = character(),
+      choice_type = character(),
+      choice_order = integer(),
+      choice_value = character(),
+      choice_label = character()
+    ))
+  }
+
+  bind_rows(map(seq_len(nrow(metadata)), \(index) {
+    choices <- strsplit(
+      metadata$choice_definition[[index]],
+      "\\|"
+    )[[1]]
+
+    bind_rows(map(seq_along(choices), \(choice_index) {
+      parts <- strsplit(choices[[choice_index]], ",", fixed = TRUE)[[1]]
+      tibble(
+        field_order = metadata$field_order[[index]],
+        field_name = metadata$field_name[[index]],
+        form_name = metadata$form_name[[index]],
+        choice_type = tolower(metadata$field_type[[index]]),
+        choice_order = choice_index,
+        choice_value = str_trim(parts[[1]]),
+        choice_label = str_trim(paste(parts[-1], collapse = ","))
+      )
+    }))
+  }))
+}