Skip to contents

Calculates summary statistics of track expression

Source: R/compute-core.R
gsummary.Rd

Calculates summary statistics of track expression.

Usage

gsummary(expr = NULL, intervals = NULL, iterator = NULL, band = NULL)

Arguments

expr

track expression

intervals

genomic scope for which the function is applied

iterator

track expression iterator. If 'NULL' iterator is determined implicitly based on track expression.

band

track expression band. If 'NULL' no band is used.

Value

An array that represents summary statistics.

Details

This function returns summary statistics of a track expression: total number of bins, total number of bins whose value is NaN, min, max, sum, mean and standard deviation of the values.

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.

See also

gintervals.summary, gbins.summary

Examples


gdb.init_examples()
gsummary("rects_track")
#> Total intervals   NaN intervals             Min             Max             Sum 
#>         1600.00            0.00            3.00       141495.00     85801800.00 
#>            Mean         Std dev 
#>        53626.12        39867.94