@@ -14,184 +14,146 @@ knitr::opts_chunk$set(
1414)
1515```
1616
17- ``` {r setup}
17+ ``` {r setup, include = FALSE }
1818library(REDCapExploreR)
1919```
2020
2121REDCapExploreR provides exploratory tools for REDCap projects accessed through
22- the REDCap API. The package focuses on project structure, record status
23- summaries, codebook review, and general data quality checks that help data
24- managers inspect REDCap data in R .
22+ the REDCap API. Use it to inspect project structure, review form completion,
23+ and identify general data quality findings without modifying the REDCap
24+ project .
2525
2626## Installation
2727
28- Install the development version from GitHub:
28+ Install the development version from GitHub and load the package :
2929
3030``` {r install, eval=FALSE}
3131devtools::install_github("CHOP-CGTInformatics/REDCapExploreR")
32- ```
33-
34- Load the package after installation:
35-
36- ``` {r load-package}
3732library(REDCapExploreR)
3833```
3934
4035## REDCap API credentials
4136
42- Most REDCapExploreR workflows need a REDCap API endpoint and an API token with
43- access to the project being reviewed. A common setup is to store these values in
44- environment variables and read them at the start of the analysis :
37+ Functions that retrieve a REDCap project need an API endpoint and a project
38+ token with appropriate API permissions. Store credentials outside
39+ version-controlled code, such as in environment variables :
4540
4641``` {r credentials, eval=FALSE}
4742redcap_uri <- Sys.getenv("REDCAP_URI")
4843token <- Sys.getenv("REDCAP_TOKEN")
4944```
5045
51- The examples below assume ` redcap_uri ` and ` token ` have been set. Avoid storing
52- API tokens directly in scripts, vignettes, or version-controlled files .
46+ The examples below assume ` redcap_uri ` and ` token ` are set. The package also
47+ includes synthetic objects for credential-free exploration .
5348
54- ## Record Status Dashboard
49+ ## Choose a workflow
5550
56- Use ` build_record_status_data() ` to retrieve a plotting-friendly table that
57- summarizes REDCap form completion status by record. Then pass the result to
58- ` plot_record_status() ` to create a ggplot heat map similar to the REDCap Record
59- Status Dashboard.
51+ The primary workflows are independent. Start with the function that matches
52+ your review goal.
6053
61- ``` {r record-status-api, eval=FALSE}
62- status_data <- build_record_status_data(
54+ | Goal | Start with |
55+ | ---| ---|
56+ | Understand project fields and structure | ` build_codebook() ` |
57+ | Review form completion | ` build_record_status_data() ` |
58+ | Review data quality findings | ` build_quality_report() ` |
59+ | Analyze the underlying API tables directly | ` pull_redcap_project() ` |
60+
61+ ## Codebook
62+
63+ ` build_codebook() ` returns a structured view of project fields, choices, forms,
64+ events, repeating configuration, and project-level metadata.
65+
66+ ``` {r codebook-api, eval=FALSE}
67+ codebook <- build_codebook(
6368 redcap_uri = redcap_uri,
6469 token = token
6570)
6671
67- plot_record_status(status_data)
72+ codebook
73+ codebook$fields
6874```
6975
70- The package includes a small synthetic dataset for examples and offline
71- exploration. ` mock_record_status_data ` is generated from ` mock_redcap_project `
72- using the same internal record-status logic that supports
73- ` build_record_status_data() ` .
74-
75- ``` {r record-status-mock, fig.alt="Synthetic REDCap record status dashboard heat map."}
76- mock_record_status_data
76+ Use ` mock_codebook ` to inspect the same output structure without API
77+ credentials.
7778
78- plot_record_status(mock_record_status_data)
79+ ``` {r codebook-mock}
80+ mock_codebook
81+ head(mock_codebook$fields)
7982```
8083
81- For larger projects, compact mode reduces x-axis text size, truncates long form
82- labels, and uses lighter tile borders.
83-
84- ``` {r record-status-compact, fig.alt="Compact synthetic REDCap record status dashboard heat map.", eval=FALSE}
85- plot_record_status(mock_record_status_data, mode = "compact")
84+ ` view_codebook() ` presents each available section as an interactive HTML table:
8685
87- plot_record_status(
88- mock_record_status_data,
89- mode = "compact",
90- form_label_max = 20
91- )
86+ ``` {r view-codebook, eval=FALSE}
87+ view_codebook(codebook)
9288```
9389
94- Because ` plot_record_status() ` returns a ggplot object, you can add ggplot2
95- layers to customize labels and display settings.
96-
97- ``` {r record-status-custom, fig.alt="Synthetic REDCap record status dashboard heat map with a custom title."}
98- plot_record_status(mock_record_status_data) +
99- ggplot2::labs(title = "REDCap Record Status")
100- ```
90+ See the [ ` build_codebook() ` reference] ( ../reference/build_codebook.html ) for
91+ output details and the available viewing options.
10192
102- ## Codebooks
93+ ## Record status dashboard
10394
104- Use ` build_codebook ()` to pull REDCap project metadata and return a structured
105- codebook with fields, choices, forms, events, event-instrument mappings,
106- repeating instrument settings, and project-level summary metadata .
95+ ` build_record_status_data ()` summarizes REDCap form completion by record.
96+ ` plot_record_status() ` converts that table into a ggplot heat map similar to the
97+ REDCap Record Status Dashboard .
10798
108- ``` {r codebook -api, eval=FALSE}
109- codebook <- build_codebook (
99+ ``` {r record-status -api, eval=FALSE}
100+ status_data <- build_record_status_data (
110101 redcap_uri = redcap_uri,
111102 token = token
112103)
113104
114- codebook$fields
115- codebook$choices
116- codebook$forms
105+ plot_record_status(status_data)
117106```
118107
119- Use ` mock_codebook ` to inspect the structure without API credentials.
108+ The synthetic ` mock_record_status_data ` can be plotted directly:
120109
121- ``` {r codebook-mock}
122- mock_codebook
123-
124- head(mock_codebook$fields)
125- mock_codebook$project
110+ ``` {r record-status-mock, fig.alt="Synthetic REDCap record status dashboard heat map."}
111+ plot_record_status(mock_record_status_data)
126112```
127113
128- Use ` view_codebook() ` to review the codebook as an interactive HTML object with
129- one table per available section.
130-
131- ``` {r view-codebook, eval=FALSE}
132- viewer <- view_codebook(codebook)
133- viewer
134-
135- htmltools::save_html(viewer, "codebook.html")
136- ```
114+ See the [ ` plot_record_status() ` reference] ( ../reference/plot_record_status.html )
115+ for compact mode and display customization.
137116
138- ## Quality reports
117+ ## Quality report
139118
140- Use ` build_quality_report() ` to retrieve project records and metadata, run
141- general data quality checks, and return findings, summaries, and interpreted
142- metadata.
119+ ` build_quality_report() ` retrieves records and project structure, runs general
120+ data quality checks, and returns findings, summaries, and standardized metadata.
143121
144122``` {r quality-report-api, eval=FALSE}
145123report <- build_quality_report(
146124 redcap_uri = redcap_uri,
147125 token = token
148126)
149127
150- report$findings
128+ report
151129report$summaries$project
152- report$summaries$fields
130+ report$findings
153131```
154132
155- Use ` mock_quality_report ` to see the shape of the report output and example
156- findings.
133+ Use ` mock_quality_report ` to explore the report structure and example findings:
157134
158135``` {r quality-report-mock}
159136mock_quality_report
160137
161138mock_quality_report$findings |>
162139 dplyr::select(
140+ finding_id,
163141 check,
164142 issue,
165143 severity,
166144 record_id,
167- form_name,
168- field_name,
169- message
145+ field_name
170146 )
171-
172- mock_quality_report$summaries$project
173- ```
174-
175- The report can be limited to selected check groups when a focused review is
176- needed.
177-
178- ``` {r quality-report-checks, eval=FALSE}
179- report <- build_quality_report(
180- redcap_uri = redcap_uri,
181- token = token,
182- checks = c("missingness", "metadata")
183- )
184147```
185148
186- See the [ quality report article] ( quality-report.html ) for a complete reference
187- to report checks, output elements, interpretation workflows, and core
188- assumptions.
149+ See the [ quality report article] ( quality-report.html ) for check definitions,
150+ output structure, interpretation guidance, and core assumptions.
189151
190- ## Pulling project data
152+ ## Advanced project data access
191153
192- ` pull_redcap_project() ` retrieves the raw REDCap records and structural metadata
193- used by the quality reporting workflow. This can be useful when you need the
194- same API tables for custom exploration .
154+ ` pull_redcap_project() ` retrieves the record and structural metadata tables used
155+ by the quality-report workflow. Use it when a custom analysis needs the
156+ underlying API responses directly .
195157
196158``` {r pull-project-api, eval=FALSE}
197159project <- pull_redcap_project(
@@ -202,10 +164,17 @@ project <- pull_redcap_project(
202164names(project)
203165```
204166
205- The same top-level structure is represented by ` mock_redcap_project ` .
167+ ` mock_redcap_project ` has the same top-level structure:
206168
207169``` {r pull-project-mock}
208170names(mock_redcap_project)
209-
210- mock_redcap_project$metadata
211171```
172+
173+ ## Next steps
174+
175+ - Use the [ quality report article] ( quality-report.html ) for a deeper review of
176+ quality checks and report interpretation.
177+ - Browse the [ function reference] ( ../reference/index.html ) for complete
178+ arguments and return values.
179+ - Explore ` mock_redcap_project ` , ` mock_record_status_data ` , ` mock_codebook ` , and
180+ ` mock_quality_report ` when REDCap credentials are not available.
0 commit comments