Skip to content

Commit

Permalink
Update docs (#130)
Browse files Browse the repository at this point in the history 
Updates some documentation in preparation for release. These changes
regard examples in the roxygen docs.

There are still a few more documentation changes to be made. However
they are beyond what I can do quickly so I opened #128.

Also note there is still some chunks usage. I've opened #129 to address
this.

Fixes #125

---------

Co-authored-by: 27856297+dependabot-preview[bot]@users.noreply.github.com <27856297+dependabot-preview[bot]@users.noreply.github.com>
  • Loading branch information
@asbates @dependabot-preview
asbates and dependabot-preview[bot] authored Apr 17, 2023
1 parent c07e750 commit 801b461
Show file tree
Hide file tree
Showing 10 changed files with 242 additions and 554 deletions.
34 changes: 14 additions & 20 deletions R/data_extract_module.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,9 @@ cond_data_extract_single_ui <- function(ns, single_data_extract_spec) {
#'
#' The output can be analyzed using `data_extract_srv(...)`.
#'
#' @section UI examples:
#' \describe{
#' \preformatted{
#' @examples
#' library(shiny)
#'
#' adtte_filters <- filter_spec(
#' vars = c("PARAMCD", "CNSR"),
#' sep = "-",
Expand All @@ -89,29 +89,23 @@ cond_data_extract_single_ui <- function(ns, single_data_extract_spec) {
#' filter = adtte_filters,
#' select = select_spec(
#' choices = c("AVAL", "BMRKR1", "AGE"),
#' selected = c("AVAL", "BMRKR1"),
#' multiple = TRUE,
#' fixed = FALSE,
#' label = "Column"
#' )
#' selected = c("AVAL", "BMRKR1"),
#' multiple = TRUE,
#' fixed = FALSE,
#' label = "Column"
#' )
#' )
#' # Call to use inside your teal module UI function
#' teal.widgets::standard_layout(
#' output = tableOutput("table"),
#' encoding = div(
#' data_extract_ui(id = "regressor", label = "Regressor Variable", data_extract_spec = response_spec)
#' data_extract_ui(
#' id = "regressor",
#' label = "Regressor Variable",
#' data_extract_spec = response_spec
#' )
#' )
#' )
#' }
#' \if{html}{
#' \figure{data_extract_spec_13.png}{options: alt="Dataset with multiple filters and column selection"}
#' }
#' \if{html}{
#' \figure{data_extract_spec_12.png}{options: alt="Dataset with multiple filters and column selection"}
#' }
#' \if{html}{
#' \figure{data_extract_spec_11.png}{options: alt="Dataset with multiple filters and column selection"}
#' }
#' }
#'
#' @export
data_extract_ui <- function(id, label, data_extract_spec, is_single_dataset = FALSE) {
Expand Down
94 changes: 30 additions & 64 deletions R/data_extract_spec.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,87 +30,53 @@
#' whether reshape long to wide. Note that it will be used only in case of long dataset with multiple
#' keys selected in filter part.
#'
#' @section Examples:
#' \describe{
#' \enumerate{
#' \item{`TealDataset` with multiple filters and column selection}{
#' \preformatted{
#' @examples
#' adtte_filters <- filter_spec(
#' vars = c("PARAMCD", "CNSR"),
#' sep = "-",
#' choices = c("OS-1" = "OS-1", "OS-0" = "OS-0", "PFS-1" = "PFS-1"),
#' selected = "OS-1",
#' multiple = FALSE,
#' label = "Choose endpoint and Censor"
#' vars = c("PARAMCD", "CNSR"),
#' sep = "-",
#' choices = c("OS-1" = "OS-1", "OS-0" = "OS-0", "PFS-1" = "PFS-1"),
#' selected = "OS-1",
#' multiple = FALSE,
#' label = "Choose endpoint and Censor"
#' )
#'
#' data_extract_spec(
#' dataname = "ADTTE",
#' filter = adtte_filters,
#' select = select_spec(
#' choices = c("AVAL", "BMRKR1", "AGE"),
#' selected = c("AVAL", "BMRKR1"),
#' multiple = TRUE,
#' fixed = FALSE,
#' label = "Column"
#' )
#' selected = c("AVAL", "BMRKR1"),
#' multiple = TRUE,
#' fixed = FALSE,
#' label = "Column"
#' )
#' )
#' }
#' \if{html}{
#' \figure{data_extract_spec_1.png}{options: alt="TealDataset with multiple filters and column selection"}
#' }
#' \if{html}{
#' \figure{data_extract_spec_12.png}{options: alt="TealDataset with multiple filters and column selection"}
#' }
#' \if{html}{
#' \figure{data_extract_spec_11.png}{options: alt="TealDataset with multiple filters and column selection"}
#' }
#' }
#' \item{Data extract without filtering}{
#' \preformatted{
#'
#' data_extract_spec(
#' dataname = "ADSL",
#' filter = NULL,
#' select = select_spec(
#' choices = c("AGE", "SEX", "USUBJID"),
#' selected = c("SEX"),
#' multiple = FALSE,
#' fixed = FALSE
#' )
#' selected = c("SEX"),
#' multiple = FALSE,
#' fixed = FALSE
#' )
#' )
#' }
#' }
#' \if{html}{
#' \figure{data_extract_spec_2.png}{options: alt="Data extract without filtering"}
#' }
#'
#' \item{Data extract with a single filter}{
#' \preformatted{
#' data_extract_spec(
#' dataname = "ADSL",
#' filter = filter_spec(
#' vars = variable_choices("ADSL", subset = c("AGE"))
#' )
#' )
#' }
#' }
#'
#' \item{Data extract with a filter that also selects columns due to no select_spec}{
#' \preformatted{
#'
#' dynamic_filter <- filter_spec(
#' vars = choices_selected(variable_choices(ADSL), "COUNTRY"),
#' multiple = TRUE
#' data_extract_spec(
#' dataname = "ADSL",
#' filter = filter_spec(
#' vars = variable_choices("ADSL", subset = c("AGE"))
#' )
#' data_extract_spec(
#' dataname = "ADSL",
#' filter = dynamic_filter
#' )
#' }
#' }
#' }
#' }
#' )
#'
#' dynamic_filter <- filter_spec(
#' vars = choices_selected(variable_choices("ADSL"), "COUNTRY"),
#' multiple = TRUE
#' )
#' data_extract_spec(
#' dataname = "ADSL",
#' filter = dynamic_filter
#' )
#'
#' @references [select_spec] [filter_spec]
data_extract_spec <- function(dataname, select = NULL, filter = NULL, reshape = FALSE) {
Expand Down
176 changes: 53 additions & 123 deletions R/filter_spec.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,142 +46,72 @@
#'
#' @return \code{filter_spec}-S3-class object or \code{delayed_filter_spec}-S3-class object.
#'
#' @examples
#' filter_spec(
#' vars = c("PARAMCD", "AVISIT"),
#' sep = " - ",
#' choices = c("CRP - BASELINE", "CRP - SCREENING", "ALT - BASELINE"),
#' selected = c("CRP - BASELINE"),
#' multiple = TRUE
#' )
#'
#' filter_spec(
#' vars = c("PARAMCD"),
#' sep = " - ",
#' choices = c("CRP", "ALT"),
#' selected = c("CRP"),
#' multiple = TRUE
#' )
#' @details
#'
#' The \code{filter_spec} is used inside \code{teal} apps to allow filtering datasets
#' for their key variables. Imagine having an adverse events table. It has
#' the columns \code{PARAMCD} and \code{CNSR}. \code{PARAMCD} contains the levels
#' \code{"OS"}, \code{"PFS"}, \code{"EFS"}. \code{CNSR} contains the levels \code{"0"} and \code{"1"}.
#' The following examples should show how a \code{filter_spec} setup will influence
#' the drop-down menu the app user will see:
#'
#' \enumerate{
#' \item{Filtering two variables }{
#' \preformatted{
#' filter_spec(
#' vars = c("PARAMCD", "CNSR"),
#' sep = "-",
#' choices = c("OS-1" = "OS-1", "OS-0" = "OS-0", "PFS-1" = "PFS-1"),
#' selected = "OS-1",
#' multiple = FALSE,
#' label = "Choose endpoint and Censor"
#' )
#' }
#' The first example should show how a \code{filter_spec} setup will influence
#' the drop-down menu the app user will see.
#'
#' \if{html}{
#' \figure{filter_spec_1.png}{options: alt="Filtering two variables"}
#' }
#' \if{html}{
#' \figure{filter_spec_11.png}{options: alt="Filtering two variables"}
#' }
#' }
#'
#' \item{Filtering a single variable }{
#' \preformatted{
#' filter_spec(
#' vars = c("PARAMCD"),
#' sep = "-",
#' choices = c("OS", "PFS", "EFS"),
#' selected = "OS",
#' multiple = FALSE,
#' label = "Choose endpoint"
#' )
#' }
#'
#' \if{html}{
#' \figure{filter_spec_2.png}{options: alt="Filtering two variables"}
#' }
#' \if{html}{
#' \figure{filter_spec_21.png}{options: alt="Filtering two variables"}
#' }
#' }
#' @examples
#' # for Adverse Events table
#' filter_spec(
#' vars = c("PARAMCD", "CNSR"),
#' sep = "-",
#' choices = c("OS-1" = "OS-1", "OS-0" = "OS-0", "PFS-1" = "PFS-1"),
#' selected = "OS-1",
#' multiple = FALSE,
#' label = "Choose endpoint and Censor"
#' )
#'
#' \item{Filtering a single variable by multiple levels of the variable}{
#' \preformatted{
#' filter_spec(
#' vars = c("PARAMCD"),
#' sep = "-",
#' choices = c("OS", "PFS", "EFS"),
#' selected = c("OS", "PFS"),
#' multiple = TRUE,
#' label = "Choose endpoint"
#' )
#' }
#' # filtering a single variable
#' filter_spec(
#' vars = c("PARAMCD"),
#' sep = "-",
#' choices = c("OS", "PFS", "EFS"),
#' selected = "OS",
#' multiple = FALSE,
#' label = "Choose endpoint"
#' )
#'
#' \if{html}{
#' \figure{filter_spec_3.png}{options: alt="Filtering two variables"}
#' }
#' \if{html}{
#' \figure{filter_spec_31.png}{options: alt="Filtering two variables"}
#' }
#' }
#' \item{Delayed version}{
#' \preformatted{
#' adsl_filter <- filter_spec(
#' vars = variable_choices("ADSL", "SEX"),
#' sep = "-",
#' choices = value_choices("ADSL", "SEX", "SEX"),
#' selected = "F",
#' multiple = FALSE,
#' label = "Choose endpoint and Censor"
#' )
#' }
#' }
#' \item{Using \code{choices_selected}
#' \preformatted{
#' adsl_filter <- filter_spec(
#' vars = choices_selected(variable_choices("ADSL", subset = c("SEX", "AGE")), "SEX", fixed = FALSE),
#' multiple = TRUE
#' )
#' # filtering a single variable by multiple levels of the variable
#' filter_spec(
#' vars = c("PARAMCD"),
#' sep = "-",
#' choices = c("OS", "PFS", "EFS"),
#' selected = c("OS", "PFS"),
#' multiple = TRUE,
#' label = "Choose endpoint"
#' )
#'
#' adsl_filter2 <- filter_spec(
#' vars = choices_selected(variable_choices("ADSL"), "SEX", fixed = TRUE),
#' multiple = TRUE
#' )
#' }
#' }
#' \item{Choose all choices
#' \preformatted{
#' adsl_filter <- filter_spec(
#' vars = choices_selected(variable_choices("ADSL"), "SEX", fixed = FALSE),
#' choices = value_choices("ADSL", "SEX"),
#' selected = all_choices()
#' )
#' }
#' }
#' }
#' # delayed version
#' filter_spec(
#' vars = variable_choices("ADSL", "SEX"),
#' sep = "-",
#' choices = value_choices("ADSL", "SEX", "SEX"),
#' selected = "F",
#' multiple = FALSE,
#' label = "Choose endpoint and Censor"
#' )
#' # using `choices_selected()`
#' filter_spec(
#' vars = choices_selected(variable_choices("ADSL", subset = c("SEX", "AGE")), "SEX", fixed = FALSE),
#' multiple = TRUE
#' )
#'
#' @examples
#' filter_spec(
#' vars = variable_choices("ADSL", "ARMCD"),
#' choices = value_choices("ADSL",
#' var_choices = "ARMCD", var_label = "ARM",
#' subset = function(data) {
#' levels(data$ARMCD)[1:2]
#' }
#' ),
#' selected = value_choices("ADSL",
#' var_choices = "ARMCD", var_label = "ARM",
#' subset = function(data) {
#' levels(data$ARMCD)[1]
#' }
#' )
#' vars = choices_selected(variable_choices("ADSL"), "SEX", fixed = TRUE),
#' multiple = TRUE
#' )
#'
#' # choose all choices
#' adsl_filter <- filter_spec(
#' vars = choices_selected(variable_choices("ADSL"), "SEX", fixed = FALSE),
#' choices = value_choices("ADSL", "SEX"),
#' selected = all_choices()
#' )
filter_spec <- function(vars,
choices = NULL,
Expand Down
3 changes: 2 additions & 1 deletion R/get_merge_call.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -301,7 +301,8 @@ parse_merge_key_i <- function(selector_list,

#' Names of filtered-out filters dropped from selection
#'
#' @details Names of filtered-out filters dropped from automatic selection (key vars are automatically included in select).
#' @details Names of filtered-out filters dropped from automatic selection
#' (key vars are automatically included in select).
#' Dropped filter is filter which became not unique for all observations.
#' This means that if variable is filtered to just one level,
#' it's not a key anymore. Other variables used in filter should also be dropped from automatic
Expand Down
Loading

0 comments on commit 801b461

Please sign in to comment.