misha (version 5.11.23)

gsegment: Divides track expression into segments

Description

Divides the values of track expression into segments by using Wilcoxon test.

Usage

gsegment(
  expr = NULL,
  minsegment = NULL,
  maxpval = 0.05,
  onetailed = TRUE,
  intervals = NULL,
  iterator = NULL,
  intervals.set.out = NULL
)

Value

If 'intervals.set.out' is 'NULL' a set of intervals where each interval represents a segment.

Arguments

expr

track expression

minsegment

minimal segment size

maxpval

maximal P-value that separates two adjacent segments

onetailed

if 'TRUE', Wilcoxon test is performed one tailed, otherwise two tailed

intervals

genomic scope for which the function is applied

iterator

track expression iterator of "fixed bin" type. If 'NULL' iterator is determined implicitly based on track expression.

intervals.set.out

intervals set name where the function result is optionally outputted

NaN values

A track expression evaluates to NaN wherever the iterator produces a bin the track has no data for. What happens next depends on the function:

• gextract keeps NaN rows, so the result has one row per iterator interval whether or not the track covered it.

• gsummary counts them and reports the count as the "NaN intervals" element, while the statistics themselves are computed over the non-NaN values only.

• gdist, gquantiles and gscreen drop them: NaN bins are not counted into any distribution bin, do not contribute to a percentile, and never satisfy a screening condition - including a condition that would be true of every real value.

• gsegment spans them: a NaN bin contributes no evidence to the test that places a boundary, but it still falls inside whichever segment surrounds it, so the returned segments tile the scope continuously rather than skipping the gaps.

So on 20 bins of which 7 are NaN, gextract returns 20 rows, gsummary reports 20 total and 7 NaN, and gdist counts 13; and on a 300 kb scope where 120 of 300 bins are NaN, gsegment still returns segments covering the full 300 kb.

The practical consequence is that NaN and zero are different, and collapsing them with ifelse(is.na(x), 0, x) turns "no data here" into a measured value of zero. Where that is genuinely what you want, note that it also changes every mean, quantile and distribution computed downstream.

Details

This function divides the values of track expression into segments, where each segment size is at least of 'minsegment' size and the P-value of comparing the segment with the first 'minsegment' values from the next segment is at most 'maxpval'. Comparison is done using Wilcoxon (also known as Mann-Whitney) test.

If 'intervals.set.out' is not 'NULL' the result is saved as an intervals set. Use this parameter if the result size exceeds the limits of the physical memory.

See Also

gscreen, gwilcox

Examples

# \dontshow{
options(gmax.processes = 2)
# }

gdb.init_examples()
gsegment("dense_track", 5000, 0.0001)