Merge pull request #6 from CHOP-CGTInformatics/codex/pkgdown-site

Add pkgdown site and mock data

Author: rsh52

.Rbuildignore

@@ -5,6 +5,7 @@
 ^\.\.Rcheck$
 ^LICENSE\.md$
 ^README\.Rmd$
+^AGENTS\.md$
 ^\.github$
 ^_pkgdown\.yml$
 ^docs$

DESCRIPTION

@@ -9,7 +9,11 @@ Depends:
 Description: Provides tools to explore REDCap projects, summarize project
     structure, and flag common data quality issues for data managers.
 License: What license is it under?
+URL: https://chop-cgtinformatics.github.io/REDCapExploreR/,
+    https://github.com/CHOP-CGTInformatics/REDCapExploreR
+BugReports: https://github.com/CHOP-CGTInformatics/REDCapExploreR/issues
 Encoding: UTF-8
+LazyData: true
 Imports: 
     cli,
     DT,
@@ -25,7 +29,10 @@ Imports:
     tidyr,
     tidyselect
 Suggests: 
+    knitr,
+    rmarkdown,
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.3
+VignetteBuilder: knitr

R/codebook.R

@@ -44,6 +44,10 @@ build_codebook <- function(redcap_uri, token) {
     )
   )
 
+  get_codebook(project)
+}
+
+get_codebook <- function(project) {
   codebook <- list(
     fields = get_codebook_fields(project),
     choices = get_codebook_choices(project),
@@ -260,8 +264,11 @@ get_codebook_fields <- function(project) {
       .data$event_count,
       .data$event_names,
       .data$repeating_status,
-      field_note = if ("field_note" %in% names(metadata))
-        as.character(.data$field_note) else NA_character_,
+      field_note = if ("field_note" %in% names(metadata)) {
+        as.character(.data$field_note)
+      } else {
+        NA_character_
+      },
       matrix_group_name = if ("matrix_group_name" %in% names(metadata)) {
         as.character(.data$matrix_group_name)
       } else {
@@ -591,10 +598,16 @@ get_codebook_validation_label <- function(
   map_chr(seq_along(validation_type), \(index) {
     pieces <- c(
       validation_type[[index]],
-      if (!get_is_missing(validation_min[[index]]))
-        paste("min", validation_min[[index]]) else NA_character_,
-      if (!get_is_missing(validation_max[[index]]))
-        paste("max", validation_max[[index]]) else NA_character_
+      if (!get_is_missing(validation_min[[index]])) {
+        paste("min", validation_min[[index]])
+      } else {
+        NA_character_
+      },
+      if (!get_is_missing(validation_max[[index]])) {
+        paste("max", validation_max[[index]])
+      } else {
+        NA_character_
+      }
     )
     pieces <- pieces[!get_is_missing(pieces)]
 

R/data.R

@@ -0,0 +1,53 @@
+#' @title Mock REDCap project
+#'
+#' @description
+#' A fully synthetic REDCap-shaped project list used in package examples,
+#' vignettes, and tests. The project is longitudinal and includes
+#' demographics, follow-up, checkbox, validation, completion status, and
+#' repeating instrument fields.
+#'
+#' @format A list with REDCap API-like data frames:
+#' \describe{
+#'   \item{data}{Synthetic REDCap records.}
+#'   \item{metadata}{Synthetic REDCap data dictionary metadata.}
+#'   \item{events}{Synthetic longitudinal event metadata.}
+#'   \item{event_instruments}{Synthetic event-instrument mapping.}
+#'   \item{instruments}{Synthetic instrument labels.}
+#'   \item{repeating_instruments}{Synthetic repeating instrument settings.}
+#'   \item{project_info}{Synthetic project-level metadata.}
+#' }
+#' @source Generated by `data-raw/mock-data.R`.
+"mock_redcap_project"
+
+#' @title Mock Record Status Dashboard data
+#'
+#' @description
+#' A synthetic dashboard tile table generated from `mock_redcap_project` with
+#' REDCapExploreR's internal record-status logic. This dataset is suitable for
+#' examples of [plot_record_status()].
+#'
+#' @format A tibble with one row per record, event, and form tile.
+#' @source Generated by `data-raw/mock-data.R`.
+"mock_record_status_data"
+
+#' @title Mock REDCap codebook
+#'
+#' @description
+#' A synthetic `redcap_codebook` object generated from `mock_redcap_project`
+#' with REDCapExploreR's internal codebook logic.
+#'
+#' @format A `redcap_codebook` list with `fields`, `choices`, `forms`, `events`,
+#'   `event_instruments`, `repeating`, and `project` elements.
+#' @source Generated by `data-raw/mock-data.R`.
+"mock_codebook"
+
+#' @title Mock REDCap quality report
+#'
+#' @description
+#' A synthetic `redcap_quality_report` object generated from
+#' `mock_redcap_project` with REDCapExploreR's internal quality-report logic.
+#'
+#' @format A `redcap_quality_report` list with `findings`, `summaries`, and
+#'   `metadata` elements.
+#' @source Generated by `data-raw/mock-data.R`.
+"mock_quality_report"

R/plot_record_status.R

@@ -46,6 +46,10 @@
 #' @returns A ggplot object.
 #'
 #' @examples
+#' plot_record_status(mock_record_status_data)
+#'
+#' plot_record_status(mock_record_status_data, mode = "compact")
+#'
 #' \dontrun{
 #' data <- get_record_status_data(
 #'   redcap_uri = Sys.getenv("REDCAP_URI"),

R/quality_report.R

@@ -112,6 +112,27 @@ build_quality_report <- function(
     redcap_uri = redcap_uri,
     token = token
   )
+
+  get_quality_report(
+    project = project,
+    checks = checks,
+    sparse_threshold = sparse_threshold,
+    outlier_iqr_multiplier = outlier_iqr_multiplier,
+    progress_bar = progress_bar,
+    progress_enabled = progress_enabled,
+    progress_force = progress_force
+  )
+}
+
+get_quality_report <- function(
+  project,
+  checks,
+  sparse_threshold,
+  outlier_iqr_multiplier,
+  progress_bar = NULL,
+  progress_enabled = FALSE,
+  progress_force = FALSE
+) {
   update_report_progress(
     progress_bar,
     progress_enabled,
@@ -360,11 +381,14 @@ close_report_progress <- function(progress_bar, enabled) {
 }
 
 get_quality_project <- function(redcap_uri, token) {
-  out <- get_api_project(pull_redcap_project(
+  get_quality_project_data(pull_redcap_project(
     redcap_uri = redcap_uri,
     token = token
   ))
+}
 
+get_quality_project_data <- function(project) {
+  out <- get_api_project(project)
   out$record_id_field <- get_record_id_field_report(out$data, out$metadata)
   out
 }

README.Rmd

@@ -19,7 +19,7 @@ knitr::opts_chunk$set(
 [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
 <!-- badges: end -->
 
-The goal of REDCapExploreR is to provide users with tools to post-process and perform exploratory data analysis on REDCap project data through the REDCap API.
+The goal of REDCapExploreR is to provide users with tools to perform exploratory data analysis on and quality assessments of REDCap project data using the REDCap API.
 
 This repository is in early stages active development!
 
@@ -30,40 +30,3 @@ You can install the development version of REDCapExploreR like so:
 ``` r
 devtools::install_github("CHOP-CGTInformatics/REDCapExploreR")
 ```
-
-## Example
-
-This is a basic example which shows you how to solve a common problem:
-
-```{r example}
-library(REDCapExploreR)
-## basic example code
-```
-
-### Recreating a Project's Record Status Dashboard
-
-```{r, eval=FALSE}
-redcap_uri <- Sys.getenv("REDCAP_URI")
-token <- Sys.getenv("REDCAP_TOKEN")
-
-data <- get_record_status_data(redcap_uri = redcap_uri, token = token)
-
-plot_record_status(data)
-```
-
-For larger projects, use compact mode to reduce x-axis text size, truncate long
-form labels, and draw lighter tile borders.
-
-```{r, eval=FALSE}
-plot_record_status(data, mode = "compact")
-
-plot_record_status(data, mode = "compact", form_label_max = 20)
-```
-
-Because `plot_record_status()` returns a ggplot object, you can add standard
-ggplot2 layers to customize the display.
-
-```{r, eval=FALSE}
-plot_record_status(data) +
-  ggplot2::labs(title = "REDCap Record Status")
-```

README.md

@@ -9,9 +9,9 @@
 experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
 <!-- badges: end -->
 
-The goal of REDCapExploreR is to provide users with tools to
-post-process and perform exploratory data analysis on REDCap project
-data through the REDCap API.
+The goal of REDCapExploreR is to provide users with tools to perform
+exploratory data analysis on and quality assessments of REDCap project
+data using the REDCap API.
 
 This repository is in early stages active development!
 
@@ -22,40 +22,3 @@ You can install the development version of REDCapExploreR like so:
 ``` r
 devtools::install_github("CHOP-CGTInformatics/REDCapExploreR")
 ```
-
-## Example
-
-This is a basic example which shows you how to solve a common problem:
-
-``` r
-library(REDCapExploreR)
-## basic example code
-```
-
-### Recreating a Project’s Record Status Dashboard
-
-``` r
-redcap_uri <- Sys.getenv("REDCAP_URI")
-token <- Sys.getenv("REDCAP_TOKEN")
-
-data <- get_record_status_data(redcap_uri = redcap_uri, token = token)
-
-plot_record_status(data)
-```
-
-For larger projects, use compact mode to reduce x-axis text size, truncate long
-form labels, and draw lighter tile borders.
-
-``` r
-plot_record_status(data, mode = "compact")
-
-plot_record_status(data, mode = "compact", form_label_max = 20)
-```
-
-Because `plot_record_status()` returns a ggplot object, you can add standard
-ggplot2 layers to customize the display.
-
-``` r
-plot_record_status(data) +
-  ggplot2::labs(title = "REDCap Record Status")
-```

_pkgdown.yml

@@ -0,0 +1,60 @@
+url: https://chop-cgtinformatics.github.io/REDCapExploreR/
+
+home:
+  title: Exploratory Data Quality Tools for REDCap Projects
+
+template:
+  bootstrap: 5
+  bslib:
+    code_font: {google: "Fira Code"}
+    primary: "#b22228"
+    text-muted: "#FFFFFF"
+
+navbar:
+  bg: primary
+  structure:
+    left:  [intro, reference]
+    right: [search, github]
+  left:
+    - icon: fa-home
+      href: index.html
+      aria-label: Home
+    - text: Get Started
+      href: articles/REDCapExploreR.html
+    - text: Reference
+      href: reference/index.html
+
+search:
+  exclude: ['news/index.html', 'AGENTS.html']
+
+reference:
+- title: "Pull REDCap Data"
+  desc: >
+    Retrieve REDCap project data and metadata from the API.
+  contents:
+  - pull_redcap_project
+- title: "Build Codebooks"
+  desc: >
+    Build and view REDCap project codebooks.
+  contents:
+  - build_codebook
+  - view_codebook
+- title: "Build Quality Reports"
+  desc: >
+    Build exploratory REDCap data quality reports.
+  contents:
+  - build_quality_report
+- title: "Record Status Dashboard"
+  desc: >
+    Recreate and plot REDCap Record Status Dashboard data.
+  contents:
+  - get_record_status_data
+  - plot_record_status
+- title: "Data"
+  desc: >
+    Synthetic REDCap-shaped datasets for examples and documentation.
+  contents:
+  - mock_redcap_project
+  - mock_record_status_data
+  - mock_codebook
+  - mock_quality_report