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