gr.val: Annotate 'GRanges' with values from another 'GRanges'

In mskilab/gUtils: R Package Providing Additional Capabilities and Speed for GenomicRanges Operations

Annotate GRanges with values from another GRanges

Description

Annotates GRanges in query with aggregated values of GRanges in target in field val. If val is numeric: given target with value column target representing ranged data (i.e. segment intensities), thn computes the value in each query GRanges as the weighted mean of its intersection with target (ie the target values weighted by the width of the intersections).

Applications include (among others):

• Querying the average value of target across a given query interval (e.g. exon to gene pileup)

• recasting a high res tiling in terms of low res intervals.

Usually query intervals are bigger than the target intervals.

Usage

gr.val(
  query,
  target,
  val = NULL,
  mean = TRUE,
  weighted = mean,
  na.rm = FALSE,
  by = NULL,
  by.prefix = val,
  merge = FALSE,
  FUN = NULL,
  default.val = NA,
  max.slice = Inf,
  mc.cores = 1,
  sep = ", ",
  verbose = FALSE,
  ...
)

Arguments

query	GRanges of query ranges whose val column we will populate with aggregated values of target
target	GRanges of target ranges that already have "val" column populated
val	If a character field: then aggregation will paste together the (unique), overlapping values, collapsing by comma. (default = NULL)
mean	boolean If FALSE then will return sum instead of mean, only applies if target val column is numeric. (default = TRUE)
weighted	Calculate a weighted mean. If FALSE, calculates unweighted mean. (default = 'mean')
na.rm	boolean Remove NA values when calulating means. only applies if val column of target is numeric (default = FALSE)
by	scalar character, specifies additional "by" column of query AND target that will be used to match up query and target pairs (i.e. in addition to pure GRanges overlap). (default = NULL)
by.prefix	Choose a set of val fields by a shared prefix. (default = 'val')
merge	boolean If merge = FALSE then will cross every range in query with every level of "by" in target (and create data matrix), otherwise will assume query has "by" and merge only ranges that have matching "by" values in both query and target (default = FALSE)
FUN	Optional different function to call than mean. Takes two arguments (value, na.rm = TRUE) if weighted = FALSE, and three (value, width, na.rm = TRUE) if weighted = TRUE. (default = NULL)
default.val	If no hit in target found in query, fill output val field with this value. (default = NA)
max.slice	integer Maximum number of query ranges to consider in one memory chunk. (default = Inf)
mc.cores	integer Number of cores to use when running in chunked mode (default = 1)
sep	string Specifies character to use as separator when aggregating character "vals" from target, only applies if target is character (default = ', ')
verbose	boolean Increase the verbosity of the output (default = FALSE)
...	Additional arguments to be sent to gr.findoverlaps.

Value

query with the val field populated

Note

query and target can be GRangesList object, in which case val will refer to GRangesList level values fields

Author(s)

Marcin Imielinski

mskilab/gUtils documentation built on June 15, 2025, 2:52 p.m.