Merge branch 'staging' into website

Author: jiajic

NAMESPACE

@@ -4,6 +4,7 @@ S3method(.DollarNames,affine2d)
 S3method(.DollarNames,dimObj)
 S3method(.DollarNames,giotto)
 S3method(.DollarNames,metaData)
+S3method(.DollarNames,processParam)
 S3method(.DollarNames,spatEnrObj)
 S3method(.DollarNames,spatLocsObj)
 S3method(.DollarNames,terraVectData)
@@ -186,6 +187,7 @@ export(pDataDT)
 export(plotGiottoImage)
 export(polyStamp)
 export(polygon_to_raster)
+export(processData)
 export(readCellMetadata)
 export(readDimReducData)
 export(readExprData)
@@ -262,6 +264,7 @@ export(subsetGiotto)
 export(subsetGiottoLocs)
 export(subsetGiottoLocsMulti)
 export(subsetGiottoLocsSubcellular)
+export(svkey)
 export(t_flex)
 export(tessellate)
 export(triGrid)
@@ -284,6 +287,7 @@ exportClasses(giottoLargeImage)
 exportClasses(giottoPoints)
 exportClasses(giottoPolygon)
 exportClasses(nnNetObj)
+exportClasses(processParam)
 exportClasses(spatEnrObj)
 exportClasses(spatLocsObj)
 exportClasses(spatialGridObj)

NEWS.md

@@ -25,6 +25,10 @@
 - `spatUnit()` and `featType()` method for `giotto` to find existing spatial units and feature types
 - expose `make_valid` param and `...` passing for `createGiottoPolygon()` `data.frame` method
 
+## new
+- `processData()` generic and `processParam` class
+- `svkey` metaprogramming object for storing `spatValue()` parameters for later eval.
+
 # GiottoClass 0.4.6 (2025/01/17)
 
 ## bug fixes

R/classes.R

@@ -4,23 +4,11 @@ NULL
 # MISC ####
 ## * Define class unions ####
 
-#' @title NULL or char class union
-#' @description class to allow either NULL or character
-#' @keywords internal
-#' @noRd
 setClassUnion("nullOrChar", c("NULL", "character"))
-
-#' @title NULL or list class union
-#' @description class to allow either NULL or list
-#' @keywords internal
-#' @noRd
 setClassUnion("nullOrList", c("NULL", "list"))
-
-#' @title NULL or data.table class union
-#' @description class to allow either NULL or data.table
-#' @keywords internal
-#' @noRd
 setClassUnion("nullOrDatatable", c("NULL", "data.table"))
+setClassUnion("nullOrLogical", c("NULL", "logical"))
+# see zzz.R for allMatrix
 
 #' @title gIndex
 #' @description
@@ -306,6 +294,7 @@ terraVectData <- setClass(
 
 # UTILITY ####
 
+# ** affine2d ####
 setClass(
     Class = "affine2d",
     slots = list(
@@ -328,7 +317,46 @@ setClass(
     )
 )
 
+# ** processParam ####
 
+#' @title Parameter Classes for Data Processing Operations
+#' @name processParam
+#' @description
+#' Utility class that defines a data processing procedure and any params used
+#' in performing it. Packages defining processing methods will create their own 
+#' child classes. These parameter objects are intended to be passed alongside
+#' the data to process to [processData()].
+#' @slot param list. Named parameters to use with the intended processing
+#' operation. These can be accessed and updated using the `$` operator.
+#' @export
+setClass("processParam", contains = "VIRTUAL", slots = list(param = "list"))
+
+
+
+# ** svkey ####
+
+#' @name svkey
+#' @title Spatial Value Key
+#' @description
+#' A metaprogramming object that references a set of information to get
+#' from a `giotto` object when used as `svkey@get(gobject)`. 
+#' Referenced data will be retrieved as a `data.table` via [spatValues()]
+#' @keywords internal
+setClass("svkey",
+    slots = list(
+        feats = "character",
+        spat_unit = "nullOrChar",
+        feat_type = "nullOrChar",
+        expression_values = "nullOrChar",
+        spat_loc_name = "nullOrChar",
+        spat_enr_name = "nullOrChar",
+        poly_info = "nullOrChar",
+        dim_reduction_to_use = "nullOrChar",
+        dim_reduction_name = "nullOrChar",
+        verbose = "nullOrLogical",
+        get = "function"
+    )
+)
 
 # SUBCLASSES ####
 

R/generics.R

@@ -86,6 +86,24 @@ setGeneric(
 )
 
 
+#' @title Data Processing
+#' @name processData
+#' @description Generic for processing an object containing measured values.
+#' Specific methods should be defined for this generic to
+#' perform pre or post processing specific to a data class type. No methods
+#' are exported from \pkg{GiottoClass}. The methods, which may 
+#' differ depending on the input data, are attached from other packages which
+#' focus on analyses and/or alternative data representations with specific ways
+#' to implement those analyses.
+#' @param x a data object
+#' @param param a [processParam] inheriting object
+#' @param ... additional arguments, for use in specific methods
+#' @returns An object of the same class containing the processed
+#' @export
+setGeneric("processData", function(x, param, ...) standardGeneric("processData"))
+
+# 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"))
@@ -100,6 +118,7 @@ if (!isGeneric("area")) {
 setGeneric("overlaps", function(x, ...) standardGeneric("overlaps"))
 
 
+
 # Giotto subnesting ####
 # All methods and documentations found in methods-nesting.R
 

R/methods-extract.R

@@ -349,6 +349,29 @@ setMethod("$", signature("affine2d"), function(x, name) {
     c("affine", "order", "rotate", "shear", "scale", "translate")
 }
 
+#' @rdname subset_dollar
+#' @section \code{`$`} methods:
+#'   Select param from `processParam` inheriting objects
+#' @export
+setMethod("$", signature("processParam"), function(x, name) {
+    x@param[[name]]
+})
+#' @export
+.DollarNames.processParam <- function(x, pattern) {
+    names(x@param)
+}
+
+#' @rdname replace_dollar
+#' @section \code{`$<-`} methods:
+#'   Set values by param name into `processParam` inheriting objects
+#' @export
+setMethod(
+    "$<-", signature("processParam"),
+    function(x, name, value) {
+        x@param[[name]] <- value
+        return(initialize(x))
+    }
+)
 
 # [ S4 access generic ####
 
@@ -1174,6 +1197,7 @@ setMethod(
     }
 )
 
+# * affine2d ####
 #' @rdname subset_bracket
 #' @export
 setMethod(
@@ -1202,8 +1226,24 @@ setMethod(
     }
 )
 
+# * processParam ####
+#' @rdname subset_bracket
+#' @export
+setMethod("[", 
+    signature(x = "processParam", 
+              i = "missing", j = "missing", drop = "missing"),
+    function(x) x@param
+)
 
-
+#' @rdname replace_bracket
+#' @export
+setMethod("[<-",
+    signature(x = "processParam", i = "missing", j = "missing", value = "list"),
+    function(x, value) {
+        x@param <- value
+        return(initialize(x))
+    }
+)
 
 
 # giotto subsets ####

R/methods-initialize.R

@@ -240,8 +240,6 @@ setMethod("initialize", signature("giottoAffineImage"), function(.Object, ...) {
 
 
 
-
-
 ## * Initialize
 # setMethod('initialize', 'nnNetObj',
 #           function(.Object, ...) {

R/methods-names.R

@@ -134,3 +134,9 @@ setMethod("names<-", signature(x = "giottoLargeImage"), function(x, value) {
     names(x[]) <- value
     x
 })
+#' @rdname names
+setMethod("names", signature("processParam"), function(x) names(x@param))
+setMethod("names<-", signature("processParam"), function(x, value) {
+    names(x@param) <- value
+    x
+})

R/methods-show.R

@@ -741,7 +741,11 @@ setMethod("as.character", signature("giottoImage"), function(x, ...) {
     sprintf("<%s> %s", class(x), objName(x))
 })
 
-
+#' @rdname as.character
+#' @export
+setMethod("as.character", signature("svkey"), function(x, ...) {
+    sprintf("<svkey> feats: '%s'", paste(x@feats, collapse = "', '"))
+})
 
 
 
@@ -792,6 +796,7 @@ setMethod(
 )
 
 
+# affine2d ####
 
 #' @rdname show
 setMethod("show", signature("affine2d"), function(object) {
@@ -827,9 +832,30 @@ setMethod("as.character", signature("giottoLargeImage"), function(x, ...) {
     sprintf("<%s> %s", class(x), objName(x))
 })
 
+# processParam ####
+setMethod("show", signature("processParam"), function(object) {
+    cat(sprintf("<%s>\n", class(object)))
+    cat("params:\n")
+    print_list(object[])
+})
 
-
-
+# svkey ####
+setMethod("show", signature("svkey"), function(object) {
+    cat(sprintf("<%s>\n", class(object)))
+    plist <- list(
+        feats = sprintf("'%s'", paste(object@feats, collapse = "' '")))
+    plist$spat_unit <- object@spat_unit
+    plist$feat_type <- object@feat_type
+    plist$expression_values <- object@expression_values
+    plist$spat_loc_name <- object@spat_loc_name
+    plist$spat_enr_name <- object@spat_enr_name
+    plist$poly_info <- object@poly_info
+    plist$dim_reduction_to_use <- object@dim_reduction_to_use
+    plist$dim_reduction_name <- object@dim_reduction_name
+    plist$verbose <- object@verbose
+
+    print_list(plist)
+})
 
 
 # show helpers ####

R/package_imports.R

@@ -23,8 +23,8 @@
 #' @importMethodsFrom terra as.data.frame as.polygons as.points
 #' @importMethodsFrom terra nrow ncol
 #' @importMethodsFrom terra hist density
-#' @importClassesFrom terra SpatExtent SpatVector
 #' @importMethodsFrom terra area
+#' @importClassesFrom terra SpatExtent SpatVector
 #' @import GiottoUtils
 #' @import data.table
 #' @import utils

R/slot_accessors.R

@@ -6353,6 +6353,41 @@ spatValues <- function(gobject,
 }
 
 
+## svkey ####
+
+#' @describeIn spatValues Create a `svkey` defining a `spatValues()` call
+#' for deferred use. Handy for contexts where the full `giotto` object is not
+#' available.
+#' @export
+svkey <- function(feats,
+    spat_unit = NULL,
+    feat_type = NULL,
+    expression_values = NULL,
+    spat_loc_name = NULL,
+    poly_info = NULL,
+    dim_reduction_to_use = NULL,
+    dim_reduction_name = NULL,
+    verbose = NULL) {
+    if (missing(feats)) stop("'feats' to get must be provided", call. = FALSE)
+    a <- get_args_list()
+    svk <- do.call(new, c(list(Class = "svkey"), a))
+    svk@get <- function(gobject) {
+        spatValues(
+            gobject = gobject,
+            feats = svk@feats,
+            spat_unit = svk@spat_unit,
+            feat_type = svk@feat_type,
+            expression_values = svk@expression_values,
+            spat_loc_name = svk@spat_loc_name,
+            poly_info = svk@poly_info,
+            dim_reduction_to_use = svk@dim_reduction_to_use,
+            dim_reduction_name = svk@dim_reduction_name,
+            verbose = svk@verbose
+        )
+    }
+    svk
+}
+
 
 # internals ####