Merge pull request #113 from sa-lee/devel

feat: add pull method, alongside tests and updated documentation

Author: sa-lee

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: plyranges
 Type: Package
 Title: A fluent interface for manipulating GenomicRanges
-Version: 1.27.5
+Version: 1.27.6
 Authors@R: c(
       person("Stuart", "Lee", role = c("aut"), 
              comment = c(ORCID = "0000-0003-1179-8436")),
@@ -22,10 +22,10 @@ Depends:
   R (>= 3.5),
   BiocGenerics,
   IRanges (>= 2.12.0),
-  GenomicRanges (>= 1.28.4)
+  GenomicRanges (>= 1.28.4),
+  dplyr
 Imports:
   methods,
-  dplyr, 
   rlang (>= 0.2.0), 
   magrittr,
   tidyselect (>= 1.0.0),
@@ -53,7 +53,7 @@ Suggests:
     ggplot2
 VignetteBuilder: knitr
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.2
 Collate: 
     'class-AnchoredRanges.R'
     'class-Operator.R'
@@ -63,6 +63,7 @@ Collate:
     'dplyr-filter.R'
     'dplyr-groups.R'
     'dplyr-mutate.R'
+    'dplyr-pull.R'
     'dplyr-select.R'
     'dplyr-slice.R'
     'dplyr-summarize.R'
@@ -105,4 +106,4 @@ Collate:
     'ranges-rangewise-setops.R'
     'ranges-reduce.R'
     'ranges-setops.R'
-    'reexports.R'
+    'utils-pipe.R'

NAMESPACE

@@ -41,6 +41,8 @@ S3method(disjoin_ranges,GroupedIntegerRanges)
 S3method(disjoin_ranges,IntegerRanges)
 S3method(disjoin_ranges_directed,GenomicRanges)
 S3method(disjoin_ranges_directed,GroupedGenomicRanges)
+S3method(dplyr::pull,Ranges)
+S3method(filter,BamFileOperator)
 S3method(filter,DeferredGenomicRanges)
 S3method(filter,DelegatingGenomicRanges)
 S3method(filter,DelegatingIntegerRanges)
@@ -50,6 +52,7 @@ S3method(filter,Ranges)
 S3method(filter_by_non_overlaps,GenomicRanges)
 S3method(filter_by_non_overlaps,IntegerRanges)
 S3method(filter_by_non_overlaps_directed,GenomicRanges)
+S3method(filter_by_overlaps,BamFileOperator)
 S3method(filter_by_overlaps,DeferredGenomicRanges)
 S3method(filter_by_overlaps,GenomicRanges)
 S3method(filter_by_overlaps,IntegerRanges)
@@ -121,6 +124,7 @@ S3method(join_precede,IntegerRanges)
 S3method(join_precede_downstream,GenomicRanges)
 S3method(join_precede_right,GenomicRanges)
 S3method(join_precede_right,IntegerRanges)
+S3method(load_genomic_file,BamFileOperator)
 S3method(mutate,AnchoredGenomicRanges)
 S3method(mutate,AnchoredIntegerRanges)
 S3method(mutate,DeferredGenomicRanges)
@@ -129,6 +133,11 @@ S3method(mutate,DelegatingIntegerRanges)
 S3method(mutate,GroupedGenomicRanges)
 S3method(mutate,GroupedIntegerRanges)
 S3method(mutate,Ranges)
+S3method(overscope_ranges,DelegatingGenomicRanges)
+S3method(overscope_ranges,DelegatingIntegerRanges)
+S3method(overscope_ranges,GroupedGenomicRanges)
+S3method(overscope_ranges,GroupedIntegerRanges)
+S3method(overscope_ranges,Ranges)
 S3method(pair_follow,GenomicRanges)
 S3method(pair_follow,IntegerRanges)
 S3method(pair_nearest,GenomicRanges)
@@ -137,6 +146,10 @@ S3method(pair_overlaps,GenomicRanges)
 S3method(pair_overlaps,IntegerRanges)
 S3method(pair_precede,GenomicRanges)
 S3method(pair_precede,IntegerRanges)
+S3method(pull,DelegatingGenomicRanges)
+S3method(pull,DelegatingIntegerRanges)
+S3method(pull,GroupedGenomicRanges)
+S3method(pull,GroupedIntegerRanges)
 S3method(reduce_ranges,GenomicRanges)
 S3method(reduce_ranges,GroupedGenomicRanges)
 S3method(reduce_ranges,GroupedIntegerRanges)
@@ -148,6 +161,13 @@ S3method(select,DeferredGenomicRanges)
 S3method(select,DelegatingGenomicRanges)
 S3method(select,DelegatingIntegerRanges)
 S3method(select,Ranges)
+S3method(set_end,Ranges)
+S3method(set_seqnames,GenomicRanges)
+S3method(set_start,Ranges)
+S3method(set_strand,GenomicRanges)
+S3method(set_width,AnchoredGenomicRanges)
+S3method(set_width,AnchoredIntegerRanges)
+S3method(set_width,Ranges)
 S3method(setdiff_ranges,GenomicRanges)
 S3method(setdiff_ranges,IntegerRanges)
 S3method(setdiff_ranges_directed,GenomicRanges)
@@ -174,8 +194,6 @@ S3method(ungroup,Ranges)
 S3method(union_ranges,GenomicRanges)
 S3method(union_ranges,IntegerRanges)
 S3method(union_ranges_directed,GenomicRanges)
-export("!!!")
-export("!!")
 export("%>%")
 export("%intersect%")
 export("%setdiff%")
@@ -192,7 +210,6 @@ export(anchor_center)
 export(anchor_centre)
 export(anchor_end)
 export(anchor_start)
-export(arrange)
 export(as_granges)
 export(as_iranges)
 export(as_ranges)
@@ -210,7 +227,6 @@ export(count_overlaps_within_directed)
 export(disjoin_ranges)
 export(disjoin_ranges_directed)
 export(expand_ranges)
-export(filter)
 export(filter_by_non_overlaps)
 export(filter_by_non_overlaps_directed)
 export(filter_by_overlaps)
@@ -225,10 +241,7 @@ export(flank_right)
 export(flank_upstream)
 export(genome_info)
 export(get_genome_info)
-export(group_by)
 export(group_by_overlaps)
-export(group_vars)
-export(groups)
 export(id_to_column)
 export(intersect_ranges)
 export(intersect_ranges_directed)
@@ -260,7 +273,6 @@ export(join_overlap_self_within_directed)
 export(join_precede)
 export(join_precede_downstream)
 export(join_precede_right)
-export(mutate)
 export(n)
 export(n_distinct)
 export(names_to_column)
@@ -282,7 +294,6 @@ export(read_wig)
 export(reduce_ranges)
 export(reduce_ranges_directed)
 export(remove_names)
-export(select)
 export(set_end)
 export(set_genome_info)
 export(set_seqnames)
@@ -295,15 +306,11 @@ export(shift_downstream)
 export(shift_left)
 export(shift_right)
 export(shift_upstream)
-export(slice)
 export(slide_ranges)
 export(span)
 export(stretch)
-export(summarise)
-export(summarize)
 export(tile_ranges)
 export(unanchor)
-export(ungroup)
 export(union_ranges)
 export(union_ranges_directed)
 export(write_bed)
@@ -320,6 +327,7 @@ exportClasses(DeferredGenomicRanges)
 exportClasses(FileOperator)
 exportClasses(GroupedGenomicRanges)
 exportClasses(GroupedIntegerRanges)
+import(dplyr)
 importFrom(BiocGenerics,"%in%")
 importFrom(BiocGenerics,"end<-")
 importFrom(BiocGenerics,"score<-")
@@ -351,9 +359,6 @@ importFrom(GenomicAlignments,readGAlignments)
 importFrom(GenomicRanges,GRanges)
 importFrom(GenomicRanges,distanceToNearest)
 importFrom(GenomicRanges,granges)
-importFrom(GenomicRanges,intersect)
-importFrom(GenomicRanges,setdiff)
-importFrom(GenomicRanges,union)
 importFrom(IRanges,IRanges)
 importFrom(IRanges,as.env)
 importFrom(IRanges,countOverlaps)
@@ -365,7 +370,6 @@ importFrom(IRanges,findOverlapPairs)
 importFrom(IRanges,findOverlaps)
 importFrom(IRanges,flank)
 importFrom(IRanges,follow)
-importFrom(IRanges,intersect)
 importFrom(IRanges,mid)
 importFrom(IRanges,nearest)
 importFrom(IRanges,pgap)
@@ -376,12 +380,10 @@ importFrom(IRanges,punion)
 importFrom(IRanges,ranges)
 importFrom(IRanges,reduce)
 importFrom(IRanges,resize)
-importFrom(IRanges,setdiff)
 importFrom(IRanges,shift)
 importFrom(IRanges,slidingWindows)
 importFrom(IRanges,subsetByOverlaps)
 importFrom(IRanges,tile)
-importFrom(IRanges,union)
 importFrom(Rsamtools,"bamFlag<-")
 importFrom(Rsamtools,"bamMapqFilter<-")
 importFrom(Rsamtools,"bamTag<-")
@@ -403,15 +405,13 @@ importFrom(S4Vectors,decode)
 importFrom(S4Vectors,elementNROWS)
 importFrom(S4Vectors,endoapply)
 importFrom(S4Vectors,expand)
-importFrom(S4Vectors,first)
 importFrom(S4Vectors,mcols)
 importFrom(S4Vectors,metadata)
 importFrom(S4Vectors,parallelVectorNames)
 importFrom(S4Vectors,queryHits)
 importFrom(S4Vectors,queryLength)
 importFrom(S4Vectors,rbind)
 importFrom(S4Vectors,runValue)
-importFrom(S4Vectors,second)
 importFrom(S4Vectors,splitAsList)
 importFrom(S4Vectors,subjectHits)
 importFrom(S4Vectors,zipup)
@@ -427,6 +427,7 @@ importFrom(dplyr,group_split)
 importFrom(dplyr,group_vars)
 importFrom(dplyr,groups)
 importFrom(dplyr,mutate)
+importFrom(dplyr,pull)
 importFrom(dplyr,sample_n)
 importFrom(dplyr,select)
 importFrom(dplyr,slice)
@@ -449,16 +450,17 @@ importFrom(methods,setMethod)
 importFrom(methods,setValidity)
 importFrom(methods,show)
 importFrom(rlang,"!!!")
-importFrom(rlang,"!!")
 importFrom(rlang,":=")
 importFrom(rlang,dots_values)
+importFrom(rlang,enquo)
 importFrom(rlang,enquos)
 importFrom(rlang,env_bind)
 importFrom(rlang,env_get)
 importFrom(rlang,env_parent)
 importFrom(rlang,eval_tidy)
 importFrom(rlang,have_name)
 importFrom(rlang,new_data_mask)
+importFrom(rlang,quo_is_missing)
 importFrom(rlang,quo_name)
 importFrom(rlang,quos)
 importFrom(rlang,syms)

NEWS.md

@@ -1,3 +1,8 @@
+# plyranges 1.27.6
+
+* added `pull()` method for Ranges objects that extracts a single column as a vector
+* moved `dplyr` to Depends and removing tidyverse reexports 
+
 # plyranges 1.9.3
 
 * minor spelling and layout fixes to vignette, 

R/class-Operator.R

@@ -38,10 +38,10 @@ new_bam_ops <- function(file, index = file, paired = FALSE) {
 # Generic File loader
 #' @importFrom Rsamtools bamFlag bamWhich ScanBamParam
 #' @importFrom GenomicAlignments readGAlignments readGAlignmentPairs
-#' @importFrom S4Vectors first second
+#' @importFrom S4Vectors DataFrame
 load_genomic_file <- function(ops) UseMethod("load_genomic_file")
 
-
+#' @export
 load_genomic_file.BamFileOperator <- function(ops) {
   if (ops@paired) return(paired_alignments(ops))
   unpaired_alignments(ops)
@@ -66,8 +66,8 @@ paired_alignments <- function(ops) {
     param = ops@param,
     with.which_label = check_which_label(ops)
   )
-  r1 <- first(alignments)
-  r2 <- second(alignments)
+  r1 <- S4Vectors::first(alignments)
+  r2 <- S4Vectors::second(alignments)
   r1_grng <- galn_to_grng(r1)
   mcols(r1_grng)[["read_pair_id"]] <- seq_along(r1_grng)
   mcols(r1_grng)[["read_pair_group"]] <- 1L

R/dplyr-groups.R

@@ -23,7 +23,7 @@
 #'
 #' @section Accessors:
 #' To return grouping variables on a grouped Ranges use either
-#' \itemize{
+#' \describe{
 #'   \item{`groups(x)`}{Returns a list of symbols}
 #'   \item{`group_vars(x)`}{Returns a character vector}
 #' }

R/dplyr-pull.R

@@ -0,0 +1,88 @@
+#' Extract a single column from a Ranges object as a vector
+#'
+#' @param .data a `Ranges` object
+#' @param var A variable specified as:
+#'   * a literal variable name
+#'   * a positive integer, giving the position counting from the left. In this
+#'   case order is start, end, width, (strand, seqnames), gc and score. 
+#'   * a negative integer, giving the position counting from the right.
+#'   The default returns the last column (on the assumption that's the column 
+#'   you've created most recently). This argument is taken by expression and 
+#'   supports quasiquotation (you can unquote column names and column locations).
+#' @param name An optional parameter that specifies the column to be used as 
+#'   names for a named vector. Specified in a similar manner as `var`.
+#' @param ... For use by methods.
+#'
+#'
+#' @importFrom dplyr pull
+#' @importFrom rlang enquo quo_is_missing
+#' @importFrom tidyselect eval_select
+#' @seealso [dplyr::pull()]
+#' @name pull-ranges
+#' @rdname pull-ranges
+#'
+#' @examples
+#' df <- data.frame(start = 1:10,
+#'                  width = 5,
+#'                  seqnames = "seq1",
+#'                  strand = sample(c("+", "-", "*"), 10, replace = TRUE),
+#'                  gc = runif(10),
+#'                  score = rpois(10, 2))
+#' rng <- as_granges(df)
+#'
+#' # Pull parts of the range
+#' pull(rng, start)
+#' # equivalent to start(rng)
+#'
+#' # Pull by column name
+#' pull(rng, gc)
+#' pull(rng, score)
+#'
+#' # Pull by position (positive from left, negative from right)
+#' pull(rng, 1)    # First metadata column
+#' pull(rng, -1)   # Last metadata column (default)
+#' pull(rng, -2)   # Second to last metadata column
+#'
+#' # Pull with names
+#' pull(rng, score, name = gc)
+#'
+#' @method pull Ranges
+#' @exportS3Method dplyr::pull
+pull.Ranges <- function(.data, var = -1, name = NULL, ...) {
+  
+  var <- tidyselect::vars_pull(tbl_vars(.data), !!rlang::enquo(var))
+  name <- rlang::enquo(name)
+  env <- overscope_ranges(.data) 
+  
+  pulled <- eval_tidy(rlang::ensym(var), env)
+  if (rlang::quo_is_null(name)) {
+    return(pulled)
+  }
+  
+  name <- tidyselect::vars_pull(tbl_vars(.data), !!name)
+  named <- eval_tidy(rlang::ensym(name), env)
+  
+  rlang::set_names(pulled, nm = named)
+  
+}
+  
+
+#' @method pull DelegatingGenomicRanges
+#' @export
+pull.DelegatingGenomicRanges <- function(.data, var = -1, name = NULL, ...) {
+  pull(.data@delegate, var = {{var}}, name = {{name}}, ...)
+}
+
+#' @method pull DelegatingIntegerRanges
+#' @export
+pull.DelegatingIntegerRanges <- pull.DelegatingGenomicRanges
+
+#' @method pull GroupedGenomicRanges
+#' @export
+pull.GroupedGenomicRanges <- function(.data, var = -1, name = NULL, ...) {
+  pull(.data@delegate, var = {{var}}, name = {{name}}, ...)
+}
+
+#' @method pull GroupedIntegerRanges
+#' @export
+pull.GroupedIntegerRanges <- pull.GroupedGenomicRanges

R/dplyr-slice.R

@@ -13,7 +13,7 @@ generate_slice <- function(.data, dots) {
 #' 
 #' @param .data a `Ranges` object
 #' @param ... Integer row values indicating rows to keep. If `.data` has
-#' been grouped via [group_by()], then the positions are selected within each group.
+#' been grouped via [group_by.GenomicRanges()], then the positions are selected within each group.
 #' @param .preserve when FALSE (the default) the grouping structure is 
 #' recomputed, otherwise it is kept as is. Currently ignored. 
 #' @return a GRanges object