Merge pull request #53 from stemangiola/fix-tidyr

fix tidyr

Author: stemangiola

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: tidySingleCellExperiment
 Title: Brings SingleCellExperiment to the Tidyverse 
-Version: 1.9.1
+Version: 1.9.2
 Authors@R: c(person("Stefano", "Mangiola", email = "[email protected]",
                   role = c("aut", "cre")) )
 Description: tidySingleCellExperiment is an adapter that abstracts the 'SingleCellExperiment' container 
@@ -57,7 +57,7 @@ Biarch: true
 biocViews: AssayDomain, Infrastructure, RNASeq, DifferentialExpression, GeneExpression, Normalization, Clustering, QualityControl, Sequencing
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.2.1
+RoxygenNote: 7.2.3
 Roxygen: list(markdown = TRUE)
 URL: https://github.com/stemangiola/tidySingleCellExperiment
 BugReports: https://github.com/stemangiola/tidySingleCellExperiment/issues

R/tidyr_methods.R

@@ -326,16 +326,36 @@ extract.SingleCellExperiment <- function(data, col, into, regex="([[:alnum:]]+)"
 #' @param data A data frame to pivot.
 #' @param cols <[`tidy-select`][tidyr_tidy_select]> Columns to pivot into
 #'   longer format.
-#' @param names_to A string specifying the name of the column to create
-#'   from the data stored in the column names of `data`.
+#' @param cols_vary When pivoting `cols` into longer format, how should the
+#'   output rows be arranged relative to their original row number?
 #'
-#'   Can be a character vector, creating multiple columns, if `names_sep`
-#'   or `names_pattern` is provided. In this case, there are two special
-#'   values you can take advantage of:
+#'   * `"fastest"`, the default, keeps individual rows from `cols` close
+#'     together in the output. This often produces intuitively ordered output
+#'     when you have at least one key column from `data` that is not involved in
+#'     the pivoting process.
 #'
-#'   * `NA` will discard that component of the name.
-#'   * `.value` indicates that component of the name defines the name of the
-#'     column containing the cell values, overriding `values_to`.
+#'   * `"slowest"` keeps individual columns from `cols` close together in the
+#'     output. This often produces intuitively ordered output when you utilize
+#'     all of the columns from `data` in the pivoting process.
+#' @param names_to A character vector specifying the new column or columns to
+#'   create from the information stored in the column names of `data` specified
+#'   by `cols`.
+#'
+#'   * If length 0, or if `NULL` is supplied, no columns will be created.
+#'
+#'   * If length 1, a single column will be created which will contain the
+#'     column names specified by `cols`.
+#'
+#'   * If length >1, multiple columns will be created. In this case, one of
+#'     `names_sep` or `names_pattern` must be supplied to specify how the
+#'     column names should be split. There are also two additional character
+#'     values you can take advantage of:
+#'
+#'     * `NA` will discard the corresponding component of the column name.
+#'
+#'     * `".value"` indicates that the corresponding component of the column
+#'       name defines the name of the output column containing the cell values,
+#'       overriding `values_to` entirely.
 #' @param names_prefix A regular expression used to remove matching text
 #'   from the start of each variable name.
 #' @param names_sep,names_pattern If `names_to` contains multiple values,
@@ -365,19 +385,24 @@ extract.SingleCellExperiment <- function(data, col, into, regex="([[:alnum:]]+)"
 #'   in the `value_to` column. This effectively converts explicit missing values
 #'   to implicit missing values, and should generally be used only when missing
 #'   values in `data` were created by its structure.
-#' @param names_transform,values_transform A list of column name-function pairs.
-#'   Use these arguments if you need to change the type of specific columns.
-#'   For example, `names_transform=list(week=as.integer)` would convert
-#'   a character week variable to an integer.
-#' @param names_ptypes,values_ptypes A list of column name-prototype pairs.
-#'   A prototype (or ptype for short) is a zero-length vector (like `integer()`
-#'   or `numeric()`) that defines the type, class, and attributes of a vector.
-#'   Use these arguments to confirm that the created columns are the types that
-#'   you expect.
+#' @param names_transform,values_transform Optionally, a list of column
+#'   name-function pairs. Alternatively, a single function can be supplied,
+#'   which will be applied to all columns. Use these arguments if you need to
+#'   change the types of specific columns. For example, `names_transform =
+#'   list(week = as.integer)` would convert a character variable called `week`
+#'   to an integer.
 #'
 #'   If not specified, the type of the columns generated from `names_to` will
 #'   be character, and the type of the variables generated from `values_to`
 #'   will be the common type of the input columns used to generate them.
+#' @param names_ptypes,values_ptypes Optionally, a list of column name-prototype
+#'   pairs. Alternatively, a single empty prototype can be supplied, which will
+#'   be applied to all columns. A prototype (or ptype for short) is a
+#'   zero-length vector (like `integer()` or `numeric()`) that defines the type,
+#'   class, and attributes of a vector. Use these arguments if you want to
+#'   confirm that the created columns are the types that you expect. Note that
+#'   if you want to change (instead of confirm) the types of specific columns,
+#'   you should use `names_transform` or `values_transform` instead.
 #' @param ... Additional arguments passed on to methods.
 #'
 #' @return A tidySingleCellExperiment objector a tibble depending on input
@@ -397,19 +422,11 @@ NULL
 
 #' @export
 pivot_longer.SingleCellExperiment <- function(data,
-    cols,
-    names_to="name",
-    names_prefix=NULL,
-    names_sep=NULL,
-    names_pattern=NULL,
-    names_ptypes=list(),
-    names_transform=list(),
-    names_repair="check_unique",
-    values_to="value",
-    values_drop_na=FALSE,
-    values_ptypes=list(),
-    values_transform=list(),
-    ...) {
+                                              cols, ..., cols_vary = "fastest", names_to = "name",
+                                              names_prefix = NULL, names_sep = NULL, names_pattern = NULL,
+                                              names_ptypes = NULL, names_transform = NULL, names_repair = "check_unique",
+                                              values_to = "value", values_drop_na = FALSE, values_ptypes = NULL,
+                                              values_transform = NULL) {
     cols <- enquo(cols)
 
     message(data_frame_returned_message)
@@ -425,18 +442,19 @@ pivot_longer.SingleCellExperiment <- function(data,
     data %>%
         as_tibble() %>%
         tidyr::pivot_longer(!!cols,
-            names_to=names_to,
-            names_prefix=names_prefix,
-            names_sep=names_sep,
-            names_pattern=names_pattern,
-            names_ptypes=names_ptypes,
-            names_transform=names_transform,
-            names_repair=names_repair,
-            values_to=values_to,
-            values_drop_na=values_drop_na,
-            values_ptypes=values_ptypes,
-            values_transform=values_transform,
-            ...
+                            ...,
+                            cols_vary = cols_vary,
+                            names_to = names_to,
+                            names_prefix = names_prefix,
+                            names_sep = names_sep,
+                            names_pattern = names_pattern,
+                            names_ptypes = names_ptypes,
+                            names_transform = names_transform,
+                            names_repair = names_repair,
+                            values_to = values_to,
+                            values_drop_na = values_drop_na,
+                            values_ptypes = values_ptypes,
+                            values_transform = values_transform
         )
 }