diff --git a/NAMESPACE b/NAMESPACE index d36304e..e8a9e70 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,11 +1,13 @@ # Generated by roxygen2: do not edit by hand +export("gsvaAnnotation<-") export(computeGeneSetsOverlap) export(deduplicateGeneSets) export(filterGeneSets) export(geneSetSizes) export(geneSets) export(gsva) +export(gsvaAnnotation) export(gsvaParam) export(igsva) export(plageParam) @@ -25,6 +27,7 @@ exportMethods(filterGeneSets) exportMethods(geneSetSizes) exportMethods(geneSets) exportMethods(gsva) +exportMethods(gsvaAnnotation) exportMethods(spatCor) import(methods) importClassesFrom(Biobase,ExpressionSet) @@ -88,6 +91,7 @@ importFrom(utils,setTxtProgressBar) importFrom(utils,tail) importFrom(utils,txtProgressBar) importFrom(utils,write.csv) +importMethodsFrom(Biobase,"annotation<-") importMethodsFrom(Biobase,annotation) importMethodsFrom(Biobase,experimentData) importMethodsFrom(Biobase,exprs) diff --git a/R/AllGenerics.R b/R/AllGenerics.R index 5108dd1..1acfd76 100644 --- a/R/AllGenerics.R +++ b/R/AllGenerics.R @@ -19,6 +19,14 @@ setGeneric("geneSets", setGeneric("geneSetSizes", function(obj, ...) standardGeneric("geneSetSizes")) +#' @export +setGeneric("gsvaAnnotation", + function(object) standardGeneric("gsvaAnnotation")) + +#' @export +setGeneric("gsvaAnnotation<-", + function(object, value) standardGeneric("gsvaAnnotation<-")) + ## for now, these should be private methods @@ -45,8 +53,6 @@ setGeneric("get_maxSize", function(object) standardGeneric("get_maxSize")) setGeneric("gsvaShow", function(object) standardGeneric("gsvaShow")) -setGeneric("gsvaAnnotation", function(object) standardGeneric("gsvaAnnotation")) - setGeneric("gsvaAssayNames", function(object) standardGeneric("gsvaAssayNames")) ## spatial methods diff --git a/R/GSVA-package.R b/R/GSVA-package.R index f7291f6..a8cfd6b 100644 --- a/R/GSVA-package.R +++ b/R/GSVA-package.R @@ -4,7 +4,8 @@ #' #' @import methods #' -#' @importMethodsFrom Biobase featureNames phenoData experimentData exprs annotation +#' @importMethodsFrom Biobase featureNames phenoData experimentData exprs +#' annotation "annotation<-" #' @importMethodsFrom S4Vectors metadata "metadata<-" #' @importMethodsFrom IRanges match #' @importMethodsFrom SummarizedExperiment assays assayNames colData rowData diff --git a/R/GsvaMethodParam.R b/R/GsvaMethodParam.R index a00b2b0..81f44c5 100644 --- a/R/GsvaMethodParam.R +++ b/R/GsvaMethodParam.R @@ -117,42 +117,6 @@ setMethod("gsvaShow", }) -## ----- uniform access to annotation ----- - -setMethod("gsvaAnnotation", - signature=signature(object="GsvaExprData"), - function(object) { - ## in general - return(NULL) - }) - -setMethod("gsvaAnnotation", - signature=signature(object="ExpressionSet"), - function(object) { - ## always a character giving the db pkg, potentially empty ("") - return(annotation(object)) - }) - -setMethod("gsvaAnnotation", signature("SummarizedExperiment"), - function(object) { - ## NULL if unset; otherwise anything but we *expect* and handle - ## a GSEABase::GeneIdentifierType with or without annotation(), - ## i.e., db pkg, available. Same for subclasses below. - return(metadata(object)$annotation) - }) - -setMethod("gsvaAnnotation", signature("SingleCellExperiment"), - function(object) { - return(metadata(object)$annotation) - }) - -setMethod("gsvaAnnotation", signature("SpatialExperiment"), - function(object) { - return(metadata(object)$annotation) - }) - - - ## ----- uniform access to assay names ----- setMethod("gsvaAssayNames", @@ -172,3 +136,9 @@ setMethod("gsvaAssayNames", signature("SingleCellExperiment"), a <- assayNames(object) return(if(.isCharNonEmpty(a)) a else NA_character_) }) + +setMethod("gsvaAssayNames", signature("SpatialExperiment"), + function(object) { + a <- assayNames(object) + return(if(.isCharNonEmpty(a)) a else NA_character_) + }) diff --git a/R/gsvaNewAPI.R b/R/gsvaNewAPI.R index 22e47d3..cd5516f 100644 --- a/R/gsvaNewAPI.R +++ b/R/gsvaNewAPI.R @@ -285,6 +285,152 @@ setMethod("gsva", signature(param="gsvaParam"), }) +### ----- methods for retrieving and setting annotation metadata ----- + +#' @title Store and Retrieve Annotation Metadata +#' +#' @description Methods for storing and retrieving annotation metadata in +#' expression data objects that support it. If gene sets and expression data +#' are using different but known gene identifier types and an appropriate +#' annotation database is available, gene set identifiers can be mapped to +#' expression data identifiers without manual user intervention, e.g. from +#' an MSigDb gene set using ENTREZ IDs or gene symbols to an expression data +#' set using ENSEMBL IDs. +#' +#' @param object An expression data object of one of the classes described in +#' [`GsvaExprData-class`]. Simple `matrix` and `dgCMatrix` objects are not +#' capable of storing annotation metadata and will return `NULL`. +#' +#' @param value For the replacement methods, the annotation metadata to be +#' stored in the object. For [`ExpressionSet-class`] objects, this must be a +#' character of length 1 specifying the name of the annotation database to be +#' used. For [`SummarizedExperiment-class`] and its subclasses, this must be +#' a [`GeneIdentifierType`] created by one of the constructors from package +#' `GSEABase` where the `annotation` argument is typically the name of an +#' organism or annotation database, e.g. `org.Hs.eg.db`. Simple `matrix` and +#' `dgCMatrix` objects are not capable of storing annotation metadata and the +#' attempt to do so will result in an error. +#' +#' @return For the retrieval methods, the annotation metadata stored in the +#' object of `NULL`. For the replacement methods, the updated object. +#' +#' @aliases gsvaAnnotation gsvaAnnotation<- +#' @name gsvaAnnotation +#' @rdname gsvaAnnotation +#' +NULL + + +#' @aliases gsvaAnnotation,GsvaExprData-method +#' @rdname gsvaAnnotation +#' @exportMethod gsvaAnnotation +setMethod("gsvaAnnotation", + signature=signature(object="GsvaExprData"), + function(object) { + ## in general + return(NULL) + }) + +#' @aliases gsvaAnnotation<-,GsvaExprData,ANY-method +#' @rdname gsvaAnnotation +#' @exportMethod gsvaAnnotation +setReplaceMethod("gsvaAnnotation", + signature=signature( + object="GsvaExprData", + value="ANY"), + function(object, value) { + ## in general + stop("Object of class '", class(object), "' cannot store ", + "annotation metadata of class '", class(value), "'.") + }) + +#' @aliases gsvaAnnotation,ExpressionSet-method +#' @rdname gsvaAnnotation +#' @exportMethod gsvaAnnotation +setMethod("gsvaAnnotation", + signature=signature(object="ExpressionSet"), + function(object) { + ## always a character giving the db pkg, potentially empty ("") + return(annotation(object)) + }) + +#' @aliases gsvaAnnotation<-,ExpressionSet,character-method +#' @rdname gsvaAnnotation +#' @exportMethod gsvaAnnotation +setReplaceMethod("gsvaAnnotation", + signature=signature( + object="ExpressionSet", + value="character"), + function(object, value) { + annotation(object) <- value + object + }) + +#' @aliases gsvaAnnotation,SummarizedExperiment-method +#' @rdname gsvaAnnotation +#' @exportMethod gsvaAnnotation +setMethod("gsvaAnnotation", signature("SummarizedExperiment"), + function(object) { + ## NULL if unset; otherwise anything but we *expect* and handle + ## a GSEABase::GeneIdentifierType with or without annotation(), + ## i.e., db pkg, available. Same for subclasses below. + return(metadata(object)$annotation) + }) + +#' @aliases gsvaAnnotation<-,SummarizedExperiment,GeneIdentifierType-method +#' @rdname gsvaAnnotation +#' @exportMethod gsvaAnnotation +setReplaceMethod("gsvaAnnotation", + signature=signature( + object="SummarizedExperiment", + value="GeneIdentifierType"), + function(object, value) { + metadata(object)$annotation <- value + object + }) + +#' @aliases gsvaAnnotation,SingleCellExperiment-method +#' @rdname gsvaAnnotation +#' @exportMethod gsvaAnnotation +setMethod("gsvaAnnotation", signature("SingleCellExperiment"), + function(object) { + return(metadata(object)$annotation) + }) + +#' @aliases gsvaAnnotation<-,SingleCellExperiment,GeneIdentifierType-method +#' @rdname gsvaAnnotation +#' @exportMethod gsvaAnnotation +setReplaceMethod("gsvaAnnotation", + signature=signature( + object="SingleCellExperiment", + value="GeneIdentifierType"), + function(object, value) { + metadata(object)$annotation <- value + object + }) + +#' @aliases gsvaAnnotation,SpatialExperiment-method +#' @rdname gsvaAnnotation +#' @exportMethod gsvaAnnotation +setMethod("gsvaAnnotation", signature("SpatialExperiment"), + function(object) { + return(metadata(object)$annotation) + }) + +#' @aliases gsvaAnnotation<-,SpatialExperiment,GeneIdentifierType-method +#' @rdname gsvaAnnotation +#' @exportMethod gsvaAnnotation +setReplaceMethod("gsvaAnnotation", + signature=signature( + object="SpatialExperiment", + value="GeneIdentifierType"), + function(object, value) { + metadata(object)$annotation <- value + object + }) + + + ### ----- methods for retrieving gene sets ----- #' @title Retrieve or Determine Gene Sets diff --git a/man/gsvaAnnotation.Rd b/man/gsvaAnnotation.Rd new file mode 100644 index 0000000..9a992c3 --- /dev/null +++ b/man/gsvaAnnotation.Rd @@ -0,0 +1,65 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/gsvaNewAPI.R +\name{gsvaAnnotation} +\alias{gsvaAnnotation} +\alias{gsvaAnnotation<-} +\alias{gsvaAnnotation,GsvaExprData-method} +\alias{gsvaAnnotation<-,GsvaExprData,ANY-method} +\alias{gsvaAnnotation,ExpressionSet-method} +\alias{gsvaAnnotation<-,ExpressionSet,character-method} +\alias{gsvaAnnotation,SummarizedExperiment-method} +\alias{gsvaAnnotation<-,SummarizedExperiment,GeneIdentifierType-method} +\alias{gsvaAnnotation,SingleCellExperiment-method} +\alias{gsvaAnnotation<-,SingleCellExperiment,GeneIdentifierType-method} +\alias{gsvaAnnotation,SpatialExperiment-method} +\alias{gsvaAnnotation<-,SpatialExperiment,GeneIdentifierType-method} +\title{Store and Retrieve Annotation Metadata} +\usage{ +\S4method{gsvaAnnotation}{GsvaExprData}(object) + +\S4method{gsvaAnnotation}{GsvaExprData,ANY}(object) <- value + +\S4method{gsvaAnnotation}{ExpressionSet}(object) + +\S4method{gsvaAnnotation}{ExpressionSet,character}(object) <- value + +\S4method{gsvaAnnotation}{SummarizedExperiment}(object) + +\S4method{gsvaAnnotation}{SummarizedExperiment,GeneIdentifierType}(object) <- value + +\S4method{gsvaAnnotation}{SingleCellExperiment}(object) + +\S4method{gsvaAnnotation}{SingleCellExperiment,GeneIdentifierType}(object) <- value + +\S4method{gsvaAnnotation}{SpatialExperiment}(object) + +\S4method{gsvaAnnotation}{SpatialExperiment,GeneIdentifierType}(object) <- value +} +\arguments{ +\item{object}{An expression data object of one of the classes described in +\code{\linkS4class{GsvaExprData}}. Simple \code{matrix} and \code{dgCMatrix} objects are not +capable of storing annotation metadata and will return \code{NULL}.} + +\item{value}{For the replacement methods, the annotation metadata to be +stored in the object. For \code{\linkS4class{ExpressionSet}} objects, this must be a +character of length 1 specifying the name of the annotation database to be +used. For \code{\linkS4class{SummarizedExperiment}} and its subclasses, this must be +a \code{\link{GeneIdentifierType}} created by one of the constructors from package +\code{GSEABase} where the \code{annotation} argument is typically the name of an +organism or annotation database, e.g. \code{org.Hs.eg.db}. Simple \code{matrix} and +\code{dgCMatrix} objects are not capable of storing annotation metadata and the +attempt to do so will result in an error.} +} +\value{ +For the retrieval methods, the annotation metadata stored in the +object of \code{NULL}. For the replacement methods, the updated object. +} +\description{ +Methods for storing and retrieving annotation metadata in +expression data objects that support it. If gene sets and expression data +are using different but known gene identifier types and an appropriate +annotation database is available, gene set identifiers can be mapped to +expression data identifiers without manual user intervention, e.g. from +an MSigDb gene set using ENTREZ IDs or gene symbols to an expression data +set using ENSEMBL IDs. +}