refactor: Make generic backend exported from MSstatsBioNet

NAMESPACE

@@ -2,8 +2,10 @@
 
 S3method(print,topicHierarchy)
 export(annotateProteinInfoFromIndra)
+export(backend_capabilities)
 export(bootstrapTopicModels)
 export(compareTopicModels)
+export(convert_ids)
 export(cytoscapeNetwork)
 export(cytoscapeNetworkOutput)
 export(decomposeSubnetworkByTopic)
@@ -12,9 +14,23 @@ export(deleteEdgeFromNetwork)
 export(exportNetworkToHTML)
 export(filterSubnetworkByContext)
 export(getSubnetworkFromIndra)
+export(get_entity_properties)
+export(get_network)
+export(indra_backend)
+export(prepare_entities)
 export(previewNetworkInBrowser)
 export(renderCytoscapeNetwork)
+export(select_entities)
+export(subnetwork_query)
 export(validate_network)
+exportClasses(IndraBackend)
+exportClasses(NetworkBackend)
+exportClasses(NetworkQuery)
+exportClasses(SubnetworkQuery)
+exportMethods(backend_capabilities)
+exportMethods(convert_ids)
+exportMethods(get_entity_properties)
+exportMethods(get_network)
 importFrom(grDevices,
   colorRamp,
   rgb

NEWS.md

@@ -2,6 +2,35 @@
 
 ## New features
 
+* A new API for building networks from MSstats results, which separates
+the steps that `annotateProteinInfoFromIndra()` and
+`getSubnetworkFromIndra()` combine, and works for proteins, PTM sites, and
+metabolites:
+    * `prepare_entities()` builds an entity table with one row per analyte,
+    its entity type (`"protein"`, `"ptm_site"`, `"metabolite"`, ...),
+    identifier system, organism, and statistics. It copies `log2FC`,
+    `log10FC`, or `logFC` to `logFC`, parses PTM sites, and stops when the
+    input has several comparisons in `Label` unless `label` names one.
+    * `indra_backend()` creates the INDRA backend, and
+    `backend_capabilities()` lists what a backend supports.
+    * `convert_ids()` grounds the entity table (CoGEx for UniProt IDs and
+    mnemonics, Gilda for gene symbols and chemical names), and
+    `get_entity_properties()` adds `is_transcription_factor`, `is_kinase`,
+    and `is_phosphatase`.
+    * `select_entities()` flags the rows that pass the cutoffs, and drops
+    none, so that nodes in the input are recognized even when they fail
+    the cutoffs.
+    * `get_network(backend, entities, query = subnetwork_query())` queries
+    the backend and returns `nodes` and `edges` that meet the contract. It
+    takes `interaction_types`, `min_evidence`, `min_confidence` (new: drops
+    edges below it, and edges with no score), `evidence_sources`, and
+    `include_entities`. It prints the question it asks as a message, e.g.
+    "INDRA subnetwork: how are 42 selected proteins connected to each
+    other, with no other nodes added?".
+    * `?network_queries` describes the questions a query can ask, with a
+    glossary. `subnetwork_query()` is the first; more are planned.
+    * The S4 classes `NetworkBackend`, `IndraBackend`, `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
@@ -92,29 +121,18 @@ release and be removed in the one after.
 
 * `getSubnetworkFromIndra()` now runs through an internal INDRA backend
 object and the S4 generic `get_network()`, the first step toward supporting
-network databases other than INDRA. Its output is unchanged. The new
-functions are not exported yet.
+network databases other than INDRA.
 * The error for a non-character `sources_filter` in
 `getSubnetworkFromIndra()` now reads "evidence_sources must be a character
 vector", the name of the argument in the new API.
-* Added internal functions for the entity table that the new API takes as
-input: `prepare_entities()` (one row per analyte, with its entity type,
-identifier system, and organism; copies `log2FC`, `log10FC`, or `logFC` to
-`logFC`; stops when the input has several comparisons in `Label` and
-`label` doesn't name one), `parse_ptm_sites()`, `build_grounding_table()`, and
-`select_entities()` (flags rows that pass the cutoffs and drops none).
-Nothing calls them yet.
-* `annotateProteinInfoFromIndra()` now runs through two internal generics
-of the new API: `convert_ids()`, which grounds an entity table through the
-INDRA backend (CoGEx for UniProt IDs and mnemonics, Gilda for gene symbols
-and chemical names), and `get_entity_properties()`, which adds the
-`is_transcription_factor`, `is_kinase`, and `is_phosphatase` columns. Its
-output is unchanged. The INDRA backend now also holds the Gilda URL, and
+* `annotateProteinInfoFromIndra()` now runs through `convert_ids()` and
+`get_entity_properties()`. Its output is unchanged. The INDRA backend now also holds the Gilda URL, and
 the organism of the entity table is passed to Gilda in place of a
 hard-coded human taxon ID.
 * `getSubnetworkFromIndra()` builds an entity table from `input`, flags
 the rows to query with `select_entities()`, and passes all rows to
 `get_network()`, which matches the nodes INDRA returns against every row.
+Like `get_network()`, it now prints the question it asks as a message.
 
 # MSstatsBioNet 0.99.0
 

R/AllClasses.R

@@ -1,23 +1,27 @@
 #' Network backend classes
 #'
-#' A backend is a source of prior-knowledge networks. \code{get_network()}
-#' dispatches on the backend and the query, so each (backend, query) pair has
-#' its own method.
+#' A backend is a source of prior-knowledge networks, such as INDRA.
+#' \code{\link{get_network}()} dispatches on the backend and the query, so
+#' each (backend, query) pair has its own method. \code{NetworkBackend} is
+#' virtual: create a backend with a constructor such as
+#' \code{\link{indra_backend}()}. Other packages can add a backend by
+#' extending \code{NetworkBackend} and writing methods for the generics.
 #'
-#' Internal until the entity model is added (Phase 3 of the API refactor).
-#' @importFrom methods setClass setValidity
-#' @keywords internal
-#' @noRd
-setClass("NetworkBackend", representation("VIRTUAL"))
-
-#' INDRA backend
+#' \code{IndraBackend} queries INDRA CoGEx for networks and grounds names
+#' with Gilda, INDRA's grounding service.
 #'
-#' Queries INDRA CoGEx, and grounds names with Gilda. The Network Search URL
-#' is added with its first query (Phase 7 of the API refactor).
 #' @slot cogex_url base URL of INDRA CoGEx
 #' @slot grounding_url base URL of Gilda
-#' @keywords internal
-#' @noRd
+#'
+#' @seealso \code{\link{indra_backend}()}, \code{\link{backend_capabilities}()}
+#' @name NetworkBackend-class
+#' @aliases NetworkBackend-class IndraBackend-class
+#' @importFrom methods setClass setValidity
+#' @exportClass NetworkBackend IndraBackend
+NULL
+
+setClass("NetworkBackend", representation("VIRTUAL"))
+
 setClass("IndraBackend", contains = "NetworkBackend",
          representation(cogex_url = "character",
                         grounding_url = "character"))
@@ -34,12 +38,17 @@ setValidity("IndraBackend", function(object) {
 
 #' Network query classes
 #'
-#' A query says which question \code{get_network()} asks of the backend.
-#' @keywords internal
-#' @noRd
+#' A query says which question \code{\link{get_network}()} asks of the
+#' backend. \code{NetworkQuery} is virtual: create a query with a
+#' constructor such as \code{\link{subnetwork_query}()}. See
+#' \code{\link{network_queries}} for the questions each query answers.
+#'
+#' @seealso \code{\link{network_queries}}
+#' @name NetworkQuery-class
+#' @aliases NetworkQuery-class SubnetworkQuery-class
+#' @exportClass NetworkQuery SubnetworkQuery
+NULL
+
 setClass("NetworkQuery", representation("VIRTUAL"))
 
-#' Subnetwork query: the edges among the selected entities, adding no nodes
-#' @keywords internal
-#' @noRd
 setClass("SubnetworkQuery", contains = "NetworkQuery")