bridgeRegions maps unaligned regions flanked by colinear regions.

Fixes #13

DESCRIPTION

@@ -52,6 +52,7 @@ Collate:
     'bp_coverage.R'
     'bp_heatmap.R'
     'bp_pair_analysis.R'
+    'bridgeRegions.R'
     'chain_contigs.R'
     'cleanGaps.R'
     'zipWithNext.R'

NAMESPACE

@@ -9,6 +9,7 @@ export(as)
 export(bp_coverage)
 export(bp_heatmap)
 export(bp_pair_analysis)
+export(bridgeRegions)
 export(chain_contigs)
 export(cleanGaps)
 export(coalesce_contigs)

NEWS.md

@@ -15,6 +15,8 @@
    will call `getSeq()` automatically.
  * New "mid" option to the `direction` argument of `get_bps()`, to output
    breakpoints at mid-distance between ranges.
+ * New `bridgeRegions()` function that maps unaligned regions of the _target_ to
+   the _query_ genome when they are flanked by colinear regions.
 
 ## Backwards-incompatible changes
 

R/bridgeRegions.R

@@ -0,0 +1,53 @@
+#' Bridge regions
+#'
+#' Maps unaligned regions of the _target_ to the _query_ genome when they are
+#' flanked by colinear regions.
+#'
+#' @note Because some aligned regions can be directly adjacent (no gaps), the
+#' returned `GBreaks` object may contain ranges of width zero, where the _start_
+#' coordinate is 1 nucleotide higher than the _end_ coordinate.
+#'
+#' @references Bridge regions have also been called \dQuote{simultaneous gaps}
+#' in the comparison of the mouse and human genomes by Kent WJ, Baertsch R,
+#' Hinrichs A, Miller W, Haussler D. (_Evolution's cauldron: duplication,
+#' deletion, and rearrangement in the mouse and human genomes._ Proc Natl Acad
+#' Sci U S A. 2003;100(20):11484-11489. doi:10.1073/pnas.1932072100)
+#'
+#' @param gb A [`GBreaks`] object.
+#'
+#' @return Returns a new `GBreaks` object of shorter length.
+#'
+#' @family Colinearity functions
+#' @family modifier functions
+#'
+#' @author Charles Plessy
+#'
+#' @examples
+#' exampleColinear5
+#' bridgeRegions(exampleColinear5)
+#'
+#' # Note the zero-width ranges when aligned regions are directly adjacent.
+#' exampleColinear3
+#' bridgeRegions(exampleColinear3)
+#'
+#' @export
+
+bridgeRegions <- function(gb) {
+  # Collect colinear regions and discard the rest
+  colinearRegions <- filterColinearRegions(flagColinearAlignments(gb), rename = FALSE)
+  # Turn the runs of [(TRUE)n, FALSE]n into indices identifying each colinear region
+  idx <- c(0, head(cumsum(!colinearRegions$colinear), -1))
+  # Split into a GRangesList
+  gbl <- split(colinearRegions, idx)
+  # Collect gap ranges in the target and query genomes of each colinear regions.
+  br <- endoapply(gbl, \(gb) {
+    # Check strand
+    onMinus <- all(strand(gb) == "-")
+    # Need to subtract 1 temporarly because some ranges are adjacent (no gap).
+    GBreaks(target = cleanGaps(gb      - 1) -1,
+            query  = cleanGaps(gb$query -1) -1 |> sort(decreasing = onMinus))
+  }) |> unlist()
+  # Remove names and return
+  names(br) <- NULL
+  br
+}