From 37c351db27f771416d4074580852b44910a1b45e Mon Sep 17 00:00:00 2001 From: Aleksander Chlebowski <114988527+chlebowa@users.noreply.github.com> Date: Tue, 30 Jan 2024 17:40:42 +0100 Subject: [PATCH] clean up after `pre-release-cleanup` (#537) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Proof reading documentation and code comments. --------- Signed-off-by: Aleksander Chlebowski <114988527+chlebowa@users.noreply.github.com> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: André Veríssimo <211358+averissimo@users.noreply.github.com> Co-authored-by: 27856297+dependabot-preview[bot]@users.noreply.github.com <27856297+dependabot-preview[bot]@users.noreply.github.com> Co-authored-by: Pawel Rucki <12943682+pawelru@users.noreply.github.com> --- DESCRIPTION | 2 +- NAMESPACE | 6 +- R/FilterPanelAPI.R | 8 +- R/FilterState-utils.R | 30 ++-- R/FilterState.R | 142 +++++++-------- R/FilterStateChoices.R | 41 ++--- R/FilterStateDate.R | 33 ++-- R/FilterStateDatettime.R | 32 ++-- R/FilterStateEmpty.R | 34 ++-- R/FilterStateExpr.R | 40 +++-- R/FilterStateLogical.R | 32 ++-- R/FilterStateRange.R | 45 +++-- R/FilterStates-utils.R | 26 +-- R/FilterStates.R | 61 +++---- R/FilterStatesDF.R | 18 +- R/FilterStatesMAE.R | 14 +- R/FilterStatesMatrix.R | 13 +- R/FilterStatesSE.R | 18 +- R/FilteredData-utils.R | 14 +- R/FilteredData.R | 132 +++++++------- R/FilteredDataset-utils.R | 43 +++-- R/FilteredDataset.R | 105 +++++------ R/FilteredDatasetDataframe.R | 63 +++---- R/FilteredDatasetDefault.R | 39 ++-- R/FilteredDatasetMAE.R | 36 ++-- R/calls_combine_by.R | 2 +- R/choices_labeled.R | 2 +- R/count_labels.R | 76 ++++---- R/filter_panel_api.R | 16 +- R/teal_slices.R | 6 +- R/utils.R | 7 +- R/variable_types.R | 95 +++------- man/ChoicesFilterState.Rd | 36 ++-- man/DFFilterStates.Rd | 18 +- man/DataframeFilteredDataset.Rd | 63 +++---- man/DateFilterState.Rd | 28 +-- man/DatetimeFilterState.Rd | 26 +-- man/DefaultFilteredDataset.Rd | 36 ++-- man/EmptyFilterState.Rd | 27 ++- man/FilterPanelAPI.Rd | 8 +- man/FilterState.Rd | 67 ++++--- man/FilterStateExpr.Rd | 40 +++-- man/FilterStates.Rd | 41 ++--- man/FilteredData.Rd | 132 +++++++------- man/FilteredDataset.Rd | 96 +++++----- man/LogicalFilterState.Rd | 26 +-- man/MAEFilterStates.Rd | 14 +- man/MAEFilteredDataset.Rd | 32 ++-- man/MatrixFilterStates.Rd | 12 +- man/RangeFilterState.Rd | 23 +-- man/SEFilterStates.Rd | 18 +- man/calls_combine_by.Rd | 2 +- man/check_simple_name.Rd | 9 +- man/choices_labeled.Rd | 2 +- man/coalesce_r.Rd | 2 +- man/countBar.Rd | 24 ++- man/countBars.Rd | 35 ++-- man/eval_expr_with_msg.Rd | 2 +- man/fetch_bs_color.Rd | 7 + man/filter_state_api.Rd | 12 +- man/get_filter_expr.Rd | 2 +- man/get_supported_filter_varnames.Rd | 2 +- man/init_filter_state.Rd | 17 +- man/init_filter_state_expr.Rd | 6 +- man/init_filter_states.Rd | 21 +-- man/init_filtered_data.Rd | 6 +- man/init_filtered_dataset.Rd | 44 +++-- man/make_count_text.Rd | 12 +- man/teal_slices.Rd | 4 +- man/toggle_button.Rd | 3 +- man/variable_types.Rd | 7 +- tests/testthat/test-FilteredData.R | 206 ++++------------------ tests/testthat/test-MAEFilteredDataset.R | 4 +- tests/testthat/test-filter_panel_api.R | 25 +-- tests/testthat/test-init_filtered_data.R | 6 +- vignettes/filter-panel-for-developers.Rmd | 14 +- vignettes/teal-slice.Rmd | 7 +- 77 files changed, 1121 insertions(+), 1334 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 2664350f0..dca9f2847 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -19,7 +19,7 @@ Authors@R: c( person("Junlue", "Zhao", role = "aut"), person("F. Hoffmann-La Roche AG", role = c("cph", "fnd")) ) -Description: Module containing filter panel for 'teal' applications. +Description: Data filtering module for 'teal' applications. Allows for interactive filtering of data stored in 'data.frame' and 'MultiAssayExperiment' objects. Also displays filtered and unfiltered observation counts. diff --git a/NAMESPACE b/NAMESPACE index 3b3adaefa..8985e512a 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -26,17 +26,13 @@ S3method(init_filtered_dataset,data.frame) S3method(init_filtered_dataset,default) S3method(print,teal_slice) S3method(print,teal_slices) -S3method(variable_types,DFrame) -S3method(variable_types,DataTable) -S3method(variable_types,data.frame) -S3method(variable_types,default) -S3method(variable_types,matrix) export(FilterPanelAPI) export(as.teal_slice) export(as.teal_slices) export(clear_filter_states) export(get_filter_expr) export(get_filter_state) +export(get_supported_filter_varnames) export(init_filter_states) export(init_filtered_data) export(init_filtered_dataset) diff --git a/R/FilterPanelAPI.R b/R/FilterPanelAPI.R index 288497832..1b57b3879 100644 --- a/R/FilterPanelAPI.R +++ b/R/FilterPanelAPI.R @@ -17,7 +17,7 @@ #' filter panel API. #' #' @examples -#' fd <- init_filtered_data(list(iris = list(dataset = iris))) +#' fd <- init_filtered_data(list(iris = iris)) #' fpa <- FilterPanelAPI$new(fd) #' #' # get the actual filter state --> empty named list @@ -71,7 +71,7 @@ FilterPanelAPI <- R6::R6Class( # nolint #' Sets active filter states. #' @param filter (`teal_slices`) #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' set_filter_state = function(filter) { private$filtered_data$set_filter_state(filter) @@ -85,7 +85,7 @@ FilterPanelAPI <- R6::R6Class( # nolint #' specifying `FilterState` objects to remove; #' `teal_slice`s may contain only `dataname` and `varname`, other elements are ignored #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' remove_filter_state = function(filter) { private$filtered_data$remove_filter_state(filter) @@ -99,7 +99,7 @@ FilterPanelAPI <- R6::R6Class( # nolint #' `datanames` to remove their `FilterStates`; #' omit to remove all `FilterStates` in the `FilteredData` object #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' clear_filter_states = function(datanames) { datanames_to_remove <- if (missing(datanames)) private$filtered_data$datanames() else datanames diff --git a/R/FilterState-utils.R b/R/FilterState-utils.R index dc035e537..d3d6bc15e 100644 --- a/R/FilterState-utils.R +++ b/R/FilterState-utils.R @@ -1,33 +1,35 @@ -#' Initializes `FilterState` +#' Initialize `FilterState` #' -#' Initializes `FilterState` depending on a variable class. +#' Initializes a `FilterState` object corresponding to the class of the filtered variable. #' #' @param x (`vector`) -#' values of the variable used in filter +#' variable to be filtered. #' @param x_reactive (`reactive`) #' returning vector of the same type as `x`. Is used to update #' counts following the change in values of the filtered dataset. #' If it is set to `reactive(NULL)` then counts based on filtered #' dataset are not shown. #' @param slice (`teal_slice`) -#' object created using [teal_slice()]. +#' specification of this filter state. +#' `teal_slice` is stored in the object and `set_state` directly manipulates values within `teal_slice`. +#' `get_state` returns `teal_slice` object which can be reused in other places. +#' Note that `teal_slice` is a `reactiveValues`, which means it has reference semantics, i.e. +#' changes made to an object are automatically reflected in all places that refer to the same `teal_slice`. #' @param extract_type (`character`) #' specifying whether condition calls should be prefixed by `dataname`. Possible values: #' - `character(0)` (default) `varname` in the condition call will not be prefixed #' - `"list"` `varname` in the condition call will be returned as `$` #' - `"matrix"` `varname` in the condition call will be returned as `[, ]` -#' @param ... additional arguments to be saved as a list in `private$extras` field #' #' @examples #' # use non-exported function from teal.slice -#' include_js_files <- getFromNamespace("include_js_files", "teal.slice") #' init_filter_state <- getFromNamespace("init_filter_state", "teal.slice") #' #' filter_state <- init_filter_state( #' x = c(1:10, NA, Inf), #' x_reactive = reactive(c(1:10, NA, Inf)), #' slice = teal_slice( -#' varname = "x", +#' varname = "varname", #' dataname = "dataname" #' ), #' extract_type = "matrix" @@ -218,11 +220,7 @@ init_filter_state.POSIXlt <- function(x, #' Initialize a `FilterStateExpr` object #' #' @param slice (`teal_slice_expr`) -#' object created using [teal_slice()]. `teal_slice` is stored -#' in the class and `set_state` directly manipulates values within `teal_slice`. `get_state` -#' returns `teal_slice` object which can be reused in other places. Beware, that `teal_slice` -#' is a `reactiveValues` which means that changes in particular object are automatically -#' reflected in all places which refer to the same `teal_slice`. +#' specifying this filter state. #' #' @return `FilterStateExpr` object #' @keywords internal @@ -241,6 +239,13 @@ init_filter_state_expr <- function(slice) { #' set to NULL to omit adding the alpha channel #' #' @return Named `character(1)` containing a hexadecimal color representation. +#' +#' @examples +#' fetch_bs_color <- getFromNamespace("fetch_bs_color", "teal.slice") +#' fetch_bs_color("primary") +#' fetch_bs_color("danger", 0.35) +#' fetch_bs_color("danger", "80") +#' #' @keywords internal #' fetch_bs_color <- function(color, alpha = NULL) { @@ -251,7 +256,6 @@ fetch_bs_color <- function(color, alpha = NULL) { ) # locate file that describes the current theme - ## TODO this is not ideal sass_file <- if (utils::packageVersion("bslib") < as.package_version("0.5.1.9000")) { bslib::bs_theme()[["layers"]][[2]][["defaults"]][[1]] } else { diff --git a/R/FilterState.R b/R/FilterState.R index cbcb738d2..75deedb32 100644 --- a/R/FilterState.R +++ b/R/FilterState.R @@ -3,42 +3,41 @@ #' @name FilterState #' @docType class #' -#' @title `FilterState` abstract Class +#' @title `FilterState` abstract class #' #' @description Abstract class to encapsulate single filter state. #' #' @details -#' This class is responsible for managing single filter item within -#' `FilteredData` class object. Filter states depend on the variable type: -#' (`logical`, `integer`, `numeric`, `factor`, `character`, `Date`, `POSIXct`, `POSIXlt`) -#' and returns `FilterState` object with class corresponding to input variable. -#' Class controls single filter entry in `module_single_filter_item` and returns -#' code relevant to selected values. -#' - `factor`, `character`: `class = ChoicesFilterState` -#' - `numeric`: `class = RangeFilterState` +#' This class is responsible for managing a single filter item within a `FilteredData` object +#' and outputs a condition call (logical predicate) for subsetting one variable. +#' Filter states depend on the variable type: +#' (`logical`, `integer`, `numeric`, `character`, `factor`, `Date`, `POSIXct`, `POSIXlt`) +#' and `FilterState` subclasses exist that correspond to those types. #' - `logical`: `class = LogicalFilterState` +#' - `integer`: `class = RangeFilterState` +#' - `numeric`: `class = RangeFilterState` +#' - `character`: `class = ChoicesFilterState` +#' - `factor`: `class = ChoicesFilterState` #' - `Date`: `class = DateFilterState` #' - `POSIXct`, `POSIXlt`: `class = DatetimeFilterState` #' - all `NA` entries: `class: FilterState`, cannot be filtered #' - default: `FilterState`, cannot be filtered #' -#' Each variable's filter state is an `R6` object which contains `choices`, -#' `selected`, `varname`, `dataname`, `labels`, `na_count`, `keep_na` and other -#' variable type specific fields (`keep_inf`, `inf_count`, `timezone`). -#' Object also contains a `shiny` module (UI and server) which manages the -#' state of the filter through reactive values `selected`, `keep_na`, `keep_inf` -#' which trigger `get_call()` and every `R` function call up in reactive chain. +#' Each variable's filter state is an `R6` object keeps the variable that is filtered, +#' a `teal_slice` object that describes the filter state, as well as a `shiny` module (UI and server) +#' that allows the user to alter the filter state. +#' Changes to the filter state that cause some observations to be omitted +#' trigger the `get_call` method and every `R` function call up in the reactive chain. #' #' @section Modifying state: #' Modifying a `FilterState` object is possible in three scenarios: -#' - In the interactive session by passing an appropriate `teal_slice` -#' to the `set_state` method, or using -#' `set_selected`, `set_keep_na` or `set_keep_inf` methods. -#' - In a running application by changing appropriate inputs. -#' - In a running application by using [filter_state_api] which directly uses -#' `set_state` method of the `InteractiveFilterState` object. +#' - In an interactive session, by passing an appropriate `teal_slice` to the `set_state` method. +#' - In a running application, by changing appropriate inputs. +#' - In a running application, by using [filter_state_api] which directly uses +#' `set_state` method of the `FilterState` object. #' #' @keywords internal +#' FilterState <- R6::R6Class( # nolint "FilterState", @@ -47,23 +46,27 @@ FilterState <- R6::R6Class( # nolint #' @description #' Initialize a `FilterState` object. + #' #' @param x (`vector`) - #' values of the variable used in filter + #' variable to be filtered. #' @param x_reactive (`reactive`) #' returning vector of the same type as `x`. Is used to update #' counts following the change in values of the filtered dataset. #' If it is set to `reactive(NULL)` then counts based on filtered #' dataset are not shown. #' @param slice (`teal_slice`) - #' object created by [teal_slice()] + #' specification of this filter state. + #' `teal_slice` is stored in the object and `set_state` directly manipulates values within `teal_slice`. + #' `get_state` returns `teal_slice` object which can be reused in other places. + #' Note that `teal_slice` is a `reactiveValues`, which means it has reference semantics, i.e. + #' changes made to an object are automatically reflected in all places that refer to the same `teal_slice`. #' @param extract_type (`character`) #' specifying whether condition calls should be prefixed by `dataname`. Possible values: #' - `character(0)` (default) `varname` in the condition call will not be prefixed #' - `"list"` `varname` in the condition call will be returned as `$` #' - `"matrix"` `varname` in the condition call will be returned as `[, ]` - #' @param ... additional arguments to be saved as a list in `private$extras` field #' - #' @return `self` invisibly + #' @return Object of class `FilterState`, invisibly. #' initialize = function(x, x_reactive = reactive(NULL), @@ -135,7 +138,7 @@ FilterState <- R6::R6Class( # nolint }, #' @description - #' Sets filtering state. + #' Sets mutable parameters of the filter state. #' - `fixed` state is prevented from changing state #' - `anchored` state is prevented from removing state #' @@ -173,7 +176,7 @@ FilterState <- R6::R6Class( # nolint #' @description - #' Returns filtering state. + #' Returns a complete description of the filter state. #' #' @return A `teal_slice` object. #' @@ -195,10 +198,9 @@ FilterState <- R6::R6Class( # nolint #' `shiny` module server. #' #' @param id (`character(1)`) - #' `shiny` module instance id + #' `shiny` module instance id. #' - #' @return `moduleServer` function which returns reactive value - #' signaling that remove button has been clicked + #' @return Reactive expression signaling that remove button has been clicked. #' server = function(id) { moduleServer( @@ -281,10 +283,9 @@ FilterState <- R6::R6Class( # nolint #' @description #' `shiny` UI module. - #' + #' The UI for this class contains simple message stating that it is not supported. #' @param id (`character(1)`) - #' `shiny` element (module instance) id; - #' the UI for this class contains simple message stating that it is not supported + #' `shiny` module instance id. #' @param parent_id (`character(1)`) id of the `FilterStates` card container ui = function(id, parent_id = "cards") { ns <- NS(id) @@ -375,7 +376,7 @@ FilterState <- R6::R6Class( # nolint #' @description #' Destroy observers stored in `private$observers`. #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' destroy_observers = function() { if (!is.null(private$destroy_shiny)) { @@ -419,7 +420,7 @@ FilterState <- R6::R6Class( # nolint # values are stored in `teal_slice$selected` which is reactive; # value types have to be the same as `private$get_choices()` # - # @return NULL invisibly + # @return `NULL`, invisibly. set_selected = function(value) { logger::log_trace( sprintf( @@ -446,14 +447,12 @@ FilterState <- R6::R6Class( # nolint }, # @description - # Set whether to keep NAs. + # Sets `value` in `private$teal_slice$keep_na`. # # @param value (`logical(1)`) - # value(s) which come from the filter selection. Value is set in `server` - # modules after selecting check-box-input in the shiny interface. Values are set to - # `private$teal_slice$keep_na` + # corresponding to the state of a checkbox input in the `shiny` interface. # - # @return NULL invisibly + # @return `NULL`, invisibly. # set_keep_na = function(value) { checkmate::assert_flag(value) @@ -470,12 +469,12 @@ FilterState <- R6::R6Class( # nolint }, # @description - # Set whether to keep Infs + # Sets `value` in `private$teal_slice$keep_inf`. # # @param value (`logical(1)`) - # Value(s) which come from the filter selection. Value is set in `server` - # modules after selecting check-box-input in the shiny interface. Values are set to - # `private$teal_slice$keep_inf` + # corresponding to the state of a checkbox input in the `shiny` interface. + # + # @return `NULL`, invisibly. # set_keep_inf = function(value) { checkmate::assert_flag(value) @@ -517,14 +516,16 @@ FilterState <- R6::R6Class( # nolint # @description # Get allowed values from `FilterState`. - # @return class of the returned object depends of class of the `FilterState` + # @return + # Vector describing the available choices. Return type depends on the `FilterState` subclass. get_choices = function() { shiny::isolate(private$teal_slice$choices) }, # @description # Get selected values from `FilterState`. - # @return class of the returned object depends of class of the `FilterState` + # @return + # Vector describing the current selection. Return type depends on the `FilterState` subclass. get_selected = function() { private$teal_slice$selected }, @@ -571,10 +572,8 @@ FilterState <- R6::R6Class( # nolint }, # @description - # Return variable name prefixed by `dataname` to be evaluated as extracted object, - # for example `data$var` - # @return a character string representation of a subset call - # that extracts the variable from the dataset + # Return variable name prefixed by `dataname` to be evaluated as extracted object, for example `data$var` + # @return Call that extracts the variable from the dataset. get_varname_prefixed = function(dataname) { varname <- private$get_varname() varname_backticked <- sprintf("`%s`", varname) @@ -590,12 +589,10 @@ FilterState <- R6::R6Class( # nolint }, # @description - # Adds `is.na(varname)` before existing condition calls if `keep_na` is selected. - # Otherwise, if missing values are found in the variable `!is.na` will be added - # only if `private$na_rm = TRUE` + # Adds `is.na(varname)` moiety to the existing condition call, according to `keep_na` status. # @param filter_call `call` raw filter call, as defined by selection # @param varname `character(1)` name of a variable - # @return a `call` + # @return `call` add_keep_na_call = function(filter_call, varname) { # No need to deal with NAs. if (private$na_count == 0L) { @@ -643,7 +640,7 @@ FilterState <- R6::R6Class( # nolint }, # @description - # Answers the question of whether the current settings and values selected actually filters out any values. + # Checks whether the current settings actually cause any values to be omitted. # @return logical scalar is_any_filtered = function() { if (private$is_choice_limited) { @@ -661,7 +658,7 @@ FilterState <- R6::R6Class( # nolint # @description # Server module to display filter summary - # @param id `shiny` id parameter + # @param id (`character(1)`) `shiny` module instance id. ui_summary = function(id) { ns <- NS(id) uiOutput(ns("summary"), class = "filter-card-summary") @@ -669,8 +666,8 @@ FilterState <- R6::R6Class( # nolint # @description # UI module to display filter summary - # @param shiny `id` parameter passed to `moduleServer` - # renders text describing current state + # @param id (`character(1)`) `shiny` module instance id. + # @return Nothing. Renders the UI. server_summary = function(id) { moduleServer( id = id, @@ -690,10 +687,9 @@ FilterState <- R6::R6Class( # nolint }, # @description - # module displaying inputs in a fixed filter state - # there are no input widgets, only selection visualizations - # @param id - # character string specifying this `shiny` module instance + # Module displaying inputs in a fixed filter state. + # There are no input widgets, only selection visualizations. + # @param id (`character(1)`) `shiny` module instance id. ui_inputs_fixed = function(id) { ns <- NS(id) div( @@ -703,18 +699,16 @@ FilterState <- R6::R6Class( # nolint }, # @description - # module creating the display of a fixed filter state - # @param id - # character string specifying this `shiny` module instance + # Module creating the display of a fixed filter state. + # @param id (`character(1)`) `shiny` module instance id. server_inputs_fixed = function(id) { stop("abstract class") }, # @description - # module displaying input to keep or remove NA in the FilterState call - # @param id `shiny` id parameter - # renders checkbox input only when variable from which FilterState has - # been created has some NA values. + # Module UI function displaying input to keep or remove NA in the `FilterState` call. + # Renders a checkbox input only when variable with which `FilterState` has been created contains NAs. + # @param id (`character(1)`) `shiny` module instance id. keep_na_ui = function(id) { ns <- NS(id) if (private$na_count > 0) { @@ -744,11 +738,11 @@ FilterState <- R6::R6Class( # nolint }, # @description - # module to handle NA values in the FilterState - # @param shiny `id` parameter passed to moduleServer - # module sets `private$keep_na` according to the selection. - # Module also updates a UI element if the `private$keep_na` has been - # changed through the api + # Module server function to handle NA values in the `FilterState`. + # Sets `private$slice$keep_na` according to the selection + # and updates the relevant UI element if `private$slice$keep_na` has been changed by the api. + # @param id (`character(1)`) `shiny` module instance id. + # @return `NULL`, invisibly. keep_na_srv = function(id) { moduleServer(id, function(input, output, session) { # 1. renderUI is used here as an observer which triggers only if output is visible diff --git a/R/FilterStateChoices.R b/R/FilterStateChoices.R index 54f693eb9..9fdb31776 100644 --- a/R/FilterStateChoices.R +++ b/R/FilterStateChoices.R @@ -3,7 +3,7 @@ #' @name ChoicesFilterState #' @docType class #' -#' @title `FilterState` object for factor or character variable +#' @title `FilterState` object for categorical data #' #' @description Manages choosing elements from a set. #' @@ -15,13 +15,13 @@ #' #' filter_state <- ChoicesFilterState$new( #' x = c(LETTERS, NA), -#' slice = teal_slice(varname = "x", dataname = "data") +#' slice = teal_slice(varname = "var", dataname = "data") #' ) #' isolate(filter_state$get_call()) #' filter_state$set_state( #' teal_slice( #' dataname = "data", -#' varname = "x", +#' varname = "var", #' selected = "A", #' keep_na = TRUE #' ) @@ -49,7 +49,7 @@ #' fs$ui("fs") #' )), #' column(4, div( -#' h4("Condition (i.e. call)"), # display the subsetting call generated by this FilterState +#' h4("Condition (i.e. call)"), # display the condition call generated by this FilterState #' textOutput("condition_choices"), br(), #' h4("Unformatted state"), # display raw filter state #' textOutput("unformatted_choices"), br(), @@ -119,28 +119,28 @@ ChoicesFilterState <- R6::R6Class( # nolint public = list( #' @description - #' Initialize a `InteractiveFilterState` object. + #' Initialize a `FilterState` object. #' - #' @param x (`vector`) - #' values of the variable used in filter + #' @param x (`character`) + #' variable to be filtered. #' @param x_reactive (`reactive`) #' returning vector of the same type as `x`. Is used to update #' counts following the change in values of the filtered dataset. #' If it is set to `reactive(NULL)` then counts based on filtered #' dataset are not shown. #' @param slice (`teal_slice`) - #' object created using [teal_slice()]. `teal_slice` is stored - #' in the class and `set_state` directly manipulates values within `teal_slice`. `get_state` - #' returns `teal_slice` object which can be reused in other places. Beware, that `teal_slice` - #' is a `reactiveValues` which means that changes in particular object are automatically - #' reflected in all places which refer to the same `teal_slice`. + #' specification of this filter state. + #' `teal_slice` is stored in the object and `set_state` directly manipulates values within `teal_slice`. + #' `get_state` returns `teal_slice` object which can be reused in other places. + #' Note that `teal_slice` is a `reactiveValues`, which means it has reference semantics, i.e. + #' changes made to an object are automatically reflected in all places that refer to the same `teal_slice`. #' @param extract_type (`character`) - #' whether condition calls should be prefixed by `dataname`. Possible values: + #' specifying whether condition calls should be prefixed by `dataname`. Possible values: #' - `character(0)` (default) `varname` in the condition call will not be prefixed #' - `"list"` `varname` in the condition call will be returned as `$` #' - `"matrix"` `varname` in the condition call will be returned as `[, ]` #' - #' @param ... additional arguments to be saved as a list in `private$extras` field + #' @return Object of class `ChoicesFilterState`, invisibly. #' initialize = function(x, x_reactive = reactive(NULL), @@ -195,9 +195,8 @@ ChoicesFilterState <- R6::R6Class( # nolint #' @description #' Returns reproducible condition call for current selection. #' For this class returned call looks like - #' ` %in% c()` with - #' optional `is.na()`. - #' @param dataname name of data set; defaults to `private$get_dataname()` + #' ` %in% c()` with optional `is.na()`. + #' @param dataname (`character(1)`) name of data set; defaults to `private$get_dataname()` #' @return `call` or `NULL` #' get_call = function(dataname) { @@ -355,8 +354,7 @@ ChoicesFilterState <- R6::R6Class( # nolint # UI Module for `ChoicesFilterState`. # This UI element contains available choices selection and # checkbox whether to keep or not keep the `NA` values. - # @param id (`character(1)`) - # id of shiny element + # @param id (`character(1)`) `shiny` module instance id. ui_inputs = function(id) { ns <- NS(id) @@ -428,9 +426,8 @@ ChoicesFilterState <- R6::R6Class( # nolint # @description # Server module - # @param id (`character(1)`) - # an ID string that corresponds with the ID used to call the module's UI function. - # @return `moduleServer` function which returns `NULL` + # @param id (`character(1)`) `shiny` module instance id. + # @return `NULL`. server_inputs = function(id) { moduleServer( id = id, diff --git a/R/FilterStateDate.R b/R/FilterStateDate.R index e78ea298e..f85fac02e 100644 --- a/R/FilterStateDate.R +++ b/R/FilterStateDate.R @@ -3,7 +3,7 @@ #' @name DateFilterState #' @docType class #' -#' @title `FilterState` object for `Date` variable +#' @title `FilterState` object for `Date` data #' #' @description Manages choosing a range of `Date`s. #' @@ -51,7 +51,7 @@ #' )), #' column(4, div( #' id = "outputs", # div id is needed for toggling the element -#' h4("Condition (i.e. call)"), # display the subsetting call generated by this FilterState +#' h4("Condition (i.e. call)"), # display the condition call generated by this FilterState #' textOutput("condition_date"), br(), #' h4("Unformatted state"), # display raw filter state #' textOutput("unformatted_date"), br(), @@ -116,25 +116,25 @@ DateFilterState <- R6::R6Class( # nolint #' Initialize a `FilterState` object. #' #' @param x (`Date`) - #' values of the variable used in filter + #' variable to be filtered. #' @param x_reactive (`reactive`) #' returning vector of the same type as `x`. Is used to update #' counts following the change in values of the filtered dataset. #' If it is set to `reactive(NULL)` then counts based on filtered #' dataset are not shown. #' @param slice (`teal_slice`) - #' object created using [teal_slice()]. `teal_slice` is stored - #' in the class and `set_state` directly manipulates values within `teal_slice`. `get_state` - #' returns `teal_slice` object which can be reused in other places. Beware, that `teal_slice` - #' is a `reactiveValues` which means that changes in particular object are automatically - #' reflected in all places which refer to the same `teal_slice`. + #' specification of this filter state. + #' `teal_slice` is stored in the object and `set_state` directly manipulates values within `teal_slice`. + #' `get_state` returns `teal_slice` object which can be reused in other places. + #' Note that `teal_slice` is a `reactiveValues`, which means it has reference semantics, i.e. + #' changes made to an object are automatically reflected in all places that refer to the same `teal_slice`. #' @param extract_type (`character`) - #' whether condition calls should be prefixed by `dataname`. Possible values: + #' specifying whether condition calls should be prefixed by `dataname`. Possible values: #' - `character(0)` (default) `varname` in the condition call will not be prefixed #' - `"list"` `varname` in the condition call will be returned as `$` #' - `"matrix"` `varname` in the condition call will be returned as `[, ]` #' - #' @param ... additional arguments to be saved as a list in `private$extras` field + #' @return Object of class `DateFilterState`, invisibly. #' initialize = function(x, x_reactive = reactive(NULL), @@ -162,10 +162,9 @@ DateFilterState <- R6::R6Class( # nolint #' @description #' Returns reproducible condition call for current selection. #' For this class returned call looks like - #' ` >= & <= ` with - #' optional `is.na()`. + #' ` >= & <= ` with optional `is.na()`. #' @param dataname (`character(1)`) containing possibly prefixed name of data set - #' @return `call` + #' @return `call` or `NULL` #' get_call = function(dataname) { if (isFALSE(private$is_any_filtered())) { @@ -273,8 +272,7 @@ DateFilterState <- R6::R6Class( # nolint # UI Module for `DateFilterState`. # This UI element contains two date selections for `min` and `max` # of the range and a checkbox whether to keep the `NA` values. - # @param id (`character(1)`) - # id of shiny element + # @param id (`character(1)`) `shiny` module instance id. ui_inputs = function(id) { ns <- NS(id) shiny::isolate({ @@ -313,9 +311,8 @@ DateFilterState <- R6::R6Class( # nolint # @description # Server module - # @param id (`character(1)`) - # an ID string that corresponds with the ID used to call the module's UI function. - # @return `moduleServer` function which returns `NULL` + # @param id (`character(1)`) `shiny` module instance id. + # @return `NULL`. server_inputs = function(id) { moduleServer( id = id, diff --git a/R/FilterStateDatettime.R b/R/FilterStateDatettime.R index 17f290e81..1324fa804 100644 --- a/R/FilterStateDatettime.R +++ b/R/FilterStateDatettime.R @@ -3,7 +3,7 @@ #' @rdname DatetimeFilterState #' @docType class #' -#' @title `FilterState` object for `POSIXct` variable +#' @title `FilterState` object for date time data #' #' @description Manages choosing a range of date-times. #' @@ -51,7 +51,7 @@ #' )), #' column(4, div( #' id = "outputs", # div id is needed for toggling the element -#' h4("Condition (i.e. call)"), # display the subsetting call generated by this FilterState +#' h4("Condition (i.e. call)"), # display the condition call generated by this FilterState #' textOutput("condition_datetime"), br(), #' h4("Unformatted state"), # display raw filter state #' textOutput("unformatted_datetime"), br(), @@ -126,26 +126,25 @@ DatetimeFilterState <- R6::R6Class( # nolint #' and is set only if object is initialized in `shiny`. #' #' @param x (`POSIXct` or `POSIXlt`) - #' values of the variable used in filter + #' variable to be filtered. #' @param x_reactive (`reactive`) #' returning vector of the same type as `x`. Is used to update #' counts following the change in values of the filtered dataset. #' If it is set to `reactive(NULL)` then counts based on filtered #' dataset are not shown. #' @param slice (`teal_slice`) - #' object created using [teal_slice()]. `teal_slice` is stored - #' in the class and `set_state` directly manipulates values within `teal_slice`. `get_state` - #' returns `teal_slice` object which can be reused in other places. Beware, that `teal_slice` - #' is a `reactiveValues` which means that changes in particular object are automatically - #' reflected in all places which refer to the same `teal_slice`. + #' specification of this filter state. + #' `teal_slice` is stored in the object and `set_state` directly manipulates values within `teal_slice`. + #' `get_state` returns `teal_slice` object which can be reused in other places. + #' Note that `teal_slice` is a `reactiveValues`, which means it has reference semantics, i.e. + #' changes made to an object are automatically reflected in all places that refer to the same `teal_slice`. #' @param extract_type (`character`) - #' whether condition calls should be prefixed by `dataname`. Possible values: - #' + #' specifying whether condition calls should be prefixed by `dataname`. Possible values: #' - `character(0)` (default) `varname` in the condition call will not be prefixed #' - `"list"` `varname` in the condition call will be returned as `$` #' - `"matrix"` `varname` in the condition call will be returned as `[, ]` #' - #' @param ... additional arguments to be saved as a list in `private$extras` field + #' @return Object of class `DatetimeFilterState`, invisibly. #' initialize = function(x, x_reactive = reactive(NULL), @@ -173,8 +172,7 @@ DatetimeFilterState <- R6::R6Class( # nolint #' @description #' Returns reproducible condition call for current selection. #' For this class returned call looks like - #' ` >= as.POSIXct() & <= )` - #' with optional `is.na()`. + #' ` >= as.POSIXct() & <= )` with optional `is.na()`. #' @param dataname name of data set; defaults to `private$get_dataname()` #' @return `call` #' @@ -313,8 +311,7 @@ DatetimeFilterState <- R6::R6Class( # nolint # UI Module for `DatetimeFilterState`. # This UI element contains two date-time selections for `min` and `max` # of the range and a checkbox whether to keep the `NA` values. - # @param id (`character(1)`) - # id of shiny element + # @param id (`character(1)`) `shiny` module instance id. ui_inputs = function(id) { ns <- NS(id) @@ -379,9 +376,8 @@ DatetimeFilterState <- R6::R6Class( # nolint # @description # Server module - # @param id (`character(1)`) - # an ID string that corresponds with the ID used to call the module's UI function. - # @return `moduleServer` function which returns `NULL` + # @param id (`character(1)`) `shiny` module instance id. + # @return `NULL`. server_inputs = function(id) { moduleServer( id = id, diff --git a/R/FilterStateEmpty.R b/R/FilterStateEmpty.R index 2d45b504c..e13e6c1d7 100644 --- a/R/FilterStateEmpty.R +++ b/R/FilterStateEmpty.R @@ -3,7 +3,7 @@ #' @name EmptyFilterState #' @docType class #' -#' @title `FilterState` object for empty variable +#' @title `FilterState` object for empty variables #' #' @description `FilterState` subclass representing an empty variable. #' @@ -34,25 +34,25 @@ EmptyFilterState <- R6::R6Class( # nolint #' Initialize `EmptyFilterState` object. #' #' @param x (`vector`) - #' values of the variable used in filter + #' variable to be filtered, #' @param x_reactive (`reactive`) #' returning vector of the same type as `x`. Is used to update #' counts following the change in values of the filtered dataset. #' If it is set to `reactive(NULL)` then counts based on filtered #' dataset are not shown. #' @param slice (`teal_slice`) - #' object created using [teal_slice()]. `teal_slice` is stored - #' in the class and `set_state` directly manipulates values within `teal_slice`. `get_state` - #' returns `teal_slice` object which can be reused in other places. Beware, that `teal_slice` - #' is a `reactiveValues` which means that changes in particular object are automatically - #' reflected in all places which refer to the same `teal_slice`. + #' specification of this filter state. + #' `teal_slice` is stored in the object and `set_state` directly manipulates values within `teal_slice`. + #' `get_state` returns `teal_slice` object which can be reused in other places. + #' Note that `teal_slice` is a `reactiveValues`, which means it has reference semantics, i.e. + #' changes made to an object are automatically reflected in all places that refer to the same `teal_slice`. #' @param extract_type (`character`) - #' whether condition calls should be prefixed by `dataname`. Possible values: + #' specifying whether condition calls should be prefixed by `dataname`. Possible values: #' - `character(0)` (default) `varname` in the condition call will not be prefixed #' - `"list"` `varname` in the condition call will be returned as `$` #' - `"matrix"` `varname` in the condition call will be returned as `[, ]` #' - #' @param ... additional arguments to be saved as a list in `private$extras` field + #' @return Object of class `EmptyFilterState`, invisibly. #' initialize = function(x, x_reactive = reactive(NULL), @@ -73,10 +73,8 @@ EmptyFilterState <- R6::R6Class( # nolint }, #' @description - #' Returns reproducible condition call for current selection relevant - #' for selected variable type. - #' Uses internal reactive values, hence must be called - #' in reactive or isolated context. + #' Returns reproducible condition call for current selection relevant for selected variable type. + #' Uses internal reactive values, hence must be called in reactive or isolated context. #' @param dataname name of data set; defaults to `private$get_dataname()` #' @return `logical(1)` #' @@ -110,7 +108,6 @@ EmptyFilterState <- R6::R6Class( # nolint # Reports whether the current state filters out any values.(?) - # # @return `logical(1)` # is_any_filtered = function() { @@ -124,9 +121,7 @@ EmptyFilterState <- R6::R6Class( # nolint # @description # UI Module for `EmptyFilterState`. # This UI element contains a checkbox input to filter or keep missing values. - # - # @param id (`character(1)`) - # shiny element (module instance) id + # @param id (`character(1)`) `shiny` module instance id. # ui_inputs = function(id) { ns <- NS(id) @@ -141,10 +136,9 @@ EmptyFilterState <- R6::R6Class( # nolint # @description # Controls state of the `keep_na` checkbox input. # - # @param id (`character(1)`) - # shiny module instance id + # @param id (`character(1)`) `shiny` module instance id. # - # @return `moduleServer` function which returns `NULL` + # @return `NULL`. # server_inputs = function(id) { moduleServer( diff --git a/R/FilterStateExpr.R b/R/FilterStateExpr.R index 7d64c1f13..0f1d6a4ac 100644 --- a/R/FilterStateExpr.R +++ b/R/FilterStateExpr.R @@ -5,10 +5,12 @@ #' #' @title `FilterStateExpr` `R6` class #' -#' @description Class to handle filter expression. +#' @description Sister class to `FilterState` that handles arbitrary filter expressions. #' #' @details -#' This class is responsible for displaying filter card and returning filter expression. +#' Creates a filter state around a predefined condition call (logical predicate). +#' The condition call is independent of the data +#' and the filter card allows no interaction (the filter is always fixed). #' #' @examples #' # use non-exported function from teal.slice @@ -38,7 +40,7 @@ #' filter_state$ui("fs") #' )), #' column(8, div( -#' h4("Condition (i.e. call)"), # display the subsetting call generated by this FilterState +#' h4("Condition (i.e. call)"), # display the condition call generated by this FilterState #' textOutput("condition_choices"), br(), #' h4("Unformatted state"), # display raw filter state #' textOutput("unformatted_choices"), br(), @@ -67,8 +69,8 @@ FilterStateExpr <- R6::R6Class( # nolint #' @description #' Initialize a `FilterStateExpr` object. #' @param slice (`teal_slice_expr`) - #' object created by [teal_slice()] - #' @return `FilterStateExpr` + #' @return Object of class `FilterStateExpr`, invisibly. + #' initialize = function(slice) { checkmate::assert_class(slice, "teal_slice_expr") private$teal_slice <- slice @@ -93,14 +95,15 @@ FilterStateExpr <- R6::R6Class( # nolint #' @description #' Prints this `FilterStateExpr` object. + #' @param ... arguments passed to the `format` method + #' @return `NULL`, invisibly. #' - #' @param ... additional arguments print = function(...) { cat(shiny::isolate(self$format(...))) }, #' @description - #' Returns filtering state. + #' Returns a complete description of this filter state. #' #' @return A `teal_slice` object. #' @@ -109,11 +112,11 @@ FilterStateExpr <- R6::R6Class( # nolint }, #' @description - #' Sets filtering state. + #' Does nothing. Exists for compatibility. #' #' @param state (`teal_slice`) #' - #' @return `self` invisibly + #' @return `self`, invisibly. #' set_state = function(state) { checkmate::assert_class(state, "teal_slice_expr") @@ -129,7 +132,9 @@ FilterStateExpr <- R6::R6Class( # nolint #' for selected variable type. #' Method is using internal reactive values which makes it reactive #' and must be executed in reactive or isolated context. - #' @return `language` + #' + #' @return `call` or `NULL` + #' get_call = function(dataname) { shiny::isolate(str2lang(private$teal_slice$expr)) }, @@ -137,7 +142,7 @@ FilterStateExpr <- R6::R6Class( # nolint #' @description #' Destroy observers stored in `private$observers`. #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' destroy_observers = function() { lapply(private$observers, function(x) x$destroy()) @@ -154,10 +159,9 @@ FilterStateExpr <- R6::R6Class( # nolint #' `shiny` module server. #' #' @param id (`character(1)`) - #' `shiny` module instance id + #' `shiny` module instance id. #' - #' @return `moduleServer` function which returns reactive value - #' signaling that remove button has been clicked + #' @return Reactive expression signaling that the remove button has been clicked. #' server = function(id) { moduleServer( @@ -178,11 +182,11 @@ FilterStateExpr <- R6::R6Class( # nolint #' @description #' `shiny` module UI. - #' + #' The UI for this class contains simple message stating that it is not supported. #' @param id (`character(1)`) - #' `shiny` element (module instance) id; - #' the UI for this class contains simple message stating that it is not supported - #' @param parent_id (`character(1)`) id of the `FilterStates` card container + #' `shiny` module instance id. + #' @param parent_id (`character(1)`) + #' id of the `FilterStates` card container. ui = function(id, parent_id = "cards") { ns <- NS(id) shiny::isolate({ diff --git a/R/FilterStateLogical.R b/R/FilterStateLogical.R index 091a14a25..69b3c0408 100644 --- a/R/FilterStateLogical.R +++ b/R/FilterStateLogical.R @@ -3,7 +3,7 @@ #' @name LogicalFilterState #' @docType class #' -#' @title `FilterState` object for logical variable +#' @title `FilterState` object for logical data #' #' @description Manages choosing a logical state. #' @@ -43,7 +43,7 @@ #' )), #' column(4, div( #' id = "outputs", # div id is needed for toggling the element -#' h4("Condition (i.e. call)"), # display the subsetting call generated by this FilterState +#' h4("Condition (i.e. call)"), # display the condition call generated by this FilterState #' textOutput("condition_logical"), br(), #' h4("Unformatted state"), # display raw filter state #' textOutput("unformatted_logical"), br(), @@ -102,25 +102,25 @@ LogicalFilterState <- R6::R6Class( # nolint #' Initialize a `FilterState` object. #' #' @param x (`logical`) - #' values of the variable used in filter + #' variable to be filtered. #' @param x_reactive (`reactive`) #' returning vector of the same type as `x`. Is used to update #' counts following the change in values of the filtered dataset. #' If it is set to `reactive(NULL)` then counts based on filtered #' dataset are not shown. #' @param slice (`teal_slice`) - #' object created using [teal_slice()]. `teal_slice` is stored - #' in the class and `set_state` directly manipulates values within `teal_slice`. `get_state` - #' returns `teal_slice` object which can be reused in other places. Beware, that `teal_slice` - #' is a `reactiveValues` which means that changes in particular object are automatically - #' reflected in all places which refer to the same `teal_slice`. + #' specification of this filter state. + #' `teal_slice` is stored in the object and `set_state` directly manipulates values within `teal_slice`. + #' `get_state` returns `teal_slice` object which can be reused in other places. + #' Note that `teal_slice` is a `reactiveValues`, which means it has reference semantics, i.e. + #' changes made to an object are automatically reflected in all places that refer to the same `teal_slice`. #' @param extract_type (`character`) - #' whether condition calls should be prefixed by `dataname`. Possible values: + #' specifying whether condition calls should be prefixed by `dataname`. Possible values: #' - `character(0)` (default) `varname` in the condition call will not be prefixed #' - `"list"` `varname` in the condition call will be returned as `$` #' - `"matrix"` `varname` in the condition call will be returned as `[, ]` #' - #' @param ... additional arguments to be saved as a list in `private$extras` field + #' @return Object of class `LogicalFilterState`, invisibly. #' initialize = function(x, x_reactive = reactive(NULL), @@ -148,8 +148,7 @@ LogicalFilterState <- R6::R6Class( # nolint #' @description #' Returns reproducible condition call for current selection. - #' For `LogicalFilterState` it's a `!` or `` and optionally - #' `is.na()` + #' For `LogicalFilterState` it's a `!` or `` and optionally `is.na()` #' @param dataname name of data set; defaults to `private$get_dataname()` #' @return `call` #' @@ -236,8 +235,7 @@ LogicalFilterState <- R6::R6Class( # nolint # UI Module for `EmptyFilterState`. # This UI element contains available choices selection and # checkbox whether to keep or not keep the `NA` values. - # @param id (`character(1)`) - # id of shiny element + # @param id (`character(1)`) `shiny` module instance id. ui_inputs = function(id) { ns <- NS(id) shiny::isolate({ @@ -286,10 +284,8 @@ LogicalFilterState <- R6::R6Class( # nolint # @description # Server module - # - # @param id (`character(1)`) - # an ID string that corresponds with the ID used to call the module's UI function. - # @return `moduleServer` function which returns `NULL` + # @param id (`character(1)`) `shiny` module instance id. + # @return `NULL`. server_inputs = function(id) { moduleServer( id = id, diff --git a/R/FilterStateRange.R b/R/FilterStateRange.R index f18e5d4e8..7abc49f7c 100644 --- a/R/FilterStateRange.R +++ b/R/FilterStateRange.R @@ -3,7 +3,7 @@ #' @name RangeFilterState #' @docType class #' -#' @title `FilterState` object for numeric variable +#' @title `FilterState` object for numeric data #' #' @description Manages choosing a numeric range. #' @@ -54,7 +54,7 @@ #' )), #' column(4, div( #' id = "outputs", # div id is needed for toggling the element -#' h4("Condition (i.e. call)"), # display the subsetting call generated by this FilterState +#' h4("Condition (i.e. call)"), # display the condition call generated by this FilterState #' textOutput("condition_range"), br(), #' h4("Unformatted state"), # display raw filter state #' textOutput("unformatted_range"), br(), @@ -128,25 +128,25 @@ RangeFilterState <- R6::R6Class( # nolint #' @description #' Initialize a `FilterState` object for range selection. #' @param x (`numeric`) - #' values of the variable used in filter + #' variable to be filtered. #' @param x_reactive (`reactive`) #' returning vector of the same type as `x`. Is used to update #' counts following the change in values of the filtered dataset. #' If it is set to `reactive(NULL)` then counts based on filtered #' dataset are not shown. #' @param slice (`teal_slice`) - #' object created using [teal_slice()]. `teal_slice` is stored - #' in the class and `set_state` directly manipulates values within `teal_slice`. `get_state` - #' returns `teal_slice` object which can be reused in other places. Beware, that `teal_slice` - #' is a `reactiveValues` which means that changes in particular object are automatically - #' reflected in all places which refer to the same `teal_slice`. + #' specification of this filter state. + #' `teal_slice` is stored in the object and `set_state` directly manipulates values within `teal_slice`. + #' `get_state` returns `teal_slice` object which can be reused in other places. + #' Note that `teal_slice` is a `reactiveValues`, which means it has reference semantics, i.e. + #' changes made to an object are automatically reflected in all places that refer to the same `teal_slice`. #' @param extract_type (`character`) - #' whether condition calls should be prefixed by `dataname`. Possible values: + #' specifying whether condition calls should be prefixed by `dataname`. Possible values: #' - `character(0)` (default) `varname` in the condition call will not be prefixed #' - `"list"` `varname` in the condition call will be returned as `$` #' - `"matrix"` `varname` in the condition call will be returned as `[, ]` #' - #' @param ... additional arguments to be saved as a list in `private$extras` field + #' @return Object of class `RangeFilterState`, invisibly. #' initialize = function(x, x_reactive = reactive(NULL), @@ -403,8 +403,7 @@ RangeFilterState <- R6::R6Class( # nolint # UI Module for `RangeFilterState`. # This UI element contains two values for `min` and `max` # of the range and two checkboxes whether to keep the `NA` or `Inf` values. - # @param id (`character(1)`) - # id of shiny element + # @param id (`character(1)`) `shiny` module instance id. ui_inputs = function(id) { ns <- NS(id) shiny::isolate({ @@ -475,9 +474,8 @@ RangeFilterState <- R6::R6Class( # nolint # @description # Server module - # @param id (`character(1)`) - # an ID string that corresponds with the ID used to call the module's UI function. - # return `moduleServer` function which returns `NULL` + # @param id (`character(1)`) `shiny` module instance id. + # return `NULL`. server_inputs = function(id) { moduleServer( id = id, @@ -656,10 +654,9 @@ RangeFilterState <- R6::R6Class( # nolint }, # @description - # module displaying input to keep or remove Inf in the FilterState call - # @param id `shiny` id parameter - # renders checkbox input only when variable from which FilterState has - # been created has some Inf values. + # Module displaying input to keep or remove NA in the `FilterState` call. + # Renders a checkbox input only when variable with which the `FilterState` has been created contains Infs. + # @param id (`character(1)`) `shiny` module instance id. keep_inf_ui = function(id) { ns <- NS(id) @@ -688,11 +685,11 @@ RangeFilterState <- R6::R6Class( # nolint }, # @description - # module to handle Inf values in the FilterState - # @param shiny `id` parametr passed to moduleServer - # module sets `private$teal_slice$keep_inf` according to the selection. - # Module also updates a UI element if the `private$teal_slice$keep_inf` has been - # changed through the api + # Module to handle Inf values in the FilterState + # Sets `private$slice$keep_inf` according to the selection + # and updates the relevant UI element if `private$slice$keep_inf` has been changed by the api. + # @param id (`character(1)`) `shiny` module instance id. + # @return `NULL`. keep_inf_srv = function(id) { moduleServer(id, function(input, output, session) { # 1. renderUI is used here as an observer which triggers only if output is visible diff --git a/R/FilterStates-utils.R b/R/FilterStates-utils.R index 2301e7f0e..1e1274a43 100644 --- a/R/FilterStates-utils.R +++ b/R/FilterStates-utils.R @@ -1,21 +1,22 @@ #' Initialize `FilterStates` object #' #' @param data (`data.frame` or `MultiAssayExperiment` or `SummarizedExperiment` or `matrix`) -#' the `R` object which `subset` function is applied on. +#' object to subset. #' @param data_reactive (`function(sid)`) #' should return an object of the same type as `data` or `NULL`. -#' This object is needed for the `FilterState` `shiny` module to update -#' counts if filtered data changes. -#' If function returns `NULL` then filtered counts -#' are not shown. Function has to have `sid` argument being a character which -#' is related to `sid` argument in the `get_call` method. +#' This function is needed for the `FilterState` `shiny` module to update counts if filtered data changes. +#' If function returns `NULL` then filtered counts are not shown. +#' Function has to have `sid` argument being a character which is related to `sid` argument in the `get_call` method. #' @param dataname (`character(1)`) -#' name of the data used in the expression -#' specified to the function argument attached to this `FilterStates`. -#' @param datalabel (`NULL` or `character(1)`) -#' text label value. +#' name of the data used in the subset expression, +#' passed to the function argument attached to this `FilterStates`. +#' @param datalabel (`character(1)`) +#' optional text label. #' @param ... (optional) #' additional arguments for specific classes: keys. +#' +#' @return Object of class `FilterStates`. +#' #' @keywords internal #' @examples #' # use non-exported function from teal.slice @@ -138,7 +139,7 @@ init_filter_states.SummarizedExperiment <- function(data, # nolint #' of classes in an vector `teal.slice:::.filterable_class`. #' @param data #' the `R` object containing elements which class can be checked through `vapply` or `apply`. -#' @return `character` vector of matched element names +#' @return `character` vector of variable names. #' @examples #' # use non-exported function from teal.slice #' get_supported_filter_varnames <- getFromNamespace("get_supported_filter_varnames", "teal.slice") @@ -152,6 +153,7 @@ init_filter_states.SummarizedExperiment <- function(data, # nolint #' ) #' get_supported_filter_varnames(df) #' @keywords internal +#' @export get_supported_filter_varnames <- function(data) { UseMethod("get_supported_filter_varnames") } @@ -212,7 +214,7 @@ data_choices_labeled <- function(data, if (length(choices) == 0) { return(character(0)) } - choice_types <- stats::setNames(variable_types(data = data, columns = choices), choices) + choice_types <- variable_types(data = data, columns = choices) choice_types[keys] <- "primary_key" choices_labeled( diff --git a/R/FilterStates.R b/R/FilterStates.R index ebec24e41..fddd88cfe 100644 --- a/R/FilterStates.R +++ b/R/FilterStates.R @@ -8,7 +8,7 @@ #' Abstract class that manages adding and removing `FilterState` objects #' and builds a *subset expression*. #' -#' A `FilterStates` object tracks all subsetting expressions +#' A `FilterStates` object tracks all condition calls #' (logical predicates that limit observations) associated with a given dataset #' and composes them into a single reproducible `R` expression #' that will assign a subset of the original data to a new variable. @@ -38,13 +38,13 @@ FilterStates <- R6::R6Class( # nolint #' on a change in filters. If function returns `NULL` then filtered counts are not shown. #' Function has to have `sid` argument being a character. #' @param dataname (`character(1)`) - #' name of the data used in the expression - #' specified to the function argument attached to this `FilterStates` - #' @param datalabel (`NULL` or `character(1)`) - #' text label value + #' name of the dataset, used in the subset expression. + #' Passed to the function argument attached to this `FilterStates`. + #' @param datalabel (`character(1)`) + #' optional text label. #' #' @return - #' self invisibly + #' Object of class `FilterStates`, invisibly. #' initialize = function(data, data_reactive = function(sid = "") NULL, @@ -118,7 +118,7 @@ FilterStates <- R6::R6Class( # nolint #' If no filters are applied, `NULL` is returned to avoid no-op calls such as `dataname <- dataname`. #' #' @param sid (`character`) - #' when specified then method returns code containing filter conditions of + #' when specified then method returns code containing condition calls (logical predicates) of #' `FilterState` objects which `"sid"` attribute is different than this `sid` argument. #' #' @return `call` or `NULL` @@ -186,7 +186,7 @@ FilterStates <- R6::R6Class( # nolint #' @description #' Prints this `FilterStates` object. #' - #' @param ... additional arguments + #' @param ... additional arguments passed to `format`. print = function(...) { cat(shiny::isolate(self$format(...)), "\n") }, @@ -198,7 +198,7 @@ FilterStates <- R6::R6Class( # nolint #' specifying `FilterState` objects to remove; #' `teal_slice`s may contain only `dataname` and `varname`, other elements are ignored #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' remove_filter_state = function(state) { checkmate::assert_class(state, "teal_slices") @@ -216,7 +216,7 @@ FilterStates <- R6::R6Class( # nolint #' Get active filter state from `FilterState` objects stored in `state_list`(s). #' The output is a list compatible with input to `self$set_filter_state`. #' - #' @return `list` containing `list` per `FilterState` in the `state_list` + #' @return Object of class `teal_slices`. #' get_filter_state = function() { slices <- unname(lapply(private$state_list(), function(x) x$get_state())) @@ -238,16 +238,13 @@ FilterStates <- R6::R6Class( # nolint ) } - return(fs) + fs }, #' @description #' Sets active `FilterState` objects. - #' - #' @param data (`data.frame`) - #' data which are supposed to be filtered #' @param state (`teal_slices`) - #' @return function which throws an error + #' @return Function that raises an error. set_filter_state = function(state) { shiny::isolate({ logger::log_trace("{ class(self)[1] }$set_filter_state initializing, dataname: { private$dataname }") @@ -293,9 +290,9 @@ FilterStates <- R6::R6Class( # nolint #' Remove all `FilterState` objects from this `FilterStates` object. #' #' @param force (`logical(1)`) - #' include locked filter states + #' flag specifying whether to include anchored filter states. #' - #' @return `NULL`, invisibly + #' @return `NULL`, invisibly. #' clear_filter_states = function(force = FALSE) { private$state_list_empty(force) @@ -309,7 +306,7 @@ FilterStates <- R6::R6Class( # nolint #' Populated with elements created with `renderUI` in the module server. #' #' @param id (`character(1)`) - #' `shiny` element (module instance) id + #' `shiny` module instance id. #' #' @return `shiny.tag` #' @@ -330,9 +327,9 @@ FilterStates <- R6::R6Class( # nolint #' `shiny` server module. #' #' @param id (`character(1)`) - #' `shiny` module instance id + #' `shiny` module instance id. #' - #' @return `moduleServer` function which returns `NULL` + #' @return `NULL`. #' srv_active = function(id) { moduleServer( @@ -399,7 +396,7 @@ FilterStates <- R6::R6Class( # nolint #' `shiny` UI module to add filter variable. #' #' @param id (`character(1)`) - #' `shiny` element (module instance) id + #' `shiny` module instance id. #' #' @return `shiny.tag` #' @@ -426,9 +423,9 @@ FilterStates <- R6::R6Class( # nolint #' Removing a filter variable adds it back to available choices. #' #' @param id (`character(1)`) - #' an id string that corresponds with the id used to call the module's `ui_add` function. + #' `shiny` module instance id. #' - #' @return `moduleServer` function which returns `NULL` + #' @return `NULL`. srv_add = function(id) { moduleServer( id = id, @@ -534,7 +531,7 @@ FilterStates <- R6::R6Class( # nolint # is called `include_varnames` is cleared - same otherwise. # are included. # - # @return NULL invisibly + # @return `NULL`, invisibly. set_filterable_varnames = function(include_varnames = character(0), exclude_varnames = character(0)) { if ((length(include_varnames) + length(exclude_varnames)) == 0L) { return(invisible(NULL)) @@ -604,7 +601,7 @@ FilterStates <- R6::R6Class( # nolint # @param state_id (`character(1)`) # name of element in a filter state (which is a `reactiveVal` containing a list) # - # @return NULL + # @return `NULL`. # state_list_push = function(x, state_id) { logger::log_trace("{ class(self)[1] } pushing into state_list, dataname: { private$dataname }") @@ -628,11 +625,11 @@ FilterStates <- R6::R6Class( # nolint # * observers tracking the selection and remove button # # @param state_id (`character`) - # names of element in a filter state (which is a `reactiveVal` containing a list) + # identifiers of elements in a filter state (which is a `reactiveVal` containing a list). # @param force (`logical(1)`) - # include locked filter states + # flag specifying whether to include anchored filter states. # - # @return NULL + # @return `NULL`, invisibly. # state_list_remove = function(state_id, force = FALSE) { checkmate::assert_character(state_id) @@ -669,8 +666,8 @@ FilterStates <- R6::R6Class( # nolint # @description # Remove all `FilterState` objects from this `FilterStates` object. # @param force (`logical(1)`) - # include locked filter states - # @return invisible NULL + # flag specifying whether to include anchored filter states. + # @return `NULL`, invisibly. # state_list_empty = function(force = FALSE) { shiny::isolate({ @@ -696,9 +693,9 @@ FilterStates <- R6::R6Class( # nolint # @param state (`teal_slices`) # @param data (`data.frame`, `matrix` or `DataFrame`) # @param data_reactive (`function`) - # function having `sid` as argument + # function having `sid` as argument. # - # @return invisible NULL + # @return `NULL`, invisibly. # set_filter_state_impl = function(state, data, diff --git a/R/FilterStatesDF.R b/R/FilterStatesDF.R index c99953675..31ed75d84 100644 --- a/R/FilterStatesDF.R +++ b/R/FilterStatesDF.R @@ -52,7 +52,7 @@ #' column(4, div( #' h4("Manual filter control"), #' filter_states_df$ui_add("add_filters"), br(), -#' h4("Condition (i.e. call)"), # display the subsetting call generated by this FilterStates +#' h4("Condition (i.e. call)"), # display the subset expression generated by this FilterStates #' textOutput("call_df"), br(), #' h4("Formatted state"), # display human readable filter state #' textOutput("formatted_df"), br() @@ -164,19 +164,19 @@ DFFilterStates <- R6::R6Class( # nolint #' (`dplyr::filter`), a list of conditions is passed to unnamed arguments (`...`). #' #' @param data (`data.frame`) - #' the `R` object which `dplyr::filter` function is applied on. + #' the `R` object which `dplyr::filter` function will be applied on. #' @param data_reactive (`function(sid)`) #' should return a `data.frame` object or `NULL`. - #' This object is needed for the `FilterState` counts being updated - #' on a change in filters. If function returns `NULL` then filtered counts are not shown. + #' This object is needed for the `FilterState` counts being updated on a change in filters. + #' If function returns `NULL` then filtered counts are not shown. #' Function has to have `sid` argument being a character. #' @param dataname (`character`) - #' name of the data used in the *subset expression* - #' specified to the function argument attached to this `FilterStates` - #' @param datalabel (`NULL` or `character(1)`) - #' text label value + #' name of the data used in the *subset expression*. + #' Passed to the function argument attached to this `FilterStates`. + #' @param datalabel (`character(1)`) + #' optional text label. #' @param keys (`character`) - #' key columns names + #' key column names. #' initialize = function(data, data_reactive = function(sid = "") NULL, diff --git a/R/FilterStatesMAE.R b/R/FilterStatesMAE.R index f17ba3cf0..aa6eae43a 100644 --- a/R/FilterStatesMAE.R +++ b/R/FilterStatesMAE.R @@ -2,7 +2,7 @@ #' @name MAEFilterStates #' @docType class -#' @title `FilterStates` subclass for `MultiAssayExperiments` +#' @title `FilterStates` subclass for `MultiAssayExperiment`s #' @description Handles filter states in a `MultiAssayExperiment`. #' @keywords internal #' @@ -22,14 +22,14 @@ MAEFilterStates <- R6::R6Class( # nolint #' on a change in filters. If function returns `NULL` then filtered counts are not shown. #' Function has to have `sid` argument being a character. #' @param dataname (`character(1)`) - #' name of the data used in the expression - #' specified to the function argument attached to this `FilterStates`. - #' @param datalabel (`NULL` or `character(1)`) - #' text label value + #' name of the data used in the subset expression. + #' Passed to the function argument attached to this `FilterStates`. + #' @param datalabel (`character(1)`) + #' optional text label. #' @param varlabels (`character`) - #' labels of the variables used in this object + #' labels of the variables used in this object. #' @param keys (`character`) - #' key columns names + #' key column names. #' initialize = function(data, data_reactive = function(sid = "") NULL, diff --git a/R/FilterStatesMatrix.R b/R/FilterStatesMatrix.R index 1cd0faf69..4392d8d2e 100644 --- a/R/FilterStatesMatrix.R +++ b/R/FilterStatesMatrix.R @@ -6,7 +6,6 @@ #' @description Handles filter states in a `matrix`. #' @keywords internal #' -#' MatrixFilterStates <- R6::R6Class( # nolint classname = "MatrixFilterStates", inherit = FilterStates, @@ -20,14 +19,14 @@ MatrixFilterStates <- R6::R6Class( # nolint #' the `R` object which `subset` function is applied on. #' @param data_reactive (`function(sid)`) #' should return a `matrix` object or `NULL`. - #' This object is needed for the `FilterState` counts being updated - #' on a change in filters. If function returns `NULL` then filtered counts are not shown. + #' This object is needed for the `FilterState` counts being updated on a change in filters. + #' If function returns `NULL` then filtered counts are not shown. #' Function has to have `sid` argument being a character. #' @param dataname (`character(1)`) - #' name of the data used in the expression - #' specified to the function argument attached to this `FilterStates`. - #' @param datalabel (`NULL` or `character(1)`) - #' text label value. Should be a name of experiment. + #' name of the data used in the subset expression. + #' Passed to the function argument attached to this `FilterStates`. + #' @param datalabel (`character(1)`) + #' Optional text label. Should be a name of experiment. #' initialize = function(data, data_reactive = function(sid = "") NULL, diff --git a/R/FilterStatesSE.R b/R/FilterStatesSE.R index 56ee031ab..e3f436d40 100644 --- a/R/FilterStatesSE.R +++ b/R/FilterStatesSE.R @@ -2,7 +2,7 @@ #' @name SEFilterStates #' @docType class -#' @title `FilterStates` subclass for `SummarizedExperiments` +#' @title `FilterStates` subclass for `SummarizedExperiment`s #' @description Handles filter states in a `SummaryExperiment`. #' @keywords internal #' @@ -19,14 +19,14 @@ SEFilterStates <- R6::R6Class( # nolint #' the `R` object which `subset` function is applied on. #' @param data_reactive (`function(sid)`) #' should return a `SummarizedExperiment` object or `NULL`. - #' This object is needed for the `FilterState` counts being updated - #' on a change in filters. If function returns `NULL` then filtered counts are not shown. + #' This object is needed for the `FilterState` counts being updated on a change in filters. + #' If function returns `NULL` then filtered counts are not shown. #' Function has to have `sid` argument being a character. #' @param dataname (`character(1)`) #' name of the data used in the expression #' specified to the function argument attached to this `FilterStates`. - #' @param datalabel (`NULL` or `character(1)`) - #' text label value. Should be a name of experiment + #' @param datalabel (`character(1)`) + #' optional text label. Should be the name of experiment. #' initialize = function(data, data_reactive = function(sid = "") NULL, @@ -49,7 +49,7 @@ SEFilterStates <- R6::R6Class( # nolint #' @param state (`teal_slices`) #' `teal_slice` objects should contain the field `arg %in% c("subset", "select")` #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' set_filter_state = function(state) { shiny::isolate({ @@ -95,7 +95,7 @@ SEFilterStates <- R6::R6Class( # nolint #' @description #' `shiny` UI module to add filter variable. #' @param id (`character(1)`) - #' id of `shiny` module + #' `shiny` module instance id. #' @return `shiny.tag` ui_add = function(id) { data <- private$data @@ -148,8 +148,8 @@ SEFilterStates <- R6::R6Class( # nolint #' `rowData`. #' #' @param id (`character(1)`) - #' an id string that corresponds with the id used to call the module's `ui_add` function. - #' @return `moduleServer` function which returns `NULL` + #' `shiny` module instance id. + #' @return `NULL` srv_add = function(id) { data <- private$data data_reactive <- private$data_reactive diff --git a/R/FilteredData-utils.R b/R/FilteredData-utils.R index d0d819b53..3d989f28e 100644 --- a/R/FilteredData-utils.R +++ b/R/FilteredData-utils.R @@ -2,13 +2,17 @@ #' #' Function creates a `FilteredData` object. #' -#' @param x (named `list`) of datasets. +#' @param x (`named list`) of datasets. #' @param join_keys (`join_keys`) see [`teal.data::join_keys()`]. #' @param code `r lifecycle::badge("deprecated")` #' @param check `r lifecycle::badge("deprecated")` +#' +#' @return Object of class `FilteredData`. +#' #' @examples #' datasets <- init_filtered_data(list(iris = iris, mtcars = mtcars)) #' datasets +#' #' @export init_filtered_data <- function(x, join_keys = teal.data::join_keys(), code, check) { # nolint checkmate::assert_list(x, any.missing = FALSE, names = "unique") @@ -36,7 +40,7 @@ init_filtered_data <- function(x, join_keys = teal.data::join_keys(), code, chec #' #' @param expr (`language`) #' @param env (`environment`) where expression is evaluated. -#' @return `NULL` invisibly. +#' @return `NULL`, invisibly. #' @keywords internal eval_expr_with_msg <- function(expr, env) { lapply( @@ -53,9 +57,9 @@ eval_expr_with_msg <- function(expr, env) { ) } ) - return(invisible(NULL)) } ) + invisible(NULL) } @@ -77,7 +81,8 @@ eval_expr_with_msg <- function(expr, env) { #' if TRUE, the target will be changed #' from the first element of `icons`/`titles` to the second #' -#' @return `NULL` invisibly +#' @return `NULL`, invisibly. +#' #' @examples #' # use non-exported function from teal.slice #' toggle_icon <- getFromNamespace("toggle_icon", "teal.slice") @@ -128,6 +133,7 @@ eval_expr_with_msg <- function(expr, env) { #' if (interactive()) { #' shinyApp(ui, server) #' } +#' #' @name toggle_button #' @rdname toggle_button #' @keywords internal diff --git a/R/FilteredData.R b/R/FilteredData.R index 4ab600d01..58d36cd59 100644 --- a/R/FilteredData.R +++ b/R/FilteredData.R @@ -6,7 +6,7 @@ #' @title Class to encapsulate filtered datasets #' #' @description -#' Class is designed to manage and encapsulate filtered datasets. +#' Manages filtering of all datasets in the application or module. #' #' @details #' The main purpose of this class is to provide a collection of reactive datasets, @@ -57,6 +57,7 @@ #' isolate(datasets$get_filter_state()) #' isolate(datasets$get_call("iris")) #' isolate(datasets$get_call("mtcars")) +#' #' @examplesIf requireNamespace("MultiAssayExperiment") #' ### set_filter_state #' @@ -93,10 +94,10 @@ FilteredData <- R6::R6Class( # nolint public = list( #' @description #' Initialize a `FilteredData` object. - #' @param data_objects (`list`) - #' Named list of data objects. - #' Names of the list will serve as `dataname`. - #' @param join_keys (`join_keys` or NULL) see [`teal.data::join_keys()`]. + #' @param data_objects (`named list`) + #' List of data objects. + #' Names of the list will be used as `dataname` for respective datasets. + #' @param join_keys (`join_keys`) optional joining keys, see [`teal.data::join_keys()`]. #' initialize = function(data_objects, join_keys = teal.data::join_keys()) { checkmate::assert_list(data_objects, any.missing = FALSE, min.len = 0, names = "unique") @@ -134,9 +135,8 @@ FilteredData <- R6::R6Class( # nolint #' @description #' Gets `datanames`. #' @details - #' The `datanames` are returned in the order in which they must be - #' evaluated (in case of dependencies). - #' @return `character` vector of `datanames` + #' The `datanames` are returned in the order in which they must be evaluated (in case of dependencies). + #' @return Character vector. datanames = function() { names(private$filtered_datasets) }, @@ -146,7 +146,7 @@ FilteredData <- R6::R6Class( # nolint #' Useful to display in `Show R Code`. #' #' @param dataname (`character(1)`) name of the dataset - #' @return `character` keys of dataset + #' @return Character string. get_datalabel = function(dataname) { private$get_filtered_dataset(dataname)$get_dataset_label() }, @@ -161,7 +161,7 @@ FilteredData <- R6::R6Class( # nolint #' List is accessible in `ui/srv_active` through `ui/srv_available_filters`. #' @param x (`reactive`) #' should return `teal_slices` - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. set_available_teal_slices = function(x) { checkmate::assert_class(x, "reactive") private$available_teal_slices <- reactive({ @@ -192,7 +192,7 @@ FilteredData <- R6::R6Class( # nolint #' All `teal_slice` objects that have been created since the beginning of the app session #' are stored in one `teal_slices` object. This returns a subset of that `teal_slices`, #' describing filter states that can be set for this object. - #' @return `reactive` that returns `teal_slices` + #' @return `reactive` that returns `teal_slices`. get_available_teal_slices = function() { private$available_teal_slices }, @@ -219,7 +219,7 @@ FilteredData <- R6::R6Class( # nolint #' #' @param dataname (`character(1)`) name of the dataset #' - #' @return (`call` or `list` of calls) to filter dataset calls + #' @return A list of `call`s. #' get_call = function(dataname) { checkmate::assert_subset(dataname, self$datanames()) @@ -229,11 +229,12 @@ FilteredData <- R6::R6Class( # nolint #' @description #' Gets filtered or unfiltered dataset. #' - #' For `filtered = FALSE`, the original data set with - #' `set_data` is returned including all attributes. + #' For `filtered = FALSE`, the original data set with `set_data` is returned including all attributes. #' - #' @param dataname (`character(1)`) name of the dataset - #' @param filtered (`logical`) whether to return a filtered or unfiltered dataset + #' @param dataname (`character(1)`) name of the dataset. + #' @param filtered (`logical(1)`) whether to return a filtered or unfiltered dataset. + #' + #' @return A data object, a `data.frame` or a `MultiAssayExperiment`. #' get_data = function(dataname, filtered = TRUE) { checkmate::assert_subset(dataname, self$datanames()) @@ -252,14 +253,13 @@ FilteredData <- R6::R6Class( # nolint }, #' @description - #' Get filter overview table in form of `X (filtered) / Y (non-filtered)`. + #' Creates filter overview table to be displayed in the application. + #' One row is created per dataset, according to the `get_filter_overview` methods + #' of the contained `FilteredDataset` objects. #' - #' This is intended to be presented in the application. - #' The content for each of the data names is defined in `get_filter_overview_info` method. + #' @param datanames (`character`) vector of dataset names. #' - #' @param datanames (`character`) vector of dataset names - #' - #' @return `matrix` of observations and subjects of all datasets + #' @return A `data.frame` listing the numbers of observations in all datasets. #' get_filter_overview = function(datanames) { rows <- lapply( @@ -275,9 +275,9 @@ FilteredData <- R6::R6Class( # nolint #' @description #' Get keys for the dataset. #' - #' @param dataname (`character(1)`) name of the dataset + #' @param dataname (`character(1)`) name of the dataset. #' - #' @return `character` keys of dataset + #' @return Character vector of key column names. #' get_keys = function(dataname) { private$get_filtered_dataset(dataname)$get_keys() @@ -296,10 +296,10 @@ FilteredData <- R6::R6Class( # nolint #' @param data (`data.frame` or `MultiAssayExperiment`) #' data to be filtered. #' - #' @param dataname (`string`) - #' the name of the `dataset` to be added to this object + #' @param dataname (`character(1)`) + #' the name of the `dataset` to be added to this object. #' - #' @return `self` invisibly + #' @return `self`, invisibly. #' set_dataset = function(data, dataname) { checkmate::assert_string(dataname) @@ -337,9 +337,9 @@ FilteredData <- R6::R6Class( # nolint #' @description #' Set the `join_keys`. #' - #' @param join_keys (`join_keys`) join_key (converted to a nested list) + #' @param join_keys (`join_keys`), see [`teal.data::join_keys()`]. #' - #' @return `self` invisibly + #' @return `self`, invisibly. #' set_join_keys = function(join_keys) { checkmate::assert_class(join_keys, "join_keys") @@ -350,7 +350,7 @@ FilteredData <- R6::R6Class( # nolint # Functions useful for restoring from another dataset ---- #' @description - #' Gets states of all active `FilterState` objects. + #' Gets states of all contained `FilterState` objects. #' #' @return A `teal_slices` object. #' @@ -367,10 +367,10 @@ FilteredData <- R6::R6Class( # nolint #' @description #' Returns a formatted string representing this `FilteredData` object. #' - #' @param show_all (`logical(1)`) passed to `format.teal_slice` - #' @param trim_lines (`logical(1)`) passed to `format.teal_slice` + #' @param show_all (`logical(1)`) passed to `format.teal_slice`. + #' @param trim_lines (`logical(1)`) passed to `format.teal_slice`. #' - #' @return `character(1)` the formatted string + #' @return `character(1)` the formatted string. #' format = function(show_all = FALSE, trim_lines = TRUE) { datasets <- lapply(self$datanames(), private$get_filtered_dataset) @@ -389,7 +389,7 @@ FilteredData <- R6::R6Class( # nolint #' @description #' Prints this `FilteredData` object. #' - #' @param ... additional arguments + #' @param ... additional arguments passed to `format`. #' print = function(...) { cat(shiny::isolate(self$format(...)), "\n") @@ -400,7 +400,7 @@ FilteredData <- R6::R6Class( # nolint #' #' @param state (`teal_slices`) #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. set_filter_state = function(state) { shiny::isolate({ logger::log_trace("{ class(self)[1] }$set_filter_state initializing") @@ -426,9 +426,9 @@ FilteredData <- R6::R6Class( # nolint #' #' @param state (`teal_slices`) #' specifying `FilterState` objects to remove; - #' `teal_slice`s may contain only `dataname` and `varname`, other elements are ignored + #' `teal_slice`s may contain only `dataname` and `varname`, other elements are ignored. #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' remove_filter_state = function(state) { shiny::isolate({ @@ -454,16 +454,15 @@ FilteredData <- R6::R6Class( # nolint }, #' @description - #' Remove all `FilterStates` of a `FilteredDataset` or all `FilterStates` - #' of a `FilteredData` object. + #' Remove all `FilterStates` of a `FilteredDataset` or all `FilterStates` of a `FilteredData` object. #' #' @param datanames (`character`) - #' `datanames` to remove their `FilterStates` or empty which removes - #' all `FilterStates` in the `FilteredData` object + #' names of datasets for which to remove all filter states. + #' Defaults to all datasets in this `FilteredData` object. #' @param force (`logical(1)`) - #' include locked filter states + #' flag specifying whether to include anchored filter states. #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' clear_filter_states = function(datanames = self$datanames(), force = FALSE) { logger::log_trace( @@ -489,14 +488,11 @@ FilteredData <- R6::R6Class( # nolint # shiny modules ----- #' @description - #' Module for the right filter panel in the teal app - #' with a filter overview panel and a filter variable panel. - #' - #' This panel contains info about the number of observations left in - #' the (active) datasets and allows to filter the datasets. + #' top-level `shiny` module for the filter panel in the `teal` app. + #' Contains 1) filter overview panel, 2) filter active panel, and 3) add filters panel. #' #' @param id (`character(1)`) - #' module id + #' `shiny` module instance id. #' @return `shiny.tag` ui_filter_panel = function(id) { ns <- NS(id) @@ -515,14 +511,13 @@ FilteredData <- R6::R6Class( # nolint #' Server function for filter panel. #' #' @param id (`character(1)`) - #' an id string that corresponds with the id used to call the module's - #' `ui_filter_panel` function. - #' @param active_datanames (`function` or `reactive`) returning `datanames` that - #' should be shown on the filter panel, - #' must be a subset of the `datanames` argument provided to `ui_filter_panel`; - #' if the function returns `NULL` (as opposed to `character(0)`), the filter - #' panel will be hidden - #' @return `moduleServer` function which returns `NULL` + #' `shiny` module instance id. + #' @param active_datanames (`function` or `reactive`) + #' returning `datanames` that should be shown on the filter panel. + #' Must be a subset of the `datanames` in this `FilteredData`. + #' If the function returns `NULL` (as opposed to `character(0)`), + #' the filter panel will be hidden. + #' @return `NULL`. srv_filter_panel = function(id, active_datanames = self$datanames) { checkmate::assert_function(active_datanames) moduleServer( @@ -550,7 +545,7 @@ FilteredData <- R6::R6Class( # nolint #' @description #' Server module responsible for displaying active filters. #' @param id (`character(1)`) - #' an id string that corresponds with the id used to call the module's `srv_active` function. + #' `shiny` module instance id. #' @return `shiny.tag` ui_active = function(id) { ns <- NS(id) @@ -600,10 +595,10 @@ FilteredData <- R6::R6Class( # nolint #' @description #' Server module responsible for displaying active filters. #' @param id (`character(1)`) - #' an id string that corresponds with the id used to call the module's `ui_active` function. + #' `shiny` module instance id. #' @param active_datanames (`reactive`) #' defining subset of `self$datanames()` to be displayed. - #' @return `moduleServer` returning `NULL` + #' @return `NULL`. srv_active = function(id, active_datanames = self$datanames) { checkmate::assert_function(active_datanames) shiny::moduleServer(id, function(input, output, session) { @@ -669,8 +664,7 @@ FilteredData <- R6::R6Class( # nolint #' @description #' Server module responsible for displaying drop-downs with variables to add a filter. #' @param id (`character(1)`) - #' an id string that corresponds with the id used to call the module's - #' `ui_add` function. + #' `shiny` module instance id. #' @return `shiny.tag` ui_add = function(id) { ns <- NS(id) @@ -712,11 +706,10 @@ FilteredData <- R6::R6Class( # nolint #' @description #' Server module responsible for displaying drop-downs with variables to add a filter. #' @param id (`character(1)`) - #' an id string that corresponds with the id used to call the module's - #' `ui_add` function. + #' `shiny` module instance id. #' @param active_datanames (`reactive`) #' defining subset of `self$datanames()` to be displayed. - #' @return `moduleServer` returning `NULL` + #' @return `NULL`. srv_add = function(id, active_datanames = reactive(self$datanames())) { checkmate::assert_class(active_datanames, "reactive") moduleServer(id, function(input, output, session) { @@ -759,7 +752,9 @@ FilteredData <- R6::R6Class( # nolint #' the number of rows/observations in each dataset, #' the number of unique subjects. #' - #' @param id module id + #' @param id (`character(1)`) + #' `shiny` module instance id. + #' ui_overview = function(id) { ns <- NS(id) div( @@ -797,14 +792,13 @@ FilteredData <- R6::R6Class( # nolint #' data. #' #' @param id (`character(1)`) - #' an id string that corresponds with the id used to call the module's - #' `ui_overview` function. + #' `shiny` module instance id. #' @param active_datanames (`reactive`) #' returning `datanames` that should be shown on the filter panel, #' must be a subset of the `datanames` argument provided to `ui_filter_panel`; #' if the function returns `NULL` (as opposed to `character(0)`), the filter #' panel will be hidden. - #' @return `moduleServer` function which returns `NULL` + #' @return `NULL`. srv_overview = function(id, active_datanames = self$datanames) { checkmate::assert_class(active_datanames, "reactive") moduleServer( diff --git a/R/FilteredDataset-utils.R b/R/FilteredDataset-utils.R index 7d1ed4edf..4a4c66a8a 100644 --- a/R/FilteredDataset-utils.R +++ b/R/FilteredDataset-utils.R @@ -1,22 +1,31 @@ -#' Initializes `FilteredDataset` +#' Initialize `FilteredDataset` #' -#' @param dataset (`data.frame` or `MultiAssayExperiment`) -#' @param dataname (`character`) -#' A given name for the dataset it may not contain spaces -#' @param keys optional, (`character`) -#' Vector with primary keys +#' Initializes a `FilteredDataset` object corresponding to the class of the filtered dataset. +#' +#' @param dataset any object +#' @param dataname (`character(1)`) +#' syntactically valid name given to the dataset. +#' @param keys (`character`) +#' optional vector of primary key column names. #' @param parent_name (`character(1)`) -#' Name of the parent dataset +#' name of the parent dataset. #' @param parent (`reactive`) -#' object returned by this reactive is a filtered `data.frame` from other `FilteredDataset` -#' named `parent_name`. Consequence of passing `parent` is a `reactive` link which causes -#' causing re-filtering of this `dataset` based on the changes in `parent`. +#' that returns a filtered `data.frame` from other `FilteredDataset` named `parent_name`. +#' Passing `parent` results in a `reactive` link that causes re-filtering of this `dataset` +#' based on the changes in `parent`. #' @param join_keys (`character`) -#' Name of the columns in this dataset to join with `parent` -#' dataset. If the column names are different if both datasets -#' then the names of the vector define the `parent` columns. -#' @param label (`character`) -#' Label to describe the dataset +#' vector of names of columns in this dataset to join with `parent` dataset. +#' If column names in the parent do not match these, they should be given as the names of this vector. +#' @param label (`character(1)`) +#' label to describe the dataset. +#' +#' @return Object of class `FilteredDataset`. +#' +#' @section Warning: +#' This function is exported to allow other packages to extend `teal.slice` but it is treated as internal. +#' Breaking changes may occur without warning. +#' We recommend consulting the package maintainer before using it. +#' #' @examples #' # DataframeFilteredDataset example #' iris_fd <- init_filtered_dataset(iris, dataname = "iris") @@ -44,6 +53,7 @@ #' # MAEFilteredDataset example #' library(MultiAssayExperiment) #' data(miniACC, package = "MultiAssayExperiment") +#' #' MAE_fd <- init_filtered_dataset(miniACC, "MAE") #' ui <- fluidPage( #' MAE_fd$ui_add(id = "add"), @@ -66,9 +76,6 @@ #' #' @keywords internal #' @export -#' @note Although this function is exported for use in other packages, it may be changed or removed in a future release -#' at which point any code which relies on this exported function will need to be changed. -#' init_filtered_dataset <- function(dataset, # nolint dataname, keys = character(0), diff --git a/R/FilteredDataset.R b/R/FilteredDataset.R index 1f421fc2e..428b31a29 100644 --- a/R/FilteredDataset.R +++ b/R/FilteredDataset.R @@ -10,6 +10,7 @@ #' (`data.frame`) or multiple (`MultiAssayExperiment`) `FilterStates` objects. #' Each `FilterStates` is responsible for one filter/subset expression applied for specific #' components of the dataset. +#' #' @keywords internal FilteredDataset <- R6::R6Class( # nolint "FilteredDataset", @@ -18,14 +19,16 @@ FilteredDataset <- R6::R6Class( # nolint #' @description #' Initializes this `FilteredDataset` object. #' - #' @param dataset (`data.frame` or `MultiAssayExperiment`) - #' single dataset for which filters are rendered + #' @param dataset any object #' @param dataname (`character(1)`) - #' A given name for the dataset it may not contain spaces - #' @param keys optional, (`character`) - #' Vector with primary keys + #' syntactically valid name given to the dataset. + #' @param keys (`character`) + #' optional vector of primary key column names. #' @param label (`character(1)`) - #' Label to describe the dataset. + #' label to describe the dataset. + #' + #' @return Object of class `FilteredDataset`, invisibly. + #' initialize = function(dataset, dataname, keys = character(0), label = attr(dataset, "label")) { logger::log_trace("Instantiating { class(self)[1] }, dataname: { dataname }") @@ -63,10 +66,10 @@ FilteredDataset <- R6::R6Class( # nolint #' @description #' Returns a formatted string representing this `FilteredDataset` object. #' - #' @param show_all (`logical(1)`) passed to `format.teal_slice` - #' @param trim_lines (`logical(1)`) passed to `format.teal_slice` + #' @param show_all (`logical(1)`) passed to `format.teal_slice`. + #' @param trim_lines (`logical(1)`) passed to `format.teal_slice`. #' - #' @return `character(1)` the formatted string + #' @return The formatted character string. #' format = function(show_all = FALSE, trim_lines = TRUE) { sprintf( @@ -79,19 +82,19 @@ FilteredDataset <- R6::R6Class( # nolint #' @description #' Prints this `FilteredDataset` object. #' - #' @param ... additional arguments + #' @param ... additional arguments passed to `format`. #' print = function(...) { cat(shiny::isolate(self$format(...)), "\n") }, #' @description - #' Removes all active filter items applied to this dataset. + #' Removes all filter items applied to this dataset. #' #' @param force (`logical(1)`) - #' include locked filter states + #' flag specifying whether to include anchored filter states. #' - #' @return NULL + #' @return `NULL`. clear_filter_states = function(force = FALSE) { logger::log_trace("Removing filters from FilteredDataset: { deparse1(self$get_dataname()) }") lapply( @@ -108,15 +111,15 @@ FilteredDataset <- R6::R6Class( # nolint #' @description #' Gets a filter expression. #' - #' This functions returns filter calls equivalent to selected items + #' This function returns filter calls equivalent to selected items #' within each of `filter_states`. Configuration of the calls is constant and #' depends on `filter_states` type and order which are set during initialization. #' #' @param sid (`character`) - #' when specified then method returns code containing filter conditions of - #' `FilterState` objects which `"sid"` attribute is different than this `sid` argument. + #' when specified, the method returns code containing conditions calls of + #' `FilterState` objects with `sid` different to this `sid` argument. #' - #' @return filter `call` or `list` of filter calls + #' @return Either a `list` of filter `call`s, or `NULL`. get_call = function(sid = "") { filter_call <- Filter( f = Negate(is.null), @@ -129,7 +132,7 @@ FilteredDataset <- R6::R6Class( # nolint }, #' @description - #' Gets states of all active `FilterState` objects. + #' Gets states of all contained `FilterState` objects. #' #' @return A `teal_slices` object. #' @@ -143,14 +146,14 @@ FilteredDataset <- R6::R6Class( # nolint #' #' @param state (`teal_slices`) #' - #' @return `NULL` invisibly + #' @return Virtual method, returns nothing and raises error. #' set_filter_state = function(state) { stop("set_filter_state is an abstract class method.") }, #' @description - #' Gets the number of active `FilterState` objects in all `FilterStates` in this `FilteredDataset`. + #' Gets the number of `FilterState` objects in all `FilterStates` in this `FilteredDataset`. #' @return `integer(1)` get_filter_count = function() { length(self$get_filter_state()) @@ -159,7 +162,7 @@ FilteredDataset <- R6::R6Class( # nolint #' @description #' Gets the name of the dataset. #' - #' @return `character(1)` as a name of this dataset + #' @return A character string. get_dataname = function() { private$dataname }, @@ -169,8 +172,9 @@ FilteredDataset <- R6::R6Class( # nolint #' #' @param filtered (`logical(1)`) #' - #' @return `data.frame` or `MultiAssayExperiment`, either raw - #' or as a reactive with current filters applied + #' @return + #' The stored dataset. If `data.frame` or `MultiAssayExperiment`, + #' either raw or as a reactive with current filters applied (depending on `filtered`). #' get_dataset = function(filtered = FALSE) { if (filtered) { @@ -181,47 +185,33 @@ FilteredDataset <- R6::R6Class( # nolint }, #' @description - #' Get filter overview rows of a dataset. - #' The output shows the comparison between `filtered_dataset` - #' function parameter and the dataset inside self. - #' @param filtered_dataset comparison object, of the same class - #' as `self$get_dataset()`, if `NULL` then `self$get_dataset()` - #' is used. - #' @return (`data.frame`) matrix of observations and subjects + #' Get filter overview of a dataset. + #' @return Virtual method, returns nothing and raises an error. get_filter_overview = function() { - dataset <- self$get_dataset() - data_filtered <- self$get_dataset(TRUE) - data.frame( - dataname = private$dataname, - obs = nrow(dataset), - obs_filtered = nrow(data_filtered) - ) + stop("get_filter_overview is an abstract class method") }, #' @description - #' Gets the keys for the dataset of this `FilteredDataset`. - #' @return `character` the keys of dataset + #' Gets the key columns for this dataset. + #' @return Character vector of variable names get_keys = function() { private$keys }, #' @description #' Gets the dataset label. - #' @return `character` the dataset label + #' @return Character string. get_dataset_label = function() { private$label }, # modules ------ #' @description - #' UI module for dataset active filters. - #' @details - #' UI module containing dataset active filters along with - #' title and remove button. + #' `shiny` module containing active filters for a dataset, along with a title and a remove button. #' @param id (`character(1)`) - #' identifier of the element - preferably containing dataset name + #' `shiny` module instance id. #' - #' @return function - `shiny` UI module + #' @return `shiny.tag` ui_active = function(id) { dataname <- self$get_dataname() checkmate::assert_string(dataname) @@ -287,8 +277,8 @@ FilteredDataset <- R6::R6Class( # nolint #' Server module for a dataset active filters. #' #' @param id (`character(1)`) - #' an id string that corresponds with the id used to call the module's `ui_active` function. - #' @return `moduleServer` function which returns `NULL` + #' `shiny` module instance id. + #' @return `NULL`. srv_active = function(id) { moduleServer( id = id, @@ -341,9 +331,9 @@ FilteredDataset <- R6::R6Class( # nolint #' UI module to add filter variable for this dataset. #' #' @param id (`character(1)`) - #' identifier of the element - preferably containing dataset name + #' `shiny` module instance id. #' - #' @return function - `shiny` UI module + #' @return Virtual method, returns nothing and raises error. ui_add = function(id) { stop("Pure virtual method") }, @@ -352,15 +342,12 @@ FilteredDataset <- R6::R6Class( # nolint #' Server module to add filter variable for this dataset. #' For this class `srv_add` calls multiple modules #' of the same name from `FilterStates` as `MAEFilteredDataset` - #' contains one `FilterStates` object for `colData` and one for each - #' experiment. + #' contains one `FilterStates` object for `colData` and one for each experiment. #' #' @param id (`character(1)`) - #' an id string that corresponds with the id used to call the module's - #' `ui_add` function. - #' - #' @return `moduleServer` function which returns `NULL` + #' `shiny` module instance id. #' + #' @return `NULL`. srv_add = function(id) { moduleServer( id = id, @@ -400,10 +387,8 @@ FilteredDataset <- R6::R6Class( # nolint }, # @description - # Gets the active `FilterStates` objects. - # @param id (`character(1)`, `character(0)`) - # the id of the `private$filter_states` list element where `FilterStates` is kept. - # @return `FilterStates` or `list` of `FilterStates` objects. + # Gets `FilterStates` objects in this `FilteredDataset`. + # @return list of `FilterStates` objects. get_filter_states = function() { private$filter_states } diff --git a/R/FilteredDatasetDataframe.R b/R/FilteredDatasetDataframe.R index 11d38967b..bae1ee673 100644 --- a/R/FilteredDatasetDataframe.R +++ b/R/FilteredDatasetDataframe.R @@ -3,6 +3,7 @@ #' @name DataframeFilteredDataset #' @docType class #' @title The `DataframeFilteredDataset` `R6` class +#' #' @examples #' # use non-exported function from teal.slice #' DataframeFilteredDataset <- getFromNamespace("DataframeFilteredDataset", "teal.slice") @@ -25,6 +26,7 @@ #' ) #' dataset$set_filter_state(state = fs) #' isolate(dataset$get_filter_state()) +#' #' @keywords internal #' DataframeFilteredDataset <- R6::R6Class( # nolint @@ -38,24 +40,25 @@ DataframeFilteredDataset <- R6::R6Class( # nolint #' Initializes this `DataframeFilteredDataset` object. #' #' @param dataset (`data.frame`) - #' single data.frame for which filters are rendered - #' @param dataname (`character`) - #' A given name for the dataset it may not contain spaces - #' @param keys optional, (`character`) - #' Vector with primary keys + #' single `data.frame` for which filters are rendered. + #' @param dataname (`character(1)`) + #' syntactically valid name given to the dataset. + #' @param keys (`character`) + #' optional vector of primary key column names. #' @param parent_name (`character(1)`) - #' Name of the parent dataset + #' name of the parent dataset. #' @param parent (`reactive`) - #' object returned by this reactive is a filtered `data.frame` from other `FilteredDataset` - #' named `parent_name`. Consequence of passing `parent` is a `reactive` link which causes - #' causing re-filtering of this `dataset` based on the changes in `parent`. + #' that returns a filtered `data.frame` from other `FilteredDataset` named `parent_name`. + #' Passing `parent` results in a `reactive` link that causes re-filtering of this `dataset` + #' based on the changes in `parent`. #' @param join_keys (`character`) - #' Name of the columns in this dataset to join with `parent` - #' dataset. If the column names are different if both datasets - #' then the names of the vector define the `parent` columns. + #' vector of names of columns in this dataset to join with `parent` dataset. + #' If column names in the parent do not match these, they should be given as the names of this vector. + #' @param label (`character(1)`) + #' label to describe the dataset. + #' + #' @return Object of class `DataframeFilteredDataset`, invisibly. #' - #' @param label (`character`) - #' Label to describe the dataset initialize = function(dataset, dataname, keys = character(0), @@ -115,20 +118,19 @@ DataframeFilteredDataset <- R6::R6Class( # nolint }, #' @description - #' Gets the filter expression. + #' Gets the subset expression. #' - #' This functions returns filter calls equivalent to selected items - #' within each of `filter_states`. Configuration of the calls is constant and + #' This function returns subset expressions equivalent to selected items + #' within each of `filter_states`. Configuration of the expressions is constant and #' depends on `filter_states` type and order which are set during initialization. - #' This class contains single `FilterStates` - #' which contains single `state_list` and all `FilterState` objects - #' applies to one argument (`...`) in `dplyr::filter` call. + #' This class contains single `FilterStates` which contains single `state_list` + #' and all `FilterState` objects apply to one argument (`...`) in a `dplyr::filter` call. #' #' @param sid (`character`) - #' when specified then method returns code containing filter conditions of - #' `FilterState` objects which `"sid"` attribute is different than this `sid` argument. + #' when specified, the method returns code containing conditions calls of + #' `FilterState` objects with `sid` different to that of this `sid` argument. #' - #' @return filter `call` or `list` of filter calls + #' @return Either a `list` of length 1 containing a filter `call`, or `NULL`. get_call = function(sid = "") { logger::log_trace("DataframeFilteredDataset$get_call initializing for dataname: { private$dataname }") filter_call <- super$get_call(sid) @@ -181,7 +183,7 @@ DataframeFilteredDataset <- R6::R6Class( # nolint #' Set filter state. #' #' @param state (`teal_slices`) - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' set_filter_state = function(state) { shiny::isolate({ @@ -202,7 +204,7 @@ DataframeFilteredDataset <- R6::R6Class( # nolint #' specifying `FilterState` objects to remove; #' `teal_slice`s may contain only `dataname` and `varname`, other elements are ignored #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' remove_filter_state = function(state) { checkmate::assert_class(state, "teal_slices") @@ -223,9 +225,9 @@ DataframeFilteredDataset <- R6::R6Class( # nolint #' UI module to add filter variable for this dataset. #' #' @param id (`character(1)`) - #' identifier of the element - preferably containing dataset name + #' `shiny` module instance id. #' - #' @return function - `shiny` UI module + #' @return `shiny.tag` ui_add = function(id) { ns <- NS(id) tagList( @@ -235,10 +237,9 @@ DataframeFilteredDataset <- R6::R6Class( # nolint }, #' @description - #' Get number of observations based on given keys. - #' The output shows the comparison between `filtered_dataset` - #' function parameter and the dataset inside self - #' @return `list` containing character `#filtered/#not_filtered` + #' Creates row for filter overview in the form of \cr + #' `dataname -- observations (remaining/total)` - data.frame + #' @return A `data.frame`. get_filter_overview = function() { logger::log_trace("FilteredDataset$srv_filter_overview initialized") # Gets filter overview subjects number and returns a list diff --git a/R/FilteredDatasetDefault.R b/R/FilteredDatasetDefault.R index a5157a28c..321cc7343 100644 --- a/R/FilteredDatasetDefault.R +++ b/R/FilteredDatasetDefault.R @@ -3,7 +3,9 @@ #' @name DefaultFilteredDataset #' @docType class #' @title `DefaultFilteredDataset` `R6` class +#' #' @description Stores any object as inert entity. Filtering is not supported. +#' #' @examples #' # use non-exported function from teal.slice #' DefaultFilteredDataset <- getFromNamespace("DefaultFilteredDataset", "teal.slice") @@ -11,7 +13,9 @@ #' ds <- DefaultFilteredDataset$new(letters, "letters") #' isolate(ds$get_filter_state()) #' isolate(ds$get_call()) +#' #' @keywords internal +#' DefaultFilteredDataset <- R6::R6Class( # nolint classname = "DefaultFilteredDataset", inherit = FilteredDataset, @@ -23,11 +27,14 @@ DefaultFilteredDataset <- R6::R6Class( # nolint #' Initializes this `DefaultFilteredDataset` object. #' #' @param dataset - #' Any type of object; will not be filtered. + #' any type of object; will not be filtered. #' @param dataname (`character(1)`) - #' Name given to the dataset; must not contain spaces. + #' syntactically valid name given to the dataset. #' @param label (`character(1)`) - #' Label to describe the dataset. + #' label to describe the dataset. + #' + #' @return Object of class `DefaultFilteredDataset`, invisibly. + #' initialize = function(dataset, dataname, label = character(0)) { super$initialize(dataset = dataset, dataname = dataname, label = label) }, @@ -35,10 +42,10 @@ DefaultFilteredDataset <- R6::R6Class( # nolint #' @description #' Returns a formatted string representing this `DefaultFilteredDataset` object. #' - #' @param show_all (`logical(1)`) for method consistency, ignored - #' @param trim_lines (`logical(1)`) flag specifying whether to trim lines if class names are too long + #' @param show_all (`logical(1)`) for method consistency, ignored. + #' @param trim_lines (`logical(1)`) flag specifying whether to trim lines if class names are too long. #' - #' @return `character(1)` the formatted string + #' @return The formatted string. #' format = function(show_all, trim_lines = FALSE) { class_string <- toString(class(private$dataset)) @@ -50,7 +57,7 @@ DefaultFilteredDataset <- R6::R6Class( # nolint sprintf(" - unfiltered dataset:\t\"%s\": %s", private$dataname, class_string) }, - #' @param sid (`character`) for method consistency, ignored + #' @param sid (`character(1)`) for method consistency, ignored. #' @return `NULL`, invisibly. get_call = function(sid) { invisible(NULL) @@ -59,7 +66,7 @@ DefaultFilteredDataset <- R6::R6Class( # nolint get_filter_state = function() { invisible(NULL) }, - #' @param state (`teal_slices`) for method consistency, ignored + #' @param state (`teal_slices`) for method consistency, ignored. #' @return `NULL`, invisibly. set_filter_state = function(state) { if (length(state) != 0L) { @@ -67,16 +74,16 @@ DefaultFilteredDataset <- R6::R6Class( # nolint } invisible(NULL) }, - #' @param force (`logical`) for method consistency, ignored + #' @param force (`logical(1)`) for method consistency, ignored. #' @return `NULL`, invisibly. clear_filter_states = function(force) { invisible(NULL) }, #' @description - #' Get `data.frame` to use in the filter-panel overview. - #' Output of this function indicates unsupported dataset class. - #' @return `list` containing character `#filtered/#not_filtered` + #' Creates row for filter overview in the form of \cr + #' `dataname` - unsupported data class + #' @return A `data.frame`. get_filter_overview = function() { data.frame(dataname = private$dataname, obs = NA, obs_filtered = NA) }, @@ -88,8 +95,8 @@ DefaultFilteredDataset <- R6::R6Class( # nolint #' @details #' Blank UI module that would list active filter states for this dataset. #' @param id (`character(1)`) - #' `shiny` module id - #' @return empty `div` + #' `shiny` module instance id. + #' @return An empty `div`. ui_active = function(id) { ns <- NS(id) div() @@ -100,8 +107,8 @@ DefaultFilteredDataset <- R6::R6Class( # nolint #' @details #' Blank UI module that would list active filter states for this dataset. #' @param id (`character(1)`) - #' `shiny` module id - #' @return empty `div` + #' `shiny` module instance id. + #' @return An empty `div`. ui_add = function(id) { ns <- NS(id) div() diff --git a/R/FilteredDatasetMAE.R b/R/FilteredDatasetMAE.R index c689befdf..50a6b679b 100644 --- a/R/FilteredDatasetMAE.R +++ b/R/FilteredDatasetMAE.R @@ -3,7 +3,7 @@ #' @name MAEFilteredDataset #' @docType class #' @title `MAEFilteredDataset` `R6` class -#' @keywords internal +#' #' @examplesIf requireNamespace("MultiAssayExperiment") #' # use non-exported function from teal.slice #' MAEFilteredDataset <- getFromNamespace("MAEFilteredDataset", "teal.slice") @@ -27,6 +27,8 @@ #' dataset$set_filter_state(state = fs) #' isolate(dataset$get_filter_state()) #' +#' @keywords internal +#' MAEFilteredDataset <- R6::R6Class( # nolint classname = "MAEFilteredDataset", inherit = FilteredDataset, @@ -37,13 +39,16 @@ MAEFilteredDataset <- R6::R6Class( # nolint #' Initialize `MAEFilteredDataset` object. #' #' @param dataset (`MulitiAssayExperiment`) - #' a single `MultiAssayExperiment` for which to define a subset - #' @param dataname (`character`) - #' a given name for the dataset it may not contain spaces - #' @param keys optional, (`character`) - #' vector with primary keys - #' @param label (`character`) - #' label to describe the dataset + #' single `MulitiAssayExperiment` for which filters are rendered. + #' @param dataname (`character(1)`) + #' syntactically valid name given to the dataset. + #' @param keys (`character`) + #' optional vector of primary key column names. + #' @param label (`character(1)`) + #' label to describe the dataset. + #' + #' @return Object of class `MAEFilteredDataset`, invisibly. + #' initialize = function(dataset, dataname, keys = character(0), label = character(0)) { if (!requireNamespace("MultiAssayExperiment", quietly = TRUE)) { stop("Cannot load MultiAssayExperiment - please install the package or restart your session.") @@ -87,7 +92,7 @@ MAEFilteredDataset <- R6::R6Class( # nolint #' Set filter state. #' #' @param state (`teal_slices`) - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' set_filter_state = function(state) { shiny::isolate({ @@ -132,9 +137,9 @@ MAEFilteredDataset <- R6::R6Class( # nolint #' #' @param state (`teal_slices`) #' specifying `FilterState` objects to remove; - #' `teal_slice`s may contain only `dataname` and `varname`, other elements are ignored + #' `teal_slice`s may contain only `dataname` and `varname`, other elements are ignored. #' - #' @return `NULL` invisibly + #' @return `NULL`, invisibly. #' remove_filter_state = function(state) { checkmate::assert_class(state, "teal_slices") @@ -174,9 +179,9 @@ MAEFilteredDataset <- R6::R6Class( # nolint #' @description #' UI module to add filter variable for this dataset. #' @param id (`character(1)`) - #' identifier of the element - preferably containing dataset name + #' `shiny` module instance id. #' - #' @return function - `shiny` UI module + #' @return `shiny.tag` #' ui_add = function(id) { ns <- NS(id) @@ -205,8 +210,9 @@ MAEFilteredDataset <- R6::R6Class( # nolint }, #' @description - #' Get filter overview rows of a dataset. - #' @return (`matrix`) matrix of observations and subjects + #' Creates row for filter overview in the form of \cr + #' `dataname -- observations (remaining/total) -- subjects (remaining/total)` - MAE + #' @return A `data.frame`. get_filter_overview = function() { data <- self$get_dataset() data_filtered <- self$get_dataset(TRUE) diff --git a/R/calls_combine_by.R b/R/calls_combine_by.R index 18c5e4583..81c9394fe 100644 --- a/R/calls_combine_by.R +++ b/R/calls_combine_by.R @@ -3,7 +3,7 @@ #' Combines calls with a logical operator. #' #' This function is used to combine logical predicates produced by `FilterState` objects -#' to build a complete subsetting expression. +#' to build a complete subset expression. #' #' @param calls (`list`) #' containing calls (or symbols) to be combined by `operator` diff --git a/R/choices_labeled.R b/R/choices_labeled.R index 99ba1e291..e7843433b 100644 --- a/R/choices_labeled.R +++ b/R/choices_labeled.R @@ -16,7 +16,7 @@ #' match its order. #' @param types vector containing the types of the columns. #' -#' @return a named character vector +#' @return A named character vector. #' #' @keywords internal #' diff --git a/R/count_labels.R b/R/count_labels.R index 46b2b5744..8d66392bc 100644 --- a/R/count_labels.R +++ b/R/count_labels.R @@ -1,24 +1,25 @@ #' Progress bars with labels #' -#' `shiny` element showing progress bar counts. Each element can have an -#' unique `id` attribute so each can be used independently. +#' `shiny` element displaying a series of progress bars and observation counts. #' -#' Progress bar size is dependent on the ratio: +#' @param inputId (`character(1)`) `shiny` id of the parent element (e.g. a check-box group input). +#' @param choices (`vector`) Available values. Used to determine label text. +#' @param countsmax (`numeric`) Maximum counts of each element. Must be the same length `choices`. +#' @param countsnow (`numeric`) Current counts of each element. Must be the same length `choices`. +#' @param session (`session`) `shiny` `session` object passed to function given to `shinyServer`. #' -#' `choicesnow[i] / countsmax[i]`. +#' @return List of `shiny.tag`s. #' -#' Label is: +#' Creates a number of progress bar elements, one for each value of `choices`. +#' The widths of all progress bars add up to the full width of the container. +#' Each progress bar has a text label that contains the name of the value and the number of counts. #' -#' `choices[i] (countsnow[i]/countsmax)` +#' If the filter panel is used with `count_type = "all"`, the progress bars will be filled +#' according to the number of counts remaining in the current selection and the label will show +#' both the current and the total number of counts. +#' +#' Each child element can have a unique `id` attribute to be used independently. #' -#' @param session (`session`) object passed to function given to `shinyServer`. -#' @param inputId (`character(1)`) `shiny` id -#' @param choices (`vector`) determines label text. -#' @param countsmax (`numeric`) determining maximal count of each element. -#' Length should be the same as `choices`. -#' @param countsnow (`numeric`) actual counts of each element. -#' Length should be the same as `choices`. -#' @return list of `shiny.tag` #' @examples #' # use non-exported function from teal.slice #' include_js_files <- getFromNamespace("include_js_files", "teal.slice") @@ -66,7 +67,9 @@ #' if (interactive()) { #' shinyApp(ui, server) #' } +#' #' @keywords internal +#' countBars <- function(inputId, choices, countsmax, countsnow = NULL) { # nolint checkmate::assert_string(inputId) checkmate::assert_vector(choices) @@ -93,16 +96,24 @@ countBars <- function(inputId, choices, countsmax, countsnow = NULL) { # nolint #' Progress bar with label #' -#' @param session (`session`) object passed to function given to `shinyServer`. -#' @param inputId (`character(1)`) `shiny` id -#' @param label (`character(1)`) Text to display followed by counts -#' @param countmax (`numeric(1)`) maximal possible count for a single item. -#' @param countnow (`numeric(1)`) current count of a single item. -#' @param counttotal (`numeric(1)`) total count to make whole progress bar -#' taking part of the container. Ratio between `countmax / counttotal` -#' determines `%">`. +#' `shiny` element displaying a progress bar and observation count. +#' +#' A progress bar is created to visualize the number of counts in a variable, with filling and a text label. +#' - progress bar width is derived as a fraction of the container width: `style = "width: / %"`, +#' - progress bar is filled up to the fraction ` / `, +#' - text label is obtained by `