From 2f0e9f414f38d5f4b08fc168c2d8a51f8e64d523 Mon Sep 17 00:00:00 2001 From: Natalie Goulett Date: Tue, 24 Jun 2025 22:49:57 -0400 Subject: [PATCH 1/7] Started basic vignette and commented on log tryCatch fix --- R/REDCap_API.R | 1 + vignettes/Basic.Rmd | 1 + 2 files changed, 2 insertions(+) diff --git a/R/REDCap_API.R b/R/REDCap_API.R index 454032de..ce2a8aab 100644 --- a/R/REDCap_API.R +++ b/R/REDCap_API.R @@ -347,6 +347,7 @@ get_REDCap_log <- function(project, if(log_begin_date == Sys.Date()){ log_begin_date <- log_begin_date - 1 # keep getting errors for same day checks? } + # If redcap_log_read() errors, log is set to NULL log <- tryCatch( expr = { REDCapR::redcap_log_read( diff --git a/vignettes/Basic.Rmd b/vignettes/Basic.Rmd index faee4a49..27c2d301 100644 --- a/vignettes/Basic.Rmd +++ b/vignettes/Basic.Rmd @@ -14,6 +14,7 @@ knitr::opts_chunk$set( ) ``` +Here is how to set up a project object. First, load the REDCapSync package. ```{r setup, eval=FALSE} library(REDCapSync) ``` From 6c5f4dee104e60c78d7a2876a08ece8070cc6b13 Mon Sep 17 00:00:00 2001 From: Natalie Goulett Date: Sun, 20 Jul 2025 18:39:06 -0400 Subject: [PATCH 2/7] Added documentation to sync_project.R (reset param, returns, and basic example) --- R/sync_project.R | 6 ++++-- man/sync_project.Rd | 7 +++++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/R/sync_project.R b/R/sync_project.R index 1045b5ff..2af03336 100644 --- a/R/sync_project.R +++ b/R/sync_project.R @@ -13,16 +13,18 @@ #' @inheritParams save_project #' @param set_token_if_fails Logical (TRUE/FALSE). If TRUE, prompts the user to #' set the REDCap API token if the update fails. Default is `TRUE`. -#' @param reset Logical that forces a fresh update if TRUE. Default is `FALSE`. +#' @param reset Logical. Forces a fresh update if TRUE. Default is `FALSE`. #' @param ask_about_overwrites Logical (TRUE/FALSE). If TRUE, prompts the user #' before overwriting existing data. Default is `TRUE`. #' @param summarize Logical (TRUE/FALSE). If TRUE, summarizes data to directory. #' @param save_to_dir Logical (TRUE/FALSE). If TRUE, saves the updated data to #' the directory. Default is `TRUE`. -#' @return Messages for confirmation. +#' @returns Invisibly returns the full path to the new project root. #' @seealso #' \link{setup_project} for initializing the `project` object. #' @family db_functions +#' @examples +#' sync_project(MyProject) #' @export sync_project <- function( project, diff --git a/man/sync_project.Rd b/man/sync_project.Rd index a009ed4a..2971ac6e 100644 --- a/man/sync_project.Rd +++ b/man/sync_project.Rd @@ -22,7 +22,7 @@ settings. Generated using \link{load_project} or \link{setup_project}} \item{set_token_if_fails}{Logical (TRUE/FALSE). If TRUE, prompts the user to set the REDCap API token if the update fails. Default is \code{TRUE}.} -\item{reset}{Logical that forces a fresh update if TRUE. Default is \code{FALSE}.} +\item{reset}{Logical. Forces a fresh update if TRUE. Default is \code{FALSE}.} \item{silent}{Logical (TRUE/FALSE). For messages.} @@ -35,7 +35,7 @@ before overwriting existing data. Default is \code{TRUE}.} the directory. Default is \code{TRUE}.} } \value{ -Messages for confirmation. +Invisibly returns the full path to the new project root. } \description{ Updates the REDCap database (\code{project} object) by fetching the latest data @@ -48,6 +48,9 @@ update, checking logs for a specified number of days, and retrieving files from REDCap. The function can also handle metadata-only updates and batch processing. } +\examples{ +sync_project(MyProject) +} \seealso{ \link{setup_project} for initializing the \code{project} object. From 672374d34ec2aa0571ce6b2a408f668f0bb4fabb Mon Sep 17 00:00:00 2001 From: Natalie Goulett Date: Sun, 20 Jul 2025 21:22:27 -0400 Subject: [PATCH 3/7] Added to the sync_project example --- R/sync_project.R | 10 +++++++++- man/sync_project.Rd | 10 +++++++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/R/sync_project.R b/R/sync_project.R index 2af03336..5443ce01 100644 --- a/R/sync_project.R +++ b/R/sync_project.R @@ -24,7 +24,15 @@ #' \link{setup_project} for initializing the `project` object. #' @family db_functions #' @examples -#' sync_project(MyProject) +#' sync_project( +#' project = MyProject, +#' set_token_if_fails = TRUE, +#' reset = FALSE, +#' silent = FALSE, +#' ask_about_overwrites = TRUE, +#' summarize = TRUE, +#' save_to_dir = TRUE +#' ) #' @export sync_project <- function( project, diff --git a/man/sync_project.Rd b/man/sync_project.Rd index 2971ac6e..d3ca8898 100644 --- a/man/sync_project.Rd +++ b/man/sync_project.Rd @@ -49,7 +49,15 @@ from REDCap. The function can also handle metadata-only updates and batch processing. } \examples{ -sync_project(MyProject) +sync_project( + project = MyProject, + set_token_if_fails = TRUE, + reset = FALSE, + silent = FALSE, + ask_about_overwrites = TRUE, + summarize = TRUE, + save_to_dir = TRUE +) } \seealso{ \link{setup_project} for initializing the \code{project} object. From e60bdc34d7dae763f82fed220b6746a867d43005 Mon Sep 17 00:00:00 2001 From: Natalie Goulett Date: Sun, 20 Jul 2025 23:18:49 -0400 Subject: [PATCH 4/7] edit sync_project example --- R/sync_project.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/sync_project.R b/R/sync_project.R index 5443ce01..40d74585 100644 --- a/R/sync_project.R +++ b/R/sync_project.R @@ -24,7 +24,7 @@ #' \link{setup_project} for initializing the `project` object. #' @family db_functions #' @examples -#' sync_project( +#' MyProject <- sync_project( #' project = MyProject, #' set_token_if_fails = TRUE, #' reset = FALSE, From f6ddec3b26668fd2692afc7752ff9a8661c0a7b8 Mon Sep 17 00:00:00 2001 From: Natalie Goulett Date: Fri, 1 Aug 2025 23:38:22 -0400 Subject: [PATCH 5/7] Edited params for save_project --- R/project_to_and_from_dir.R | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/R/project_to_and_from_dir.R b/R/project_to_and_from_dir.R index c954a143..a2ccdd1d 100644 --- a/R/project_to_and_from_dir.R +++ b/R/project_to_and_from_dir.R @@ -1,10 +1,10 @@ #' @title Reads project from the dropped REDCap files in dir/REDCap/upload #' @inheritParams save_project -#' @param allow_all logical TF for allowing project$data names that are not also +#' @param allow_all logical indicating whether to allow project$data names that are not also #' form names -#' @param drop_nonredcap_vars logical TF for dropping non-redcap variable names -#' @param drop_non_form_vars logical TF for dropping non-form variable names -#' @param stop_or_warn character string of whether to stop, warn, or do nothing +#' @param drop_nonredcap_vars logical indicating if non-REDCap variable names should be dropped. +#' @param drop_non_form_vars logical indicating if non-form variable names should be dropped. +#' @param stop_or_warn character string indicating whether to stop, warn, or do nothing #' when forbidden cols are present #' @return messages for confirmation #' @export From edc0296f9976eea58f50a66f0d1b2173b75803e1 Mon Sep 17 00:00:00 2001 From: Natalie Goulett Date: Sat, 2 Aug 2025 23:56:39 -0400 Subject: [PATCH 6/7] Removed the with_data param documentation - it's an internal param for setup_test_project() only. Reworded corrupted project warning. --- R/setup_project.R | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/R/setup_project.R b/R/setup_project.R index 04e5c241..37bda035 100644 --- a/R/setup_project.R +++ b/R/setup_project.R @@ -58,8 +58,6 @@ #' Default is `FALSE`. #' @param metadata_only Logical (TRUE/FALSE). If TRUE, updates only the #' metadata. Default is `FALSE`. -#' @param with_data Logical (TRUE/FALSE). If TRUE, loads the test project -#' object with data included. #' @param get_type optional character of REDCap API call type. #' data as if user ran `sync_project`. Default is `FALSE`. #' @param batch_size_download Integer. Number of records to process in each @@ -189,7 +187,7 @@ setup_project <- function( if (!is.null(project_details)) { add_project_details_to_cache(project_details) } else { - cli_alert_warning("currupted project_details so will be overwritten") + cli_alert_warning("project_details were corrupted and will be overwritten") } # add check for if it was loaded from right place } From 50ac6a9983db1bcaeddb49212267a33af1e091e3 Mon Sep 17 00:00:00 2001 From: Natalie Goulett Date: Sun, 14 Sep 2025 17:09:10 -0400 Subject: [PATCH 7/7] Expanded on project_cache vignette. --- vignettes/project_cache.Rmd | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/vignettes/project_cache.Rmd b/vignettes/project_cache.Rmd index 7c7c3d3c..ce01cf1c 100644 --- a/vignettes/project_cache.Rmd +++ b/vignettes/project_cache.Rmd @@ -14,7 +14,7 @@ knitr::opts_chunk$set( ) ``` -The REDCapSync package benefits from storing/caching key information about your different projects. The two most important pieces of information is the `short_name` and `directory` where it's stored. This is enough information to be able to find where you have chosen to securely store your files, load what has already been collected, and then communicate with R to fetch any new updates. REDCapSync's ability to store your projects in a standardized directory is what allows for powerful pipeline tasks. +The REDCapSync package benefits from storing/caching key information about your different projects. The two most important pieces of information stored in the cache are the `short_name` identifying your project and your `directory` where your project data.frame is stored. Only metadata, no tokens or data files, are stored in the cache. This is enough information to be able to find where you have chosen to securely store your files, load what has already been collected, and then communicate with R to fetch any new updates. REDCapSync's ability to store your projects in a standardized directory is what allows for powerful pipeline tasks. ```{r, eval=F} library(REDCapSync) # don't forget to load the package @@ -22,7 +22,7 @@ library(REDCapSync) # don't forget to load the package # The Cache -Using the `hoadr` package, R finds the standard location where R typically stores cahced package data. For example, on Mac the location might look like, "/Users/yourmacname/Library/Caches/R/REDCapSync". Your exact path can be found with `cache_path()` At the time writing this article, the only thing that REDCapSync stores in this cache is the projects data.frame, which can be loaded with `projects <- get_projects()`. +Using the `hoadr` package, R finds the standard location where R typically stores cached package data. For example, on Mac the location might look like, "/Users/yourmacname/Library/Caches/R/REDCapSync". Your exact path can be found with `cache_path()` At the time writing this article, the only thing that REDCapSync stores in this cache is the projects data.frame, which can be loaded with `projects <- get_projects()`. ```{r, eval=F} cache_path() @@ -30,6 +30,8 @@ cache_path() # Projects +After a project has been set up, a list object containing cached project data can be retrieved using the get_projects() function. To learn how to set up a project, see the [get started](https://thecodingdocs.github.io/REDCapSync/articles/REDCapSync.html) guide. + ```{r, eval=F} projects <- get_projects() print.data.frame(projects)