R/enz_sub.R

In saezlab/OmnipathR: OmniPath web service client and more

#!/usr/bin/env Rscript

#
#  This file is part of the `OmnipathR` R package
#
#  Copyright
#  2018-2024
#  Saez Lab, Uniklinik RWTH Aachen, Heidelberg University
#
#  File author(s): Alberto Valdeolivas
#                  Dénes Türei (turei.denes@gmail.com)
#                  Attila Gábor
#
#  Distributed under the MIT (Expat) License.
#  See accompanying file `LICENSE` or find a copy at
#      https://directory.fsf.org/wiki/License:Expat
#
#  Website: https://r.omnipathdb.org/
#  Git repo: https://github.com/saezlab/OmnipathR
#


#' Imports enzyme-substrate relationships from OmniPath
#'
#' Imports the enzyme-substrate (more exactly, enzyme-PTM) relationship
#' database from \url{https://omnipathdb.org/enzsub}
#'
#' @return A data frame containing the information about ptms
#'
#' @param resources PTMs not reported in these databases are
#'     removed. See \code{\link{get_ptms_databases}} for more information.
#' @param organism PTMs are available for human, mouse and rat.
#'     Choose among: 9606 human (default), 10116 rat and 10090 Mouse
#' @param fields You can define here additional fields to be added to the
#'     result. If used, set the next argument, \code{default_fields}, to
#'     \code{FALSE}.
#' @param default_fields Whether to include the default fields (columns) for
#'     the query type. If \code{FALSE}, only the fields defined by the user
#'     in the \code{fields} argument will be added.
#' @param references_by_resource if FALSE, removes the resource name prefixes
#'     from the references (PubMed IDs); this way the information which
#'     reference comes from which resource will be lost and the PubMed IDs
#'     will be unique.
#' @param exclude Character: datasets or resources to exclude.
#' @param ... Optional additional arguments.
#'
#' @examples
#' enzsub <- import_omnipath_enzsub(
#'     resources = c('PhosphoSite', 'SIGNOR'),
#'     organism = 9606
#' )
#'
#' @export
#'
#' @seealso \itemize{
#'     \item{\code{\link{get_enzsub_resources}}}
#'     \item{\code{\link{import_omnipath_interactions}}}
#'     \item{\code{\link{enzsub_graph}}}
#'     \item{\code{\link{print_interactions}}}
#' }
#'
#' @aliases import_Omnipath_PTMS import_OmniPath_PTMS
import_omnipath_enzsub <- function(
    resources = NULL,
    organism = 9606,
    fields = NULL,
    default_fields = TRUE,
    references_by_resource = TRUE,
    exclude = NULL,
    ...
){

    result <- import_omnipath(
        query_type = 'enzsub',
        resources = resources,
        organism = organism,
        fields = fields,
        default_fields = default_fields,
        references_by_resource = references_by_resource,
        exclude = exclude,
        ...
    )

    return(result)

}

# Aliases (old names) to be Deprecated
#' @rdname import_omnipath_enzsub
#' @param ... Passed to \code{import_omnipath_enzsub}.
#' @export
#'
#' @noRd
import_Omnipath_PTMS <- function(...){
    .Deprecated("import_omnipath_enzsub")
    import_omnipath_enzsub(...)
}


# Aliases (old names) to be Deprecated
#' @rdname import_omnipath_enzsub
#' @param ... Passed to \code{import_omnipath_enzsub}.
#' @export
#'
#' @noRd
import_OmniPath_PTMS <- function(...){
    .Deprecated("import_omnipath_enzsub")
    import_omnipath_enzsub(...)
}


#' Retrieves a list of enzyme-substrate resources available in OmniPath
#'
#' Get the names of the enzyme-substrate relationship resources available
#' in \url{https://omnipath.org/enzsub}
#'
#' @param dataset ignored for this query type
#' @return character vector with the names of the enzyme-substrate resources
#' @export
#'
#' @examples
#' get_enzsub_resources()
#'
#' @seealso \itemize{
#'     \item{\code{\link{get_resources}}}
#'     \item{\code{\link{import_omnipath_enzsub}}}
#' }
#'
#' @aliases get_ptms_databases
get_enzsub_resources <- function(dataset = NULL){

    return(get_resources(query_type = 'enzsub', datasets = dataset))

}


# Aliases (old names) to be deprecated
#' @rdname get_enzsub_resources
#' @param ... Passed to \code{get_enzsub_resources}.
#' @export
#'
#' @noRd
get_ptms_databases <- function(...){
    .Deprecated("get_enzsub_resources")
    get_enzsub_resources(...)
}


#' Signs for enzyme-substrate interactions
#'
#' Enzyme-substrate data does not contain sign (activation/inhibition), we
#' generate this information based on the interaction network.
#'
#' @param enzsub Enzyme-substrate data frame generated by
#'     \code{\link{import_omnipath_enzsub}}
#' @param interactions interaction data frame generated by
#'     \code{\link{import_omnipath_interactions}}
#'
#' @return Data frame of enzyme-substrate relationships with is_inhibition
#'     and is_stimulation columns.
#'
#' @export
#'
#' @examples
#' enzsub <- import_omnipath_enzsub(resources = c('PhosphoSite', 'SIGNOR'))
#' interactions <- import_omnipath_interactions()
#' enzsub <- get_signed_ptms(enzsub, interactions)
#'
#' @seealso \itemize{
#'     \item{\code{\link{import_omnipath_enzsub}}}
#'     \item{\code{\link{import_omnipath_interactions}}}
#' }
get_signed_ptms <- function(
    enzsub = import_omnipath_enzsub(),
    interactions = import_omnipath_interactions()
){

    signed.ptms <- merge(
        enzsub,
        interactions[,
            c("source", "target", "is_stimulation", "is_inhibition")
        ],
        by.x = c("enzyme", "substrate"),
        by.y = c("source", "target"),
        all.x = TRUE
    )

    return(signed.ptms)
}