From e553a5a5be78029b46c5e74f63a1dcbfaed43473 Mon Sep 17 00:00:00 2001
From: George Chen <72078254+jiajic@users.noreply.github.com>
Date: Sat, 26 Oct 2024 11:23:40 -0400
Subject: [PATCH] feat: `convHull()`

---
 DESCRIPTION          |  3 +-
 NAMESPACE            |  6 ++++
 NEWS.md              |  2 ++
 R/methods-convHull.R | 73 ++++++++++++++++++++++++++++++++++++++++++++
 R/package_imports.R  |  2 +-
 man/convHull.Rd      | 49 +++++++++++++++++++++++++++++
 6 files changed, 133 insertions(+), 2 deletions(-)
 create mode 100644 R/methods-convHull.R
 create mode 100644 man/convHull.Rd

diff --git a/DESCRIPTION b/DESCRIPTION
index b00689f9..e2601716 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -44,7 +44,7 @@ Imports:
     methods,
     reticulate (>= 1.25),
     stats,
-    terra (>= 1.7-39)
+    terra (>= 1.7-41)
 Suggests: 
     Biobase,
     chihaya,
@@ -109,6 +109,7 @@ Collate:
     'methods-affine.R'
     'methods-centroids.R'
     'methods-coerce.R'
+    'methods-convHull.R'
     'methods-copy.R'
     'methods-crop.R'
     'methods-dims.R'
diff --git a/NAMESPACE b/NAMESPACE
index af705c2f..82e3700c 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -320,6 +320,7 @@ exportMethods(as.terra)
 exportMethods(calculateOverlap)
 exportMethods(centroids)
 exportMethods(colnames)
+exportMethods(convHull)
 exportMethods(copy)
 exportMethods(createGiottoPoints)
 exportMethods(createGiottoPolygon)
@@ -335,6 +336,8 @@ exportMethods(flip)
 exportMethods(hist)
 exportMethods(instructions)
 exportMethods(intersect)
+exportMethods(minCircle)
+exportMethods(minRect)
 exportMethods(ncol)
 exportMethods(nrow)
 exportMethods(objName)
@@ -389,12 +392,15 @@ importMethodsFrom(terra,as.data.frame)
 importMethodsFrom(terra,as.points)
 importMethodsFrom(terra,as.polygons)
 importMethodsFrom(terra,centroids)
+importMethodsFrom(terra,convHull)
 importMethodsFrom(terra,crop)
 importMethodsFrom(terra,density)
 importMethodsFrom(terra,ext)
 importMethodsFrom(terra,flip)
 importMethodsFrom(terra,hist)
 importMethodsFrom(terra,intersect)
+importMethodsFrom(terra,minCircle)
+importMethodsFrom(terra,minRect)
 importMethodsFrom(terra,ncol)
 importMethodsFrom(terra,nrow)
 importMethodsFrom(terra,plot)
diff --git a/NEWS.md b/NEWS.md
index a4a41be1..e465c9f3 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -3,6 +3,7 @@
 
 ## breaking changes
 - stop exporting deprecated internal accessors
+- terra requirement raised to 1.7.41 for `minCircle()`
 
 ## bug fixes
 - fix `dimnames()` for some subobjects
@@ -34,6 +35,7 @@
 - `splitGiotto()` for splitting a Giotto object into a list of Giotto objects based on a cell metadata column
 - `as.list()` method for `giotto` to dump the data as a list of subobjects
 - `XY()` and `XY<-()` for accessing and setting coordinate values of subobjects as `matrix`
+- terra `convHull()`, `minRect()`, `minCircle()` for Giotto spatial vector classes
 
 
 # GiottoClass 0.3.5 (2024/08/28)
diff --git a/R/methods-convHull.R b/R/methods-convHull.R
new file mode 100644
index 00000000..bdad0e65
--- /dev/null
+++ b/R/methods-convHull.R
@@ -0,0 +1,73 @@
+# docs ----------------------------------------------------------- #
+#' @title Convex hull, minimal bounding rotated rectangle, and minimal bounding circle
+#' @name convHull
+#' @description Get the convex hull, the minimal bounding rotated rectangle, 
+#' or minimal bounding circle of a Giotto spatial object or terra SpatVector
+#' @param x any of giotto image, giottoPolygon, giottoPoints, spatLocsObj, SpatVector
+#' @param by character (variable name), to get a new geometry for groups of input geometries
+#' @param \dots additional parameters to pass
+#' @examples
+#' sl <- GiottoData::loadSubObjectMini("spatLocsObj")
+#' gpoints <- GiottoData::loadSubObjectMini("giottoPoints")
+#' 
+#' h <- convHull(sl)
+#' plot(h)
+#' 
+#' r <- minRect(sl)
+#' plot(r)
+#' 
+#' circ <- minCircle(gpoints, by = "feat_ID")
+#' plot(circ, border = rainbow(100))
+#' 
+#' @returns SpatVector
+NULL
+# ---------------------------------------------------------------- #
+
+#' @rdname convHull
+#' @usage
+#' ## S4 method for signatures 'spatLocsObj', 'giottoPolygon', 'giottoPoints'
+#' convHull(x, by = "")
+#' @export
+setMethod("convHull", signature("spatLocsObj"), function(x, by = "") {
+    convHull(x = as.points(x), by = by)
+})
+#' @rdname convHull
+#' @usage NULL
+#' @export
+setMethod("convHull", signature("giottoSpatial"), function(x, by = "") {
+    convHull(x[], by = by)
+})
+
+
+#' @rdname convHull
+#' @usage
+#' ## S4 method for signatures 'spatLocsObj', 'giottoPolygon', 'giottoPoints'
+#' minRect(x, by = "")
+#' @export
+setMethod("minRect", signature("spatLocsObj"), function(x, by = "") {
+    minRect(x = as.points(x), by = by)
+})
+#' @rdname convHull
+#' @usage NULL
+#' @export
+setMethod("minRect", signature("giottoSpatial"), function(x, by = "") {
+    minRect(x[], by = by)
+})
+
+
+#' @rdname convHull
+#' @usage
+#' ## S4 method for signatures 'spatLocsObj', 'giottoPolygon', 'giottoPoints'
+#' minCircle(x, by = "")
+#' @export
+setMethod("minCircle", signature("spatLocsObj"), function(x, by = "") {
+    minCircle(x = as.points(x), by = by)
+})
+#' @rdname convHull
+#' @usage NULL
+#' @export
+setMethod("minCircle", signature("giottoSpatial"), function(x, by = "") {
+    minCircle(x[], by = by)
+})
+
+
diff --git a/R/package_imports.R b/R/package_imports.R
index 21dd010b..6352c193 100644
--- a/R/package_imports.R
+++ b/R/package_imports.R
@@ -15,7 +15,7 @@
 #' @importMethodsFrom terra rescale
 #' @importMethodsFrom Matrix t
 #' @importMethodsFrom terra t
-#' @importMethodsFrom terra ext ext<-
+#' @importMethodsFrom terra ext ext<- convHull minCircle minRect
 #' @importMethodsFrom terra plot
 #' @importMethodsFrom terra wrap
 #' @importMethodsFrom terra zoom
diff --git a/man/convHull.Rd b/man/convHull.Rd
new file mode 100644
index 00000000..f43c6379
--- /dev/null
+++ b/man/convHull.Rd
@@ -0,0 +1,49 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/methods-convHull.R
+\name{convHull}
+\alias{convHull}
+\alias{convHull,spatLocsObj-method}
+\alias{convHull,giottoSpatial-method}
+\alias{minRect,spatLocsObj-method}
+\alias{minRect,giottoSpatial-method}
+\alias{minCircle,spatLocsObj-method}
+\alias{minCircle,giottoSpatial-method}
+\title{Convex hull, minimal bounding rotated rectangle, and minimal bounding circle}
+\usage{
+## S4 method for signatures 'spatLocsObj', 'giottoPolygon', 'giottoPoints'
+convHull(x, by = "")
+
+## S4 method for signatures 'spatLocsObj', 'giottoPolygon', 'giottoPoints'
+minRect(x, by = "")
+
+## S4 method for signatures 'spatLocsObj', 'giottoPolygon', 'giottoPoints'
+minCircle(x, by = "")
+}
+\arguments{
+\item{x}{any of giotto image, giottoPolygon, giottoPoints, spatLocsObj, SpatVector}
+
+\item{by}{character (variable name), to get a new geometry for groups of input geometries}
+
+\item{\dots}{additional parameters to pass}
+}
+\value{
+SpatVector
+}
+\description{
+Get the convex hull, the minimal bounding rotated rectangle,
+or minimal bounding circle of a Giotto spatial object or terra SpatVector
+}
+\examples{
+sl <- GiottoData::loadSubObjectMini("spatLocsObj")
+gpoints <- GiottoData::loadSubObjectMini("giottoPoints")
+
+h <- convHull(sl)
+plot(h)
+
+r <- minRect(sl)
+plot(r)
+
+circ <- minCircle(gpoints, by = "feat_ID")
+plot(circ, border = rainbow(100))
+
+}