From 7c6fb21261ba13ec73ce76ee2fe62ea6bc94afdd Mon Sep 17 00:00:00 2001
From: George Chen <72078254+jiajic@users.noreply.github.com>
Date: Sat, 26 Oct 2024 13:02:05 -0400
Subject: [PATCH] feat: `area()`

---
 DESCRIPTION      |  1 +
 NAMESPACE        |  1 +
 R/generics.R     |  3 ++-
 R/methods-area.R | 36 ++++++++++++++++++++++++++++++++++++
 man/area.Rd      | 37 +++++++++++++++++++++++++++++++++++++
 5 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 R/methods-area.R
 create mode 100644 man/area.Rd

diff --git a/DESCRIPTION b/DESCRIPTION
index cc77b46c..e25cd511 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -106,6 +106,7 @@ Collate:
     'methods-IDs.R'
     'methods-XY.R'
     'methods-affine.R'
+    'methods-area.R'
     'methods-centroids.R'
     'methods-coerce.R'
     'methods-convHull.R'
diff --git a/NAMESPACE b/NAMESPACE
index 82e3700c..a72eb62d 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -308,6 +308,7 @@ exportMethods(XY)
 exportMethods(activeFeatType)
 exportMethods(activeSpatUnit)
 exportMethods(affine)
+exportMethods(area)
 exportMethods(as.character)
 exportMethods(as.list)
 exportMethods(as.matrix)
diff --git a/R/generics.R b/R/generics.R
index 4113eb14..fe24b016 100644
--- a/R/generics.R
+++ b/R/generics.R
@@ -84,12 +84,13 @@ setGeneric(
     function(x, ...) standardGeneric("overlapToMatrix")
 )
 
-# Methods and documentations found in methods-spatShift.R
+
 setGeneric("spatShift", function(x, ...) standardGeneric("spatShift"))
 setGeneric("affine", function(x, y, ...) standardGeneric("affine"))
 setGeneric("shear", function(x, ...) standardGeneric("shear"))
 setGeneric("XY", function(x, ...) standardGeneric("XY"))
 setGeneric("XY<-", function(x, ..., value) standardGeneric("XY<-"))
+setGeneric("area", function(x, ...) standardGeneric("area"))
 
 # Methods and documentations found in methods-overlaps.R
 setGeneric("overlaps", function(x, ...) standardGeneric("overlaps"))
diff --git a/R/methods-area.R b/R/methods-area.R
new file mode 100644
index 00000000..5d4f84af
--- /dev/null
+++ b/R/methods-area.R
@@ -0,0 +1,36 @@
+# docs ----------------------------------------------------------- #
+#' @title Get the area of individual polygons
+#' @name area
+#' @description Compute the area covered by polygons
+#' @param x `giottoPolygon`
+#' @param ... additional args to pass
+#' @returns `numeric` vector of spatial area
+#' @examples
+#' sl <- GiottoData::loadSubObjectMini("spatLocsObj")
+#' gpoly <- GiottoData::loadSubObjectMini("giottoPolygon")
+#' gpoints <- GiottoData::loadSubObjectMini("giottoPoints")
+#' 
+#' # area of polygons
+#' area(gpoly)
+#' 
+#' # area of the convex hull
+#' area(convHull(sl))
+#' feature_hulls <- convHull(gpoints, by = "feat_ID")
+#' area(feature_hulls)
+#'
+NULL
+# ---------------------------------------------------------------- #
+
+#' @rdname area
+#' @export
+setMethod("area", signature("giottoPolygon"), function(x, ...) {
+    # handle warning about missing CRS
+    handle_warnings(area(x[], ...))$result
+})
+
+#' @rdname area
+#' @export
+setMethod("area", signature("SpatVector"), function(x, ...) {
+    # handle warning about missing CRS
+    handle_warnings(terra::expanse(x, transform = FALSE, ...))$result
+})
diff --git a/man/area.Rd b/man/area.Rd
new file mode 100644
index 00000000..38ac744d
--- /dev/null
+++ b/man/area.Rd
@@ -0,0 +1,37 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/methods-area.R
+\name{area}
+\alias{area}
+\alias{area,giottoPolygon-method}
+\alias{area,SpatVector-method}
+\title{Get the area of individual polygons}
+\usage{
+\S4method{area}{giottoPolygon}(x, ...)
+
+\S4method{area}{SpatVector}(x, ...)
+}
+\arguments{
+\item{x}{\code{giottoPolygon}}
+
+\item{...}{additional args to pass}
+}
+\value{
+\code{numeric} vector of spatial area
+}
+\description{
+Compute the area covered by polygons
+}
+\examples{
+sl <- GiottoData::loadSubObjectMini("spatLocsObj")
+gpoly <- GiottoData::loadSubObjectMini("giottoPolygon")
+gpoints <- GiottoData::loadSubObjectMini("giottoPoints")
+
+# area of polygons
+area(gpoly)
+
+# area of the convex hull
+area(convHull(sl))
+feature_hulls <- convHull(gpoints, by = "feat_ID")
+area(feature_hulls)
+
+}