linking syntax in markdown

a lot of tibble/data.frame changes too

ref #425, #415

R/create-batch-glossary.R

@@ -29,7 +29,7 @@
 #'
 #' @details
 #' This function can also assist splitting and saving a large
-#' [base::data.frame()] to disk as smaller files (such as a .csv).  The
+#' data frame to disk as smaller files (such as a .csv).  The
 #' padded columns allow the OS to sort the batches/files in sequential order.
 #'
 #' @author

R/redcap-arm-export.R

@@ -23,7 +23,7 @@
 #' * `has_arms`: a `logical` value indicating if the REDCap project has
 #' arms (*i.e.*, "TRUE") or is a classic non-longitudinal project
 #' (*i.e.*, "FALSE").
-#' * `data`: a [`tibble`] with one row per arm.  The columns are
+#' * `data`: a [tibble::tibble()] with one row per arm.  The columns are
 #' `arm_number` (an integer) and `arm_name` (a human-friendly string).
 #' * `success`: A boolean value indicating if the operation was apparently
 #' successful.

R/redcap-column-sanitize.R

@@ -5,16 +5,16 @@
 #' Replace non-ASCII characters with legal characters that won't
 #' cause problems when writing to a REDCap project.
 #'
-#' @param d The [base::data.frame()] containing the dataset used to update
-#' the REDCap project.  Required.
+#' @param d The [base::data.frame()] or [tibble::tibble()] containing the dataset
+#' used to update the REDCap project.  Required.
 #' @param column_names An array of `character` values indicating the names of
 #' the variables to sanitize.  Optional.
 #' @param encoding_initial An array of `character` values indicating the names
 #' of the variables to sanitize.  Optional.
 #' @param substitution_character The `character` value that replaces characters
 #' that were unable to be appropriately matched.
 #'
-#' @return A [base::data.frame()] with same columns, but whose character values
+#' @return A data frame with same columns, but whose character values
 #' have been sanitized.
 #'
 #' @details

R/redcap-metadata-write.R

@@ -6,7 +6,8 @@
 #' into a project. Because of this method's destructive nature,
 #' it works for only projects in Development status.
 #'
-#' @param ds The [base::data.frame()] to be imported into the REDCap project.
+#' @param ds The [base::data.frame()] or [tibble::tibble()]
+#' to be imported into the REDCap project.
 #' Required.
 #' @param redcap_uri The
 #' [uri](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier)/url

R/redcap-write-oneshot.R

@@ -4,7 +4,8 @@
 #' @description
 #' This function uses REDCap's API to select and return data.
 #'
-#' @param ds The [base::data.frame()] to be imported into the REDCap project.
+#' @param ds The [base::data.frame()] or [tibble::tibble()]
+#' to be imported into the REDCap project.
 #' Required.
 #' @param redcap_uri The
 #' [uri](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier)/url
@@ -14,11 +15,11 @@
 #' @param token The user-specific string that serves as the password for a
 #' project.  Required.
 #' @param overwrite_with_blanks A boolean value indicating if
-#' blank/`NA` values in the R [base::data.frame]
+#' blank/`NA` values in the R data frame
 #' will overwrite data on the server.
 #' This is the default behavior for REDCapR,
 #' which essentially deletes the cell's value
-#' If `FALSE`, blank/`NA` values in the [base::data.frame]
+#' If `FALSE`, blank/`NA` values in the data frame
 #' will be ignored.  Optional.
 #' @param convert_logical_to_integer If `TRUE`, all [base::logical] columns
 #' in `ds` are cast to an integer before uploading to REDCap.

R/redcap-write.R

@@ -4,8 +4,8 @@
 #' @description
 #' This function uses REDCap's APIs to select and return data.
 #'
-#' @param ds_to_write The [base::data.frame()] to be imported into the REDCap
-#' project.  Required.
+#' @param ds_to_write The [base::data.frame()] or [tibble::tibble()]
+#' to be imported into the REDCap project.  Required.
 #' @param batch_size The maximum number of subject records a single batch
 #' should contain.  The default is 100.
 #' @param interbatch_delay The number of seconds the function will wait before
@@ -21,11 +21,11 @@
 #' @param token The user-specific string that serves as the password for a
 #' project.  Required.
 #' @param overwrite_with_blanks A boolean value indicating if
-#' blank/`NA` values in the R [base::data.frame]
+#' blank/`NA` values in the R data frame
 #' will overwrite data on the server.
 #' This is the default behavior for REDCapR,
 #' which essentially deletes the cell's value
-#' If `FALSE`, blank/`NA` values in the [base::data.frame]
+#' If `FALSE`, blank/`NA` values in the data.frame
 #' will be ignored.  Optional.
 #' @param convert_logical_to_integer If `TRUE`, all [base::logical] columns
 #' in `ds` are cast to an integer before uploading to REDCap.

R/validate.R

@@ -21,13 +21,14 @@
 #' writing to a REDCap project
 #'
 #' @description
-#' This set of functions inspect a [base::data.frame()] to
-#' anticipate problems before writing with REDCap's API.
+#' This set of functions inspect a data frame
+#' to anticipate problems before writing with REDCap's API.
 #'
-#' @param d The [base::data.frame()] containing the dataset used to update
+#' @param d The [base::data.frame()] or [tibble::tibble()]
+#' containing the dataset used to update
 #' the REDCap project.
-#' @param data_types The data types of the [base::data.frame()] corresponding
-#'  to the REDCap project.
+#' @param data_types The data types of the data frame corresponding
+#' to the REDCap project.
 #' @param field_names The names of the fields/variables in the REDCap project.
 #' Each field is an individual element in the character vector.
 #' @param field_names_collapsed  The names of the fields/variables in the
@@ -39,7 +40,7 @@
 #' @return
 #' A [tibble::tibble()], where each potential violation is a row.
 #' The two columns are:
-#' * `field_name`: The name of the [base::data.frame()] that might cause
+#' * `field_name`: The name of the field/column/variable that might cause
 #' problems during the upload.
 #' * `field_index`: The position of the field.  (For example, a value of
 #' '1' indicates the first column, while a '3' indicates the third column.)
@@ -163,6 +164,6 @@ validate_for_write <- function(d) {
     validate_field_names(colnames(d))
   )
 
-  # Vertically stack all the data.frames into a single data.frame
+  # Vertically stack all the data.frames into a single data frame
   dplyr::bind_rows(lst_concerns)
 }

utility/refresh.R

@@ -5,7 +5,7 @@ options(device = deviceType) #https://support.rstudio.org/help/discussions/probl
 spelling::spell_check_package()
 # spelling::update_wordlist()
 lintr::lint_package()
-lintr::lint("R/redcap-metadata-coltypes.R")
+# lintr::lint("R/redcap-metadata-coltypes.R")
 urlchecker::url_check(); urlchecker::url_update()
 
 devtools::document()

vignettes/BasicREDCapROperations.Rmd

@@ -9,12 +9,13 @@ vignette: >
   %\VignetteEncoding{UTF-8}
 ---
 
-This vignette covers the the basic functions exposed by the [`httr`](https://github.com/r-lib/httr) and [`curl`](https://cran.r-project.org/package=curl) packages which allow you to interact with [REDCap](https://www.project-redcap.org/) through its API.
+This vignette covers the the basic functions exposed by the [httr](https://github.com/r-lib/httr) and [curl](https://cran.r-project.org/package=curl) packages which allow you to interact with [REDCap](https://www.project-redcap.org/) through its API.
 
 Reading REDCap Data
 ==================================================================
 
-The function `redcap_read_oneshot` uses the [`httr`](https://cran.r-project.org/package=httr) package to call the REDCap API.
+The functions [`redcap_read()`](https://ouhscbbmc.github.io/REDCapR/reference/redcap_read.html) and [`redcap_read_oneshot()`](https://ouhscbbmc.github.io/REDCapR/reference/redcap_read_oneshot.html) use the [httr](https://cran.r-project.org/package=httr) package to call the REDCap API.
+
 ```{r set_options}
 #| echo = FALSE, results = 'hide'
 
@@ -108,7 +109,7 @@ ds_some_rows_v2 # Inspect the returned dataset
 Read a subset of the fields
 ------------------------------------------------------------------
 
-If only a subset of the **fields** is desired, then two approaches exist.  The first is to pass an array (where each element is an field) to the `fields` parameter.  The second is to pass a single string (where the elements are separated by commas) to the `fields_collapsed` parameter. Like with `records` and `records_collapsed` described above, this function converts the more natural format (*i.e.*, `fields`) to the format required by the API (*ie*, `fields_collapsed`) if `fields` is specified and `fields_collapsed` is not.
+If only a subset of the **fields** is desired, then two approaches exist.  The first is to pass an array (where each element is an field) to the `fields` parameter.  The second is to pass a single string (where the elements are separated by commas) to the `fields_collapsed` parameter. Like with `records` and `records_collapsed` described above, this function converts the more natural format (*i.e.*, `fields`) to the format required by the API (*i.e.*, `fields_collapsed`) if `fields` is specified and `fields_collapsed` is not.
 
 ```{r read_field_subset}
 # Return only the fields record_id, name_first, and age
@@ -170,9 +171,9 @@ ds_some_rows_v3 #Examine the results.
 Additional Returned Information
 ------------------------------------------------------------------
 
-The examples above have shown only the resulting `data.frame`, by specifying `$data` at the end of the call.  However, more is available to those wanting additional information, such as:
+The examples above have shown only the resulting data frame, by specifying `$data` at the end of the call.  However, more is available to those wanting additional information, such as:
 
-1. The `data` object has the `data.frame`, as in the previous examples.
+1. The `data` object has the data frame, as in the previous examples.
 1. The `success` boolean value indicates if `redcap_read_oneshot` believes the operation completed as intended.
 1. The `status_codes` is a collection of [http status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes), separated by semicolons.  There is one code for each batch attempted.
 1. The `outcome_messages`: A collection of human readable strings indicating the operations' semicolons.  There is one code for each batch attempted.  In an unsuccessful operation, it should contain diagnostic information.

vignettes/TroubleshootingApiCalls.Rmd

@@ -124,13 +124,13 @@ Troubleshooting import operations is trickier than export operations for two maj
 
 The second reason why importing can be trickier is because the schema (*e.g.*, the names and data types) of your local dataset must match the project's schema.  Current recommendations include checking if you can write to simpler projects (perhaps with 1 ID field and 1 string field), and progressively moving to mimic the problematic project's schema and dataset.  Also, consider exporting the dataset to your machine, and look for differences.  Note that you cannot import calculated fields into REDCap.
 
-1. **Does the dataset pass [`REDCapR::validate_for_write()`](https://ouhscbbmc.github.io/REDCapR/reference/validate.html)?**  The `REDCapR::validate_for_write()` inspects a data.frame to anticipate problems before writing with REDCap's API.  The reference manual contains specifics of the validation checks.
+1. **Does the dataset pass [`REDCapR::validate_for_write()`](https://ouhscbbmc.github.io/REDCapR/reference/validate.html)?**  The `REDCapR::validate_for_write()` inspects a data frame to anticipate problems before writing with REDCap's API.  The reference manual contains specifics of the validation checks.
 
 1. **Can you import a *small subset* of the project?**  For instance, just the `record_id` column.
 
 1. **Can you export the dataset and then import it *without any modifications***?  
 
-    For instance, using REDCapR: First, manually complete ~10 example record in the web browser, and then export/download the records with [`REDCapR::redcap_read_oneshot()`](https://ouhscbbmc.github.io/REDCapR/reference/redcap_read_oneshot.html) to a [`data.frame`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/data.frame.html).  (If you have longitudinal or repeating instruments, make sure your examples cover those dimensions adequately) Second, can you successfully upload that same `data.frame` (without modification) with [`REDCapR::redcap_write_oneshot()`](https://ouhscbbmc.github.io/REDCapR/reference/redcap_write_oneshot.html)?  
+    For instance, using REDCapR: First, manually complete ~10 example record in the web browser, and then export/download the records with [`REDCapR::redcap_read_oneshot()`](https://ouhscbbmc.github.io/REDCapR/reference/redcap_read_oneshot.html) to a data frame.  (If you have longitudinal or repeating instruments, make sure your examples cover those dimensions adequately) Second, can you successfully upload that same `data.frame` (without modification) with [`REDCapR::redcap_write_oneshot()`](https://ouhscbbmc.github.io/REDCapR/reference/redcap_write_oneshot.html)?  
     
     If so, that dataset will provide a template for how you structure the real dataset and assign values.  If not, that is a helpful piece of troubleshooting.  
 

vignettes/advanced-redcapr-operations.Rmd

@@ -102,7 +102,7 @@ ds_wide <-
 ds_wide
 ```
 
-In some scenarios, multiple variables (*e.g.*, `pmq1` - `pmq4`) can be widened in a single `tidyr::pivot_wider()` operation.  This example contains the additional wrinkle that the REDCap event names "first_dose" and "first_visit" are renamed "dose_1" and "visit_1", which will help all the values be dose and visit values be proper numbers.
+In some scenarios, multiple variables (*e.g.*, `pmq1` - `pmq4`) can be widened in a single [`tidyr::pivot_wider()`](https://tidyr.tidyverse.org/reference/pivot_wider.html) operation.  This example contains the additional wrinkle that the REDCap event names "first_dose" and "first_visit" are renamed "dose_1" and "visit_1", which will help all the values be dose and visit values be proper numbers.
 
 ```{r widen-typical}
 pattern <- "^(\\w+?)_arm_(\\d)$"