From e78e0d3ff928a0979ba646edbd8129d5c759ebf9 Mon Sep 17 00:00:00 2001
From: Andreas Gammelgaard Damsbo <andreas@gdamsbo.dk>
Date: Mon, 29 Jan 2024 12:43:37 +0100
Subject: [PATCH] new read_redcap_instrument in development

---
 NEWS.md                       |  9 +++++++++
 R/read_redcap_instrument.R    | 25 +++++++++++++++++++++++++
 man/read_redcap_instrument.Rd | 34 ++++++++++++++++++++++++++++++++++
 3 files changed, 68 insertions(+)
 create mode 100644 R/read_redcap_instrument.R
 create mode 100644 man/read_redcap_instrument.Rd

diff --git a/NEWS.md b/NEWS.md
index 348967c..0f49537 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -6,10 +6,19 @@
 
 * NEW: `ds2dd_detailed()`: extension of the `ds2dd()`, which serves to preserve as much metadata as possible automatically. Depends on a group of helper functions also introduced. Of special note is the `guess_time_only_filter()`, which will try to guess which columns/variables should be formatted as time only formats. Supports hms time format. DETAILED INSTRUCTION AND VIGNETTE IS PENDING.
 
+* NEW: `read_redcap_instrument()` convenience function to retrieve complete instrument. Goes a little against the focused approach. DETAILED INSTRUCTION IS PENDING.
+
 ### Other
 
 I believe `renv` has now been added and runs correctly. After clone, do `renv::restore()` to install all necessary package to modify the package.
 
+### Whishes before CRAN release
+
+* Vignette for `ds2dd_detailed()`
+
+* Tests for `ds2dd_detailed()`
+
+
 # REDCapCAST 24.1.1
 
 ### Functions
diff --git a/R/read_redcap_instrument.R b/R/read_redcap_instrument.R
new file mode 100644
index 0000000..a9d2dd9
--- /dev/null
+++ b/R/read_redcap_instrument.R
@@ -0,0 +1,25 @@
+#' Convenience function to download complete instrument, using token storage in keyring.
+#'
+#' @param key key name in standard keyring for token retrieval.
+#' @param uri redcap api url
+#' @param instrument instrument name
+#' @param raw_or_label raw or label passed to `REDCapR::redcap_read()`
+#' @param id_name id variable name. Default is "record_id".
+#' @param records specify the records to download. Index numbers. Numeric vector.
+#'
+#' @return data.frame
+#' @export
+read_redcap_instrument <- function(key,
+                            uri,
+                            instrument = "rbans",
+                            raw_or_label = "raw",
+                            id_name = "record_id",
+                            records = NULL) {
+  REDCapCAST::read_redcap_tables(
+    records = records,
+    uri = uri, token = keyring::key_get(key),
+    fields = id_name,
+    forms = instrument,
+    raw_or_label = raw_or_label
+  )[[{{ instrument }}]]
+}
diff --git a/man/read_redcap_instrument.Rd b/man/read_redcap_instrument.Rd
new file mode 100644
index 0000000..8ef6792
--- /dev/null
+++ b/man/read_redcap_instrument.Rd
@@ -0,0 +1,34 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/read_redcap_instrument.R
+\name{read_redcap_instrument}
+\alias{read_redcap_instrument}
+\title{Convenience function to download complete instrument, using token storage in keyring.}
+\usage{
+read_redcap_instrument(
+  key,
+  uri,
+  instrument = "rbans",
+  raw_or_label = "raw",
+  id_name = "record_id",
+  records = NULL
+)
+}
+\arguments{
+\item{key}{key name in standard keyring for token retrieval.}
+
+\item{uri}{redcap api url}
+
+\item{instrument}{instrument name}
+
+\item{raw_or_label}{raw or label passed to `REDCapR::redcap_read()`}
+
+\item{id_name}{id variable name. Default is "record_id".}
+
+\item{records}{specify the records to download. Index numbers. Numeric vector.}
+}
+\value{
+data.frame
+}
+\description{
+Convenience function to download complete instrument, using token storage in keyring.
+}