Developing in NDEx

Last updated: December 7th, 2018

Overview

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:

  • Input or generate a gene list with your code
  • Get an interactome network from NDEx, such as the BioGRID
  • Map the genes to nodes in the network
  • Find a “neighborhood” subnetwork, perhaps via a heat diffusion algorithm
  • Apply graphic styling to the subnetwork, copying the styles from another network from NDEx that you use as a template
  • Apply a layout to the subnetwork
  • Save the subnetwork to NDEx

Responsible Practices for Application Design and Development

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.


Python

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).

  • For the ndex2 v2.0 Sphinx documentation, please visit THIS PAGE.
  • Additional documentation and examples, including Jupyter Notebooks are available in the ndex2 GitHub repo.

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.


Important Note: bugs, feature requests and other issues relative to either NDEx Python Clients should be reported through the respective client GitHub pages.

R

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.

ndexR also makes it simple to work with NDEx using Cytoscape Automation. An NDEx-Cytoscape example in R is available in THIS VIGNETTE and is included in the latest RCy3 Bioconductor package.


Important Note: all inquiries about ndexR as well as bug reports should be directed to the Kramer Lab.

Unique Identifiers for NDEx Objects

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.)

Implications for Copying Networks

"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.


Thank you for developing on NDEx and contributing to a satisfactory end-user experience.

The NDEx Team

R Unique Identifiers for NDEx Objects 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.) Implications for Copying Networks Responsible Practices for Application Design and Development