% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/REDCapSyncDataset.R
\name{dataset}
\alias{dataset}
\alias{REDCapSyncDataset}
\title{REDCapSync Dataset Object}
\value{
An R6 \code{REDCapSyncDataset} object containing dataset output, metadata,
records, user information, and optional REDCap log data.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
\link[R6:R6Class]{R6} object representing a standardized dataset generated from
a \link{REDCapSync} project. Use this object to inspect transformed REDCap data,
export datasets, and assign prepared analysis tables into the calling
environment.
}
\details{
A \code{REDCapSyncDataset} can be created ad-hoc from a project with
\code{dataset <- project$generate_dataset()}. For reusability, you can also
define with \code{project$add_dataset()} and then load with
\code{dataset <- project$load_dataset()}.

You can add variables manually if you want them to be passed to Excel. But
\code{add_field} is a feature in development.
\subsection{Typical workflow}{

\if{html}{\out{<div class="sourceCode r">}}\preformatted{setup project from test object
project <- setup_project(
  project_name = "TEST_CLASSIC",
  dir_path = tempdir()
)
# Create and save a filtered dataset
project$add_dataset(
  dataset_name = "analysis_set",
  filter_field = "var_yesno",
  filter_choices = "Yes",
  field_names = c("ecog_at_diagnosis", "stage_at_diagnosis")
)
# generate dataset for R environment
dataset <- project$load_dataset("analysis_set")
# optional send to global environment
dataset$to_envir(globalenv()) # keep in mind potential name conflicts
# Optional modify (final save depends on what is in the dataset object)
dataset$data$merged$stage_2 <- dataset$data$merged$stage_at_diagnosis == "II"
# save to directory
dataset$save() # can specify `dir_other`, by default saves to output folder
}\if{html}{\out{</div>}}

This object is designed for users who want a stable dataset output from
REDCap without modifying the underlying project. This is also used
behind-the-scenes in the RosyREDCap shiny app.
}

\subsection{Key features}{
\itemize{
\item Stores a project-specific dataset definition and resulting data
\item Keeps metadata, record details, user information, and comments in sync
\item Saves datasets in Excel or CSV formats with optional hyperlinks
\item Exports dataset components to a user-specified environment
}
}
}
\examples{
project <- load_project("TEST_CLASSIC")

dataset <- project$generate_dataset(
  dataset_name = "stage_2_patients",
  filter_field = "stage_at_diagnosis",
  filter_choices = "II",
  field_names = c("ecog_at_diagnosis", "stage_at_diagnosis")
 )

dataset$save(dir_other = tempdir())

}
\seealso{
\link{project} for using the project objects
\code{vignette("Datasets", package = "REDCapSync")}
\code{vignette("RosyREDCap", package = "REDCapSync")}
}
\section{Public fields}{
  \if{html}{\out{<div class="r6-fields">}}
  \describe{
    \item{\code{data}}{list of data where names are forms}

    \item{\code{metadata}}{list of metadata}

    \item{\code{records}}{data.frame of records with timestamps}

    \item{\code{users}}{data.frame of users with timestamps}

    \item{\code{log}}{data.frame of log}

    \item{\code{comments}}{data.frame of comments}
  }
  \if{html}{\out{</div>}}
}
\section{Active bindings}{
  \if{html}{\out{<div class="r6-active-bindings">}}
  \describe{
    \item{\code{project_details}}{Read-only list of dataset details from
\code{\link[=setup_project]{setup_project()}}.}

    \item{\code{dataset_details}}{Read-only list of dataset details}

    \item{\code{redcap}}{Read-only list of dataset details from \link{project}}

    \item{\code{links}}{Read-only list of dataset details from \link{project}}
  }
  \if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
  \itemize{
    \item \href{#method-REDCapSyncDataset-initialize}{\code{REDCapSyncDataset$new()}}
    \item \href{#method-REDCapSyncDataset-print}{\code{REDCapSyncDataset$print()}}
    \item \href{#method-REDCapSyncDataset-save}{\code{REDCapSyncDataset$save()}}
    \item \href{#method-REDCapSyncDataset-to_envir}{\code{REDCapSyncDataset$to_envir()}}
  }
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-REDCapSyncDataset-initialize"></a>}}
\if{latex}{\out{\hypertarget{method-REDCapSyncDataset-initialize}{}}}
\subsection{\code{REDCapSyncDataset$new()}}{
  The end user will not see \code{dataset$new()}. This is handled internally.
Users should construct objects using \link{REDCapSyncProject}.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{REDCapSyncDataset$new(
  project,
  dataset_name,
  transformation_type = "default",
  merge_form_name = "merged",
  filter_field = NULL,
  filter_choices = NULL,
  filter_list = NULL,
  filter_strict = TRUE,
  field_names = NULL,
  form_names = NULL,
  exclude_identifiers = FALSE,
  exclude_free_text = FALSE,
  date_handling = "none",
  labelled = TRUE,
  clean = TRUE,
  drop_blanks = FALSE,
  drop_missing_codes = FALSE,
  drop_others = NULL,
  include_metadata = TRUE,
  include_users = TRUE,
  include_records = TRUE,
  include_log = FALSE,
  annotate_from_log = TRUE,
  include_comments = FALSE
)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{project}}{Project object from \code{\link[=setup_project]{setup_project()}} or \code{\link[=load_project]{load_project()}}.}
      \item{\code{dataset_name}}{Character. Name of the dataset to generate or load.
If the dataset already exists in the project, the existing definition is
reused.}
      \item{\code{transformation_type}}{Character. Data transformation strategy: "default"
(preferred merged output), "none" (raw data structure), or
"merge_non_repeating" (merge only non-repeating forms). Default is
"default".}
      \item{\code{merge_form_name}}{Character. Name used for merged non-repeating records.
Default is "merged".}
      \item{\code{filter_field}}{Character. Field used for filtering the dataset.}
      \item{\code{filter_choices}}{Vector. Allowed values for \code{filter_field}.}
      \item{\code{filter_list}}{List. Named list mapping field names to allowed values.
Use instead of \code{filter_field}/\code{filter_choices} for more complex filters.}
      \item{\code{filter_strict}}{Logical. If \code{TRUE}, filters are applied to every form.
If \code{FALSE}, filters apply only to the record identifier. Default is
\code{TRUE}.}
      \item{\code{field_names}}{Character vector. Variables to include in the dataset.
Default is \code{NULL} (all fields).}
      \item{\code{form_names}}{Character vector. Forms to include in the dataset.
Default is \code{NULL} (all forms).}
      \item{\code{exclude_identifiers}}{Logical. Remove identifier fields. Default is
\code{TRUE}.}
      \item{\code{exclude_free_text}}{Logical. Remove free text fields. Default is
\code{FALSE}.}
      \item{\code{date_handling}}{Character. Date handling method: "none",
"exclude_dates", "random_shift_by_record", "random_shift_by_project",
"zero_by_record", or "zero_by_project". Default is "none".}
      \item{\code{labelled}}{Logical. Convert values to labelled vectors if \code{TRUE}.
Default is \code{TRUE}.}
      \item{\code{clean}}{Logical. Clean the dataset by standardizing missing values and
blanks. Default is \code{TRUE}.}
      \item{\code{drop_blanks}}{Logical. Drop records with blank fields. Default is
\code{FALSE}.}
      \item{\code{drop_missing_codes}}{Logical. Convert REDCap missing codes to \code{NA}.
Default is \code{FALSE}.}
      \item{\code{drop_others}}{Character vector of additional values to remove.}
      \item{\code{include_metadata}}{Logical. Include field metadata in the dataset.
Default is \code{TRUE}.}
      \item{\code{include_users}}{Logical. Include user information in the dataset.
Default is \code{TRUE}.}
      \item{\code{include_records}}{Logical. Include record-level details. Default is
\code{TRUE}.}
      \item{\code{include_log}}{Logical. Include REDCap activity log details. Default is
\code{FALSE}.}
      \item{\code{annotate_from_log}}{Logical. Annotate metadata and records using the
change log. Default is \code{TRUE}.}
      \item{\code{include_comments}}{Logical. Include REDCap comments. Default is
\code{FALSE}.}
    }
    \if{html}{\out{</div>}}
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-REDCapSyncDataset-print"></a>}}
\if{latex}{\out{\hypertarget{method-REDCapSyncDataset-print}{}}}
\subsection{\code{REDCapSyncDataset$print()}}{
  Print some key dataset information
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{REDCapSyncDataset$print()}
    \if{html}{\out{</div>}}
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-REDCapSyncDataset-save"></a>}}
\if{latex}{\out{\hypertarget{method-REDCapSyncDataset-save}{}}}
\subsection{\code{REDCapSyncDataset$save()}}{
  Return flat list
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{REDCapSyncDataset$save(
  with_links = TRUE,
  separate = FALSE,
  use_csv = FALSE,
  dir_other = NULL,
  file_name = NULL
)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{with_links}}{Logical. Include hyperlinks in Excel exports. Default is
\code{TRUE}.}
      \item{\code{separate}}{Logical. Save each form as a separate file instead of a
multi-sheet workbook. Default is \code{FALSE}.}
      \item{\code{use_csv}}{Logical. Write CSV files instead of Excel. Default is
\code{FALSE}.}
      \item{\code{dir_other}}{Character. Directory where the dataset file should be
saved. Defaults to the project's output folder.}
      \item{\code{file_name}}{Character. Base file name for saved datasets. Defaults to
\verb{<project_name>_<dataset_name>}.}
    }
    \if{html}{\out{</div>}}
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-REDCapSyncDataset-to_envir"></a>}}
\if{latex}{\out{\hypertarget{method-REDCapSyncDataset-to_envir}{}}}
\subsection{\code{REDCapSyncDataset$to_envir()}}{
  export dataset to envir of your choosing. Keep in mind
potential name conflicts
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{REDCapSyncDataset$to_envir(envir = NULL)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{envir}}{Environment to assign exported dataset objects. Default is
\code{NULL}.}
    }
    \if{html}{\out{</div>}}
  }
}

}
