Returns the result of track expressions evaluation for each of the iterator intervals.
gextract(
...,
intervals = NULL,
colnames = NULL,
iterator = NULL,
band = NULL,
file = NULL,
intervals.set.out = NULL,
intervals_join = c("id", "intervals", "none")
)If 'file' and 'intervals.set.out' are 'NULL' a set of intervals with an additional column for each of the track expressions and 'intervalID' column.
track expression
genomic scope for which the function is applied
sets the columns names in the returned value. If 'NULL' names are set to track expression.
track expression iterator. If 'NULL' iterator is determined implicitly based on track expressions.
track expression band. If 'NULL' no band is used.
file name where the function result is optionally outputted in tab-delimited format
intervals set name where the function result is optionally outputted
how the output relates to the input intervals data
frame. "id" (default) appends an intervalID integer column
carrying the 1-based row index of the originating input interval.
"intervals" drops intervalID and instead attaches every column
of the input intervals data frame (coords + metadata) to each output row,
suffixing names that collide with existing output columns with "1".
"none" drops intervalID and attaches nothing. The
"intervals" mode is only supported when the result is returned in
memory; combining it with file or intervals.set.out raises an
error.
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.
This function returns the result of track expressions evaluation for each of the iterator intervals. The returned value is a set of intervals with an additional column for each of the track expressions. This value can be used as an input for any other function that accepts intervals. If the intervals inside 'intervals' argument overlap gextract returns the overlapped coordinate more than once.
The order inside the result might not be the same as the order of intervals. An additional column 'intervalID' is added to the return value. Use this column to refer to the index of the original interval from the supplied 'intervals'.
If 'file' parameter is not 'NULL' the result is outputted to a tab-delimited text file (without 'intervalID' column) rather than returned to the user. This can be especially useful when the result is too big to fit into the physical memory. The resulted file can be used as an input for 'gtrack.import' or 'gtrack.array.import' functions.
If 'intervals.set.out' is not 'NULL' the result is saved as an intervals set. Similarly to 'file' parameter 'intervals.set.out' can be useful to overcome the limits of the physical memory.
'colnames' parameter controls the names of the columns that contain the evaluated expressions. By default the column names match the track expressions.
gtrack.array.extract, gsample,
gtrack.import, gtrack.array.import,
glookup, gpartition, gdist
# \dontshow{
options(gmax.processes = 2)
# }
gdb.init_examples()
## get values of 'dense_track' for [0, 400), chrom 1
gextract("dense_track", gintervals(1, 0, 400))
## get values of 'rects_track' (a 2D track) for a 2D interval
gextract(
"rects_track",
gintervals.2d("chr1", 0, 4000, "chr2", 2000, 5000)
)
Run the code above in your browser using DataLab