group_by-ranges: Group a Ranges by one or more variables

In sa-lee/plyranges: A fluent interface for manipulating GenomicRanges

Group a Ranges by one or more variables

Description

The function group_by takes a Ranges object and defines groups by one or more variables. Operations are then performed on the Ranges by their "group". ungroup() removes grouping.

Usage

## S3 method for class 'GenomicRanges'
group_by(.data, ..., add = FALSE)

## S3 method for class 'GroupedGenomicRanges'
ungroup(x, ...)

## S3 method for class 'GroupedGenomicRanges'
groups(x)

## S3 method for class 'GroupedIntegerRanges'
groups(x)

Arguments

.data	a Ranges object.
...	Variable names to group by. These can be either metadata columns or the core variables of a Ranges.
add	if .data is already a GroupedRanges object, when add = FALSE the (default), group_by() will override existing groups. If add = TRUE, additional groups will be added.
x	a GroupedRanges object.

Details

group_by() creates a new object of class GroupedGenomicRanges if the input is a GRanges object or an object of class GroupedIntegerRanges if the input is a IRanges object. Both of these classes contain a slot called groups corresponding to the names of grouping variables. They also inherit from their parent classes, Ranges and GenomicRanges respectively. ungroup() removes the grouping and will return either a GRanges or IRanges object.

Value

The group_by() function will return a GroupedRanges object. These have the same appearance as a regular Ranges object but with an additional groups slot.

Accessors

To return grouping variables on a grouped Ranges use either

• groups(x)Returns a list of symbols

• group_vars(x)Returns a character vector

Examples

set.seed(100)
df <- data.frame(start = 1:10,
                 width = 5,
                 gc = runif(10),
                 cat = sample(letters[1:2], 10, replace = TRUE))
rng <- as_iranges(df)
rng_by_cat <- rng %>% group_by(cat)
# grouping does not change appearance or shape of Ranges
rng_by_cat
# a list of symbols
groups(rng_by_cat)
# ungroup removes any grouping
ungroup(rng_by_cat)
# group_by works best with other verbs
grng <- as_granges(df,
                   seqnames = "chr1",
                   strand = sample(c("+", "-"), size = 10, replace = TRUE))

grng_by_strand <- grng %>% group_by(strand)
grng_by_strand
# grouping with other verbs
grng_by_strand %>% summarise(gc = mean(gc))
grng_by_strand %>% filter(gc == min(gc))
grng_by_strand %>%
  ungroup() %>%
  summarise(gc = mean(gc))

sa-lee/plyranges documentation built on April 15, 2024, 12:25 p.m.