Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions NAMESPACE
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,13 @@ export(previewNetworkInBrowser)
export(renderCytoscapeNetwork)
export(save_network)
export(select_entities)
export(string_backend)
export(subnetwork_query)
export(validate_network)
exportClasses(IndraBackend)
exportClasses(NetworkBackend)
exportClasses(NetworkQuery)
exportClasses(StringBackend)
exportClasses(SubnetworkQuery)
exportMethods(backend_capabilities)
exportMethods(convert_ids)
Expand All @@ -56,6 +58,7 @@ importFrom(httr,
add_headers,
content,
content_type_json,
http_error,
status_code
)
importFrom(jsonlite,
Expand Down
37 changes: 32 additions & 5 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,8 @@ metabolites:
evidence curated as incorrect, and `filter_by_curation(network,
min_evidence = 1)` subtracts it from `evidence_count`, drops the edges
left below `min_evidence` (and edges left with no evidence), and drops
the nodes left without edges. Like `get_evidence()`, it uses the
the nodes left without edges. Edges with an `NA` `evidence_count`
(STRING) are kept as they are. Like `get_evidence()`, it uses the
backend named in each edge's `backend_database` unless `backend` is
given. `indra_backend(curation_url = )` sets the INDRA database URL.
* `merge_networks(..., entities = NULL)` combines networks from several
Expand All @@ -72,11 +73,35 @@ metabolites:
`getSubnetworkFromIndra(sources_filter =)`, gives a warning that
suggests the internal name where there is one (e.g. `"psp"` for
`"phosphosite"`).
* The S4 classes `NetworkBackend`, `IndraBackend`, `NetworkQuery`, and
`SubnetworkQuery` are exported, so other packages can add backends.
* `string_backend(network_type = "physical", version = NULL)` is a
second backend, for the STRING database of protein-protein
associations, over its REST API (no new dependency). Its
`convert_ids()` grounds UniProt accessions to STRING proteins (other
identifiers give an error before any request, since STRING's search
maps them to the wrong protein; isoforms get their canonical
accession's protein), and `get_network()` answers `subnetwork_query()`.
`network_type` is `"physical"` (undirected `Complex` edges),
`"functional"` (undirected `Association` edges), or `"regulatory"`
(directed `Activation`, `Inhibition`, or `Regulation` edges, with
`sign`). `confidence` is STRING's combined score, and
`min_confidence` is sent as STRING's `required_score`.
`evidence_count` is `NA`, and `evidence_sources` lists STRING's
evidence channels with a non-zero score (e.g.
`"database;experiments;textmining"`), which `evidence_sources =`
filters on. Every
request goes to the address of one STRING version, which `provenance`
records, and requests are at least one second apart, as STRING asks.
* `convert_ids()` keeps the groundings of other backends and replaces
only its own, so one entity table can be grounded by INDRA and STRING,
and each backend's `get_network()` reads only its own groundings. The
two networks then share node IDs and combine with `merge_networks()`.
* The S4 classes `NetworkBackend`, `IndraBackend`, `StringBackend`,
`NetworkQuery`, and `SubnetworkQuery` are exported, so other packages
can add backends.
* New function `validate_network()` checks a `list(nodes, edges)` network
against the edge and node contract (v1.0): required columns and types, the
statement-type and entity-type vocabularies, value ranges, `NA` statistics
statement-type and entity-type vocabularies, value ranges (`evidence_count`
is at least 1, or `NA` for a backend with no evidence count), `NA` statistics
on nodes that are not in the input data, and that every edge's source and
target are nodes. It stops with an error listing every problem found.

Expand Down Expand Up @@ -114,7 +139,9 @@ zero fold change.
Columns are renamed, with no aliases: `stmt_hash` to `statement_id` (now
always character, taken from INDRA's full-precision `matches_hash`),
`evidenceLink` to `evidence_url`, `evidenceCount` to `evidence_count` (now
integer), and `sourceCounts` to `evidence_sources`. New columns: `directed`
integer), and `sourceCounts` to `evidence_sources`, which now holds the
source names joined by `;` (e.g. `"psp;reach"`) instead of a JSON object
of counts per source. New columns: `directed`
(`FALSE` for symmetric types such as `Complex`), `confidence` (INDRA belief
score), `backend_database` (`"INDRA"`), and `query_type` (`"subnetwork"`).
`filterSubnetworkByContext()`, the topic-model functions, and
Expand Down
52 changes: 45 additions & 7 deletions R/AllClasses.R
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,29 @@
#' with Gilda, INDRA's grounding service. Curations come from the INDRA
#' database.
#'
#' @slot cogex_url base URL of INDRA CoGEx
#' @slot grounding_url base URL of Gilda
#' @slot curation_url base URL of the INDRA database, which holds the
#' curations
#' \code{StringBackend} queries the STRING database of protein-protein
#' associations through its REST API, for one network type and one STRING
#' version.
#'
#' @seealso \code{\link{indra_backend}()}, \code{\link{backend_capabilities}()}
#' @slot cogex_url (\code{IndraBackend}) base URL of INDRA CoGEx
#' @slot grounding_url (\code{IndraBackend}) base URL of Gilda
#' @slot curation_url (\code{IndraBackend}) base URL of the INDRA
#' database, which holds the curations
#' @slot network_type (\code{StringBackend}) \code{"physical"},
#' \code{"functional"}, or \code{"regulatory"}
#' @slot version (\code{StringBackend}) the STRING version, e.g.
#' \code{"12.5"}, or \code{NA} for the current one
#' @slot caller_identity (\code{StringBackend}) the name sent to STRING
#' with each request
#' @slot host (\code{StringBackend}) environment holding the STRING
#' version and address, once resolved
#'
#' @seealso \code{\link{indra_backend}()}, \code{\link{string_backend}()},
#' \code{\link{backend_capabilities}()}
#' @name NetworkBackend-class
#' @aliases NetworkBackend-class IndraBackend-class
#' @aliases NetworkBackend-class IndraBackend-class StringBackend-class
#' @importFrom methods setClass setValidity
#' @exportClass NetworkBackend IndraBackend
#' @exportClass NetworkBackend IndraBackend StringBackend
NULL

setClass("NetworkBackend", representation("VIRTUAL"))
Expand All @@ -40,6 +53,31 @@ setValidity("IndraBackend", function(object) {
TRUE
})

setClass("StringBackend", contains = "NetworkBackend",
representation(network_type = "character",
version = "character",
caller_identity = "character",
host = "environment"))

setValidity("StringBackend", function(object) {
if (length(object@network_type) != 1 ||
!object@network_type %in% STRING_NETWORK_TYPES) {
return(paste0("network_type must be one of ",
paste0("\"", STRING_NETWORK_TYPES, "\"",
collapse = ", ")))
}
if (length(object@version) != 1 ||
(!is.na(object@version) &&
!grepl("^[0-9]+\\.[0-9]+$", object@version))) {
return("version must be NULL or a single string such as \"12.5\"")
}
if (length(object@caller_identity) != 1 ||
is.na(object@caller_identity) || !nzchar(object@caller_identity)) {
return("caller_identity must be a single non-empty string")
}
TRUE
})

#' Network query classes
#'
#' A query says which question \code{\link{get_network}()} asks of the
Expand Down
45 changes: 36 additions & 9 deletions R/AllGenerics.R
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,16 @@
#' without the documentation.
#'
#' Confidence values are comparable within one backend, not across
#' backends. For INDRA, \code{confidence} is the INDRA belief score.
#' backends. For INDRA, \code{confidence} is the INDRA belief score; for
#' STRING, the combined score.
#'
#' Each backend reads only its own groundings of \code{entities}, so one
#' table grounded by several backends' \code{\link{convert_ids}()} serves
#' all of them, and their networks share node IDs for
#' \code{\link{merge_networks}()}.
#'
#' @param backend a \code{NetworkBackend}, e.g. from
#' \code{\link{indra_backend}()}
#' \code{\link{indra_backend}()} or \code{\link{string_backend}()}
#' @param entities entity table from \code{\link{prepare_entities}()},
#' grounded by \code{\link{convert_ids}()} and flagged by
#' \code{\link{select_entities}()}
Expand All @@ -37,18 +43,25 @@
#' \code{\link{network_queries}}.
#' @param interaction_types values of \code{edges$interaction} to keep
#' (INDRA statement types, e.g. \code{"Activation"}). \code{NULL} keeps all.
#' @param min_evidence minimum evidence count per edge
#' @param min_evidence minimum evidence count per edge. Edges with no
#' evidence count (\code{NA}, as from STRING) pass the default of 1, and
#' are dropped by a higher cutoff, with a message saying how many.
#' @param min_confidence minimum \code{confidence} per edge, in [0, 1].
#' Edges with no confidence score (\code{NA}) are dropped too, and a message
#' says how many. \code{NULL} applies no cutoff.
#' says how many. \code{NULL} applies no cutoff. STRING gets the cutoff as
#' its \code{required_score}; STRING's website uses 0.4 by default.
#' @param evidence_sources keeps edges with evidence from at least one of
#' these sources, e.g. \code{c("reach")}. \code{NULL} keeps all.
#' \code{backend_capabilities(backend)$evidence_sources} lists a backend's
#' sources; for INDRA, \code{\link{INDRA_DATABASE_SOURCES}} keeps edges
#' with curated-database evidence and
#' \code{\link{INDRA_TEXT_MINED_SOURCES}} edges with text-mined evidence.
#' For STRING, the sources are its evidence channels, e.g.
#' \code{"experiments"}, and an edge is kept when one of them has a
#' non-zero score.
#' @param include_entities \code{"namespace:identifier"} groundings to add to
#' the query, e.g. \code{"HGNC:1234"}. Use this for entities outside the
#' the query, e.g. \code{"HGNC:1234"}, or for STRING
#' \code{"STRING:9606.ENSP00000269305"}. Use this for entities outside the
#' input; to keep entities of the input that fail the cutoffs, use
#' \code{select_entities(force_include = )}.
#' @param ... passed to methods
Expand All @@ -57,8 +70,8 @@
#' \code{provenance}: a data.frame with one row recording the query, with
#' the columns \code{backend_database}, \code{query_type},
#' \code{retrieved_at} (when the response arrived, in UTC),
#' \code{backend_version} (\code{NA} for INDRA, which has no data
#' versions), \code{backend_url}, \code{organism} (NCBI taxon IDs of the
#' \code{backend_version} (e.g. \code{"12.5"} for STRING; \code{NA} for
#' INDRA, which has no data versions), \code{backend_url}, \code{organism} (NCBI taxon IDs of the
#' queried rows), \code{parameters} (the query arguments, as JSON), and
#' \code{package_version} (of MSstatsBioNet). It joins to the edges on
#' \code{backend_database} and \code{query_type}.
Expand Down Expand Up @@ -129,13 +142,26 @@ setMethod("get_network", signature("NetworkBackend", "NetworkQuery"),
#' \code{\link{get_network}()} can recognize every node that is in the
#' input.
#'
#' A backend replaces only the groundings in its own namespaces and keeps
#' the others, so a table grounded by \code{indra_backend()} and then by
#' \code{string_backend()} has both groundings, e.g. \code{namespace =
#' "HGNC;STRING"}, and serves both backends.
#'
#' For STRING, only UniProt accessions are converted (\code{id_type =
#' "uniprot"}), each to one STRING protein of the row's organism, and the
#' namespace is \code{"STRING"}. An isoform (\code{"P04637-2"}) gets the
#' protein of its canonical accession. Identifiers that aren't accessions
#' give an error before any request, since STRING's search maps other text
#' to the wrong protein, and accessions STRING doesn't know are listed in a
#' message.
#'
#' For INDRA, UniProt IDs and mnemonics are mapped through CoGEx, and gene
#' symbols and chemical names are grounded with Gilda. When an identifier
#' is a protein group (\code{"P1;P2"}) or a name with several candidates,
#' the groundings are \code{";"}-joined and positionally aligned.
#'
#' @param backend a \code{NetworkBackend}, e.g. from
#' \code{\link{indra_backend}()}
#' \code{\link{indra_backend}()} or \code{\link{string_backend}()}
#' @param entities entity table from \code{\link{prepare_entities}()}
#' @param ... passed to methods
#' @return \code{entities} with the grounding columns filled in
Expand Down Expand Up @@ -322,7 +348,8 @@ setMethod("get_curations", "NetworkBackend",
#' \item{evidence_sources}{the \code{evidence_sources} values
#' \code{\link{get_network}()} filters on, as a list with
#' \code{database} and \code{text_mined} elements, e.g.
#' \code{\link{INDRA_DATABASE_SOURCES}}}
#' \code{\link{INDRA_DATABASE_SOURCES}}. STRING also has
#' \code{predicted} (genomic context and co-expression channels).}
#' \item{max_nodes}{for each query type, the largest number of
#' groundings one query can take}
#' }
Expand Down
15 changes: 14 additions & 1 deletion R/backend-indra-cogex.R
Original file line number Diff line number Diff line change
Expand Up @@ -209,14 +209,27 @@
backend_database = rep("INDRA", length(statements)),
query_type = rep("subnetwork", length(statements)),
evidence_sources = vapply(statements, function(x) {
x$data$source_counts
.list_indra_evidence_sources(x$data$source_counts)
}, ""),
paperCount = vapply(statements, function(x) x$data$paper_count, 1),
stringsAsFactors = FALSE
)
.add_edge_per_node_pair(edges, statements)
}

#' The evidence sources of an INDRA statement, for edges$evidence_sources
#' @param source_counts CoGEx's \code{source_counts}, a JSON object of
#' evidence count per source, e.g. \code{'{"reach": 12, "psp": 1}'}
#' @return the source names, sorted and \code{";"}-joined, e.g.
#' \code{"psp;reach"}, or \code{NA} when there are none
#' @keywords internal
#' @noRd
.list_indra_evidence_sources <- function(source_counts) {
parsed <- tryCatch(jsonlite::fromJSON(source_counts),
error = function(e) NULL)
.join_evidence_sources(names(parsed))
}

#' Give an edge to every pair of nodes its statement connects
#'
#' A statement whose source or target grounding matches several nodes
Expand Down
Loading
Loading