NDEx v1.3 – BEL Support

Overview

There are three updates to BEL support in NDEx v1.3:

BEL can be encoded in the CX exchange format

BEL format networks can be exported as CX files. BEL format networks can be retrieved by CyNDEx in CX format, but with the important caveat that Cytoscape does not handle a number of CX aspects that BEL uses, so the transfer is lossy.

BEL Namespace resource files can be archived as a special CX aspect with a BEL network, preserving them for archival reference rather than relying on external links.

The Web UI now has controls to upload namespace files and to show the namespace files associated with a given BEL network

The Web UI now correctly displays reified edges, used to encode BEL statements in which the object of the statement is another statement.

BEL in CX

The NDEx Web UI now supports the export of BEL format networks in CX and API functions that retrieve networks in CX format will work correctly for BEL format networks. Networks uploaded as XBEL, exported as CX and then re-uploaded will retain their BEL structure. NDEx v1.3 relies on the following CX aspects for encoding BEL:

networkProperties

BEL document properties are encoded as network properties.

nodes

Each node represents a term. The term can be referenced in multiple statements, encoded as edges referencing nodes.

The meaning of the represented BEL term is encoded in a functionTerm CX aspect element that references the node.

edges

Each edge represents a subject-relationship-object statement.

nodeAttributes

Represents context attributes for a "source-only" statement.

edgeAttributes

Represents context attributes for a statement.

citations

Represents a citation.

nodeCitations

Links a "source-only" statement to a citation.

edgeCitations

Links a statement to a citation.

supports

Represents an evidence text.

nodeSupports

Links a "source only" statement to evidence.

edgeSupports

Links a statement to evidence.

functionTerms

Stores BEL functionTerms. These refer to nodes by id, defining the meaning of the node.

reifiedEdges

Handles statements in which the object is another statement.

@context

Encodes BEL namespace specifications, mapping namespace URIs to prefixes used in other CX aspects.

BELNamespaceFiles

Optionally archives BEL namespace files referenced by the network.

BEL Namespace Resource Files as a CX Aspect

NDEx v1.3 extends the supported CX aspects to add the BEL-specific aspect ‘BELNamespaceFiles' to optionally store the namespace files referenced by the network within the NDEx network itself.

This addresses the need to archive a snapshot of all information required to interpret and use the BEL content. Archived BEL networks can then be reliably retrieved and used regardless of changes to external resources.

API Changes

Storing and retrieving BEL namespace files is implemented by extensions to the NDEx REST API.

Archive a BEL Namespace File in a Network

POST : /network/{networkId}/namespace

Requires Authentication

This method adds or replaces a POSTed BEL namespace to be archived in a BEL format network specified by a UUID.

Java Client Method:

public void addNetworkNamespace(UUID networkId, Namespace namespace)


Get an Archived BEL Namespace File from a Network

GET : /network/{networkId}/namespaceFile/{prefix}

This method retrieves the archived BEL namespace file associated with prefix if it exists. Otherwise 404 will be returned.


Get the BEL Namespaces Associated with a Network

GET : /network/{networkId}/namespace

Retrieves a list of Namespace objects from the network specified by ‘networkId'. The maximum number of Namespace objects to retrieve in the query is set by ‘blockSize' (which may be any number chosen by the user) while ‘skipBlocks' specifies the number of blocks that have already been read.

Java Client Method:

public List<Namespace> getNetworkNamespaces(UUID networkId, int skipBlocks, int blockSize)

  • attachNamespaceFiles(String networkUUID)
    • This function creates a task on the NDEx server. The task will use the namespace URLs in the specified BEL format network and attempt to download the namespace files and store them as an opaque CX aspect of the network.
  • getNamespaceFile(String networkUUID, String namespacePrefix)
    • Returns the specified namespace file as a string, if it exists

If a user downloads a BEL format network as CX, the namespace files will be included as an aspect in the CX stream if they exist.

The CX API methods also enable the retrieval of selected aspects of a network, so the namespace file aspects can be ignored by applications that will not use them.

Note that there is no change to the current XBEL network upload and export interface.


Examples:

Archive namespace files for a specified network:

http://localhost:8080/ndexbio-rest/network/1cdfb478-87d3-11e5-bd7f-aaf438b4bb9d/attachNamespacesFiles

Download a namespace file for a specific namespace in a BEL network, where "MGI" is the prefix of the namespace:

http://localhost:8080/ndexbio-rest/network/1cdfb478-87d3-11e5-bd7f-aaf438b4bb9d/namespaceFile/MGI

Check if namespace files are available for a network using an API method to get the CX metadata for the network:

http://dev2.ndexbio.org/rest/network/3ab54ab9-87dd-11e5-afd5-0251251672f9/metadata


User Interface Changes

When a network is displayed, if the sourceFormat is ‘BEL' then an "Archive BEL Namespaces" button is displayed. When it is clicked, a dialog is displayed to confirm that the user wants to archive the namespace files. If confirmed, then the API method is used to create an archiving task for that network. The namespace files are found by their URLs and retrieved for archiving.

The network page also displays the current status of the BEL namespaces for a BEL format network, either ‘Not Archived" or "Archived(n)" where ‘n' is the number of namespaces archived.