GroupedGenomicRanges-class {plyranges} | R Documentation

## 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))

[Package plyranges version 1.12.1 Index]