flip overlapPointDT[i] / [,j] default: ids = TRUE → FALSE

R/classes-overlaps.R

@@ -13,11 +13,10 @@ setClass("overlapIntensity", contains = c("overlapInfo", "VIRTUAL"))
 #' @title Polygon and Point Relationships
 #' @description
 #' Utility class for storing overlaps relationships between polygons and points
-#' in a sparse `data.table` format. Retrieve the unique ID index of overlapped
-#' points `[i, ]`. Get indices of which polys are overlapping specific feature
-#' species using `[, j]`.
-#'
-#' Subsetting with `ids = FALSE` and `[i, j]` indexing is also supported.
+#' in a sparse `data.table` format. `[i, ]` / `[, j]` / `[i, j]` all return a
+#' subset `overlapPointDT`. To retrieve indices instead — feat_ID_uniqs
+#' overlapped by poly i, or poly indices overlapping feature j — pass
+#' `ids = TRUE`.
 #'
 #' Supports `as.matrix` for conversion to `dgCMatrix`. Contained poly and
 #' feature names simplify rownames/colnames and empty row/col creation.
@@ -41,14 +40,15 @@ setClass("overlapIntensity", contains = c("overlapInfo", "VIRTUAL"))
 #' polygons
 #' @param j numeric, character, logical. Index of or name of feature being
 #' overlapped.
-#' @param use_names logical (default = `FALSE`). Whether to return as integer
-#' indices or with character ids.
-#' @param ids logical (default = `TRUE`). Whether to return the requested
-#' integer indices (`TRUE`) or the subset overlap object (`FALSE`).
+#' @param use_names logical (default = `FALSE`). When `ids = TRUE`, whether
+#' to return integer indices (`FALSE`) or character ids (`TRUE`).
+#' @param ids logical (default = `FALSE`). Whether to return the requested
+#' integer indices (`TRUE`) or the subset overlap object (`FALSE`, default).
 #' @param drop not used.
 #' @param \dots additional params to pass (none implemented)
-#' @returns integer or character if only `i` or `j` provided, depending on
-#' `use_names`. A subset `overlapPointDT` if both `i` and `j` are used.
+#' @returns A subset `overlapPointDT` by default. When `ids = TRUE`,
+#' an integer (or character via `use_names = TRUE`) vector of the queried
+#' indices.
 #' @examples
 #' g <- GiottoData::loadGiottoMini("vizgen")
 #' poly <- g[["spatial_info", "z0"]][[1]]
@@ -60,19 +60,19 @@ setClass("overlapIntensity", contains = c("overlapInfo", "VIRTUAL"))
 #' dim(ovlp)
 #' nrow(ovlp) # number of relationships
 #'
-#' # get feature unique IDs overlapped by nth poly
-#' ovlp[1] # check one (no overlaps returns integer(0))
-#' ovlp[1:5] # check multiple
-#' ovlp[1:5, use_names = TRUE] # returns feature names, but no longer unique
+#' # subset (default) — returns an overlapPointDT
+#' ovlp[1:10] # first 10 polys
+#' ovlp[, 1:10] # first 10 feature species
+#' ovlp[1:10, 1:10] # both
 #'
-#' # get integer index of poly(s) overlapping particular feature species
-#' ovlp[, 1]
-#' ovlp[, "Mlc1"] # this is the same
+#' # selection query — feature unique IDs overlapped by nth poly
+#' ovlp[1, ids = TRUE] # integer feat_ID_uniqs (integer(0) if no overlap)
+#' ovlp[1:5, ids = TRUE]
+#' ovlp[1:5, ids = TRUE, use_names = TRUE] # feature names instead of ints
 #'
-#' # get a subset of overlap object
-#' ovlp[1:10, ids = FALSE] # subset to first 10 polys
-#' ovlp[, 1:10, ids = FALSE] # subset to first 10 feature species
-#' ovlp[1:10, 1:10] # subset to first 10 polys and first 10 features species
+#' # selection query — poly indices overlapping particular feature species
+#' ovlp[, 1, ids = TRUE]
+#' ovlp[, "Mlc1", ids = TRUE]
 #' @exportClass overlapPointDT
 setClass("overlapPointDT",
     contains = "overlapPoint",

R/methods-extract.R

@@ -1083,7 +1083,7 @@ setMethod(
             if (!inherits(o[[feat]], "overlapInfo")) {
                 warning("[subset overlaps feats] unrecognized overlap type")
             }
-            o[[feat]] <- o[[feat]][, i, ids = FALSE]
+            o[[feat]] <- o[[feat]][, i]
         }
         o
     }
@@ -1337,12 +1337,11 @@ setMethod("[",
         i = "gIndex",
         j = "missing",
         drop = "missing"
-    ), function(x, i, j, ..., use_names = FALSE, ids = TRUE, drop) {
-        if (!isTRUE(ids)) {
-            res <- .subset_overlap_point_dt_i(x, i)
-            return(res)
+    ), function(x, i, j, ..., use_names = FALSE, ids = FALSE, drop) {
+        if (isTRUE(ids)) {
+            return(.select_overlap_point_dt_i(x, i, use_names = use_names))
         }
-        .select_overlap_point_dt_i(x, i, use_names = use_names)
+        .subset_overlap_point_dt_i(x, i)
     }
 )
 
@@ -1354,12 +1353,11 @@ setMethod("[",
         i = "missing",
         j = "gIndex",
         drop = "missing"
-    ), function(x, i, j, ..., use_names = FALSE, ids = TRUE, drop) {
-        if (!isTRUE(ids)) {
-            res <- .subset_overlap_point_dt_j(x, j)
-            return(res)
+    ), function(x, i, j, ..., use_names = FALSE, ids = FALSE, drop) {
+        if (isTRUE(ids)) {
+            return(.select_overlap_point_dt_j(x, j, use_names = use_names))
         }
-        .select_overlap_point_dt_j(x, j, use_names = use_names)
+        .subset_overlap_point_dt_j(x, j)
     }
 )
 

tests/testthat/test-aggregate.R

@@ -171,33 +171,44 @@ res_vect <- calculateOverlap(gpoly, gpts,
 )
 ovlp <- overlaps(res_vect, "rna")
 
-test_that("overlap `[]` subset works", {
-    # expect the feat_ID_uniq overlapped by poly 9
-    fuid9 <- ovlp[9]
+test_that("overlap `[]` selection query (ids = TRUE) works", {
+    # feat_ID_uniq overlapped by poly 9
+    fuid9 <- ovlp[9, ids = TRUE]
     expected_fuid9 <- c(
         1949, 4234, 6934, 9360, 11891, 12037, 13671, 13766, 14633, 14732,
         22670, 25184, 27910, 30742, 37026, 44881, 45922, 50053, 53519, 67618,
         68997, 69003, 69911, 70336, 72325, 74205, 76817
     )
     expect_equal(fuid9, expected_fuid9)
-    # expect the feat_ID_uniq overlapped by poly 40
-    fuid40 <- ovlp[40]
+    # feat_ID_uniq overlapped by poly 40
+    fuid40 <- ovlp[40, ids = TRUE]
     expected_fuid40 <- c(
         2184, 3710, 3870, 5862, 12664, 19589, 24959, 25368, 26082, 29026,
         36516, 45774, 49727, 50094, 50514, 53664, 53834, 54290, 54365, 54534,
         55520, 59178, 66336, 66812, 70350, 73361, 75951
     )
     expect_equal(fuid40, expected_fuid40)
 
-    # expect poly overlapping specific features
+    # poly indices overlapping specific features
     feat_idx <- match("Bp5vKRUi", ovlp@feat_ids)
-    poly_idx_by_fidx <- head(ovlp[, feat_idx])
-    poly_idx_by_fname <- head(ovlp[, "Bp5vKRUi"])
+    poly_idx_by_fidx <- head(ovlp[, feat_idx, ids = TRUE])
+    poly_idx_by_fname <- head(ovlp[, "Bp5vKRUi", ids = TRUE])
     expect_identical(poly_idx_by_fidx, poly_idx_by_fname)
     expected_idx <- c(459, 215, 11, 30, 294, 301)
     expect_equal(poly_idx_by_fidx, expected_idx)
 })
 
+test_that("overlap `[]` default returns subset object", {
+    # default is subset (ids = FALSE) — symmetric across overlapPointDT,
+    # overlapIntensityDT, and SpatVector legacy
+    sub <- ovlp[1:10]
+    expect_s4_class(sub, "overlapPointDT")
+    sub_j <- ovlp[, 1:10]
+    expect_s4_class(sub_j, "overlapPointDT")
+    sub_ij <- ovlp[1:10, 1:10]
+    expect_s4_class(sub_ij, "overlapPointDT")
+})
+
 test_that("overlap `as.data.frame` works", {
     res <- as.data.frame(ovlp)
     expect_equal(ncol(res), 3)