Operating on Integer-Bounded Intervals

Description

Manipulate integer-bounded intervals including finding overlaps, piling and merging.

Details

The DESCRIPTION file:

Index of help topics:

IntervalSurgeon-package                                     Operating on Integer-Bounded Intervals
annotate                                                    Annotate one set of intervals with the names of those which intersect with the other
breaks                                                      Get break points for set of intervals
depth                                                       Depth of piled intervals
detached_sorted_nonempty                                    Check intervals are detached, sorted and non-empty.
flatten                                                     Flatten a set of intervals
intersected                                                 Determine whether each interval in a given set are intersected/covered by intervals in another set
join                                                        Get all overlapping tuples of intervals from multiple sets
overlaps                                                    Compute overlaps of two sets of detached and sorted intervals
pile                                                        Get IDs of intervals covering each sub-interval
proportion_overlap                                          Calculate proportion overlapping of intersecting intervals
sections                                                    Get the sections from a set of interval breaks
stitch                                                      Stich together touching intervals and remove empty intervals

IntervalSurgeon presents functions for manipulating integer-bounded sets of intervals. Sets of intervals are represented by two-column matrices, where inclusive start points are stored in the first column, and exclusive end points in the second. A central concept in the package is the ‘sections’ of a set of intervals x: the non-overlapping, completely-covering set of intervals on the range of x, formed by making intervals between the consecutive sorted start/end points of the intevals in x. The function sections returns such a set of intervals given an input set.

Author(s)

Daniel Greene

Maintainer: Daniel Greene <dg333@cam.ac.uk>

Annotate one set of intervals with the names of those which intersect with the other

Description

Create a list of vectors of indices/names of intervals/points in annotation (if annotation is a two-column matrix/vector respectively) which intersect with each interval/point in x (if x is a two-column matrix/vector respectively).

Usage

annotate(x, annotation)

Arguments

Value

List of vectors of indices of overlapping intervals/points.

Examples

annotate(rbind(A=c(1, 100), B=c(50, 100)), rbind(a=c(1, 2), b=c(49, 51), c=c(50, 200)))
annotate(rbind(A=c(1, 100), B=c(50, 100)), c(a=1, b=49, c=51, d=100))

Get break points for set of intervals

Description

Get the sorted set start points and end points for a set of intervals specified as an integer matrix.

Usage

breaks(x)

Arguments

Value

Ordered integer vector of unique interval start/end points.

Examples

breaks(cbind(2*1:5, 3*1:5))

Depth of piled intervals

Description

Get the depth of piled intervals for each section in the sections of x (see sections).

Usage

depth(x, include_intervals = FALSE)

Arguments

Value

Integer vector giving depth of piled intervals from x (within each sub-interval) or list containing a property "intervals", a matrix of sections, and property "depths", giving the corresponding pile depths.

Examples

depth(cbind(1:10, 11:20))

Check intervals are detached, sorted and non-empty.

Description

Check that x is an integer matrix specifying intervals, that the specified intervals are detached (i.e. non-overlapping/disjoint and non-touching) and that it is sorted (given that the intervals are detached, sorting by start position gives a unique result), and that the start points are greater than the end points (i.e. that they are non-empty/the lengths of all intervals is greater than zero).

Usage

detached_sorted_nonempty(x)

Arguments

Value

Boolean value.

Examples

detached_sorted_nonempty(cbind(1:2, 2:3)) 
detached_sorted_nonempty(cbind(c(1, 3), c(2, 4))) 
detached_sorted_nonempty(cbind(1, 1)) 

Flatten a set of intervals

Description

For a given set of intervals compute the set of intervals where there is overlap with at least one from the given. The resulting intervals are sorted and detached.

Usage

flatten(x)

Arguments

Value

Intervals represented by integer matrix of two columns.

Examples

flatten(rbind(c(1, 3), c(2, 4), c(5, 6)))

Determine whether each interval in a given set are intersected/covered by intervals in another set

Description

Compute a logical vector indicating whether corresponding intervals specified by x overlap (intersected)/are covered by (covered) those in by_intervals.

Usage

intersected(x, by_intervals)

covered(x, by_intervals)

Arguments

Value

Logical vector with elements corresponding to rows of x.

Examples

intersected(rbind(c(1, 2), c(49, 51), c(50, 200)), rbind(c(50, 100)))
covered(rbind(c(1, 10), c(49, 51), c(50, 200)), rbind(c(2, 60)))

Get all overlapping tuples of intervals from multiple sets

Description

Get matrix specifying overlapping tuples of intervals from multiple sets. Each row specifies an overlapping tuple. The nth element in a row contains the row index of the interval in the nth set of intervals passed to the function. Depending on the value of the output argument, there may two additional columns giving the start and end coordinates of the overlap (the default: output="intervals", no extra columns (output="indices") or one additional column giving the row index of the 'section' of the complete set of intervals (output="sections", see sections).

Usage

join(..., output = "intervals")

Arguments

Value

Integer matrix.

Examples

join(rbind(c(1, 100), c(50, 100)), rbind(c(1, 2), c(49, 51), c(50, 200)))

Compute overlaps of two sets of detached and sorted intervals

Description

Find intervals satisfying particular conditions, including corresponding base R functions intersect (i.e. find intersections of intervals), union (i.e. unions of intervals) and setdiff (i.e. finding intervals which are contained in one set of intervals but not another).

Usage

overlaps(x, y, check = TRUE, in_x = TRUE, in_y = TRUE, op = "and")

intersects(x, y, ...)

unions(x, y, ...)

setdiffs(x, y, ...)

Arguments

Value

Intervals represented by integer matrix of two columns.

Examples

intersects(cbind(1, 3), cbind(2, 4))
setdiffs(cbind(1, 3), cbind(2, 4))
unions(cbind(1, 3), cbind(2, 4))

Get IDs of intervals covering each sub-interval

Description

Get the intervals overlapping each section as a list.

Usage

pile(x, interval_names = rownames(x), output = "list")

Arguments

Value

See notes on output parameter.

Examples

pile(cbind(1:10, 11:20))

Calculate proportion overlapping of intersecting intervals

Description

Proportion overlapping is calculated as the size of the intersection of intervals, divided by the size of the union.

Usage

proportion_overlap(...)

Arguments

Value

data.frame containing integer columns corresponding to indices of intervals within the input matrices and a final numeric column called proportion_overlap containing the fraction of the size of the intersection within the union.

Examples

proportion_overlap(rbind(c(1, 2), c(49, 51), c(50, 200)), rbind(c(50, 100)))

Get the sections from a set of interval breaks

Description

Given a set of interval breaks (see breaks), generate a new set of intervals, the ‘sections’, which partitions the full range of the given set, with an interval between every ‘break’ (i.e. start/end point) in the given set.

Usage

sections(x)

Arguments

Value

Intervals represented by integer matrix of two columns.

Examples

sections(1:10)

Stich together touching intervals and remove empty intervals

Description

Given an integer matrix specifying disjoint intervals sorted by start position, merge intervals with matching start and ends, and remove intervals of length zero.

Usage

stitch(x)

Arguments

Value

Intervals represented by integer matrix of two columns.

Examples

stitch(cbind(1:2, 2:3))