diff --git a/NEWS.md b/NEWS.md index db758f9c3..2a7e7140d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,9 @@ # teal.slice 0.5.0.9008 +### Miscellaneous + +* Added `teal_slice` and `teal_slices` to package index. + # teal.slice 0.5.0 ### Enhancements diff --git a/R/teal_slice.R b/R/teal_slice.R index 08201fc4e..2140396dc 100644 --- a/R/teal_slice.R +++ b/R/teal_slice.R @@ -1,6 +1,7 @@ #' Specify single filter #' #' Create a `teal_slice` object that holds complete information on filtering one variable. +#' Check out [`teal_slice-utilities`] functions for working with `teal_slice` object. #' #' `teal_slice` object fully describes filter state and can be used to create, #' modify, and delete a filter state. A `teal_slice` contains a number of common fields @@ -67,12 +68,7 @@ #' @param fixed (`logical(1)`) flag specifying whether to fix this filter state (forbid setting state) #' @param anchored (`logical(1)`) flag specifying whether to lock this filter state (forbid removing and inactivating) #' @param title (`character(1)`) optional title of the filter. Ignored when `varname` is set. -#' @param ... in `teal_slice` method these are additional arguments which can be handled by extensions -#' of `teal.slice` classes. In other methods these are further arguments passed to or from other methods. -#' @param x (`teal.slice`) -#' @param show_all (`logical(1)`) indicating whether to show all fields. If set to `FALSE`, -#' only non-NULL elements will be printed. -#' @param trim_lines (`logical(1)`) indicating whether to trim lines when printing. +#' @param ... additional arguments which can be handled by extensions of `teal.slice` classes. #' #' @return A `teal.slice` object. Depending on whether `varname` or `expr` was specified, the resulting #' `teal_slice` also receives class `teal_slice_var` or `teal_slice_expr`, respectively. @@ -108,7 +104,8 @@ #' print(x1) #' print(x1, show_all = TRUE, trim_lines = FALSE) #' -#' @seealso [`teal_slices`] +#' @seealso [`teal_slices`], +#' [`is.teal_slice`], [`as.teal_slice`], [`as.list.teal_slice`], [`print.teal_slice`], [`format.teal_slice`] #' #' @export teal_slice <- function(dataname, @@ -172,26 +169,35 @@ teal_slice <- function(dataname, ans } -#' @rdname teal_slice -#' @export +#' `teal_slice` utility functions +#' +#' Helper functions for working with [`teal_slice`] object. +#' @param x (`teal.slice`) +#' @param show_all (`logical(1)`) indicating whether to show all fields. If set to `FALSE`, +#' only non-NULL elements will be printed. +#' @param trim_lines (`logical(1)`) indicating whether to trim lines when printing. +#' @param ... additional arguments passed to other functions. +#' @name teal_slice-utilities +#' @inherit teal_slice examples #' @keywords internal + +#' @rdname teal_slice-utilities +#' @export #' is.teal_slice <- function(x) { # nolint inherits(x, "teal_slice") } -#' @rdname teal_slice +#' @rdname teal_slice-utilities #' @export -#' @keywords internal #' as.teal_slice <- function(x) { # nolint checkmate::assert_list(x, names = "named") do.call(teal_slice, x) } -#' @rdname teal_slice +#' @rdname teal_slice-utilities #' @export -#' @keywords internal #' as.list.teal_slice <- function(x, ...) { formal_args <- setdiff(names(formals(teal_slice)), "...") @@ -209,9 +215,8 @@ as.list.teal_slice <- function(x, ...) { } -#' @rdname teal_slice +#' @rdname teal_slice-utilities #' @export -#' @keywords internal #' format.teal_slice <- function(x, show_all = FALSE, trim_lines = TRUE, ...) { checkmate::assert_flag(show_all) @@ -223,9 +228,8 @@ format.teal_slice <- function(x, show_all = FALSE, trim_lines = TRUE, ...) { jsonify(x_list, trim_lines) } -#' @rdname teal_slice +#' @rdname teal_slice-utilities #' @export -#' @keywords internal #' print.teal_slice <- function(x, ...) { cat(format(x, ...)) diff --git a/R/teal_slices.R b/R/teal_slices.R index 7fb9161c0..51d78b080 100644 --- a/R/teal_slices.R +++ b/R/teal_slices.R @@ -1,6 +1,7 @@ #' Complete filter specification #' #' Create `teal_slices` object to package multiple filters and additional settings. +#' Check out [`teal_slices-utilities`] functions for working with `teal_slices` object. #' #' `teal_slices()` collates multiple `teal_slice` objects into a `teal_slices` object, #' a complete filter specification. This is used by all classes above `FilterState` @@ -12,8 +13,7 @@ #' Since these could be mutually exclusive, it is impossible to set both allowed and forbidden #' variables for one data set in one `teal_slices`. #' -#' @param ... any number of `teal_slice` objects. For `print` and `format`, -#' additional arguments passed to other functions. +#' @param ... any number of `teal_slice` objects. #' @param include_varnames,exclude_varnames (`named list`s of `character`) where list names #' match names of data sets and vector elements match variable names in respective data sets; #' specify which variables are allowed to be filtered; see `Details`. @@ -28,9 +28,6 @@ #' and unfiltered dataset. Note, that issues were reported when using this option with `MultiAssayExperiment`. #' Please make sure that adding new filters doesn't fail on target platform before deploying for production. #' @param allow_add (`logical(1)`) logical flag specifying whether the user will be able to add new filters -#' @param x object to test for `teal_slices`, object to convert to `teal_slices` or a `teal_slices` object -#' @param i (`character` or `numeric` or `logical`) indicating which elements to extract -#' @param recursive (`logical(1)`) flag specifying whether to also convert to list the elements of this `teal_slices` #' #' @return #' `teal_slices`, which is an unnamed list of `teal_slice` objects. @@ -85,6 +82,8 @@ #' @seealso #' - [`teal_slice`] for creating constituent elements of `teal_slices` #' - [`teal::slices_store`] for robust utilities for saving and loading `teal_slices` in `JSON` format +#' - [`is.teal_slices`], [`as.teal_slices`], [`as.list.teal_slices`], [`[.teal_slices`], [`c.teal_slices`] +#' [`print.teal_slices`], [`format.teal_slices`] #' #' @export #' @@ -126,19 +125,26 @@ teal_slices <- function(..., ) } +#' `teal_slices` utility functions +#' +#' Helper functions for working with [`teal_slices`] object. +#' @param x object to test for `teal_slices`, object to convert to `teal_slices` or a `teal_slices` object +#' @param i (`character` or `numeric` or `logical`) indicating which elements to extract +#' @param recursive (`logical(1)`) flag specifying whether to also convert to list the elements of this `teal_slices` +#' @param ... additional arguments passed to other functions. +#' @name teal_slices-utilities +#' @inherit teal_slices examples +#' @keywords internal -#' @rdname teal_slices +#' @rdname teal_slices-utilities #' @export -#' @keywords internal #' is.teal_slices <- function(x) { # nolint inherits(x, "teal_slices") } - -#' @rdname teal_slices +#' @rdname teal_slices-utilities #' @export -#' @keywords internal #' as.teal_slices <- function(x) { # nolint checkmate::assert_list(x) @@ -150,9 +156,8 @@ as.teal_slices <- function(x) { # nolint } -#' @rdname teal_slices +#' @rdname teal_slices-utilities #' @export -#' @keywords internal #' as.list.teal_slices <- function(x, recursive = FALSE, ...) { # nolint ans <- unclass(x) @@ -161,9 +166,8 @@ as.list.teal_slices <- function(x, recursive = FALSE, ...) { # nolint } -#' @rdname teal_slices +#' @rdname teal_slices-utilities #' @export -#' @keywords internal #' `[.teal_slices` <- function(x, i) { if (missing(i)) i <- seq_along(x) @@ -185,9 +189,8 @@ as.list.teal_slices <- function(x, recursive = FALSE, ...) { # nolint } -#' @rdname teal_slices +#' @rdname teal_slices-utilities #' @export -#' @keywords internal #' c.teal_slices <- function(...) { x <- list(...) @@ -207,11 +210,10 @@ c.teal_slices <- function(...) { } -#' @rdname teal_slices +#' @rdname teal_slices-utilities #' @param show_all (`logical(1)`) whether to display non-null elements of constituent `teal_slice` objects #' @param trim_lines (`logical(1)`) whether to trim lines #' @export -#' @keywords internal #' format.teal_slices <- function(x, show_all = FALSE, trim_lines = TRUE, ...) { checkmate::assert_flag(show_all) @@ -228,9 +230,8 @@ format.teal_slices <- function(x, show_all = FALSE, trim_lines = TRUE, ...) { jsonify(slices_list, trim_lines) } -#' @rdname teal_slices +#' @rdname teal_slices-utilities #' @export -#' @keywords internal #' print.teal_slices <- function(x, ...) { cat(format(x, ...), "\n") diff --git a/man/teal_slice-utilities.Rd b/man/teal_slice-utilities.Rd new file mode 100644 index 000000000..27977d20f --- /dev/null +++ b/man/teal_slice-utilities.Rd @@ -0,0 +1,65 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/teal_slice.R +\name{teal_slice-utilities} +\alias{teal_slice-utilities} +\alias{is.teal_slice} +\alias{as.teal_slice} +\alias{as.list.teal_slice} +\alias{format.teal_slice} +\alias{print.teal_slice} +\title{\code{teal_slice} utility functions} +\usage{ +is.teal_slice(x) + +as.teal_slice(x) + +\method{as.list}{teal_slice}(x, ...) + +\method{format}{teal_slice}(x, show_all = FALSE, trim_lines = TRUE, ...) + +\method{print}{teal_slice}(x, ...) +} +\arguments{ +\item{x}{(\code{teal.slice})} + +\item{...}{additional arguments passed to other functions.} + +\item{show_all}{(\code{logical(1)}) indicating whether to show all fields. If set to \code{FALSE}, +only non-NULL elements will be printed.} + +\item{trim_lines}{(\code{logical(1)}) indicating whether to trim lines when printing.} +} +\description{ +Helper functions for working with \code{\link{teal_slice}} object. +} +\examples{ +x1 <- teal_slice( + dataname = "data", + id = "Female adults", + expr = "SEX == 'F' & AGE >= 18", + title = "Female adults" +) +x2 <- teal_slice( + dataname = "data", + varname = "var", + choices = c("F", "M", "U"), + selected = "F", + keep_na = TRUE, + keep_inf = TRUE, + fixed = FALSE, + anchored = FALSE, + multiple = TRUE, + id = "Gender", + extra_arg = "extra" +) + +is.teal_slice(x1) +as.list(x1) +as.teal_slice(list(dataname = "a", varname = "var")) +format(x1) +format(x1, show_all = TRUE, trim_lines = FALSE) +print(x1) +print(x1, show_all = TRUE, trim_lines = FALSE) + +} +\keyword{internal} diff --git a/man/teal_slice.Rd b/man/teal_slice.Rd index 937bac65b..8ab89acbd 100644 --- a/man/teal_slice.Rd +++ b/man/teal_slice.Rd @@ -2,11 +2,6 @@ % Please edit documentation in R/teal_slice.R \name{teal_slice} \alias{teal_slice} -\alias{is.teal_slice} -\alias{as.teal_slice} -\alias{as.list.teal_slice} -\alias{format.teal_slice} -\alias{print.teal_slice} \title{Specify single filter} \usage{ teal_slice( @@ -24,16 +19,6 @@ teal_slice( title = NULL, ... ) - -is.teal_slice(x) - -as.teal_slice(x) - -\method{as.list}{teal_slice}(x, ...) - -\method{format}{teal_slice}(x, show_all = FALSE, trim_lines = TRUE, ...) - -\method{print}{teal_slice}(x, ...) } \arguments{ \item{dataname}{(\code{character(1)}) name of data set} @@ -68,15 +53,7 @@ only applicable to \code{ChoicesFilterState} and \code{LogicalFilterState}} \item{title}{(\code{character(1)}) optional title of the filter. Ignored when \code{varname} is set.} -\item{...}{in \code{teal_slice} method these are additional arguments which can be handled by extensions -of \code{teal.slice} classes. In other methods these are further arguments passed to or from other methods.} - -\item{x}{(\code{teal.slice})} - -\item{show_all}{(\code{logical(1)}) indicating whether to show all fields. If set to \code{FALSE}, -only non-NULL elements will be printed.} - -\item{trim_lines}{(\code{logical(1)}) indicating whether to trim lines when printing.} +\item{...}{additional arguments which can be handled by extensions of \code{teal.slice} classes.} } \value{ A \code{teal.slice} object. Depending on whether \code{varname} or \code{expr} was specified, the resulting @@ -84,6 +61,7 @@ A \code{teal.slice} object. Depending on whether \code{varname} or \code{expr} w } \description{ Create a \code{teal_slice} object that holds complete information on filtering one variable. +Check out \code{\link{teal_slice-utilities}} functions for working with \code{teal_slice} object. } \details{ \code{teal_slice} object fully describes filter state and can be used to create, @@ -169,6 +147,6 @@ print(x1, show_all = TRUE, trim_lines = FALSE) } \seealso{ -\code{\link{teal_slices}} +\code{\link{teal_slices}}, +\code{\link{is.teal_slice}}, \code{\link{as.teal_slice}}, \code{\link{as.list.teal_slice}}, \code{\link{print.teal_slice}}, \code{\link{format.teal_slice}} } -\keyword{internal} diff --git a/man/teal_slices-utilities.Rd b/man/teal_slices-utilities.Rd new file mode 100644 index 000000000..a40e7abe3 --- /dev/null +++ b/man/teal_slices-utilities.Rd @@ -0,0 +1,92 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/teal_slices.R +\name{teal_slices-utilities} +\alias{teal_slices-utilities} +\alias{is.teal_slices} +\alias{as.teal_slices} +\alias{as.list.teal_slices} +\alias{[.teal_slices} +\alias{c.teal_slices} +\alias{format.teal_slices} +\alias{print.teal_slices} +\title{\code{teal_slices} utility functions} +\usage{ +is.teal_slices(x) + +as.teal_slices(x) + +\method{as.list}{teal_slices}(x, recursive = FALSE, ...) + +\method{[}{teal_slices}(x, i) + +\method{c}{teal_slices}(...) + +\method{format}{teal_slices}(x, show_all = FALSE, trim_lines = TRUE, ...) + +\method{print}{teal_slices}(x, ...) +} +\arguments{ +\item{x}{object to test for \code{teal_slices}, object to convert to \code{teal_slices} or a \code{teal_slices} object} + +\item{recursive}{(\code{logical(1)}) flag specifying whether to also convert to list the elements of this \code{teal_slices}} + +\item{...}{additional arguments passed to other functions.} + +\item{i}{(\code{character} or \code{numeric} or \code{logical}) indicating which elements to extract} + +\item{show_all}{(\code{logical(1)}) whether to display non-null elements of constituent \code{teal_slice} objects} + +\item{trim_lines}{(\code{logical(1)}) whether to trim lines} +} +\description{ +Helper functions for working with \code{\link{teal_slices}} object. +} +\examples{ +filter_1 <- teal_slice( + dataname = "dataname1", + varname = "varname1", + choices = letters, + selected = "b", + keep_na = TRUE, + fixed = FALSE, + extra1 = "extraone" +) +filter_2 <- teal_slice( + dataname = "dataname1", + varname = "varname2", + choices = 1:10, + keep_na = TRUE, + selected = 2, + fixed = TRUE, + anchored = FALSE, + extra2 = "extratwo" +) +filter_3 <- teal_slice( + dataname = "dataname2", + varname = "varname3", + choices = 1:10 / 10, + keep_na = TRUE, + selected = 0.2, + fixed = TRUE, + anchored = FALSE, + extra1 = "extraone", + extra2 = "extratwo" +) + +all_filters <- teal_slices( + filter_1, + filter_2, + filter_3, + exclude_varnames = list( + "dataname1" = "varname2" + ) +) + +is.teal_slices(all_filters) +all_filters[1:2] +c(all_filters[1], all_filters[2]) +print(all_filters) +print(all_filters, trim_lines = FALSE) + +} +\keyword{internal} diff --git a/man/teal_slices.Rd b/man/teal_slices.Rd index 0e931d40b..d2fc19328 100644 --- a/man/teal_slices.Rd +++ b/man/teal_slices.Rd @@ -2,13 +2,6 @@ % Please edit documentation in R/teal_slices.R \name{teal_slices} \alias{teal_slices} -\alias{is.teal_slices} -\alias{as.teal_slices} -\alias{as.list.teal_slices} -\alias{[.teal_slices} -\alias{c.teal_slices} -\alias{format.teal_slices} -\alias{print.teal_slices} \title{Complete filter specification} \usage{ teal_slices( @@ -18,24 +11,9 @@ teal_slices( count_type = NULL, allow_add = TRUE ) - -is.teal_slices(x) - -as.teal_slices(x) - -\method{as.list}{teal_slices}(x, recursive = FALSE, ...) - -\method{[}{teal_slices}(x, i) - -\method{c}{teal_slices}(...) - -\method{format}{teal_slices}(x, show_all = FALSE, trim_lines = TRUE, ...) - -\method{print}{teal_slices}(x, ...) } \arguments{ -\item{...}{any number of \code{teal_slice} objects. For \code{print} and \code{format}, -additional arguments passed to other functions.} +\item{...}{any number of \code{teal_slice} objects.} \item{include_varnames, exclude_varnames}{(\verb{named list}s of \code{character}) where list names match names of data sets and vector elements match variable names in respective data sets; @@ -55,22 +33,13 @@ Please make sure that adding new filters doesn't fail on target platform before }} \item{allow_add}{(\code{logical(1)}) logical flag specifying whether the user will be able to add new filters} - -\item{x}{object to test for \code{teal_slices}, object to convert to \code{teal_slices} or a \code{teal_slices} object} - -\item{recursive}{(\code{logical(1)}) flag specifying whether to also convert to list the elements of this \code{teal_slices}} - -\item{i}{(\code{character} or \code{numeric} or \code{logical}) indicating which elements to extract} - -\item{show_all}{(\code{logical(1)}) whether to display non-null elements of constituent \code{teal_slice} objects} - -\item{trim_lines}{(\code{logical(1)}) whether to trim lines} } \value{ \code{teal_slices}, which is an unnamed list of \code{teal_slice} objects. } \description{ Create \code{teal_slices} object to package multiple filters and additional settings. +Check out \code{\link{teal_slices-utilities}} functions for working with \code{teal_slices} object. } \details{ \code{teal_slices()} collates multiple \code{teal_slice} objects into a \code{teal_slices} object, @@ -135,6 +104,7 @@ print(all_filters, trim_lines = FALSE) \itemize{ \item \code{\link{teal_slice}} for creating constituent elements of \code{teal_slices} \item \code{\link[teal:slices_store]{teal::slices_store}} for robust utilities for saving and loading \code{teal_slices} in \code{JSON} format +\item \code{\link{is.teal_slices}}, \code{\link{as.teal_slices}}, \code{\link{as.list.teal_slices}}, [\verb{[.teal_slices}], \code{\link{c.teal_slices}} +\code{\link{print.teal_slices}}, \code{\link{format.teal_slices}} } } -\keyword{internal}