From 29d385aaa069754248072e5dd66ea0e92f6919d0 Mon Sep 17 00:00:00 2001 From: Tony Wu Date: Fri, 9 Oct 2026 16:15:20 -0400 Subject: [PATCH] feat: Add StringDB integration with new contract --- NAMESPACE | 3 + NEWS.md | 37 +- R/AllClasses.R | 52 +- R/AllGenerics.R | 45 +- R/backend-indra-cogex.R | 15 +- R/backend-indra.R | 61 +- R/backend-registry.R | 32 +- R/backend-string.R | 737 ++++++++++++++++++ R/contract.R | 29 +- R/entities.R | 96 +++ R/filter-edges.R | 35 + R/getSubnetworkFromIndra.R | 2 +- R/network-postprocess.R | 16 +- man/NetworkBackend-class.Rd | 28 +- man/backend_capabilities.Rd | 9 +- man/convert_ids.Rd | 21 +- man/filter_by_curation.Rd | 3 +- man/getSubnetworkFromIndra.Rd | 2 +- man/get_network.Rd | 45 +- man/string_backend.Rd | 86 ++ man/validate_network.Rd | 6 +- .../testthat/_fixtures/golden_subnetwork.rds | Bin 1457 -> 1428 bytes .../testthat/_fixtures/make_string_fixtures.R | 38 + .../_fixtures/string/get_string_ids.json | 1 + .../_fixtures/string/network_functional.json | 1 + .../_fixtures/string/network_physical.json | 1 + .../_fixtures/string/network_regulatory.json | 1 + tests/testthat/_fixtures/string/version.json | 1 + tests/testthat/helper-indra.R | 23 + tests/testthat/test-backend-indra.R | 27 +- tests/testthat/test-backend-string.R | 656 ++++++++++++++++ tests/testthat/test-contract.R | 45 +- 32 files changed, 2035 insertions(+), 119 deletions(-) create mode 100644 R/backend-string.R create mode 100644 man/string_backend.Rd create mode 100644 tests/testthat/_fixtures/make_string_fixtures.R create mode 100644 tests/testthat/_fixtures/string/get_string_ids.json create mode 100644 tests/testthat/_fixtures/string/network_functional.json create mode 100644 tests/testthat/_fixtures/string/network_physical.json create mode 100644 tests/testthat/_fixtures/string/network_regulatory.json create mode 100644 tests/testthat/_fixtures/string/version.json create mode 100644 tests/testthat/helper-indra.R create mode 100644 tests/testthat/test-backend-string.R diff --git a/NAMESPACE b/NAMESPACE index 1fc5bd8..5e59d42 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -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) @@ -56,6 +58,7 @@ importFrom(httr, add_headers, content, content_type_json, + http_error, status_code ) importFrom(jsonlite, diff --git a/NEWS.md b/NEWS.md index f00f4d2..d2aee4d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -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 @@ -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. @@ -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 diff --git a/R/AllClasses.R b/R/AllClasses.R index cc1ae8b..02f766c 100644 --- a/R/AllClasses.R +++ b/R/AllClasses.R @@ -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")) @@ -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 diff --git a/R/AllGenerics.R b/R/AllGenerics.R index 899be6a..5a994f0 100644 --- a/R/AllGenerics.R +++ b/R/AllGenerics.R @@ -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}()} @@ -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 @@ -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}. @@ -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 @@ -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} #' } diff --git a/R/backend-indra-cogex.R b/R/backend-indra-cogex.R index 6b50fa7..3b5008b 100644 --- a/R/backend-indra-cogex.R +++ b/R/backend-indra-cogex.R @@ -209,7 +209,7 @@ 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 @@ -217,6 +217,19 @@ .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 diff --git a/R/backend-indra.R b/R/backend-indra.R index aab52c2..2b9909b 100644 --- a/R/backend-indra.R +++ b/R/backend-indra.R @@ -48,8 +48,9 @@ indra_backend <- function(cogex_url = INDRA_API_URL, curation_url = curation_url) } -# INDRA subnetwork query. Sends the groundings of the included_in_query rows -# to CoGEx indra_subnetwork_relations, filters the statements, and +# INDRA subnetwork query. Reads only INDRA's groundings (not STRING's), and +# sends those of the included_in_query rows to CoGEx +# indra_subnetwork_relations, filters the statements, and # normalizes them to the edge contract. The source and target of each # statement are matched back to the rows of entities by grounding, so nodes # carry their statistics. A grounding shared by the rows of several nodes @@ -61,6 +62,7 @@ setMethod("get_network", signature("IndraBackend", "SubnetworkQuery"), function(backend, entities, query, interaction_types = NULL, min_evidence = 1, min_confidence = NULL, evidence_sources = NULL, include_entities = NULL, ...) { + entities <- .keep_groundings(entities, .is_indra_namespace) groundings <- .get_groundings_to_query(entities) .validateIndraSubnetworkInput(groundings, evidence_sources, include_entities) @@ -97,6 +99,19 @@ setMethod("get_network", signature("IndraBackend", "SubnetworkQuery"), network }) +#' Whether namespaces are INDRA's +#' +#' INDRA grounds to whichever namespace CoGEx or Gilda returns (HGNC, +#' CHEBI, FPLX, ...), so it owns every namespace that isn't another +#' backend's. +#' @param namespaces character vector +#' @return logical vector +#' @keywords internal +#' @noRd +.is_indra_namespace <- function(namespaces) { + !namespaces %in% STRING_NAMESPACE +} + #' Largest number of groundings one INDRA query takes, by query type #' #' CoGEx \code{indra_subnetwork_relations} takes fewer than 400, so at most @@ -245,11 +260,13 @@ EVIDENCE_EDGE_COLUMNS <- c("source", "target", "interaction", "site", #' @param groundings groundings of the rows to query, from #' \code{.get_groundings_to_query()} #' @param include_entities groundings added to the query +#' @param backend_label the backend's name, first in the question #' @return a single string #' @keywords internal #' @noRd .describe_subnetwork_question <- function(entities, groundings, - include_entities) { + include_entities, + backend_label = "INDRA") { queried_types <- entities$entity_type[entities$id %in% groundings$id] selected <- .describe_entity_count(queried_types, "selected") if (length(include_entities) > 0) { @@ -258,7 +275,7 @@ EVIDENCE_EDGE_COLUMNS <- c("source", "target", "interaction", "site", if (length(include_entities) == 1) "entity" else "entities") } - paste0("INDRA subnetwork: how are ", selected, " connected to each ", + paste0(backend_label, " subnetwork: how are ", selected, " connected to each ", "other, with no other nodes added?") } @@ -754,7 +771,8 @@ INDRA_ENTITY_PROPERTIES <- list( # hgnc_symbol through Gilda restricted to HGNC and the row's organism, and # chemical_name through Gilda with no namespace restriction. Each # ";"-separated member of an identifier (a protein group) is grounded on its -# own, and the groundings are pooled onto the row. +# own, and the groundings are pooled onto the row. Groundings of other +# backends (STRING) are kept. #' @rdname convert_ids #' @export setMethod("convert_ids", "IndraBackend", @@ -775,9 +793,8 @@ setMethod("convert_ids", "IndraBackend", organisms = as.list(unique(.get_entity_organisms(entities)[rows]))), chemical_name = .ground_text_with_gilda( members[rows], backend@grounding_url)) - entities$namespace[rows] <- groundings$namespace - entities$entity_id[rows] <- groundings$entity_id - entities$entity_name[rows] <- groundings$entity_name + entities <- .replace_groundings(entities, rows, groundings, + .is_indra_namespace) } entities }) @@ -793,21 +810,24 @@ setMethod("get_entity_properties", "IndraBackend", .validate_entities(entities) properties <- .resolve_entity_properties( backend, properties, names(INDRA_ENTITY_PROPERTIES)) - # A ";"-joined namespace (several groundings) never equals "HGNC" - single_hgnc <- entities$namespace %in% "HGNC" & - !is.na(entities$entity_name) + # A ";"-joined namespace (several groundings) never equals "HGNC". + # STRING groundings don't count. + indra_groundings <- .keep_groundings(entities, .is_indra_namespace) + single_hgnc <- indra_groundings$namespace %in% "HGNC" & + !is.na(indra_groundings$entity_name) for (property in properties) { spec <- INDRA_ENTITY_PROPERTIES[[property]] queried <- single_hgnc & entities$entity_type %in% spec$entity_types values <- rep(NA, nrow(entities)) - genes <- unique(entities$entity_name[queried]) + genes <- unique(indra_groundings$entity_name[queried]) if (length(genes) > 0) { # Looked up by name at call time, so tests can mock the call call_api <- get(spec$api, mode = "function") response <- call_api(as.list(genes), backend@cogex_url) for (gene in names(response)) { if (!is.null(response[[gene]])) { - values[queried & entities$entity_name == gene] <- + values[queried & + indra_groundings$entity_name == gene] <- response[[gene]] } } @@ -827,20 +847,7 @@ setMethod("get_entity_properties", "IndraBackend", #' @keywords internal #' @noRd .check_indra_id_conversions <- function(entities) { - pairs <- unique(entities[, c("entity_type", "id_type")]) - supported <- vapply(seq_len(nrow(pairs)), function(i) { - pairs$id_type[i] %in% INDRA_ID_CONVERSIONS[[pairs$entity_type[i]]] - }, logical(1)) - if (any(!supported)) { - unsupported <- paste(pairs$entity_type[!supported], - pairs$id_type[!supported], sep = " / ") - allowed <- unlist(lapply(names(INDRA_ID_CONVERSIONS), function(type) { - paste(type, INDRA_ID_CONVERSIONS[[type]], sep = " / ") - })) - stop("IndraBackend can't convert entity_type / id_type: ", - .list_values_for_message(unsupported), ". Supported: ", - paste(allowed, collapse = ", "), ".", call. = FALSE) - } + .check_id_conversions(entities, indra_backend(), INDRA_ID_CONVERSIONS) is_protein <- entities$entity_type %in% c("protein", "ptm_site") organisms <- unique(.get_entity_organisms(entities)[is_protein]) non_human <- setdiff(organisms, "9606") diff --git a/R/backend-registry.R b/R/backend-registry.R index d68e853..bd06391 100644 --- a/R/backend-registry.R +++ b/R/backend-registry.R @@ -6,9 +6,39 @@ #' @keywords internal #' @noRd BACKEND_CONSTRUCTORS <- list( - INDRA = function() indra_backend() + INDRA = function() indra_backend(), + STRING = function() string_backend() ) +#' Stop when a backend can't convert some rows of an entity table +#' +#' Checks each row's (\code{entity_type}, \code{id_type}) pair against the +#' backend's supported conversions. +#' @param entities entity table +#' @param backend the backend, for the message +#' @param conversions named list: for each \code{entity_type}, the +#' \code{id_type} values the backend converts +#' @return \code{NULL}, invisibly; errors otherwise +#' @keywords internal +#' @noRd +.check_id_conversions <- function(entities, backend, conversions) { + pairs <- unique(entities[, c("entity_type", "id_type")]) + supported <- vapply(seq_len(nrow(pairs)), function(i) { + pairs$id_type[i] %in% conversions[[pairs$entity_type[i]]] + }, logical(1)) + if (any(!supported)) { + unsupported <- paste(pairs$entity_type[!supported], + pairs$id_type[!supported], sep = " / ") + allowed <- unlist(lapply(names(conversions), function(type) { + paste(type, conversions[[type]], sep = " / ") + })) + stop(class(backend), " can't convert entity_type / id_type: ", + .list_values_for_message(unsupported), ". Supported: ", + paste(allowed, collapse = ", "), ".", call. = FALSE) + } + invisible(NULL) +} + #' Check a backend argument #' @param backend \code{NULL} or a \code{NetworkBackend} #' @return \code{NULL}, invisibly; errors otherwise diff --git a/R/backend-string.R b/R/backend-string.R new file mode 100644 index 0000000..c110fe6 --- /dev/null +++ b/R/backend-string.R @@ -0,0 +1,737 @@ +# STRING backend: protein-protein associations from the STRING database, +# through its REST API (https://string-db.org/help/api/). Phase 5d of the +# API refactor; the design is in TODO-MSBio-20261001_refactor_api.md, 4.8. + +#' Address of STRING's current version, used to resolve the version +#' @keywords internal +#' @noRd +STRING_API_URL <- "https://string-db.org" + +#' The namespace of STRING groundings, e.g. STRING:9606.ENSP00000269305 +#' @keywords internal +#' @noRd +STRING_NAMESPACE <- "STRING" + +#' STRING network types +#' @keywords internal +#' @noRd +STRING_NETWORK_TYPES <- c("physical", "functional", "regulatory") + +#' Identifier systems the STRING backend converts, by entity type +#' +#' UniProt accessions only: get_string_ids is a text search, which maps a +#' mnemonic such as TP53_HUMAN to the wrong protein (HIPK4). +#' @keywords internal +#' @noRd +STRING_ID_CONVERSIONS <- list( + protein = "uniprot", + ptm_site = "uniprot" +) + +#' Pattern of a UniProt accession, with an optional isoform suffix +#' +#' From https://www.uniprot.org/help/accession_numbers. +#' @keywords internal +#' @noRd +UNIPROT_ACCESSION_PATTERN <- paste0( + "^([OPQ][0-9][A-Z0-9]{3}[0-9]|", + "[A-NR-Z][0-9]([A-Z][A-Z0-9]{2}[0-9]){1,2})(-[0-9]+)?$") + +#' Evidence channels of each STRING network type, and their response fields +#' +#' Names are the values of edges$evidence_sources and of the +#' evidence_sources argument of get_network(). +#' @keywords internal +#' @noRd +STRING_CHANNELS <- list( + physical = c(neighborhood = "nscore", fusion = "fscore", + cooccurence = "pscore", coexpression = "ascore", + experiments = "escore", database = "dscore", + textmining = "tscore"), + regulatory = c(experiments = "experimental_score", + database = "database_score", + textmining = "textmining_score") +) +STRING_CHANNELS$functional <- STRING_CHANNELS$physical + +#' STRING evidence channels, grouped as backend_capabilities() lists them +#' +#' "experiments" holds interactions imported from primary interaction +#' databases (BioGRID, IntAct, ...), and "database" from curated pathway +#' databases (KEGG, Reactome, ...), so both are database evidence. The +#' other channels are predictions from genomic context and co-expression. +#' @keywords internal +#' @noRd +STRING_CHANNEL_GROUPS <- list( + database = c("experiments", "database"), + text_mined = "textmining", + predicted = c("neighborhood", "fusion", "cooccurence", "coexpression") +) + +#' The interaction types of each STRING network type +#' @keywords internal +#' @noRd +STRING_INTERACTION_TYPES <- list( + physical = "Complex", + functional = "Association", + regulatory = c("Activation", "Inhibition", "Regulation") +) + +#' Largest number of proteins one STRING query takes, by query type +#' +#' More than 10 proteins also need a species, which get_network() always +#' sends. +#' @keywords internal +#' @noRd +STRING_MAX_NODES <- c(subnetwork = 2000) + +#' Create a STRING backend +#' +#' STRING is a database of protein-protein associations, scored by how +#' likely they are to be real. The backend queries STRING's REST API, so it +#' needs no other package. It grounds UniProt accessions to STRING proteins +#' and answers \code{\link{subnetwork_query}()}: the STRING edges among the +#' selected proteins. \code{backend_capabilities(string_backend())} lists +#' what it supports. +#' +#' STRING has three network types. \code{"physical"} (the default) has +#' edges between proteins that bind, as undirected \code{"Complex"} edges, +#' and is the closest to INDRA's mechanisms. \code{"functional"} adds +#' proteins that work together without binding, e.g. from co-expression +#' or text mining, as undirected \code{"Association"} edges, and is much +#' denser. \code{"regulatory"} has directed edges, as \code{"Activation"}, +#' \code{"Inhibition"}, or \code{"Regulation"} (no sign). +#' +#' Each STRING version has its own address, and the backend sends every +#' request to the address of one version, so one backend never mixes +#' versions and \code{network$provenance} records the version. With +#' \code{version = NULL}, the current version is looked up on the first +#' request. STRING asks for no more than one request per second, so the +#' backend waits between requests. +#' +#' STRING has no evidence count: \code{evidence_count} is \code{NA}. +#' \code{evidence_sources} lists the evidence channels with a non-zero +#' score, e.g. \code{"database;experiments;textmining"}: \code{experiments} +#' (interactions imported from experimental databases such as BioGRID and +#' IntAct), \code{database} (curated pathway databases such as KEGG and +#' Reactome), \code{textmining} (co-mention in the literature), and, for +#' the physical and functional networks, the predictions +#' \code{neighborhood}, \code{fusion}, \code{cooccurence}, and +#' \code{coexpression}. A channel pools many databases, so STRING edges +#' can't be filtered by one database. \code{confidence} is STRING's +#' combined score of the channels. STRING has no PTM sites, evidence text, or +#' curations, so \code{\link{get_evidence}()} and +#' \code{\link{get_curations}()} give an error for it, and +#' \code{\link{filter_by_curation}()} keeps its edges as they are. +#' +#' STRING is licensed under the Creative Commons Attribution 4.0 license. +#' Cite STRING when using its networks; see +#' \url{https://string-db.org/cgi/about}. +#' +#' @param network_type \code{"physical"}, \code{"functional"}, or +#' \code{"regulatory"} +#' @param version STRING version, e.g. \code{"12.5"}. \code{NULL} uses the +#' current version. +#' @param caller_identity name sent to STRING with each request, so STRING +#' can see which tool its requests come from +#' @return a \code{StringBackend} object, to pass to +#' \code{\link{convert_ids}()} and \code{\link{get_network}()} +#' @seealso \code{\link{NetworkBackend-class}}, \code{\link{indra_backend}()} +#' @export +#' @examples +#' string <- string_backend() +#' backend_capabilities(string)$interaction_types +#' \donttest{ +#' df <- data.frame(Protein = c("P04637", "Q00987", "P38936"), +#' adj.pvalue = c(0.01, 0.02, 0.03)) +#' entities <- prepare_entities(df, entity_type = "protein", +#' id_type = "uniprot") +#' entities <- convert_ids(string, entities) +#' entities <- select_entities(entities, pvalue_cutoff = 0.05) +#' network <- get_network(string, entities, min_confidence = 0.7) +#' network$edges[, c("source", "target", "interaction", "confidence")] +#' } +string_backend <- function(network_type = c("physical", "functional", + "regulatory"), + version = NULL, + caller_identity = "MSstatsBioNet") { + network_type <- match.arg(network_type) + new("StringBackend", network_type = network_type, + version = if (is.null(version)) NA_character_ else + as.character(version), + caller_identity = caller_identity, + host = new.env(parent = emptyenv())) +} + +#' @rdname backend_capabilities +#' @export +setMethod("backend_capabilities", "StringBackend", + function(backend) { + channels <- names(STRING_CHANNELS[[backend@network_type]]) + list(query_types = "subnetwork", + id_conversions = STRING_ID_CONVERSIONS, + entity_properties = character(0), + interaction_types = + STRING_INTERACTION_TYPES[[backend@network_type]], + evidence_sources = lapply(STRING_CHANNEL_GROUPS, intersect, + channels), + max_nodes = STRING_MAX_NODES) + }) + +# STRING identifier conversion. Sends the unique UniProt accessions of each +# organism to get_string_ids, without isoform suffixes, since STRING maps +# only canonical accessions. Rows of a protein group get the STRING protein +# of each member. Groundings of other backends (INDRA) are kept. +#' @rdname convert_ids +#' @export +setMethod("convert_ids", "StringBackend", + function(backend, entities, ...) { + .validate_entities(entities) + .check_id_conversions(entities, backend, STRING_ID_CONVERSIONS) + members <- .get_grounding_inputs(entities) + .check_uniprot_accessions(unlist(members, use.names = FALSE)) + accessions <- lapply(members, function(row_members) { + unique(sub("-[0-9]+$", "", row_members)) + }) + organisms <- .get_entity_organisms(entities) + groundings <- .build_empty_groundings(nrow(entities)) + unmapped <- character(0) + for (organism in unique(organisms)) { + rows <- which(organisms == organism) + queries <- unique(unlist(accessions[rows], use.names = FALSE)) + if (length(queries) == 0) { + next + } + mapping <- .map_accessions_to_string(backend, queries, organism) + unmapped <- c(unmapped, setdiff(queries, mapping$accession)) + for (i in rows) { + matched <- mapping[mapping$accession %in% accessions[[i]], , + drop = FALSE] + matched <- matched[order(match(matched$accession, + accessions[[i]])), , + drop = FALSE] + matched <- matched[!duplicated(matched$string_id), , + drop = FALSE] + if (nrow(matched) == 0) { + next + } + groundings$namespace[i] <- .joinProteinGroup( + rep(STRING_NAMESPACE, nrow(matched))) + groundings$entity_id[i] <- .joinProteinGroup(matched$string_id) + groundings$entity_name[i] <- .joinProteinGroup( + matched$preferred_name) + } + } + if (length(unmapped) > 0) { + message(length(unmapped), " UniProt accession(s) not found in ", + "STRING: ", .list_values_for_message(unmapped), ".") + } + .replace_groundings(entities, seq_len(nrow(entities)), groundings, + .is_string_namespace) + }) + +# STRING subnetwork query. Reads only the STRING groundings, sends the STRING +# proteins of the included_in_query rows to the network endpoint, which +# returns the edges among them, and normalizes the edges to the contract. +# Proteins from include_entities that match no row become latent nodes. +#' @rdname get_network +#' @export +setMethod("get_network", signature("StringBackend", "SubnetworkQuery"), + function(backend, entities, query, interaction_types = NULL, + min_evidence = 1, min_confidence = NULL, + evidence_sources = NULL, include_entities = NULL, ...) { + entities <- .keep_groundings(entities, .is_string_namespace) + groundings <- .get_groundings_to_query(entities) + .check_min_confidence(min_confidence) + .validate_string_subnetwork_input(backend, groundings, min_evidence, + evidence_sources, include_entities) + organism <- .get_string_query_organism(entities) + string_ids <- unique(c( + groundings$entity_id, + sub(paste0("^", STRING_NAMESPACE, ":"), "", include_entities))) + message(.describe_subnetwork_question( + entities, groundings, include_entities, + backend_label = paste("STRING", backend@network_type))) + host <- .resolve_string_host(backend) + response <- .call_string_api( + backend, "network", + list(identifiers = paste(string_ids, collapse = "\r"), + species = organism, + network_type = backend@network_type, + required_score = .get_string_required_score(min_confidence))) + retrieved_at <- .get_current_time() + interactions <- .parse_string_network(response, backend@network_type) + interactions <- .filter_string_interactions( + interactions, interaction_types, evidence_sources, + backend@network_type) + grounding_lookup <- .build_grounding_lookup(entities) + edges <- .build_string_edges(interactions, grounding_lookup, + backend@network_type, host$address, + organism) + edges <- .filter_by_min_evidence(edges, min_evidence) + edges <- .filter_by_min_confidence(edges, min_confidence) + edges <- .filterEdgesDataFrame(edges) + nodes <- .build_network_nodes( + grounding_lookup, edges, + .list_latent_string_nodes(interactions, grounding_lookup)) + nodes$entity_type[!nodes$measured & + nodes$namespace %in% STRING_NAMESPACE] <- + "protein" + provenance <- .build_provenance( + backend_database = "STRING", query_type = "subnetwork", + backend_url = host$address, organism = organism, + parameters = list(interaction_types = interaction_types, + min_evidence = min_evidence, + min_confidence = min_confidence, + evidence_sources = evidence_sources, + include_entities = include_entities, + network_type = backend@network_type), + backend_version = host$version, + retrieved_at = retrieved_at) + network <- list(nodes = nodes, edges = edges, provenance = provenance) + validate_network(network) + network + }) + +#' Whether namespaces are STRING's +#' @param namespaces character vector +#' @return logical vector +#' @keywords internal +#' @noRd +.is_string_namespace <- function(namespaces) { + namespaces %in% STRING_NAMESPACE +} + +#' Stop unless every identifier is a UniProt accession +#' +#' Checked before any request: STRING's get_string_ids is a text search and +#' would map, e.g., a mnemonic in a column labelled "uniprot" to the wrong +#' protein. +#' @param identifiers character vector +#' @return \code{NULL}, invisibly; errors listing the others +#' @keywords internal +#' @noRd +.check_uniprot_accessions <- function(identifiers) { + not_accessions <- unique(identifiers[!grepl(UNIPROT_ACCESSION_PATTERN, + identifiers)]) + if (length(not_accessions) > 0) { + stop("StringBackend takes UniProt accessions (e.g. \"P04637\"), ", + "since STRING's ID search maps other text to the wrong ", + "protein. Not accessions: ", + .list_values_for_message(not_accessions), ".", call. = FALSE) + } + invisible(NULL) +} + +#' Map UniProt accessions to STRING proteins +#' +#' STRING leaves out the identifiers it can't map, and also all but one of +#' several identifiers of the same protein, so the accessions missing from +#' the first response are sent once more on their own. +#' @param backend a \code{StringBackend} +#' @param accessions unique UniProt accessions, without isoform suffixes +#' @param organism NCBI taxon ID +#' @return data.frame with \code{accession}, \code{string_id}, +#' \code{preferred_name}, for the accessions that map +#' @keywords internal +#' @noRd +.map_accessions_to_string <- function(backend, accessions, organism) { + mapping <- .request_string_ids(backend, accessions, organism) + missing <- setdiff(accessions, mapping$accession) + if (length(missing) > 0 && length(missing) < length(accessions)) { + mapping <- rbind(mapping, + .request_string_ids(backend, missing, organism)) + } + mapping +} + +#' Call get_string_ids for a set of accessions +#' +#' Each returned row is checked against the accession sent at its +#' \code{queryIndex} and against the organism, so a row STRING matched to +#' something else is dropped. +#' @inheritParams .map_accessions_to_string +#' @return data.frame like \code{.map_accessions_to_string()}'s +#' @keywords internal +#' @noRd +.request_string_ids <- function(backend, accessions, organism) { + response <- .call_string_api( + backend, "get_string_ids", + list(identifiers = paste(accessions, collapse = "\r"), + species = organism, echo_query = 1, limit = 1)) + mapping <- data.frame(accession = character(0), string_id = character(0), + preferred_name = character(0), + stringsAsFactors = FALSE) + if (nrow(response) == 0) { + return(mapping) + } + sent <- accessions[as.integer(response$queryIndex) + 1] + matches_query <- !is.na(sent) & sent == response$queryItem & + as.character(response$ncbiTaxonId) == organism + rbind(mapping, data.frame( + accession = sent[matches_query], + string_id = as.character(response$stringId[matches_query]), + preferred_name = as.character(response$preferredName[matches_query]), + stringsAsFactors = FALSE)) +} + +#' Validate the input of the STRING subnetwork query +#' @param backend a \code{StringBackend} +#' @param groundings grounding table of the rows to query +#' @param min_evidence,evidence_sources,include_entities arguments of +#' \code{get_network()} +#' @keywords internal +#' @noRd +.validate_string_subnetwork_input <- function(backend, groundings, + min_evidence, evidence_sources, + include_entities) { + if (nrow(groundings) == 0) { + stop("No selected entity has a STRING grounding. Run ", + "convert_ids(string_backend(), entities) first.", call. = FALSE) + } + n_proteins <- length(unique(groundings$entity_id)) + + length(include_entities) + if (n_proteins > STRING_MAX_NODES[["subnetwork"]]) { + stop("A STRING query takes at most ", + STRING_MAX_NODES[["subnetwork"]], " proteins; got ", n_proteins, + ". Consider lowering your p-value cutoff.", call. = FALSE) + } + if (!is.numeric(min_evidence) || length(min_evidence) != 1 || + is.na(min_evidence)) { + stop("min_evidence must be a single number.", call. = FALSE) + } + if (!is.null(evidence_sources)) { + channels <- names(STRING_CHANNELS[[backend@network_type]]) + unknown <- setdiff(evidence_sources, channels) + if (!is.character(evidence_sources) || length(unknown) > 0) { + stop("evidence_sources for the STRING ", backend@network_type, + " network must be among: ", paste(channels, collapse = ", "), + ".", call. = FALSE) + } + } + if (!is.null(include_entities)) { + pattern <- paste0("^", STRING_NAMESPACE, ":.+") + if (!is.character(include_entities) || + !all(grepl(pattern, include_entities))) { + stop("include_entities for STRING must be STRING groundings, ", + "e.g. \"STRING:9606.ENSP00000269305\".", call. = FALSE) + } + } + invisible(NULL) +} + +#' The organism of a STRING query +#' +#' STRING takes one species per request. +#' @param entities entity table +#' @return NCBI taxon ID of the queried rows +#' @keywords internal +#' @noRd +.get_string_query_organism <- function(entities) { + organisms <- unique(.get_entity_organisms(entities)[ + entities$included_in_query & !is.na(entities$entity_id)]) + if (length(organisms) != 1) { + stop("A STRING query takes one organism; the selected entities ", + "have: ", .list_values_for_message(organisms), ".", + call. = FALSE) + } + organisms +} + +#' The required_score of a STRING request +#' +#' STRING applies 0.4 when none is sent; \code{min_confidence = NULL} means +#' no cutoff, so 0 is sent. +#' @param min_confidence the argument of get_network() +#' @return integer in [0, 1000] +#' @keywords internal +#' @noRd +.get_string_required_score <- function(min_confidence) { + if (is.null(min_confidence)) 0L else as.integer(round(1000 * min_confidence)) +} + +#' Parse a STRING network response +#' +#' @param response data.frame from the network endpoint +#' @param network_type the backend's network type +#' @return data.frame with one row per STRING interaction: +#' \code{source_id}, \code{target_id}, \code{source_name}, +#' \code{target_name}, \code{interaction}, \code{interaction_raw}, +#' \code{directed}, \code{sign}, \code{confidence}, \code{statement_id}, +#' and one score column per evidence channel. Undirected interactions +#' listed in both orders are kept once. +#' @keywords internal +#' @noRd +.parse_string_network <- function(response, network_type) { + channels <- STRING_CHANNELS[[network_type]] + n <- nrow(response) + if (network_type == "regulatory") { + ids <- c("source_string_id", "target_string_id") + names <- c("source_preferred_name", "target_preferred_name") + score <- "combined_score" + } else { + ids <- c("stringId_A", "stringId_B") + names <- c("preferredName_A", "preferredName_B") + score <- "score" + } + if (n == 0) { + response <- as.data.frame( + stats::setNames(rep(list(character(0)), 4), c(ids, names)), + stringsAsFactors = FALSE) + } + directed <- network_type == "regulatory" + sign_raw <- if (directed) as.character(response$sign) else + rep(NA_character_, n) + interactions <- data.frame( + source_id = as.character(response[[ids[1]]]), + target_id = as.character(response[[ids[2]]]), + source_name = as.character(response[[names[1]]]), + target_name = as.character(response[[names[2]]]), + interaction = .get_string_interaction(network_type, sign_raw), + interaction_raw = if (directed) { + paste0("regulatory:", sign_raw, recycle0 = TRUE) + } else { + rep(network_type, n) + }, + directed = rep(directed, n), + sign = ifelse(sign_raw %in% "pos", 1L, + ifelse(sign_raw %in% "neg", -1L, NA_integer_)), + confidence = as.numeric(response[[score]]), + stringsAsFactors = FALSE + ) + for (channel in names(channels)) { + values <- response[[channels[[channel]]]] + interactions[[channel]] <- if (is.null(values)) rep(0, n) else + as.numeric(values) + } + pair <- if (directed) { + paste(interactions$source_id, interactions$target_id, sep = "|") + } else { + paste(pmin(interactions$source_id, interactions$target_id), + pmax(interactions$source_id, interactions$target_id), sep = "|") + } + interactions$statement_id <- paste0("string:", network_type, ":", pair, + recycle0 = TRUE) + interactions[!duplicated(interactions$statement_id), , drop = FALSE] +} + +#' The interaction type of STRING edges +#' @param network_type the backend's network type +#' @param sign_raw STRING's \code{sign} of each edge (regulatory only) +#' @return character vector +#' @keywords internal +#' @noRd +.get_string_interaction <- function(network_type, sign_raw) { + switch(network_type, + physical = rep("Complex", length(sign_raw)), + functional = rep("Association", length(sign_raw)), + regulatory = ifelse(sign_raw %in% "pos", "Activation", + ifelse(sign_raw %in% "neg", "Inhibition", + "Regulation"))) +} + +#' Filter STRING interactions by type and evidence channel +#' @param interactions from \code{.parse_string_network()} +#' @param interaction_types,evidence_sources arguments of get_network() +#' @param network_type the backend's network type +#' @return \code{interactions}, filtered. With \code{evidence_sources}, an +#' interaction is kept when one of the named channels has a non-zero score. +#' @keywords internal +#' @noRd +.filter_string_interactions <- function(interactions, interaction_types, + evidence_sources, network_type) { + if (!is.null(interaction_types)) { + interactions <- interactions[ + interactions$interaction %in% interaction_types, , drop = FALSE] + } + if (!is.null(evidence_sources)) { + scores <- as.matrix(interactions[, evidence_sources, drop = FALSE]) + interactions <- interactions[rowSums(scores > 0) > 0, , drop = FALSE] + } + interactions +} + +#' Build the edges of a STRING network +#' +#' Each interaction becomes one edge per (source node, target node) pair, +#' as for INDRA, so rows that share a STRING protein (two isoforms of one +#' protein) each get its edges. +#' @param interactions from \code{.parse_string_network()} +#' @param grounding_lookup from \code{.build_grounding_lookup()} +#' @param network_type the backend's network type +#' @param address the STRING version's address, for \code{evidence_url} +#' @param organism NCBI taxon ID, for \code{evidence_url} +#' @return edges data.frame that meets the contract +#' @keywords internal +#' @noRd +.build_string_edges <- function(interactions, grounding_lookup, + network_type, address, organism) { + n <- nrow(interactions) + channels <- names(STRING_CHANNELS[[network_type]]) + evidence_sources <- vapply(seq_len(n), function(i) { + scores <- unlist(interactions[i, channels, drop = TRUE]) + .join_evidence_sources(names(scores)[scores > 0]) + }, character(1)) + edges <- data.frame( + source = character(n), + target = character(n), + interaction = interactions$interaction, + directed = interactions$directed, + site = rep(NA_character_, n), + confidence = interactions$confidence, + evidence_count = rep(NA_integer_, n), + evidence_url = paste0(address, "/cgi/network?identifiers=", + interactions$source_id, "%0d", + interactions$target_id, "&species=", + organism, recycle0 = TRUE), + statement_id = interactions$statement_id, + backend_database = rep("STRING", n), + query_type = rep("subnetwork", n), + evidence_sources = evidence_sources, + interaction_raw = interactions$interaction_raw, + sign = interactions$sign, + stringsAsFactors = FALSE + ) + statements <- lapply(seq_len(n), function(i) { + list(source_ns = STRING_NAMESPACE, + source_id = interactions$source_id[i], + target_ns = STRING_NAMESPACE, + target_id = interactions$target_id[i], + source_node_ids = .find_node_ids_for_grounding( + grounding_lookup, STRING_NAMESPACE, + interactions$source_id[i], interactions$source_name[i]), + target_node_ids = .find_node_ids_for_grounding( + grounding_lookup, STRING_NAMESPACE, + interactions$target_id[i], interactions$target_name[i])) + }) + .add_edge_per_node_pair(edges, statements) +} + +#' List the STRING proteins of interactions that match no entity row +#' @param interactions from \code{.parse_string_network()} +#' @param grounding_lookup from \code{.build_grounding_lookup()} +#' @return data.frame like \code{.list_latent_backend_nodes()}'s, with +#' STRING's preferred name as \code{id} +#' @keywords internal +#' @noRd +.list_latent_string_nodes <- function(interactions, grounding_lookup) { + backend_nodes <- data.frame( + namespace = rep(STRING_NAMESPACE, 2 * nrow(interactions)), + entity_id = c(interactions$source_id, interactions$target_id), + entity_name = c(interactions$source_name, interactions$target_name), + stringsAsFactors = FALSE) + matches_no_row <- vapply(backend_nodes$entity_id, function(entity_id) { + length(.find_entity_rows_for_grounding( + grounding_lookup, STRING_NAMESPACE, entity_id)) == 0 + }, logical(1), USE.NAMES = FALSE) + backend_nodes <- backend_nodes[matches_no_row, , drop = FALSE] + backend_nodes$id <- backend_nodes$entity_name + backend_nodes[!duplicated(backend_nodes$id), , drop = FALSE] +} + +#' Resolve the version and address a STRING backend sends requests to +#' +#' Resolved once per backend object and kept in its \code{host} +#' environment: a given version has a fixed address +#' (\code{https://version-12-5.string-db.org}), and \code{version = NULL} +#' asks STRING's version endpoint for the current one. +#' @param backend a \code{StringBackend} +#' @return list with \code{version} and \code{address} +#' @keywords internal +#' @noRd +.resolve_string_host <- function(backend) { + host <- backend@host + if (is.null(host$address)) { + if (is.na(backend@version)) { + response <- .send_string_request( + paste0(STRING_API_URL, "/api/json/version"), + list(caller_identity = backend@caller_identity)) + host$version <- as.character(response$string_version[1]) + host$address <- as.character(response$stable_address[1]) + } else { + host$version <- backend@version + host$address <- paste0("https://version-", + gsub(".", "-", backend@version, + fixed = TRUE), + ".string-db.org") + } + } + list(version = host$version, address = host$address) +} + +#' Call an endpoint of the backend's STRING version +#' @param backend a \code{StringBackend} +#' @param endpoint e.g. \code{"network"} +#' @param parameters named list of request parameters +#' @return data.frame of the JSON response, with no rows when it is empty +#' @keywords internal +#' @noRd +.call_string_api <- function(backend, endpoint, parameters) { + address <- .resolve_string_host(backend)$address + .send_string_request( + paste0(address, "/api/json/", endpoint), + c(parameters, caller_identity = backend@caller_identity)) +} + +#' When the last STRING request was sent, for the one-per-second limit +#' @keywords internal +#' @noRd +.string_request_times <- new.env(parent = emptyenv()) + +#' Send a request to STRING, at most one per second +#' +#' STRING asks for no more than one request per second and no parallel +#' requests. +#' @param url endpoint URL +#' @param body named list of form parameters +#' @return data.frame of the JSON response, with no rows when it is empty +#' @keywords internal +#' @noRd +.send_string_request <- function(url, body) { + last_request <- .string_request_times$last + if (!is.null(last_request)) { + elapsed <- as.numeric(difftime(.get_string_clock(), last_request, + units = "secs")) + if (elapsed < 1) { + .wait_for_string(1 - elapsed) + } + } + on.exit(.string_request_times$last <- .get_string_clock()) + response <- .post_string_request(url, body) + if (length(response) == 0) { + return(data.frame()) + } + as.data.frame(response, stringsAsFactors = FALSE) +} + +#' The clock for the STRING request limit; its own function for tests +#' @keywords internal +#' @noRd +.get_string_clock <- function() { + Sys.time() +} + +#' Wait before the next STRING request; its own function for tests +#' @param seconds how long +#' @keywords internal +#' @noRd +.wait_for_string <- function(seconds) { + Sys.sleep(seconds) +} + +#' POST a form to STRING and parse the JSON response +#' @param url endpoint URL +#' @param body named list of form parameters +#' @return the parsed JSON, a data.frame or an empty list +#' @importFrom httr POST content http_error status_code +#' @keywords internal +#' @noRd +.post_string_request <- function(url, body) { + response <- httr::POST(url, body = body, encode = "form") + if (httr::http_error(response)) { + stop("STRING request to ", url, " failed with HTTP status ", + httr::status_code(response), ".", call. = FALSE) + } + jsonlite::fromJSON(httr::content(response, as = "text", + encoding = "UTF-8")) +} diff --git a/R/contract.R b/R/contract.R index dce94ba..62986a8 100644 --- a/R/contract.R +++ b/R/contract.R @@ -103,7 +103,8 @@ OPTIONAL_NODE_COLUMNS <- c( #' \code{site} (PTM site on the target such as \code{"S148"}, \code{;}-joined #' when there are several, or \code{NA}), \code{confidence} (in [0, 1], or #' \code{NA} when the source provides no score), \code{evidence_count} -#' (whole number, at least 1, not \code{NA}), \code{evidence_url}, +#' (whole number, at least 1, or \code{NA} when the source has no +#' evidence count, as STRING), \code{evidence_url}, #' \code{statement_id} (character), \code{backend_database}, and #' \code{query_type}. #' Edges of the symmetric statement types \code{"Complex"} and @@ -111,6 +112,9 @@ OPTIONAL_NODE_COLUMNS <- c( #' can share a \code{statement_id}: an undirected statement can be listed #' in both directions, and a statement reaches every node with its #' grounding (see \code{\link{get_network}()}). +#' When present, \code{evidence_sources} must be the names of the edge's +#' evidence sources, joined by \code{";"} (e.g. \code{"psp;reach"}), or +#' \code{NA}. #' #' Required node columns: \code{id}, \code{entity_type} (e.g. #' \code{"protein"}, \code{"ptm_site"}, \code{"metabolite"}, @@ -282,17 +286,32 @@ validate_network <- function(network) { } if ("evidence_count" %in% colnames(edges)) { evidence_count <- edges$evidence_count - # is.infinite() errors on list columns; .check_columns() reports those - if (anyNA(evidence_count) || - (is.numeric(evidence_count) && any(is.infinite(evidence_count)))) { + # NA means the backend has no evidence count, e.g. STRING. is.infinite() + # errors on list columns; .check_columns() reports those + if (is.numeric(evidence_count) && any(is.infinite(evidence_count))) { problems <- c(problems, - "edges$evidence_count must not be NA or infinite") + "edges$evidence_count must not be infinite") } if (is.numeric(evidence_count) && any(evidence_count[is.finite(evidence_count)] < 1)) { problems <- c(problems, "edges$evidence_count must be at least 1") } } + if ("evidence_sources" %in% colnames(edges)) { + sources <- edges$evidence_sources + if (!is.character(sources) && !all(is.na(sources))) { + problems <- c(problems, "edges$evidence_sources must be character") + } else { + sources <- sources[!is.na(sources)] + badly_formatted <- sources[!grepl("^[^;]+(;[^;]+)*$", sources)] + if (length(badly_formatted) > 0) { + problems <- c(problems, paste0( + "edges$evidence_sources must be source names joined ", + "by ';', e.g. 'psp;reach': ", + paste(unique(badly_formatted), collapse = ", "))) + } + } + } if ("site" %in% colnames(edges) && is.character(edges$site)) { sites <- edges$site[!is.na(edges$site)] badly_formatted_sites <- diff --git a/R/entities.R b/R/entities.R index 1f630d6..b0d8a80 100644 --- a/R/entities.R +++ b/R/entities.R @@ -270,6 +270,102 @@ build_grounding_table <- function(entities, namespaces = NULL) { long } +#' Keep only some namespaces in an entity table's groundings +#' +#' Each backend reads only its own groundings, so that one entity table +#' grounded by several backends (see \code{.replace_groundings()}) gives +#' each backend's \code{get_network()} its own namespaces, and its nodes +#' only those groundings. +#' @param entities entity table +#' @param keep_namespace function of a character vector of namespaces, +#' returning \code{TRUE} for the ones to keep, e.g. +#' \code{.is_indra_namespace} +#' @return \code{entities}, with \code{namespace}, \code{entity_id}, and +#' \code{entity_name} rebuilt from the kept groundings (\code{NA} for rows +#' left with none). Unchanged when every grounding is kept. +#' @keywords internal +#' @noRd +.keep_groundings <- function(entities, keep_namespace) { + long <- build_grounding_table(entities) + kept <- keep_namespace(long$namespace) + if (all(kept)) { + return(entities) + } + groundings <- .collapse_groundings(long[kept, , drop = FALSE], + entities$id) + entities$namespace <- groundings$namespace + entities$entity_id <- groundings$entity_id + entities$entity_name <- groundings$entity_name + entities +} + +#' Replace a backend's groundings of some rows, keeping the others +#' +#' A backend's \code{convert_ids()} replaces only the groundings in its own +#' namespaces and keeps those of other backends, so that one entity table +#' can be grounded by INDRA and STRING and serve both. The kept groundings +#' come first, then the new ones. +#' @param entities entity table +#' @param rows row numbers to replace the groundings of +#' @param groundings data.frame with \code{namespace}, \code{entity_id}, +#' \code{entity_name}, one row per element of \code{rows}, \code{";"}-joined +#' @param owned_namespace function of a character vector of namespaces, +#' returning \code{TRUE} for the backend's own +#' @return \code{entities} with the grounding columns of \code{rows} replaced +#' @keywords internal +#' @noRd +.replace_groundings <- function(entities, rows, groundings, + owned_namespace) { + columns <- c("namespace", "entity_id", "entity_name") + current <- build_grounding_table(entities[rows, , drop = FALSE]) + others <- current[!owned_namespace(current$namespace), , drop = FALSE] + if (nrow(others) == 0) { + entities[rows, columns] <- groundings[, columns] + return(entities) + } + replaced <- entities[rows, , drop = FALSE] + replaced[, columns] <- groundings[, columns] + combined <- rbind(others, build_grounding_table(replaced)) + # order() keeps ties in their original order, so other backends first + combined <- combined[order(match(combined$id, entities$id[rows])), , + drop = FALSE] + entities[rows, columns] <- .collapse_groundings(combined, + entities$id[rows]) + entities +} + +#' Join a long grounding table back into the entity grounding columns +#' +#' The inverse of \code{build_grounding_table()}. +#' @param long data.frame with \code{id}, \code{namespace}, +#' \code{entity_id}, \code{entity_name}, one row per grounding +#' @param ids the \code{id} of each row to return +#' @return data.frame with \code{namespace}, \code{entity_id}, +#' \code{entity_name}, one row per element of \code{ids}, \code{";"}-joined, +#' and \code{NA} for ids with no grounding. \code{entity_name} has +#' \code{"NA"} for a grounding with no name, and is \code{NA} when no +#' grounding of the row has one. +#' @keywords internal +#' @noRd +.collapse_groundings <- function(long, ids) { + collapsed <- .build_empty_groundings(length(ids)) + rows_by_id <- split(seq_len(nrow(long)), + factor(long$id, levels = unique(long$id))) + for (id in names(rows_by_id)) { + i <- match(id, ids) + rows <- rows_by_id[[id]] + collapsed$namespace[i] <- paste(long$namespace[rows], collapse = ";") + collapsed$entity_id[i] <- paste(long$entity_id[rows], collapse = ";") + entity_names <- long$entity_name[rows] + if (!all(is.na(entity_names))) { + collapsed$entity_name[i] <- paste( + ifelse(is.na(entity_names), "NA", entity_names), + collapse = ";") + } + } + collapsed +} + #' Flag the entities to query #' #' Sets \code{included_in_query} from the statistical cutoffs. Only these diff --git a/R/filter-edges.R b/R/filter-edges.R index 3b40590..9cd9fd9 100644 --- a/R/filter-edges.R +++ b/R/filter-edges.R @@ -1,5 +1,16 @@ # Edge filters shared by every backend's get_network() method. +#' Join the evidence source names of one edge for edges$evidence_sources +#' @param sources character vector of source names +#' @return a single string: the unique names, sorted and \code{";"}-joined, +#' or \code{NA} when there are none +#' @keywords internal +#' @noRd +.join_evidence_sources <- function(sources) { + sources <- sort(unique(sources[!is.na(sources) & nzchar(sources)])) + if (length(sources) == 0) NA_character_ else paste(sources, collapse = ";") +} + #' Stop unless min_confidence is NULL or a single number in [0, 1] #' @param min_confidence the argument of get_network() #' @keywords internal @@ -36,3 +47,27 @@ } edges[!no_score & edges$confidence >= min_confidence, , drop = FALSE] } + +#' Drop edges below an evidence count cutoff +#' +#' Edges with no evidence count (\code{NA}, e.g. from STRING) pass the +#' default \code{min_evidence = 1}, since every edge has at least one piece +#' of evidence. A higher cutoff drops them, since they can't be shown to +#' pass, and a message says how many. +#' @param edges edges data.frame with an \code{evidence_count} column +#' @param min_evidence cutoff +#' @return \code{edges}, filtered +#' @keywords internal +#' @noRd +.filter_by_min_evidence <- function(edges, min_evidence) { + no_count <- is.na(edges$evidence_count) + if (min_evidence <= 1) { + return(edges[no_count | edges$evidence_count >= min_evidence, , + drop = FALSE]) + } + if (any(no_count)) { + message("Dropping ", sum(no_count), " edge(s) with no evidence ", + "count (NA evidence_count), because min_evidence is above 1.") + } + edges[!no_count & edges$evidence_count >= min_evidence, , drop = FALSE] +} diff --git a/R/getSubnetworkFromIndra.R b/R/getSubnetworkFromIndra.R index cc5b665..39efa9a 100644 --- a/R/getSubnetworkFromIndra.R +++ b/R/getSubnetworkFromIndra.R @@ -66,7 +66,7 @@ #' \code{evidence_url} (INDRA page for this statement), \code{statement_id} #' (INDRA statement hash, as character), \code{backend_database} #' (\code{"INDRA"}), \code{query_type} (\code{"subnetwork"}), -#' \code{evidence_sources} (evidence count per source, as JSON), and the +#' \code{evidence_sources} (the evidence sources, \code{";"}-joined, e.g. \code{"psp;reach"}), and the #' deprecated \code{paperCount} (and \code{correlation} when #' \code{protein_level_data} is given). #' diff --git a/R/network-postprocess.R b/R/network-postprocess.R index 4640175..e8c7cb5 100644 --- a/R/network-postprocess.R +++ b/R/network-postprocess.R @@ -7,7 +7,8 @@ #' then drops the edges left below \code{min_evidence}, and the nodes those #' edges leave without any edge. Edges left with no evidence are dropped #' whatever \code{min_evidence} is. A message says how many edges were -#' dropped. +#' dropped. Edges with no evidence count (\code{NA}), such as STRING's, +#' are kept as they are, and their backend is not asked for curations. #' #' Run it after any filter that pools edges, such as the PTM-site filter of #' \code{\link{getSubnetworkFromIndra}()}: dropping edges first can change @@ -50,9 +51,16 @@ filter_by_curation <- function(network, min_evidence = 1, backend = NULL) { .check_filter_by_curation_input(network, min_evidence) .check_backend_argument(backend) edges <- network$edges - incorrect_counts <- .count_incorrect_evidence(edges, backend) - edges$evidence_count <- as.integer(edges$evidence_count - incorrect_counts) - keep <- edges$evidence_count >= min_evidence & edges$evidence_count >= 1 + # Edges with no evidence count (NA, e.g. STRING) have nothing to subtract + # from, so they are kept and their backend is not asked + counted <- !is.na(edges$evidence_count) + incorrect_counts <- .count_incorrect_evidence( + edges[counted, , drop = FALSE], backend) + edges$evidence_count[counted] <- as.integer( + edges$evidence_count[counted] - incorrect_counts) + edges$evidence_count <- as.integer(edges$evidence_count) + keep <- !counted | + (edges$evidence_count >= min_evidence & edges$evidence_count >= 1) if (any(!keep)) { message("Dropping ", sum(!keep), " edge(s) with fewer than ", max(min_evidence, 1), " evidence after removing the ", diff --git a/man/NetworkBackend-class.Rd b/man/NetworkBackend-class.Rd index 5acd2c5..61a352c 100644 --- a/man/NetworkBackend-class.Rd +++ b/man/NetworkBackend-class.Rd @@ -3,6 +3,7 @@ \name{NetworkBackend-class} \alias{NetworkBackend-class} \alias{IndraBackend-class} +\alias{StringBackend-class} \title{Network backend classes} \description{ A backend is a source of prior-knowledge networks, such as INDRA. @@ -16,18 +17,35 @@ extending \code{NetworkBackend} and writing methods for the generics. \code{IndraBackend} queries INDRA CoGEx for networks and grounds names with Gilda, INDRA's grounding service. Curations come from the INDRA database. + +\code{StringBackend} queries the STRING database of protein-protein +associations through its REST API, for one network type and one STRING +version. } \section{Slots}{ \describe{ -\item{\code{cogex_url}}{base URL of INDRA CoGEx} +\item{\code{cogex_url}}{(\code{IndraBackend}) base URL of INDRA CoGEx} + +\item{\code{grounding_url}}{(\code{IndraBackend}) base URL of Gilda} + +\item{\code{curation_url}}{(\code{IndraBackend}) base URL of the INDRA +database, which holds the curations} + +\item{\code{network_type}}{(\code{StringBackend}) \code{"physical"}, +\code{"functional"}, or \code{"regulatory"}} + +\item{\code{version}}{(\code{StringBackend}) the STRING version, e.g. +\code{"12.5"}, or \code{NA} for the current one} -\item{\code{grounding_url}}{base URL of Gilda} +\item{\code{caller_identity}}{(\code{StringBackend}) the name sent to STRING +with each request} -\item{\code{curation_url}}{base URL of the INDRA database, which holds the -curations} +\item{\code{host}}{(\code{StringBackend}) environment holding the STRING +version and address, once resolved} }} \seealso{ -\code{\link{indra_backend}()}, \code{\link{backend_capabilities}()} +\code{\link{indra_backend}()}, \code{\link{string_backend}()}, +\code{\link{backend_capabilities}()} } diff --git a/man/backend_capabilities.Rd b/man/backend_capabilities.Rd index 7c1c3c3..c828284 100644 --- a/man/backend_capabilities.Rd +++ b/man/backend_capabilities.Rd @@ -1,9 +1,11 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/AllGenerics.R, R/backend-indra.R +% Please edit documentation in R/AllGenerics.R, R/backend-indra.R, +% R/backend-string.R \name{backend_capabilities} \alias{backend_capabilities} \alias{backend_capabilities,NetworkBackend-method} \alias{backend_capabilities,IndraBackend-method} +\alias{backend_capabilities,StringBackend-method} \title{What a backend supports} \usage{ backend_capabilities(backend) @@ -11,6 +13,8 @@ backend_capabilities(backend) \S4method{backend_capabilities}{NetworkBackend}(backend) \S4method{backend_capabilities}{IndraBackend}(backend) + +\S4method{backend_capabilities}{StringBackend}(backend) } \arguments{ \item{backend}{a \code{NetworkBackend}, e.g. from @@ -31,7 +35,8 @@ named list: \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} } diff --git a/man/convert_ids.Rd b/man/convert_ids.Rd index 2b017e2..b8a64f2 100644 --- a/man/convert_ids.Rd +++ b/man/convert_ids.Rd @@ -1,9 +1,11 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/AllGenerics.R, R/backend-indra.R +% Please edit documentation in R/AllGenerics.R, R/backend-indra.R, +% R/backend-string.R \name{convert_ids} \alias{convert_ids} \alias{convert_ids,NetworkBackend-method} \alias{convert_ids,IndraBackend-method} +\alias{convert_ids,StringBackend-method} \title{Ground entities in a backend's namespaces} \usage{ convert_ids(backend, entities, ...) @@ -11,10 +13,12 @@ convert_ids(backend, entities, ...) \S4method{convert_ids}{NetworkBackend}(backend, entities, ...) \S4method{convert_ids}{IndraBackend}(backend, entities, ...) + +\S4method{convert_ids}{StringBackend}(backend, entities, ...) } \arguments{ \item{backend}{a \code{NetworkBackend}, e.g. from -\code{\link{indra_backend}()}} +\code{\link{indra_backend}()} or \code{\link{string_backend}()}} \item{entities}{entity table from \code{\link{prepare_entities}()}} @@ -35,6 +39,19 @@ Ground the full results table, not only the significant rows, so that \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, diff --git a/man/filter_by_curation.Rd b/man/filter_by_curation.Rd index 80a122c..311dff3 100644 --- a/man/filter_by_curation.Rd +++ b/man/filter_by_curation.Rd @@ -34,7 +34,8 @@ Subtracts the evidence curated as incorrect, from then drops the edges left below \code{min_evidence}, and the nodes those edges leave without any edge. Edges left with no evidence are dropped whatever \code{min_evidence} is. A message says how many edges were -dropped. +dropped. Edges with no evidence count (\code{NA}), such as STRING's, +are kept as they are, and their backend is not asked for curations. } \details{ Run it after any filter that pools edges, such as the PTM-site filter of diff --git a/man/getSubnetworkFromIndra.Rd b/man/getSubnetworkFromIndra.Rd index 9e1b2ec..73a1ec0 100644 --- a/man/getSubnetworkFromIndra.Rd +++ b/man/getSubnetworkFromIndra.Rd @@ -99,7 +99,7 @@ rows, such as two isoforms of one gene, gives each of them an edge): \code{evidence_url} (INDRA page for this statement), \code{statement_id} (INDRA statement hash, as character), \code{backend_database} (\code{"INDRA"}), \code{query_type} (\code{"subnetwork"}), -\code{evidence_sources} (evidence count per source, as JSON), and the +\code{evidence_sources} (the evidence sources, \code{";"}-joined, e.g. \code{"psp;reach"}), and the deprecated \code{paperCount} (and \code{correlation} when \code{protein_level_data} is given). diff --git a/man/get_network.Rd b/man/get_network.Rd index 455a608..6fcdc70 100644 --- a/man/get_network.Rd +++ b/man/get_network.Rd @@ -1,10 +1,12 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/AllGenerics.R, R/backend-indra.R +% Please edit documentation in R/AllGenerics.R, R/backend-indra.R, +% R/backend-string.R \name{get_network} \alias{get_network} \alias{get_network,NetworkBackend,missing-method} \alias{get_network,NetworkBackend,NetworkQuery-method} \alias{get_network,IndraBackend,SubnetworkQuery-method} +\alias{get_network,StringBackend,SubnetworkQuery-method} \title{Get a network from a backend} \usage{ get_network( @@ -54,10 +56,22 @@ get_network( include_entities = NULL, ... ) + +\S4method{get_network}{StringBackend,SubnetworkQuery}( + backend, + entities, + query = subnetwork_query(), + interaction_types = NULL, + min_evidence = 1, + min_confidence = NULL, + evidence_sources = NULL, + include_entities = NULL, + ... +) } \arguments{ \item{backend}{a \code{NetworkBackend}, e.g. from -\code{\link{indra_backend}()}} +\code{\link{indra_backend}()} or \code{\link{string_backend}()}} \item{entities}{entity table from \code{\link{prepare_entities}()}, grounded by \code{\link{convert_ids}()} and flagged by @@ -70,21 +84,28 @@ grounded by \code{\link{convert_ids}()} and flagged by \item{interaction_types}{values of \code{edges$interaction} to keep (INDRA statement types, e.g. \code{"Activation"}). \code{NULL} keeps all.} -\item{min_evidence}{minimum evidence count per edge} +\item{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.} \item{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.} \item{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.} +\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.} \item{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 = )}.} @@ -96,8 +117,8 @@ contract checked by \code{\link{validate_network}()}, and \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}. @@ -132,7 +153,13 @@ number of entities, so the query in a saved script or log is readable 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}()}. } \examples{ input <- data.table::fread(system.file( diff --git a/man/string_backend.Rd b/man/string_backend.Rd new file mode 100644 index 0000000..cb5d5d6 --- /dev/null +++ b/man/string_backend.Rd @@ -0,0 +1,86 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/backend-string.R +\name{string_backend} +\alias{string_backend} +\title{Create a STRING backend} +\usage{ +string_backend( + network_type = c("physical", "functional", "regulatory"), + version = NULL, + caller_identity = "MSstatsBioNet" +) +} +\arguments{ +\item{network_type}{\code{"physical"}, \code{"functional"}, or +\code{"regulatory"}} + +\item{version}{STRING version, e.g. \code{"12.5"}. \code{NULL} uses the +current version.} + +\item{caller_identity}{name sent to STRING with each request, so STRING +can see which tool its requests come from} +} +\value{ +a \code{StringBackend} object, to pass to +\code{\link{convert_ids}()} and \code{\link{get_network}()} +} +\description{ +STRING is a database of protein-protein associations, scored by how +likely they are to be real. The backend queries STRING's REST API, so it +needs no other package. It grounds UniProt accessions to STRING proteins +and answers \code{\link{subnetwork_query}()}: the STRING edges among the +selected proteins. \code{backend_capabilities(string_backend())} lists +what it supports. +} +\details{ +STRING has three network types. \code{"physical"} (the default) has +edges between proteins that bind, as undirected \code{"Complex"} edges, +and is the closest to INDRA's mechanisms. \code{"functional"} adds +proteins that work together without binding, e.g. from co-expression +or text mining, as undirected \code{"Association"} edges, and is much +denser. \code{"regulatory"} has directed edges, as \code{"Activation"}, +\code{"Inhibition"}, or \code{"Regulation"} (no sign). + +Each STRING version has its own address, and the backend sends every +request to the address of one version, so one backend never mixes +versions and \code{network$provenance} records the version. With +\code{version = NULL}, the current version is looked up on the first +request. STRING asks for no more than one request per second, so the +backend waits between requests. + +STRING has no evidence count: \code{evidence_count} is \code{NA}. +\code{evidence_sources} lists the evidence channels with a non-zero +score, e.g. \code{"database;experiments;textmining"}: \code{experiments} +(interactions imported from experimental databases such as BioGRID and +IntAct), \code{database} (curated pathway databases such as KEGG and +Reactome), \code{textmining} (co-mention in the literature), and, for +the physical and functional networks, the predictions +\code{neighborhood}, \code{fusion}, \code{cooccurence}, and +\code{coexpression}. A channel pools many databases, so STRING edges +can't be filtered by one database. \code{confidence} is STRING's +combined score of the channels. STRING has no PTM sites, evidence text, or +curations, so \code{\link{get_evidence}()} and +\code{\link{get_curations}()} give an error for it, and +\code{\link{filter_by_curation}()} keeps its edges as they are. + +STRING is licensed under the Creative Commons Attribution 4.0 license. +Cite STRING when using its networks; see +\url{https://string-db.org/cgi/about}. +} +\examples{ +string <- string_backend() +backend_capabilities(string)$interaction_types +\donttest{ +df <- data.frame(Protein = c("P04637", "Q00987", "P38936"), + adj.pvalue = c(0.01, 0.02, 0.03)) +entities <- prepare_entities(df, entity_type = "protein", + id_type = "uniprot") +entities <- convert_ids(string, entities) +entities <- select_entities(entities, pvalue_cutoff = 0.05) +network <- get_network(string, entities, min_confidence = 0.7) +network$edges[, c("source", "target", "interaction", "confidence")] +} +} +\seealso{ +\code{\link{NetworkBackend-class}}, \code{\link{indra_backend}()} +} diff --git a/man/validate_network.Rd b/man/validate_network.Rd index 29b8580..e0e11c3 100644 --- a/man/validate_network.Rd +++ b/man/validate_network.Rd @@ -25,7 +25,8 @@ Required edge columns: \code{source}, \code{target} (both matching \code{site} (PTM site on the target such as \code{"S148"}, \code{;}-joined when there are several, or \code{NA}), \code{confidence} (in [0, 1], or \code{NA} when the source provides no score), \code{evidence_count} -(whole number, at least 1, not \code{NA}), \code{evidence_url}, +(whole number, at least 1, or \code{NA} when the source has no +evidence count, as STRING), \code{evidence_url}, \code{statement_id} (character), \code{backend_database}, and \code{query_type}. Edges of the symmetric statement types \code{"Complex"} and @@ -33,6 +34,9 @@ Edges of the symmetric statement types \code{"Complex"} and can share a \code{statement_id}: an undirected statement can be listed in both directions, and a statement reaches every node with its grounding (see \code{\link{get_network}()}). +When present, \code{evidence_sources} must be the names of the edge's +evidence sources, joined by \code{";"} (e.g. \code{"psp;reach"}), or +\code{NA}. Required node columns: \code{id}, \code{entity_type} (e.g. \code{"protein"}, \code{"ptm_site"}, \code{"metabolite"}, diff --git a/tests/testthat/_fixtures/golden_subnetwork.rds b/tests/testthat/_fixtures/golden_subnetwork.rds index 112093c60d3e96ffb6b92979b825012b3aae73aa..af03ab4ae5a205ab8df7cbabc6e33a8518a72ad7 100644 GIT binary patch literal 1428 zcmV;F1#9{riwFP!000001ML`1ZyQB)<2Z5Rd?-xX90XaNRvbZmh45;7%UTZTiinz;B!0nQF$x)VO7~H2=UPNuYEQBDMw)odO z&Z~5HLAETYrj?>?WHQzs#$vq*qJ14b4Yb%!TRq*Sal^!c^mo5Mx**+JOzpq6njLPw z{Pp6EAO4i?PxgVupUOW8UEA4MfKY_=u_X+zyBL+Tv;EPXQm6lJx_0{X|LCi-w zJ8>cP{Fox0>$=u?WA%_^CeHkI{=qxa@%PtGEu3tV&Rsqf%YJ-XI(zTJx1Y9Nm!7@) z&Ie1`nDpi!vA*wzFQM%aDf`da^}3vg*eIP2GNP$YuLJ6~X3wYX`2q}}N)sJadznc= zR$PQL#^uwNhq6^PA%^#9x{@oZ$Ssd6$);!nA4RFsrDg*|^`Em8~@9lr9ml zlUs7e%m_YIaalb+SeTV_MHpPIl0%!pSuIA!RoRvYGiGT${^9MWF*k?})KxOfOX!81 zzlxeQCm44*?E0$*<8X-G4Dtu+KoIvs{%~Jgo-c^|gMT@s*P%ulk{rV{e^T{~45eRRiY-a^+b5PZ@`W5cSsjcg6kD5>ZOzc@ z8s7-moq~#qP8&?*jiPSf4U3&sw|iW#rO-x1?)OCACSvm^NUJs$<9Zyvjb@D9Zc7=W zUs^f#@NbK69FtZqKKA)H%U7hIuausv(n{gomtVYZsX`BoTfYB78~M<$E_~|@|HPN) zZ-?hO^qc*smPS9ir!vo>yYd3C(-Ipov){3A#A!Q-%9lmN(>8l(5f5#%FA{u?#A2M#x(M2lu@!n1Ek0^ydcmN4@j2hcvi|7W?r@* z$=dnc-SDF*6uA&nk_YIF(?S(~BlYv6MMmHm3eX}6SdQfy)Q$oa`q3Q63rIl$&{g=2 z*3XZk7>*_xo+U-V0aj?(c>jVkw#APpX`U205da3gsD|}JU*{adae(3|fuw#&Bo@dC>TEC)!$l0zAHkJ*nBSpn^69SgKe-Qkqan}7m;H{7LcO2tE=^=klt`Cs!)Pa#i8^BgS9&&bdK;{ zC}gn)#P^1`TZIxlC>2UDWNfK)Z+IKlAt!XS>d?A|oS-YWGU&e0W~#xCsKzK z|5dP)$CxAr%-*ZA3082|vBNyF>_ literal 1457 zcmV;i1y1@OiwFP!000001ML`FZxmH{*lur2+myCm5{)4>F+TKi&fJGYr)x_AjctRF zcp+J*GpF5w-I;Y}7ATEDpOgeO8sdX5Di7iV5TA^1nrgfR@CSHFs4*A=6kb$}0X(yv zGdq{*G{2tpDFKnzcpA(0c_r%!V@ux%&N={CtVTj^epWZVCeOgm`YKlCPo|+u<=FPiC(@zqf^e8OzKOQAt~O$h;@3*cl=z;}Xas zH|NaRadN0qinf2Ka8St=QPf*Chc|=gEkUL<#ZiW4EZ3hfd%I;G8X^JebOZAezTw5c zfrndOGVb)m^;J&B@f5of6i(EUBp!ys>At$YP!bO(|58e?!VzC3k3 z{+vg@(syKW$Jx8e&v|rTUj+6>YB^{2dGSqn<7TS-W|0VtO#xaWKwIgJgq)+DS;r~Z z+lGg==^@?FEM;g~H-~LUaZnzYCwq9tGV>W+QL@8>P!d={6d76okP~=;lV?mTuQ-on zoqX<2?C~8`hyGcC_lSx{99YQq~ISme^*hA}hQVns-f%?N0w! zfp9ERc5&K3&LPt}@IPi6&S~oRwtNwl;_jSXQ04QuL$G zldrVvRO#BN<8mu((`|1rc9NcjZ5A!R&)4E8)+{0);+u8DL6)KhzV_QR-9oD4_x*z1 zyp(DhGrEQhUtAYDxD031!1sNJk1blH;&=GPz1(B$o>tTY$j~xwKW|#GeLbcAVz7nT z?MqzthIA2A1*L$j(UR_x`w8OyioL?7+f=wUc!esp21CJ1kZkHUH~p3+(q>DI#an*^ L7CstH^%(#FH}vEM diff --git a/tests/testthat/_fixtures/make_string_fixtures.R b/tests/testthat/_fixtures/make_string_fixtures.R new file mode 100644 index 0000000..a82daf9 --- /dev/null +++ b/tests/testthat/_fixtures/make_string_fixtures.R @@ -0,0 +1,38 @@ +# Saves the STRING responses that test-backend-string.R replays: version, +# get_string_ids, and network (physical, functional, regulatory) for TP53, +# MDM2, CDKN1A, and MAPK1, from STRING 12.5. The get_string_ids request also +# sends P0DTC2 (SARS-CoV-2 spike), which has no human STRING protein, so +# the saved response has no row for it, as STRING leaves out unmapped IDs. +# +# Run from the package root: +# Rscript tests/testthat/_fixtures/make_string_fixtures.R +stable_address <- "https://version-12-5.string-db.org" +fixture_dir <- "tests/testthat/_fixtures/string" +dir.create(fixture_dir, showWarnings = FALSE) + +save_response <- function(file, url, body) { + Sys.sleep(1) + response <- httr::POST(url, body = body, encode = "form") + httr::stop_for_status(response) + writeLines(httr::content(response, as = "text", encoding = "UTF-8"), + file.path(fixture_dir, file)) +} + +save_response("version.json", "https://string-db.org/api/json/version", + list(caller_identity = "MSstatsBioNet")) +save_response("get_string_ids.json", + paste0(stable_address, "/api/json/get_string_ids"), + list(identifiers = paste("P04637", "Q00987", "P38936", + "P28482", "P0DTC2", sep = "\r"), + species = "9606", echo_query = 1, limit = 1, + caller_identity = "MSstatsBioNet")) +string_ids <- c("9606.ENSP00000269305", "9606.ENSP00000258149", + "9606.ENSP00000384849", "9606.ENSP00000215832") +for (network_type in c("physical", "functional", "regulatory")) { + save_response(paste0("network_", network_type, ".json"), + paste0(stable_address, "/api/json/network"), + list(identifiers = paste(string_ids, collapse = "\r"), + species = "9606", network_type = network_type, + required_score = 0, + caller_identity = "MSstatsBioNet")) +} diff --git a/tests/testthat/_fixtures/string/get_string_ids.json b/tests/testthat/_fixtures/string/get_string_ids.json new file mode 100644 index 0000000..f948e35 --- /dev/null +++ b/tests/testthat/_fixtures/string/get_string_ids.json @@ -0,0 +1 @@ +[{"queryIndex": 0, "queryItem": "P04637", "stringId": "9606.ENSP00000269305", "ncbiTaxonId": 9606, "taxonName": "Homo sapiens", "preferredName": "TP53", "annotation": "Cellular tumor antigen p53; Acts as a tumor suppressor in many tumor types; induces growth arrest or apoptosis depending on the physiological circumstances and cell type. Involved in cell cycle regulation as a trans-activator that acts to negatively regulate cell division by controlling a set of genes required for this process. One of the activated genes is an inhibitor of cyclin-dependent kinases. Apoptosis induction seems to be mediated either by stimulation of BAX and FAS antigen expression, or by repression of Bcl-2 expression. Its pro-apoptotic activity is activated via its intera [...] "}, {"queryIndex": 1, "queryItem": "Q00987", "stringId": "9606.ENSP00000258149", "ncbiTaxonId": 9606, "taxonName": "Homo sapiens", "preferredName": "MDM2", "annotation": "E3 ubiquitin-protein ligase Mdm2; E3 ubiquitin-protein ligase that mediates ubiquitination of p53/TP53, leading to its degradation by the proteasome. Inhibits p53/TP53- and p73/TP73-mediated cell cycle arrest and apoptosis by binding its transcriptional activation domain. Also acts as a ubiquitin ligase E3 toward itself and ARRB1. Permits the nuclear export of p53/TP53. Promotes proteasome-dependent ubiquitin-independent degradation of retinoblastoma RB1 protein. Inhibits DAXX-mediated apoptosis by inducing its ubiquitination and degradation. Component of the TRIM28/KAP1-MDM2-p53/TP53 [...] "}, {"queryIndex": 2, "queryItem": "P38936", "stringId": "9606.ENSP00000384849", "ncbiTaxonId": 9606, "taxonName": "Homo sapiens", "preferredName": "CDKN1A", "annotation": "Cyclin-dependent kinase inhibitor 1; May be involved in p53/TP53 mediated inhibition of cellular proliferation in response to DNA damage. Binds to and inhibits cyclin- dependent kinase activity, preventing phosphorylation of critical cyclin-dependent kinase substrates and blocking cell cycle progression. Functions in the nuclear localization and assembly of cyclin D-CDK4 complex and promotes its kinase activity towards RB1. At higher stoichiometric ratios, inhibits the kinase activity of the cyclin D- CDK4 complex. Inhibits DNA synthesis by DNA polymerase delta by competing with POLD3 [...] "}, {"queryIndex": 3, "queryItem": "P28482", "stringId": "9606.ENSP00000215832", "ncbiTaxonId": 9606, "taxonName": "Homo sapiens", "preferredName": "MAPK1", "annotation": "Mitogen-activated protein kinase 1; Serine/threonine kinase which acts as an essential component of the MAP kinase signal transduction pathway. MAPK1/ERK2 and MAPK3/ERK1 are the 2 MAPKs which play an important role in the MAPK/ERK cascade. They participate also in a signaling cascade initiated by activated KIT and KITLG/SCF. Depending on the cellular context, the MAPK/ERK cascade mediates diverse biological functions such as cell growth, adhesion, survival and differentiation through the regulation of transcription, translation, cytoskeletal rearrangements. The MAPK/ERK cascade plays a [...] "}] diff --git a/tests/testthat/_fixtures/string/network_functional.json b/tests/testthat/_fixtures/string/network_functional.json new file mode 100644 index 0000000..6d7115f --- /dev/null +++ b/tests/testthat/_fixtures/string/network_functional.json @@ -0,0 +1 @@ +[{"stringId_A": "9606.ENSP00000215832", "stringId_B": "9606.ENSP00000258149", "preferredName_A": "MAPK1", "preferredName_B": "MDM2", "ncbiTaxonId": "9606", "score": 0.452, "nscore": 0, "fscore": 0, "pscore": 0, "ascore": 0.066, "escore": 0.046, "dscore": 0, "tscore": 0.435}, {"stringId_A": "9606.ENSP00000215832", "stringId_B": "9606.ENSP00000384849", "preferredName_A": "MAPK1", "preferredName_B": "CDKN1A", "ncbiTaxonId": "9606", "score": 0.759, "nscore": 0, "fscore": 0, "pscore": 0, "ascore": 0, "escore": 0.489, "dscore": 0, "tscore": 0.548}, {"stringId_A": "9606.ENSP00000215832", "stringId_B": "9606.ENSP00000269305", "preferredName_A": "MAPK1", "preferredName_B": "TP53", "ncbiTaxonId": "9606", "score": 0.999, "nscore": 0, "fscore": 0, "pscore": 0, "ascore": 0.052, "escore": 0.999, "dscore": 0.9, "tscore": 0.68}, {"stringId_A": "9606.ENSP00000258149", "stringId_B": "9606.ENSP00000269305", "preferredName_A": "MDM2", "preferredName_B": "TP53", "ncbiTaxonId": "9606", "score": 0.999, "nscore": 0, "fscore": 0, "pscore": 0, "ascore": 0.129, "escore": 0.999, "dscore": 0.9, "tscore": 0.984}, {"stringId_A": "9606.ENSP00000258149", "stringId_B": "9606.ENSP00000384849", "preferredName_A": "MDM2", "preferredName_B": "CDKN1A", "ncbiTaxonId": "9606", "score": 0.999, "nscore": 0, "fscore": 0, "pscore": 0, "ascore": 0.075, "escore": 0.999, "dscore": 0, "tscore": 0.855}, {"stringId_A": "9606.ENSP00000269305", "stringId_B": "9606.ENSP00000384849", "preferredName_A": "TP53", "preferredName_B": "CDKN1A", "ncbiTaxonId": "9606", "score": 0.999, "nscore": 0, "fscore": 0, "pscore": 0, "ascore": 0, "escore": 0.999, "dscore": 0.9, "tscore": 0.959}] diff --git a/tests/testthat/_fixtures/string/network_physical.json b/tests/testthat/_fixtures/string/network_physical.json new file mode 100644 index 0000000..7b26cb4 --- /dev/null +++ b/tests/testthat/_fixtures/string/network_physical.json @@ -0,0 +1 @@ +[{"stringId_A": "9606.ENSP00000215832", "stringId_B": "9606.ENSP00000269305", "preferredName_A": "MAPK1", "preferredName_B": "TP53", "ncbiTaxonId": "9606", "score": 0.999, "nscore": 0, "fscore": 0, "pscore": 0, "ascore": 0, "escore": 0.999, "dscore": 0, "tscore": 0.098}, {"stringId_A": "9606.ENSP00000258149", "stringId_B": "9606.ENSP00000269305", "preferredName_A": "MDM2", "preferredName_B": "TP53", "ncbiTaxonId": "9606", "score": 0.999, "nscore": 0, "fscore": 0, "pscore": 0, "ascore": 0, "escore": 0.999, "dscore": 0.7, "tscore": 0.927}, {"stringId_A": "9606.ENSP00000258149", "stringId_B": "9606.ENSP00000384849", "preferredName_A": "MDM2", "preferredName_B": "CDKN1A", "ncbiTaxonId": "9606", "score": 0.999, "nscore": 0, "fscore": 0, "pscore": 0, "ascore": 0, "escore": 0.999, "dscore": 0, "tscore": 0}, {"stringId_A": "9606.ENSP00000269305", "stringId_B": "9606.ENSP00000384849", "preferredName_A": "TP53", "preferredName_B": "CDKN1A", "ncbiTaxonId": "9606", "score": 0.999, "nscore": 0, "fscore": 0, "pscore": 0, "ascore": 0, "escore": 0.999, "dscore": 0, "tscore": 0.343}] diff --git a/tests/testthat/_fixtures/string/network_regulatory.json b/tests/testthat/_fixtures/string/network_regulatory.json new file mode 100644 index 0000000..76314e8 --- /dev/null +++ b/tests/testthat/_fixtures/string/network_regulatory.json @@ -0,0 +1 @@ +[{"source_string_id": "9606.ENSP00000384849", "target_string_id": "9606.ENSP00000215832", "source_preferred_name": "CDKN1A", "target_preferred_name": "MAPK1", "ncbiTaxonId": "9606", "experimental_score": 0.0, "database_score": 0.0, "textmining_score": 0.068, "sign": "pos", "combined_score": 0.068}, {"source_string_id": "9606.ENSP00000384849", "target_string_id": "9606.ENSP00000269305", "source_preferred_name": "CDKN1A", "target_preferred_name": "TP53", "ncbiTaxonId": "9606", "experimental_score": 0.0, "database_score": 0.0, "textmining_score": 0.529, "sign": "n/a", "combined_score": 0.529}, {"source_string_id": "9606.ENSP00000215832", "target_string_id": "9606.ENSP00000384849", "source_preferred_name": "MAPK1", "target_preferred_name": "CDKN1A", "ncbiTaxonId": "9606", "experimental_score": 0.489, "database_score": 0.0, "textmining_score": 0.204, "sign": "pos", "combined_score": 0.575}, {"source_string_id": "9606.ENSP00000215832", "target_string_id": "9606.ENSP00000269305", "source_preferred_name": "MAPK1", "target_preferred_name": "TP53", "ncbiTaxonId": "9606", "experimental_score": 0.781, "database_score": 0.8, "textmining_score": 0.267, "sign": "pos", "combined_score": 0.965}, {"source_string_id": "9606.ENSP00000258149", "target_string_id": "9606.ENSP00000384849", "source_preferred_name": "MDM2", "target_preferred_name": "CDKN1A", "ncbiTaxonId": "9606", "experimental_score": 0.68, "database_score": 0.0, "textmining_score": 0.549, "sign": "neg", "combined_score": 0.849}, {"source_string_id": "9606.ENSP00000258149", "target_string_id": "9606.ENSP00000269305", "source_preferred_name": "MDM2", "target_preferred_name": "TP53", "ncbiTaxonId": "9606", "experimental_score": 0.85, "database_score": 0.8, "textmining_score": 0.927, "sign": "n/a", "combined_score": 0.997}, {"source_string_id": "9606.ENSP00000269305", "target_string_id": "9606.ENSP00000215832", "source_preferred_name": "TP53", "target_preferred_name": "MAPK1", "ncbiTaxonId": "9606", "experimental_score": 0.0, "database_score": 0.0, "textmining_score": 0.122, "sign": "n/a", "combined_score": 0.122}, {"source_string_id": "9606.ENSP00000269305", "target_string_id": "9606.ENSP00000258149", "source_preferred_name": "TP53", "target_preferred_name": "MDM2", "ncbiTaxonId": "9606", "experimental_score": 0.85, "database_score": 0.8, "textmining_score": 0.885, "sign": "n/a", "combined_score": 0.996}, {"source_string_id": "9606.ENSP00000269305", "target_string_id": "9606.ENSP00000384849", "source_preferred_name": "TP53", "target_preferred_name": "CDKN1A", "ncbiTaxonId": "9606", "experimental_score": 0.823, "database_score": 0.8, "textmining_score": 0.89, "sign": "n/a", "combined_score": 0.995}] diff --git a/tests/testthat/_fixtures/string/version.json b/tests/testthat/_fixtures/string/version.json new file mode 100644 index 0000000..b9eb815 --- /dev/null +++ b/tests/testthat/_fixtures/string/version.json @@ -0,0 +1 @@ +[{"string_version": "12.5", "stable_address": "https://version-12-5.string-db.org"}] diff --git a/tests/testthat/helper-indra.R b/tests/testthat/helper-indra.R new file mode 100644 index 0000000..23a1bed --- /dev/null +++ b/tests/testthat/helper-indra.R @@ -0,0 +1,23 @@ +# INDRA mocks shared by the backend test files. CoGEx is never called: +# .callIndraCogexApi() returns the saved response in inst/extdata. + +.selected_input <- function() { + input <- data.table::fread( + system.file("extdata/groupComparisonModel.csv", package = "MSstatsBioNet") + ) + select_entities(.build_entities_from_annotated_input(input)) +} + +.mock_indra_response <- function(env = parent.frame()) { + local_mocked_bindings( + .callIndraCogexApi = function(ns, ids, fio, cogex_url) { + readRDS(system.file("extdata/indraResponse.rds", package = "MSstatsBioNet")) + }, + .get_current_time = function() .fixed_retrieval_time(), + .env = env + ) +} + +.fixed_retrieval_time <- function() { + as.POSIXct("2026-10-09 12:00:00", tz = "UTC") +} diff --git a/tests/testthat/test-backend-indra.R b/tests/testthat/test-backend-indra.R index 18ab690..3966d22 100644 --- a/tests/testthat/test-backend-indra.R +++ b/tests/testthat/test-backend-indra.R @@ -1,26 +1,5 @@ # ----- INDRA backend and get_network() (Phase 2 of the API refactor) ----- -.selected_input <- function() { - input <- data.table::fread( - system.file("extdata/groupComparisonModel.csv", package = "MSstatsBioNet") - ) - select_entities(.build_entities_from_annotated_input(input)) -} - -.mock_indra_response <- function(env = parent.frame()) { - local_mocked_bindings( - .callIndraCogexApi = function(ns, ids, fio, cogex_url) { - readRDS(system.file("extdata/indraResponse.rds", package = "MSstatsBioNet")) - }, - .get_current_time = function() .fixed_retrieval_time(), - .env = env - ) -} - -.fixed_retrieval_time <- function() { - as.POSIXct("2026-10-09 12:00:00", tz = "UTC") -} - test_that("indra_backend() defaults to the public CoGEx and Gilda URLs", { backend <- indra_backend() expect_s4_class(backend, "IndraBackend") @@ -74,7 +53,7 @@ test_that("get_network() passes the arguments on to the old filters", { network <- get_network(indra_backend(), input, evidence_sources = "signor") expect_gt(nrow(network$edges), 0) - expect_true(all(grepl('"signor"', network$edges$evidence_sources))) + expect_true(all(grepl("(^|;)signor(;|$)", network$edges$evidence_sources))) }) test_that("get_network() sends the backend's cogex_url", { @@ -570,8 +549,8 @@ test_that("backend_capabilities() lists INDRA's evidence sources", { test_that("evidence_sources = INDRA_DATABASE_SOURCES keeps edges with database evidence", { .mock_indra_response() input <- .selected_input() - has_any <- function(json, sources) { - any(names(jsonlite::fromJSON(json)) %in% sources) + has_any <- function(edge_sources, sources) { + any(strsplit(edge_sources, ";")[[1]] %in% sources) } curated <- suppressMessages(get_network( indra_backend(), input, evidence_sources = INDRA_DATABASE_SOURCES)) diff --git a/tests/testthat/test-backend-string.R b/tests/testthat/test-backend-string.R new file mode 100644 index 0000000..cb8128b --- /dev/null +++ b/tests/testthat/test-backend-string.R @@ -0,0 +1,656 @@ +# Tests of the STRING backend (string_backend(), its convert_ids() and +# get_network() methods). STRING is never called: .post_string_request() is +# mocked with the responses saved by _fixtures/make_string_fixtures.R. + +.read_string_fixture <- function(file) { + jsonlite::fromJSON(readLines(test_path("_fixtures", "string", file))) +} + +# Mocks STRING with the saved responses and records each request in the +# returned environment's `requests` (list of url and body). Waits are +# recorded in `waits` instead of slept. +.mock_string <- function(ids_response = .read_string_fixture( + "get_string_ids.json"), + env = parent.frame()) { + calls <- new.env() + calls$requests <- list() + calls$waits <- numeric(0) + local_mocked_bindings( + .post_string_request = function(url, body) { + calls$requests <- c(calls$requests, + list(list(url = url, body = body))) + if (grepl("/version$", url)) { + return(.read_string_fixture("version.json")) + } + if (grepl("/get_string_ids$", url)) { + return(ids_response) + } + .read_string_fixture(paste0("network_", body$network_type, + ".json")) + }, + .wait_for_string = function(seconds) { + calls$waits <- c(calls$waits, seconds) + }, + .get_current_time = function() .fixed_string_time(), + .env = env + ) + calls +} + +.fixed_string_time <- function() { + as.POSIXct("2026-10-09 12:00:00", tz = "UTC") +} + +.string_test_input <- function() { + data.frame(Protein = c("P04637", "P04637-2", "Q00987", "P38936", + "P28482", "P0DTC2"), + log2FC = c(1, 2, -1, 0.5, 3, 1), + adj.pvalue = c(0.01, 0.02, 0.03, 0.04, 0.01, 0.5), + stringsAsFactors = FALSE) +} + +.prepare_string_entities <- function(df = .string_test_input()) { + prepare_entities(df, entity_type = "protein", id_type = "uniprot") +} + +# Entity table grounded to STRING without a request +STRING_TEST_IDS <- c(P04637 = "9606.ENSP00000269305", + Q00987 = "9606.ENSP00000258149", + P38936 = "9606.ENSP00000384849", + P28482 = "9606.ENSP00000215832") +STRING_TEST_NAMES <- c(P04637 = "TP53", Q00987 = "MDM2", P38936 = "CDKN1A", + P28482 = "MAPK1") + +.grounded_string_entities <- function() { + entities <- .prepare_string_entities() + accession <- sub("-[0-9]+$", "", entities$id) + grounded <- accession %in% names(STRING_TEST_IDS) + entities$namespace[grounded] <- "STRING" + entities$entity_id[grounded] <- STRING_TEST_IDS[accession[grounded]] + entities$entity_name[grounded] <- STRING_TEST_NAMES[accession[grounded]] + select_entities(entities, pvalue_cutoff = 0.05) +} + +.request_urls <- function(calls) { + vapply(calls$requests, `[[`, "", "url") +} + +test_that("string_backend() defaults to physical, the current version", { + backend <- string_backend() + expect_s4_class(backend, "StringBackend") + expect_s4_class(backend, "NetworkBackend") + expect_equal(backend@network_type, "physical") + expect_true(is.na(backend@version)) + expect_equal(backend@caller_identity, "MSstatsBioNet") +}) + +test_that("string_backend() rejects invalid arguments", { + expect_error(string_backend("coexpression"), "should be one of") + expect_error(string_backend(version = "latest"), "version") + expect_error(string_backend(version = c("12.0", "12.5")), "version") + expect_error(string_backend(caller_identity = ""), "caller_identity") +}) + +test_that("backend_capabilities() depends on the network type", { + physical <- backend_capabilities(string_backend("physical")) + expect_equal(physical$query_types, "subnetwork") + expect_equal(physical$interaction_types, "Complex") + expect_equal(physical$id_conversions, + list(protein = "uniprot", ptm_site = "uniprot")) + expect_equal(physical$evidence_sources$database, + c("experiments", "database")) + expect_equal(physical$evidence_sources$text_mined, "textmining") + expect_true("coexpression" %in% physical$evidence_sources$predicted) + + regulatory <- backend_capabilities(string_backend("regulatory")) + expect_equal(regulatory$interaction_types, + c("Activation", "Inhibition", "Regulation")) + expect_length(regulatory$evidence_sources$predicted, 0) + expect_equal(backend_capabilities(string_backend("functional"))$ + interaction_types, "Association") +}) + +test_that("convert_ids() grounds accessions to STRING proteins", { + calls <- .mock_string() + expect_message( + entities <- convert_ids(string_backend(), .prepare_string_entities()), + "1 UniProt accession\\(s\\) not found in STRING: P0DTC2") + expect_equal(entities$namespace, + c(rep("STRING", 5), NA)) + expect_equal(entities$entity_id[1:5], + unname(STRING_TEST_IDS[c("P04637", "P04637", "Q00987", + "P38936", "P28482")])) + expect_equal(entities$entity_name[1:5], + c("TP53", "TP53", "MDM2", "CDKN1A", "MAPK1")) +}) + +test_that("convert_ids() sends unique accessions without isoform suffixes", { + calls <- .mock_string() + suppressMessages(convert_ids(string_backend(), .prepare_string_entities())) + first_ids_request <- calls$requests[[2]] + expect_match(first_ids_request$url, "/get_string_ids$") + expect_equal(strsplit(first_ids_request$body$identifiers, "\r")[[1]], + c("P04637", "Q00987", "P38936", "P28482", "P0DTC2")) + expect_equal(first_ids_request$body$species, "9606") + expect_equal(first_ids_request$body$limit, 1) + expect_equal(first_ids_request$body$caller_identity, "MSstatsBioNet") +}) + +test_that("convert_ids() resends accessions STRING collapsed into one row", { + # Two accessions of one protein: STRING answers only the first + df <- data.frame(Protein = c("P04637", "P04637-2", "Q00987"), + adj.pvalue = 0.01) + first <- data.frame(queryIndex = 0L, queryItem = "P04637", + stringId = "9606.ENSP00000269305", + ncbiTaxonId = 9606L, preferredName = "TP53") + second <- data.frame(queryIndex = 0L, queryItem = "Q00987", + stringId = "9606.ENSP00000258149", + ncbiTaxonId = 9606L, preferredName = "MDM2") + responses <- list(first, second) + sent <- list() + local_mocked_bindings( + .post_string_request = function(url, body) { + if (grepl("/version$", url)) { + return(.read_string_fixture("version.json")) + } + sent[[length(sent) + 1]] <<- body$identifiers + response <- responses[[1]] + responses <<- responses[-1] + response + }, + .wait_for_string = function(seconds) NULL + ) + entities <- convert_ids(string_backend(), .prepare_string_entities(df)) + expect_equal(sent, list("P04637\rQ00987", "Q00987")) + expect_equal(entities$entity_name, c("TP53", "TP53", "MDM2")) +}) + +test_that("convert_ids() drops rows STRING matched to another query", { + # A row whose queryItem differs from the accession sent at its + # queryIndex is not trusted + response <- data.frame(queryIndex = c(0L, 1L), + queryItem = c("P04637", "SOMETHING_ELSE"), + stringId = c("9606.ENSP00000269305", "9606.X"), + ncbiTaxonId = c(9606L, 9606L), + preferredName = c("TP53", "X")) + .mock_string(ids_response = response) + df <- data.frame(Protein = c("P04637", "Q00987"), adj.pvalue = 0.01) + expect_message( + entities <- convert_ids(string_backend(), + .prepare_string_entities(df)), + "not found in STRING: Q00987") + expect_equal(entities$entity_name, c("TP53", NA)) +}) + +test_that("convert_ids() grounds each member of a protein group", { + .mock_string() + df <- data.frame(Protein = c("P04637;Q00987", "P38936"), + adj.pvalue = 0.01) + entities <- convert_ids(string_backend(), .prepare_string_entities(df)) + expect_equal(entities$namespace[1], "STRING;STRING") + expect_equal(entities$entity_name[1], "TP53;MDM2") +}) + +test_that("convert_ids() rejects non-accessions before any request", { + calls <- .mock_string() + df <- data.frame(Protein = c("P04637", "TP53_HUMAN", "TP53"), + adj.pvalue = 0.01) + expect_error(convert_ids(string_backend(), .prepare_string_entities(df)), + "Not accessions: TP53_HUMAN, TP53") + expect_length(calls$requests, 0) + + entities <- prepare_entities(data.frame(Protein = "TP53"), + entity_type = "protein", + id_type = "hgnc_symbol") + expect_error(convert_ids(string_backend(), entities), + "StringBackend can't convert entity_type / id_type: protein / hgnc_symbol") + expect_length(calls$requests, 0) +}) + +test_that("convert_ids() keeps INDRA's groundings and replaces STRING's", { + .mock_string() + entities <- .prepare_string_entities() + entities$namespace[1] <- "HGNC" + entities$entity_id[1] <- "11998" + entities$entity_name[1] <- "TP53" + entities$namespace[3] <- "HGNC;STRING" + entities$entity_id[3] <- "6973;9606.OLD" + entities$entity_name[3] <- "MDM2;OLD" + entities <- suppressMessages(convert_ids(string_backend(), entities)) + expect_equal(entities$namespace[1], "HGNC;STRING") + expect_equal(entities$entity_id[1], "11998;9606.ENSP00000269305") + expect_equal(entities$entity_name[1], "TP53;TP53") + expect_equal(entities$entity_id[3], "6973;9606.ENSP00000258149") + # An unmapped row keeps nothing of STRING + expect_true(is.na(entities$namespace[6])) +}) + +test_that("INDRA's convert_ids() keeps STRING's groundings", { + local_mocked_bindings( + .callGetHgncIdsFromUniprotIdsApi = function(uniprotIds, cogex_url) { + list(P04637 = "11998") + }, + .callGetHgncNamesFromHgncIdsApi = function(hgncIds, cogex_url) { + list(`11998` = "TP53") + } + ) + entities <- .grounded_string_entities() + entities <- convert_ids(indra_backend(), entities) + expect_equal(entities$namespace[1], "STRING;HGNC") + expect_equal(entities$entity_id[1], "9606.ENSP00000269305;11998") + # Q00987 doesn't map to HGNC here: its STRING grounding stays + expect_equal(entities$namespace[3], "STRING") + expect_true(is.na(entities$namespace[6])) +}) + +test_that("INDRA reads only its own groundings of a shared entity table", { + .mock_indra_response() + indra_only <- .selected_input() + shared <- indra_only + shared$namespace <- ifelse(is.na(shared$namespace), "STRING", + paste0(shared$namespace, ";STRING")) + shared$entity_id <- ifelse(is.na(shared$entity_id), "9606.X", + paste0(shared$entity_id, ";9606.X")) + shared$entity_name <- ifelse(is.na(shared$entity_name), "X", + paste0(shared$entity_name, ";X")) + network <- suppressMessages(get_network(indra_backend(), shared)) + expected <- suppressMessages(get_network(indra_backend(), indra_only)) + expect_identical(network, expected) + expect_false(any(grepl("STRING", network$nodes$namespace))) +}) + +test_that("INDRA's get_entity_properties() ignores STRING groundings", { + local_mocked_bindings( + .callIsKinaseApi = function(genes, cogex_url) list(MAPK1 = TRUE) + ) + entities <- .grounded_string_entities() + entities$namespace[5] <- "HGNC;STRING" + entities$entity_id[5] <- "6871;9606.ENSP00000215832" + entities$entity_name[5] <- "MAPK1;MAPK1" + entities <- get_entity_properties(indra_backend(), entities, + properties = "is_kinase") + expect_equal(entities$is_kinase, c(NA, NA, NA, NA, TRUE, NA)) +}) + +test_that("get_network() maps physical interactions to the contract", { + .mock_string() + expect_message( + network <- get_network(string_backend(version = "12.5"), + .grounded_string_entities()), + "STRING physical subnetwork: how are 5 selected proteins") + edges <- network$edges + expect_true(all(edges$interaction == "Complex")) + expect_true(all(!edges$directed)) + expect_true(all(is.na(edges$site))) + expect_true(all(is.na(edges$evidence_count))) + expect_true(all(is.na(edges$sign))) + expect_true(all(edges$interaction_raw == "physical")) + expect_true(all(edges$backend_database == "STRING")) + mdm2_tp53 <- edges[edges$source == "Q00987" & edges$target == "P04637", ] + expect_equal(mdm2_tp53$confidence, 0.999) + expect_equal(mdm2_tp53$evidence_sources, + "database;experiments;textmining") + expect_equal(mdm2_tp53$statement_id, + "string:physical:9606.ENSP00000258149|9606.ENSP00000269305") + expect_equal(mdm2_tp53$evidence_url, paste0( + "https://version-12-5.string-db.org/cgi/network?identifiers=", + "9606.ENSP00000258149%0d9606.ENSP00000269305&species=9606")) + expect_no_error(validate_network(network)) +}) + +test_that("get_network() gives isoforms sharing a STRING protein each edge", { + .mock_string() + network <- get_network(string_backend(version = "12.5"), + .grounded_string_entities()) + edges <- network$edges + to_mdm2 <- edges[edges$source == "Q00987" & + edges$target %in% c("P04637", "P04637-2"), ] + expect_equal(sort(to_mdm2$target), c("P04637", "P04637-2")) + expect_equal(length(unique(to_mdm2$statement_id)), 1) + tp53_nodes <- network$nodes[network$nodes$entity_name == "TP53", ] + expect_equal(tp53_nodes$logFC, c(1, 2)) +}) + +test_that("get_network() maps regulatory signs to interaction types", { + .mock_string() + network <- get_network(string_backend("regulatory", version = "12.5"), + .grounded_string_entities()) + edges <- network$edges + expect_true(all(edges$directed)) + pick <- function(source, target) { + edges[edges$source == source & edges$target == target, ] + } + expect_equal(pick("P28482", "P04637")$interaction, "Activation") + expect_equal(pick("P28482", "P04637")$sign, 1L) + expect_equal(pick("P28482", "P04637")$interaction_raw, "regulatory:pos") + expect_equal(pick("Q00987", "P38936")$interaction, "Inhibition") + expect_equal(pick("Q00987", "P38936")$sign, -1L) + expect_equal(pick("Q00987", "P04637")$interaction, "Regulation") + expect_true(is.na(pick("Q00987", "P04637")$sign)) + # Both directions of a pair are separate statements + expect_equal(nrow(pick("P04637", "Q00987")), 1) + expect_false(pick("P04637", "Q00987")$statement_id == + pick("Q00987", "P04637")$statement_id) + expect_equal(pick("Q00987", "P04637")$evidence_sources, + "database;experiments;textmining") +}) + +test_that("get_network() keeps an undirected pair listed in both orders once", { + response <- .read_string_fixture("network_physical.json") + reversed <- response[1, ] + reversed[, c("stringId_A", "stringId_B")] <- + reversed[, c("stringId_B", "stringId_A")] + reversed[, c("preferredName_A", "preferredName_B")] <- + reversed[, c("preferredName_B", "preferredName_A")] + local_mocked_bindings( + .post_string_request = function(url, body) rbind(response, reversed) + ) + network <- get_network(string_backend(version = "12.5"), + .grounded_string_entities()) + expected <- suppressMessages({ + .mock_string() + get_network(string_backend(version = "12.5"), + .grounded_string_entities()) + }) + expect_equal(nrow(network$edges), nrow(expected$edges)) +}) + +test_that("get_network() stops when STRING returns no edges", { + for (network_type in STRING_NETWORK_TYPES) { + expect_equal(nrow(.parse_string_network(data.frame(), network_type)), + 0) + } + local_mocked_bindings(.post_string_request = function(url, body) list()) + expect_error(get_network(string_backend("regulatory", version = "12.5"), + .grounded_string_entities()), + "No edges remain") +}) + +test_that("get_network() maps functional interactions to Association", { + .mock_string() + network <- get_network(string_backend("functional", version = "12.5"), + .grounded_string_entities()) + expect_true(all(network$edges$interaction == "Association")) + expect_true(any(grepl("coexpression", network$edges$evidence_sources))) +}) + +test_that("get_network() sends min_confidence as required_score", { + calls <- .mock_string() + backend <- string_backend(version = "12.5") + entities <- .grounded_string_entities() + get_network(backend, entities) + expect_equal(calls$requests[[1]]$body$required_score, 0L) + network <- get_network(string_backend("regulatory", version = "12.5"), + entities, min_confidence = 0.9) + expect_equal(calls$requests[[2]]$body$required_score, 900L) + # Also applied after parsing (the fixture has lower scores) + expect_true(all(network$edges$confidence >= 0.9)) +}) + +test_that("get_network() sends the STRING proteins of the selected rows", { + calls <- .mock_string() + entities <- .grounded_string_entities() + entities$included_in_query[entities$id == "P38936"] <- FALSE + get_network(string_backend(version = "12.5"), entities) + body <- calls$requests[[1]]$body + expect_equal(strsplit(body$identifiers, "\r")[[1]], + unname(STRING_TEST_IDS[c("P04637", "Q00987", "P28482")])) + expect_equal(body$species, "9606") + expect_equal(body$network_type, "physical") +}) + +test_that("get_network() filters by evidence channel and interaction type", { + .mock_string() + backend <- string_backend("regulatory", version = "12.5") + entities <- .grounded_string_entities() + network <- get_network(backend, entities, evidence_sources = "database") + expect_true(all(grepl("(^|;)database(;|$)", network$edges$evidence_sources))) + expect_false(any(network$edges$source == "P38936")) + + network <- get_network(backend, entities, + interaction_types = "Inhibition") + expect_equal(unique(network$edges$interaction), "Inhibition") + + expect_error(get_network(backend, entities, + evidence_sources = "coexpression"), + "must be among: experiments, database, textmining") +}) + +test_that("get_network() keeps NA evidence counts unless min_evidence > 1", { + .mock_string() + backend <- string_backend(version = "12.5") + entities <- .grounded_string_entities() + expect_gt(nrow(get_network(backend, entities, min_evidence = 1)$edges), 0) + expect_message( + expect_error(get_network(backend, entities, min_evidence = 2), + "No edges remain"), + "Dropping 7 edge\\(s\\) with no evidence count") +}) + +test_that("get_network() adds STRING proteins from include_entities", { + .mock_string() + entities <- .grounded_string_entities() + # CDKN1A becomes an entity outside the table + entities <- entities[entities$id != "P38936", ] + network <- get_network(string_backend(version = "12.5"), entities, + include_entities = "STRING:9606.ENSP00000384849") + latent <- network$nodes[network$nodes$id == "CDKN1A", ] + expect_equal(nrow(latent), 1) + expect_false(latent$measured) + expect_equal(latent$entity_type, "protein") + expect_equal(latent$namespace, "STRING") + expect_equal(latent$node_role, "user_added") + + expect_error(get_network(string_backend(version = "12.5"), entities, + include_entities = "HGNC:1234"), + "STRING groundings") +}) + +test_that("get_network() checks its input before any request", { + calls <- .mock_string() + backend <- string_backend(version = "12.5") + expect_error(get_network(backend, + select_entities(.prepare_string_entities())), + "No selected entity has a STRING grounding") + entities <- .grounded_string_entities() + entities$organism[1] <- "10090" + expect_error(get_network(backend, entities), "one organism") + expect_error(get_network(backend, .grounded_string_entities(), + min_confidence = 2), "min_confidence") + expect_length(calls$requests, 0) +}) + +test_that("get_network() records the STRING version in provenance", { + .mock_string() + network <- get_network(string_backend(), .grounded_string_entities()) + provenance <- network$provenance + expect_equal(provenance$backend_database, "STRING") + expect_equal(provenance$backend_version, "12.5") + expect_equal(provenance$backend_url, "https://version-12-5.string-db.org") + expect_equal(provenance$organism, "9606") + expect_equal(provenance$retrieved_at, .fixed_string_time()) + expect_match(provenance$parameters, '"network_type":"physical"') +}) + +test_that("a backend resolves the current version once and keeps its host", { + calls <- .mock_string() + backend <- string_backend() + entities <- suppressMessages(convert_ids(backend, + .prepare_string_entities())) + entities <- select_entities(entities, pvalue_cutoff = 0.05) + suppressMessages(get_network(backend, entities)) + urls <- .request_urls(calls) + expect_equal(sum(grepl("/version$", urls)), 1) + expect_equal(urls[1], "https://string-db.org/api/json/version") + expect_true(all(startsWith(urls[-1], + "https://version-12-5.string-db.org/api/json/"))) +}) + +test_that("a pinned version needs no version request", { + calls <- .mock_string() + suppressMessages(get_network(string_backend(version = "12.0"), + .grounded_string_entities())) + expect_equal(.request_urls(calls), + "https://version-12-0.string-db.org/api/json/network") +}) + +test_that("STRING requests are at least one second apart", { + clock <- as.POSIXct("2026-10-09 12:00:00", tz = "UTC") + waits <- numeric(0) + local_mocked_bindings( + .post_string_request = function(url, body) list(), + .get_string_clock = function() clock, + .wait_for_string = function(seconds) waits <<- c(waits, seconds) + ) + .string_request_times$last <- NULL + .send_string_request("https://example.org/a", list()) + expect_length(waits, 0) + clock <- clock + 0.25 + .send_string_request("https://example.org/b", list()) + expect_equal(waits, 0.75) + clock <- clock + 5 + .send_string_request("https://example.org/c", list()) + expect_equal(waits, 0.75) +}) + +test_that("STRING has no evidence text or curations", { + .mock_string() + network <- get_network(string_backend(version = "12.5"), + .grounded_string_entities()) + expect_error(get_evidence(string_backend(), network$edges), + "StringBackend does not support get_evidence") + expect_error(get_curations(string_backend(), network$edges), + "StringBackend does not support get_curations") + expect_error(get_entity_properties(string_backend(), + .grounded_string_entities()), + "StringBackend does not support get_entity_properties") + # filter_by_curation() keeps edges with no evidence count, and asks no + # backend about them + expect_identical(filter_by_curation(network), network) +}) + +test_that("the STRING backend meets the shared backend contract", { + .mock_string() + for (network_type in STRING_NETWORK_TYPES) { + expect_backend_contract(string_backend(network_type, + version = "12.5"), + .grounded_string_entities()) + } +}) + +# An INDRA statement TP53 Complex MDM2, built from the first statement of +# the saved CoGEx response +.indra_tp53_mdm2_statement <- function() { + statement <- readRDS(system.file("extdata/indraResponse.rds", + package = "MSstatsBioNet"))[[1]] + statement$source_ns <- "HGNC" + statement$source_id <- "11998" + statement$source_name <- "TP53" + statement$target_ns <- "HGNC" + statement$target_id <- "6973" + statement$target_name <- "MDM2" + statement +} + +test_that("INDRA and STRING networks of one entity table share node ids", { + .mock_string() + local_mocked_bindings( + .callIndraCogexApi = function(ns, ids, fio, cogex_url) { + list(.indra_tp53_mdm2_statement()) + } + ) + entities <- .grounded_string_entities() + hgnc <- c(P04637 = "11998", `P04637-2` = "11998", Q00987 = "6973", + P38936 = "1784", P28482 = "6871") + rows <- match(names(hgnc), entities$id) + entities$namespace[rows] <- paste0("HGNC;", entities$namespace[rows]) + entities$entity_id[rows] <- paste0(hgnc, ";", entities$entity_id[rows]) + entities$entity_name[rows] <- paste0(entities$entity_name[rows], ";", + entities$entity_name[rows]) + + indra <- suppressMessages(get_network(indra_backend(), entities)) + string <- suppressMessages(get_network(string_backend(version = "12.5"), + entities)) + expect_setequal(c(indra$edges$source, indra$edges$target), + c("P04637", "P04637-2", "Q00987")) + expect_true(all(c(indra$edges$source, indra$edges$target) %in% + string$nodes$id)) + expect_equal(unique(indra$nodes$namespace), "HGNC") + expect_equal(unique(string$nodes$namespace), "STRING") + + merged <- suppressMessages(merge_networks(indra, string, + entities = entities)) + expect_no_error(validate_network(merged)) + expect_setequal(merged$edges$backend_database, c("INDRA", "STRING")) + expect_equal(nrow(merged$edges), + nrow(indra$edges) + nrow(string$edges)) + expect_equal(anyDuplicated(merged$nodes$id), 0) + expect_equal(merged$provenance$backend_database, c("INDRA", "STRING")) +}) + +test_that("filter_by_curation() on a merged network asks only INDRA", { + .mock_string() + asked <- character(0) + local_mocked_bindings( + .callIndraCogexApi = function(ns, ids, fio, cogex_url) { + list(.indra_tp53_mdm2_statement()) + }, + .get_incorrect_curation_count = function(statement_id, curation_url) { + asked <<- c(asked, statement_id) + 1L + } + ) + entities <- .grounded_string_entities() + entities$namespace[1] <- "STRING;HGNC" + entities$entity_id[1] <- "9606.ENSP00000269305;11998" + entities$entity_name[1] <- "TP53;TP53" + entities$namespace[3] <- "STRING;HGNC" + entities$entity_id[3] <- "9606.ENSP00000258149;6973" + entities$entity_name[3] <- "MDM2;MDM2" + indra <- suppressMessages(get_network(indra_backend(), entities)) + string <- suppressMessages(get_network(string_backend(version = "12.5"), + entities)) + merged <- suppressMessages(merge_networks(indra, string)) + filtered <- suppressMessages(filter_by_curation(merged)) + expect_equal(unique(asked), unique(indra$edges$statement_id)) + # The INDRA edge had 1 evidence, curated as incorrect + expect_equal(unique(filtered$edges$backend_database), "STRING") + expect_equal(nrow(filtered$edges), nrow(string$edges)) +}) + +test_that(".filter_by_min_evidence() keeps NA counts only at 1 or below", { + edges <- data.frame(evidence_count = c(NA, 1L, 3L)) + expect_equal(.filter_by_min_evidence(edges, 1)$evidence_count, + c(NA, 1L, 3L)) + expect_equal(.filter_by_min_evidence(edges, 0)$evidence_count, + c(NA, 1L, 3L)) + expect_message(kept <- .filter_by_min_evidence(edges, 2), + "Dropping 1 edge\\(s\\) with no evidence count") + expect_equal(kept$evidence_count, 3L) + expect_silent(.filter_by_min_evidence(edges[2:3, , drop = FALSE], 2)) +}) + +test_that(".replace_groundings() and .keep_groundings() round-trip", { + entities <- .prepare_string_entities()[1:3, ] + entities$namespace <- c("HGNC;STRING", "STRING", NA) + entities$entity_id <- c("11998;9606.A", "9606.B", NA) + entities$entity_name <- c("NA;TP53", "TP53", NA) + indra_only <- .keep_groundings(entities, .is_indra_namespace) + expect_equal(indra_only$namespace, c("HGNC", NA, NA)) + expect_true(is.na(indra_only$entity_name[1])) + string_only <- .keep_groundings(entities, .is_string_namespace) + expect_equal(string_only$entity_id, c("9606.A", "9606.B", NA)) + # Unchanged when every grounding is kept + expect_identical(.keep_groundings(indra_only, .is_indra_namespace), + indra_only) + + replaced <- .replace_groundings( + entities, 1:3, + data.frame(namespace = c("STRING", NA, "STRING"), + entity_id = c("9606.C", NA, "9606.D"), + entity_name = c("C", NA, "D")), + .is_string_namespace) + expect_equal(replaced$namespace, c("HGNC;STRING", NA, "STRING")) + expect_equal(replaced$entity_id, c("11998;9606.C", NA, "9606.D")) + expect_equal(replaced$entity_name, c("NA;C", NA, "D")) +}) diff --git a/tests/testthat/test-contract.R b/tests/testthat/test-contract.R index d4d2eda..9ffaa87 100644 --- a/tests/testthat/test-contract.R +++ b/tests/testthat/test-contract.R @@ -131,27 +131,27 @@ test_that("validate_network checks confidence and evidence_count ranges", { expect_error(validate_network(network), "evidence_count must be at least 1") }) -test_that("validate_network rejects NA or infinite evidence_count", { +test_that("validate_network accepts NA evidence_count and rejects infinite", { + # NA: the backend has no evidence count, e.g. STRING network <- .valid_network() - network$edges$evidence_count <- c(12, NA) - expect_error(validate_network(network), - "evidence_count must not be NA or infinite") + network$edges$evidence_count <- c(12L, NA) + expect_no_error(validate_network(network)) + + # An all-NA logical column passes the type check too + network$edges$evidence_count <- NA + expect_no_error(validate_network(network)) network$edges$evidence_count <- c(12, Inf) expect_error(validate_network(network), - "evidence_count must not be NA or infinite") + "evidence_count must not be infinite") - # An all-NA logical column passes the type check, but not the NA check - network$edges$evidence_count <- NA - expect_error(validate_network(network), - "evidence_count must not be NA or infinite") + # 0 still fails when other edges are NA + network$edges$evidence_count <- c(0L, NA) + expect_error(validate_network(network), "evidence_count must be at least 1") - # A character column gets both the type error and the NA error network$edges$evidence_count <- c("12", NA) - err <- tryCatch(validate_network(network), - error = function(e) conditionMessage(e)) - expect_match(err, "edges\\$evidence_count must be integer") - expect_match(err, "evidence_count must not be NA or infinite") + expect_error(validate_network(network), + "edges\\$evidence_count must be integer") # A list column is reported as a type problem, not an R error network$edges$evidence_count <- list(12L, 1L) @@ -159,6 +159,23 @@ test_that("validate_network rejects NA or infinite evidence_count", { "edges\\$evidence_count must be integer") }) +test_that("validate_network checks evidence_sources are joined source names", { + network <- .valid_network() + network$edges$evidence_sources <- c("psp;reach", NA) + expect_no_error(validate_network(network)) + network$edges$evidence_sources <- NA + expect_no_error(validate_network(network)) + + network$edges$evidence_sources <- c('{"reach": 12}', "reach") + expect_no_error(validate_network(network)) # one name, odd but allowed + network$edges$evidence_sources <- c("psp;;reach", ";reach") + expect_error(validate_network(network), + "evidence_sources must be source names joined by ';'") + network$edges$evidence_sources <- c(1, 2) + expect_error(validate_network(network), + "evidence_sources must be character") +}) + test_that("validate_network requires directed == FALSE for symmetric types", { network <- .valid_network() network$edges$directed[2] <- TRUE # the Complex edge