Networks are a powerful and flexible methodology for expressing biological knowledge for computation and communication. Albeit its benefits, the sharing of networks, the collaboration on network curation, keeping track of changes between different network versions, and detecting different versions itself, still is a major problem in network biology.
The Network Data Exchange, or NDEx, is an open-source software framework to manipulate, store and exchange networks of various types and formats (Pratt et al., 2015, Cell Systems 1, 302-305, October 28, 2015 ©2015 Elsevier Inc. ScienceDirect). NDEx can be used to upload, share and publicly distribute networks, while providing an output in formats, that can be used by plenty of other applications.
The public NDEx server is a network data commons which provides pathway collections like the Pathway Interaction Database of the NCI (http://www.ndexbio.org/#/user/301a91c6-a37b-11e4-bda0-000c29202374) and the Cancer Cell Maps Initiative (http://www.ndexbio.org/#/user/b47268a6-8112-11e6-b0a6-06603eb7f303).
This package provides an interface to query the public NDEx server, as well as private installations, in order to upload, download or modify biological networks.
This document aims to help the user to install and benefit from the wide range of funtionality of this implementation. The package also provides classes to implement the Cytoscape Cyberinfrastructure (CX) Format and to extend the [iGraph Package] (http://igraph.org/r/).
The package is compatible with both NDEx versions 1.3 and 2.0.
Installation instructions (from Bioconductor)
if (!requireNamespace("BiocManager", quietly=TRUE))
install.packages("BiocManager")
BiocManager::install("ndexr")
library(ndexr)Installation via GitHub using devtools R package
require(devtools)
install_github("frankkramer-lab/ndexr")
library(ndexr)Some short overview of the most important functions
## load the library!
library(ndexr)## login to the NDEx server
ndexcon = ndex_connect("username", "password")## search the networks for "EGFR"
networks <- ndex_find_networks(ndexcon, "EGFR")
## UUID of the first search result
networkId <- networks[1,'externalId']
## get summary of the network
networkSummary <- ndex_network_get_summary(ndexcon, networkId)
## get the entire network as RCX object
rcx <- ndex_get_network(ndexcon, networkId)
## remove NDEx artefacts from network
rcx <- rcx_asNewNetwork(rcx)
## do some fancy stuff with the network, then
## update the meta-data
rcx <- rcx_updateMetaData(rcx)## upload network as a new network to the NDEx server
networkId <- ndex_create_network(ndexcon, rcx)
## do some other fancy stuff with the network, then
## update the network on the server
networkId <- ndex_update_network(ndexcon, rcx)
## realize, you did bad things to the poor network, so better
## delete it on the server
ndex_delete_network(ndexcon, networkId)First, establish an connection to the NDEx server. This object is required for most of the other ndexr functions, because it stores options and authentication details. It is possible to connect to the server anonymously or provide a username and password to enable further functionality. If you have set up your own NDEx server, you might change the host to your local installation.
## load the library
library(ndexr)
## connect anonymously
ndexcon = ndex_connect()
## log in with user name and password
ndexconUser = ndex_connect(username="username", password="password")
## specify the server
ndexconLocal = ndex_connect(username="username",
password="password",
host="localhost:8888/ndex/rest")
## manually change the api and connection configuration
ndexcon13 = ndex_connect(ndexConf=ndex_config$Version_1.3)This package is developed following the structure of the documented api structure. For complete description of the NDEx server api see http://www.home.ndexbio.org/using-the-ndex-server-api/. The R functions are named by the category, context and function they fullfil. In the following, the usage is described in detail, and hopefully gives a better understanding of logic behind the naming convention of this package.
To explore or search the networks on an NDEx server, this package offers a function to retrieve a list of networks from the server. It is possible to restrict the networks to a specific search string (e.g. “EGFR”), an account name (only networks of this account will be shown), or limit the number of fetched networks.
## list networks on server
networks <- ndex_find_networks(ndexcon)
## same as previous
networks <- ndex_find_networks(ndexcon, start=0, size=5)
## search for "EGFR"
networksEgfr <- ndex_find_networks(ndexcon, searchString="EGFR")
## same as previous
networksEgfr <- ndex_find_networks(ndexcon, "EGFR")
## same as previous
networksOfUser <- ndex_find_networks(ndexcon, accountName="ndextutorials")As result you get a data.frame containing information of the networks.
names(networks) ## [1] "ownerUUID" "isReadOnly" "subnetworkIds"
## [4] "isValid" "warnings" "isShowcase"
## [7] "isCertified" "indexLevel" "hasLayout"
## [10] "hasSample" "visibility" "nodeCount"
## [13] "completed" "edgeCount" "owner"
## [16] "version" "description" "name"
## [19] "properties" "externalId" "isDeleted"
## [22] "modificationTime" "creationTime"networks[,c('name','externalId')]## name
## 1 rasmachine
## 2 The Diabetes Machine
## 3 The RAS Machine
## 4 NCI PID - Complete Interactions
## 5 batch1-145.9cancer.system-diagram.v5.2
## externalId
## 1 85276abf-379f-11e7-8f50-0ac135e8bacf
## 2 7aed4dd0-14e4-11e6-a1f8-06603eb7f303
## 3 50e3dff7-133e-11e6-a039-06603eb7f303
## 4 640e2cef-795d-11e8-a4bf-0ac135e8bacf
## 5 c220c99d-041a-11e9-bb6a-0ac135e8bacfTo both, users and networks stored on an NDEx server, a universally
unique identifier (UUID) is assigned. Although both have the same format
(i.e. “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”, where x is one of
[a-z0-9]), it has to be distinguished between the user UUID and the
network UUID, but the difference is obvious by the context. Within RCX
objects and search results, the network UUID is also referred to as
“externalId” (see previous section). This UUID can be
used to access a network on the server and retrieve just a summary of
the network (similar to the results of a network search) or even the
entire network as RCX object (see next section).
Since networks can contain many nodes and edges, and a huge amount of other attributes, it is typically advisable to first get a network summary, to check the node and edge counts for a network before retrieving the entire network. Thereby the structure of the network summary is similar the structure of the network list
## UUID of the first search result
networkId <- networks[1,'externalId']
## get network summary
networkSummary <- ndex_network_get_summary(ndexcon, networkId)
names(networkSummary)## [1] "ownerUUID" "isReadOnly" "subnetworkIds"
## [4] "isValid" "warnings" "isShowcase"
## [7] "isCertified" "indexLevel" "hasLayout"
## [10] "hasSample" "visibility" "nodeCount"
## [13] "completed" "edgeCount" "owner"
## [16] "version" "description" "name"
## [19] "properties" "externalId" "isDeleted"
## [22] "modificationTime" "creationTime"networkSummary[c('name','externalId')]## $name
## [1] "rasmachine"
##
## $externalId
## [1] "85276abf-379f-11e7-8f50-0ac135e8bacf"## get the entire network as RCX object
rcx <- ndex_get_network(ndexcon, networkId)To send a network to an server, there are two possibilities. Either one wants to update an existing network on the server or create a new one. In both cases, a UUID is returned, either of the updated network or a newly generated one for the created network. For updating a network, the UUID is extracted from the “externalId” property of the “ndexStatus” aspect, or can be set manually.
## create a new network on server
networkId <- ndex_create_network(ndexcon, rcx)
## update a network on server
networkId <- ndex_update_network(ndexcon, rcx)
## same as previous
networkId <- ndex_update_network(ndexcon, rcx, networkId)Besides creating, reading and updating, it is also possible to delete networks on the server. This operation cannot be undone, so be careful!
## deletes the network from the server
ndex_delete_network(ndexcon, networkId)This example workflow shows how to connect to the public NDEx server, browse and retrieve the pathways of the Pathway Interaction Database of the NCI which are hosted there.
## load the library!
library(ndexr)
## login to the NDEx server
ndexcon = ndex_connect()
## retrieve pathways of user "nci-pid"
networks_pid <- ndex_find_networks(ndexcon, accountName="nci-pid")
## list retrieved network information
networks_pid[,"name"]
## show information on the first pathways listed
networks_pid[1,]
## retrieve network data
mynetwork = ndex_get_network(ndexcon, networks_pid[1,"externalId"])
## convert into R graph format
mygraph = rcx_toRCXgraph(mynetwork)
## show graph information
mygraph
## use readable node names instead of IDs and plot the graph
V(mygraph)[as.character(mynetwork$nodes[,"@id"])]$name = mynetwork$nodes[,"n"]
plot(mygraph)This code snippet starts with loading the ndexr library and connecting to the server anonymously.
Afterwards ndex_find_networks retrieves a list of networks of user nci-pid, which contains the data of the Pathway Interaction Database. The function ndex_get_network downloads the network data and stores in the RCX format (explained in the next section) and is then converted into an igraph-based object via rcx_toRCXgraph.
Here, the node IDs of the graph are set to readable names and the graph is plotted. Naturally, this graph can be annotated and beautified as required for the specific use cases.
For the exchange of network data, NDEx uses the Cytoscape Cyberinfrastructure Network Interchange Format, or just CX format (See http://www.home.ndexbio.org/data-model/). CX is an Aspect-Oriented Network Interchange Format encoded in JSON, which is used as basis for the R implementation of the CX format, namely RCX.
The RCX object is currently implemented within this package as a list of
data.frames, containing meta-data and all aspects of the network. The
structure of an RCX object, as shown via str(rcx) could be a list like
this:
str(rcx, max.level = 2)## List of 13
## $ metaData :'data.frame': 10 obs. of 6 variables:
## ..$ name : chr [1:10] "cyVisualProperties" "nodes" "edges" "networkAttributes" ...
## ..$ elementCount : int [1:10] 3 168 205 3 467 1640 259 205 563 205
## ..$ version : chr [1:10] "1.0" "1.0" "1.0" "1.0" ...
## ..$ consistencyGroup: int [1:10] 1 1 1 1 1 1 1 1 1 1
## ..$ properties :List of 10
## ..$ idCounter : int [1:10] NA 168 205 3 467 1640 259 205 563 205
## $ numberVerification:'data.frame': 1 obs. of 1 variable:
## ..$ longNumber: num 2.81e+14
## $ cyVisualProperties:'data.frame': 3 obs. of 4 variables:
## ..$ properties_of: chr [1:3] "network" "nodes:default" "edges:default"
## ..$ properties :'data.frame': 3 obs. of 96 variables:
## ..$ dependencies :'data.frame': 3 obs. of 3 variables:
## ..$ mappings :'data.frame': 3 obs. of 7 variables:
## $ nodes :'data.frame': 168 obs. of 2 variables:
## ..$ @id: int [1:168] 0 1 13 14 19 24 29 30 35 36 ...
## ..$ n : chr [1:168] "AGT" "ADRB2" "ATF2" "PTGS2" ...
## $ edges :'data.frame': 205 obs. of 4 variables:
## ..$ @id: int [1:205] 2 15 20 25 31 37 43 50 56 63 ...
## ..$ s : int [1:205] 0 13 19 19 29 35 41 41 41 61 ...
## ..$ t : int [1:205] 1 14 14 24 30 36 42 49 55 62 ...
## ..$ i : chr [1:205] "Activation" "Activation" "Activation" "Activation" ...
## $ networkAttributes :'data.frame': 3 obs. of 2 variables:
## ..$ n: chr [1:3] "name" "description" "version"
## ..$ v: chr [1:3] "rasmachine" "" "1.28"
## $ nodeAttributes :'data.frame': 467 obs. of 3 variables:
## ..$ po: int [1:467] 0 0 0 1 1 1 13 13 13 14 ...
## ..$ n : chr [1:467] "type" "UniProt" "HGNC" "type" ...
## ..$ v : chr [1:467] "protein" "http://identifiers.org/uniprot/P01019" "http://identifiers.org/hgnc/HGNC:333" "protein" ...
## $ edgeAttributes :'data.frame': 1640 obs. of 3 variables:
## ..$ po: int [1:1640] 2 2 2 2 2 2 2 2 15 15 ...
## ..$ n : chr [1:1640] "INDRA statement" "__INDRA json" "type" "polarity" ...
## ..$ v : chr [1:1640] "Activation(AGT(), ADRB2())" "{\"type\": \"Activation\", \"subj\": {\"name\": \"AGT\", \"db_refs\": {\"TEXT\": \"Ang II\", \"UP\": \"P01019\""| __truncated__ "Activation" "positive" ...
## $ citations :'data.frame': 259 obs. of 3 variables:
## ..$ @id : int [1:259] 3 16 21 26 32 38 44 45 51 52 ...
## ..$ dc:identifier: chr [1:259] "pmid:30510587" "pmid:30526621" "pmid:30498475" "pmid:30524887" ...
## ..$ attributes :List of 259
## $ edgeCitations :'data.frame': 205 obs. of 2 variables:
## ..$ po :List of 205
## ..$ citations:List of 205
## $ supports :'data.frame': 563 obs. of 4 variables:
## ..$ text : chr [1:563] "In clinical settings, we report an important observation that inhibition of Ang II using telmisartan (an AT1R b"| __truncated__ "To confirm whether the Ang II induced ADRB2 downregulation influenced EPCs bioactivities, we treated EPCs with "| __truncated__ "To study the restorative effect of the AT1R blocker on Ang II induced ADRB2 depletion, we added TERT to EPCs fo"| __truncated__ "As shown in Ang II treatment reduced the expression of ADRB2 in EPCs; however, pretreatment with TERT signific"| __truncated__ ...
## ..$ citation : logi [1:563] NA NA NA NA NA NA ...
## ..$ @id : int [1:563] 4 5 6 7 8 9 10 11 12 17 ...
## ..$ attributes:List of 563
## $ edgeSupports :'data.frame': 205 obs. of 2 variables:
## ..$ po :List of 205
## ..$ supports:List of 205
## $ status :'data.frame': 1 obs. of 2 variables:
## ..$ error : chr ""
## ..$ success: logi TRUE
## - attr(*, "class")= chr [1:2] "RCX" "list"The data.frames representing nodes and edges could look like this:
rcx[["nodes"]][1:5,]## @id n
## 1 0 AGT
## 2 1 ADRB2
## 3 13 ATF2
## 4 14 PTGS2
## 5 19 ATF4rcx[["edges"]][1:5,]## @id s t i
## 1 2 0 1 Activation
## 2 15 13 14 Activation
## 3 20 19 14 Activation
## 4 25 19 24 Activation
## 5 31 29 30 ActivationUsually, and RCX object is automatically created by using the functions of this package for downloading network data from a NDEx server. But it might be useful to convert an RCX object from/to JSON manually, for example for down-/uploading a CX file from/to a NDEx server via the web interface. For handling the network information within R, besides RCX objects, one can use RCXgraph objects. A lossless conversion between the two files can be done using the following functions:
## convert RCX to JSON
json <- rcx_toJSON(rcx)
## ...and back
rcx <- rcx_fromJSON(json)
## convert RCX to RCXgraph
rcxgraph <- rcx_toRCXgraph(rcx)
## ...and back
rcx <- rcxgraph_toRCX(rcxgraph)It is possible to create blank RCX objects from scratch:
newRcx <- rcx_new()After a RCX object is downloaded from an NDEx server, it will contain some aspects that are not present in a newly generated network, i.e. “ndexStatus”, “provenanceHistory” and “status”. Removing those aspects might be useful in some cases.
asNewRcx <- rcx_asNewNetwork(rcx)After a RCX object underwent some changes (adding/removing nodes/edges/aspects/meta- data, etc.), it is advisable to check a RCX object for its integrity and update its meta-data.
rcx <- rcx_updateMetaData(rcx)The meta-data is not only updated by the function, but also created, if not existent in the first place. It is necessary to mention, that the function tries to check the format and content of most of the aspects and properties, but due to the dynamic structure of RCX and CX, it is advised to have a look at the CX data model specification for a deeper insight about the core structure, dependencies and limitations.
In general it is not advisable to retrieve a complete RCX object from a server without knowing the number of aspects and its corresponding size, because this may cause unwanted or unnecessary network traffic and decline in performance. To avoid these problems, a possible workflow is to download the meta-data of a network at first to check the available aspects.
## get meta-data for a network
metadata = ndex_network_get_metadata(ndexcon, networkId)
names(metadata)## [1] "name" "elementCount" "version"
## [4] "consistencyGroup" "properties" "idCounter"metadata[c('name','elementCount')]## name elementCount
## 1 cyVisualProperties 3
## 2 nodes 168
## 3 edges 205
## 4 networkAttributes 3
## 5 nodeAttributes 467
## 6 edgeAttributes 1640
## 7 citations 259
## 8 edgeCitations 205
## 9 supports 563
## 10 edgeSupports 205Afterwards, only the favored aspects can be downloaded individually.
## get aspect "nodeCitations" for the network
networkAttibutes = ndex_network_get_aspect(ndexcon, networkId, "networkAttributes")
networkAttibutes## n v
## 1 name rasmachine
## 2 description
## 3 version 1.28Even after creation, it is possible to change the name, the description or version of a network.
ndex_network_update_profile(ndexcon, networkId, name="My network", version="1.3")
ndex_network_update_profile(ndexcon, networkId, description="Nothing to see here")For collaborative work, it is necessary to share networks between several users and groups. Therefore there are specialized functions to grant access to a network, change the permissions and withdraw access permissions. It is possible to use those functions on single users or groups. Possible permissions are “READ” to have reading access to private networks, “WRITE” to be able modify, and “ADMIN” for the owner of the network.
## show all user who have permission to a network
permissions = ndex_network_get_permission(ndexcon, networkId, 'user')
## show all groups who have permission to a network
permissions = ndex_network_get_permission(ndexcon, networkId, 'group')
## show all users with write access to a network
permissions = ndex_network_get_permission(ndexcon, networkId, 'user', 'WRITE')
## grant an user permission to a network
ndex_network_update_permission(ndexcon, networkId, user=someUserUuid, 'READ')
## change the permission of an user to the network
ndex_network_update_permission(ndexcon, networkId, user=someUserUuid, 'WRITE')
## withdraw the permission from an user
ndex_network_delete_permission(ndexcon, networkId, user=someUserUuid)Besides permission management on user and group level, it is also possible to set some system properties on a network that influence the accessibility further. By default a network is private, which means that it is only visible to the owner and invited users and groups. If at some point one decides to make the network readable by anyone, it is possible to change the visibility of a network to “PUBLIC”.
ndex_network_set_systemProperties(ndexcon, networkId, visibility="PUBLIC")
ndex_network_set_systemProperties(ndexcon, networkId, visibility="PRIVATE")When a network has reached the point to be published, further edits should be prevented. While it would be possible to set the access permissions of all users and groups to “READ”, this approach is very inconvenient. Therefore, a simpler way is to just set the network to read-only using the network system properties.
ndex_network_set_systemProperties(ndexcon, networkId, readOnly=TRUE)One also has the option at the NDEx server to choose a selection of their favorite networks for display in his or her home page.
ndex_network_set_systemProperties(ndexcon, networkId, showcase=TRUE)
ndex_network_set_systemProperties(ndexcon, networkId, showcase=FALSE)
# change more than one property simultaneously
ndex_network_set_systemProperties(ndexcon, networkId, readOnly=TRUE, visibility="PUBLIC", showcase=TRUE)The provenance history aspect of an NDEx network is used to document the workflow of events and information sources that produced the current network (for the official provenance documentation see http://www.home.ndexbio.org/network-provenance-history/ ). There is a convenience function, that retrieves the provenance of the network.
provenance = ndex_network_get_provenance(ndexcon, networkId) In the following table all API functions are listed. The functions are grouped by the content they access, namely networks, users, or groups. For every function also is shown, if authentication is needed, and by which version it is supported (Version 2.0 or 1.3). A function marked with brackets indicates, that, although the function would be supported by this version, for different reasons no function could be implemented. Limitations of the single API functions are also given in the column of the corresponding version.
| Function name | Authentication | Version 2.1 | Version 2.0 | Version 1.3 |
| Networks | ||||
| ndex_find_networks | no | X | X | X |
| ndex_network_get_summary | no | X | X | X |
| ndex_get_network | no | X | X | X |
| ndex_create_network | yes | X | X | X |
| ndex_update_network | yes | X | X | X |
| ndex_delete_network | yes | X | X | X |
| ndex_network_get_metadata | no | X | X | (x) |
| ndex_network_aspect_get_metadata | no | (x) | (x) | |
| ndex_network_get_aspect | no | X | X | (x) |
| ndex_network_update_aspect | yes | (x) | (x) | |
| ndex_network_get_permission | yes | X | X | only for users, different response |
| ndex_network_update_permission | yes | X | X | (only for users) |
| ndex_network_delete_permission | yes | X | X | only for users |
| ndex_network_set_systemProperties | yes | X | X | only readOnly |
| ndex_network_update_profile | yes | X | X | X |
| ndex_network_get_provenance | no | X | X | X |
| Users | ||||
| ndex_find_users | no | X | X | X |
| ndex_find_user_byName | no | X | X | |
| ndex_find_user_byId | no | X | X | |
| ndex_create_user | yes | X | X | |
| ndex_delete_user | yes | X | X | |
| ndex_update_user | yes | X | X | |
| ndex_verify_user | no | X | X | |
| ndex_user_change_password | yes | X | X | |
| ndex_user_mail_password | no | X | X | |
| ndex_user_forgot_password | no | X | X | |
| ndex_user_list_groups | yes | X | X | |
| ndex_user_show_group | yes | X | X | |
| ndex_user_list_permissions | yes | X | X | |
| ndex_user_show_permission | yes | X | X | |
| ndex_user_get_showcase | no | X | X | |
| ndex_user_get_networksummary | yes | X | X | |
| Groups | ||||
| ndex_find_groups | no | X | X | X |
| ndex_get_group | no | X | X | |
| ndex_create_group | yes | X | X | |
| ndex_delete_group | yes | X | X | |
| ndex_update_group | yes | X | X | |
| ndex_group_list_users | no | X | X | |
| ndex_group_set_membership | yes | X | X | |
| ndex_group_list_networks | no | X | X | |
| ndex_group_network_get_permission | no | X | X |
In the section “Connect to a server”, briefly a method for manually changing the API version was introduced, with the API definition stored in ndex_config.
names(ndex_config)## [1] "defaultVersion" "Version_2.1" "Version_2.0" "Version_1.3"str(ndex_config, max.level = 3)## List of 4
## $ defaultVersion: chr "Version_2.0"
## $ Version_2.1 :List of 3
## ..$ version : chr "2.1"
## ..$ connection:List of 3
## .. ..$ description: chr "URL of the NDEx server"
## .. ..$ host : chr "www.ndexbio.org"
## .. ..$ api : chr "/v2"
## ..$ api :List of 5
## .. ..$ serverStatus:List of 4
## .. ..$ user :List of 11
## .. ..$ group :List of 6
## .. ..$ network :List of 12
## .. ..$ search :List of 3
## $ Version_2.0 :List of 3
## ..$ version : chr "2.0"
## ..$ connection:List of 3
## .. ..$ description: chr "URL of the NDEx server"
## .. ..$ host : chr "www.ndexbio.org"
## .. ..$ api : chr "/v2"
## ..$ api :List of 5
## .. ..$ serverStatus:List of 3
## .. ..$ user :List of 11
## .. ..$ group :List of 6
## .. ..$ network :List of 12
## .. ..$ search :List of 3
## $ Version_1.3 :List of 3
## ..$ version : chr "1.3"
## ..$ connection:List of 3
## .. ..$ description: chr "URL of the NDEx server"
## .. ..$ host : chr "www.ndexbio.org"
## .. ..$ api : chr "/rest"
## ..$ api :List of 4
## .. ..$ serverStatus:List of 3
## .. ..$ user :List of 1
## .. ..$ network :List of 11
## .. ..$ search :List of 3This object contains the api definition for several versions (currently
version 1.3, 2.0 and 2.1). By default, ndex_connect() uses the version defined
in ndex_config$defaultVersion (“Version_2.0”). To use another, or even a
customized version to establish a server connection, the ndexConf
parameter can be used, like shown before. In the following, the
structure of such a configuration is elaborated in more detail.
names(ndex_config$Version_2.0)## [1] "version" "connection" "api"The main structure of the configuration consists of three elements: The version is used to distinguish manually set configurations, which is used in some API functions to work differently for the single versions.
The “connection” element holds information about the default connection to the server, namely the host (e.g. “http://www.ndexbio.org/”) and the path to the api (e.g. “/v2” or “/rest”).
The REST API itself is defined in the “api” element, and follows the scheme of the function names, or the scheme of url paths likewise. E.g. in the “user” branch the different functions for handling user data are defined. If required, the functions might be grouped together in sub-branches furthermore. At the end of an branch, the actual definition of an API can be found.
To show, how such an API is defined and how to define one by themselves,
let’s have a look at
ndex_config$Version_2.0$api$user$password$mail, which is used by
ndex_user_mail_password(). Where to find the configuration of the
function is shown in the “REST query” section of the function
documentation. For a better readability, the yaml notation for this
function configuration is used:
mail:
description: "Causes a new password to be generated for ..."
url: "/user/#USERID#/password"
method: "PUT"
params:
user:
method: "replace"
tag: "#USERID#"
forgot:
method: "parameter"
tag: "forgot"
default: "true"Note: To get the yaml notation for the whole ndex_config simply use
yaml::as.yaml(ndex_config) (requires package yaml to be installed).
The single parameter definitions are given as list by the “params” parameter. Each parameter is defined by a method, and, if applicable, a tag, a default value and/or an optional flag. There are three keywords defining the method: replace, append or parameter.
#NETWORKID# in the url /network/#NETWORKID#/provenance is
replaced by a value (e.g. aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee)
given as network id, which leads to the url
/network/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/provenance./network/search and the given values for
start = 0 and size = 100 generates the following url:
/network/search/0/100username and the value SomeName is encoded in the url /user as
follows: /user?username=SomeNameIt is also possible to set parameter as optional (except for replace),
or define default values. Values are assigned to the parameters using
the parameter name in the … parameter of the ndex_helper_encodeParams()
function. Parameters, that are not defined in the configuration are
ignored.
The easiest to write an own configuration is by simply copying an existing configuration and tailor it to the needs.
# Copy an existing config
custom_ndex_config = ndex_config$Version_2.0
# Change the host connection for a local NDEx server installation
custom_ndex_config$connection$host ="localhost:8090"
# Custom path to the REST api
custom_ndex_config$connection$api ="/api/rest"
# Change the REST path for the ndex_get_network function
custom_ndex_config$api$network$get$url ="/custom/networks/#NETWORKID#"
# Add some (default) parameters to the function
custom_ndex_config$api$network$get$params$newParam = list(method="parameter", tag="someTag", default="someValue")It is also possible to write an own configuration in yaml (or convert
ndex_config to yaml, see above) and load it as object (yaml::load or
yaml::load_file) or to translate the configuration into R code using
the function ndexr:::yamlToRConfig()
Note: For package maintenance it is advised to add new versions as yaml
definitions in /R/ndex_api_config.yml (for example as "Version_3.0") and update the R code in /R/ndex_api_config.r, which defines the ndex_config object.
yamlToRConfig = function(yamlFile='R/ndex_api_config.yml', rScriptFile='R/ndex_api_config.r', defaultHeader=ndex_conf_header){
yamlObj = yaml::yaml.load_file(yamlFile)
rCodeTxt = paste0(defaultHeader, listToRCode(yamlObj))
outFile = file(rScriptFile)
writeLines(rCodeTxt, outFile)
close(outFile)
}
yamlToRConfig()#Session info Here is the output of sessionInfo() on the system on which this document was compiled:
sessionInfo()## R version 3.5.2 (2018-12-20)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 16.04.5 LTS
##
## Matrix products: default
## BLAS: /home/biocbuild/bbs-3.8-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.8-bioc/R/lib/libRlapack.so
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=C
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] ndexr_1.4.1 igraph_1.2.2 BiocStyle_2.10.0
##
## loaded via a namespace (and not attached):
## [1] Rcpp_1.0.0 knitr_1.21 magrittr_1.5
## [4] tidyselect_0.2.5 R6_2.3.0 rlang_0.3.1
## [7] stringr_1.3.1 httr_1.4.0 plyr_1.8.4
## [10] tools_3.5.2 xfun_0.4 htmltools_0.3.6
## [13] yaml_2.2.0 digest_0.6.18 tibble_2.0.0
## [16] crayon_1.3.4 bookdown_0.9 BiocManager_1.30.4
## [19] purrr_0.2.5 tidyr_0.8.2 curl_3.3
## [22] glue_1.3.0 evaluate_0.12 rmarkdown_1.11
## [25] stringi_1.2.4 pillar_1.3.1 compiler_3.5.2
## [28] jsonlite_1.6 pkgconfig_2.0.2