Last updated: December 7th, 2018
The NDEx framework is intended for integration into your applications, whether scripts, notebooks, web applications, web services, or Cytoscape Apps. Outreach to application developers is one of the specific aims of the NDEx project and we are always happy to help you successfully use NDEx in your software.
Analysis workflows can use NDEx as a source for reference interactomes and sets of pathways or for networks produced in your lab or by your collaborators. Vice versa, networks generated by workflows can be stored in NDEx to be shared or for later use. If you have an existing application, you can augment it by expanding the range of network that you user for input or by enabling your users to save their output.
Applications communicate with NDEx via a REST API, transferring networks using CX, the Cytoscape Cyberinfrastructure Network Exchange Format. CX is a streamable transmission format that places few constraints on the schema of networks and that has a modular, extensible structure.
Here is an outline of a workflow using NDEx that could be performed interactively in Cytoscape but can be automated using the NDEx REST API:
The public NDEx server is a shared public resource and so we ask you to be considerate of other users as you design and test your applications.
When designing your application, please consider the load on the server. This is not only civic minded, but will typically improve the application’s performance. For example, caching of the results of repetitive requests will reduce server load and single large transactions are typically more efficient than many smaller transactions.
It’s also worthwhile to familiarize yourself with the CX Data Model and using the NDEx API as some operations have parameters to control the amount of data returned. For example, you can retrieve selected aspects of a network, limiting the query to what is required by you application, such as only retrieving the edges of a network without the nodes, node attributes, or edge attributes.
The public server is appropriate for lightweight testing such as working with our tutorials, but for more intense use we suggest that you contact us and we can arrange for you to use a test server. If you anticipate very heavy server load during testing, you can even run your own NDEx Server and test your applications locally. Please check our installation instructions to download and install your own NDEx Server instance.
The NDEx Python Client, ndex2, is a module that simplifies access to the NDEx Server API and provides convenience methods for common operations on networks; it can be installed via PIP and requires Python 3. In addition to the API methods, ndex2 provides a convenient Python data model and utilities for working with Pandas Data Frames and NetworkX (including NetworkX 2.x).
There is also a legacy NDEx Python Client, ndex v3.1, that is compatible with both Python 2.7.9 and Python 3. Although this client is supported and maintained, it is now obsolete and no additional development is planned.
The NDEx R Client, ndexR, is available as a Bioconductor package developed by the Kramer Lab at the University of Goettingen, Germany; it simplifies access to the NDEx REST API and provides convenience methods for common operations on networks. You can download the ndexR Cheat Sheet in PDF format using the "Download PDF" button at the top of this page. The source code and documentation are available on GitHub.
Networks, Users, Groups, and some other objects stored on an NDEx are assigned a universally unique identifier (UUID) and can be referenced at URIs based on the address of their host NDEx Server, the type of the object, and the object's externalId. (It is therefore best practice to deploy at an NDEx server at a stable URI.)
"Unique" in UUID must really mean unique: when a network is copied, the copy gets a new UUID on the NDEx where it is created. This is a central design issue for NDEx, supporting the construction of network provenance information that can be used to track the chain of sources and events leading to the current state of a given network.
The NDEx Team