NDEx Network Data Model – The CX Format

Overview

Starting from v1.3, NDEx supports network I/O operations where network data is encoded in CX v1.0, the Cytoscape Cyberinfrastructure Network Interchange Format. NDEx v1.3 marks an important point in the evolution of NDEx, redefining the benchmark behavior of NDEx in terms of the input and output of networks in CX format.

CX has been developed in conjunction with the Cytoscape group to be the standard for network interchange by Cytoscape, NDEx, and applications and services in the Cytoscape Cyberinfrastructure (CI).

NDEx and CX Support Diverse Representations of Biology

Because of the wide diversity of network formats used in biology, a critical aspect of CX is that it provides straightforward strategies for lossless encoding of potentially any network. Semantically complex formats such as OWL, BioPAX, OpenBEL, SGML, or SBGN can be supported while at the same time enabling the expression of simple networks without undue overhead. CX does not, itself, make any commitment to a single "correct" model of biology or graphic markup scheme. At the most basic level, this means that CX imposes very few restrictions: graphs can be cyclic or acyclic and edges are implicitly directed, but formats can choose annotations schemes to override this. The meaning of the relationships indicated by edges or the classes indicated by the types of nodes in a network may conform to a rich standard such as BioPAX3 or OpenBEL, or they may have ad-hoc meanings unique to the particular network. The role of NDEx is to provide a common storage medium and access protocol, facilitating the use of diverse networks by applications but not limiting the semantics that they may express.

CX makes NDEx Extensible

Although NDEx provides both API and user interfaces to upload files in common formats (XGMML, XBEL, SIF, BioPAX3), the API also provides methods to create and query networks in CX. This enables researchers and developers to create and use networks with arbitrary semantics while still taking advantage of the common infrastructure supported by NDEx. For example, researchers might experiment with novel representations of RNA-RNA and RNA-DNA interactions using CX encoding for controlled vocabularies, citations, or terminology definition by functional composition.

Network Accession in NDEx

Networks stored on an NDEx server are assigned a 128-bit identifier that is a universally unique identifier (UUID). All networks are unique objects, regardless of what server they are created on.

The network UUID serves as an accession number across all NDEx servers. Networks can be accessed on their NDEx server by providing their UUID as a parameter to appropriate API methods.

The uniqueness of each network implies that copies of networks are different objects and will have a different UUID. It also facilitates the construction of network provenance histories that can be used to track the chain of sources and events leading to the current state of a given network.

CX v1.0 Mission

The purpose of CX is to provide a format in which networks can be transmitted between diverse services. It is designed for flexibility, modularity, and extensibility, and as a message payload in common REST protocols. It enables applications to standardize on core aspects of networks, coordinate on more specific standards within CX, and to ignore or omit irrelevant aspects. It is not intended as an optimized format for storage or for specific functionality in applications.

The context in which CX will transmit networks is the Cytoscape Cyberinfrastructure, a Service Oriented Architecture implemented using REST protocols and primarily intended to facilitate computation with biological networks of many types. Within that framework, services will be created to store, query, visualize, layout, and transform networks, orchestrated by applications that implement bioinformatic analyses. Such applications range from custom user interfaces to interactively scripted applications in environments like IPython Notebook, to managed workflows in environments such as Taverna or Galaxy. An application such as the Cytoscape desktop application can participate both as a client of services and as a service for other applications.

Finally, CX also addresses the critical requirement of enabling exchange of large networks while maintaining a low burden on both sending and receiving applications. Particularly, it enables a sending application to begin streaming a network without having the entire network in memory, and allows the receiving application to begin processing a network before having received the entire network. Thus, the design of CX enables applications to reduce memory requirements for both the sender and receiver, while also lowering delivery latencies.

CX is an Aspect-Oriented Network Interchange Format

CX is distinct from other network formats in that it seeks to avoid the gridlock of a standard requiring constant centralized coordination. It is aspect-oriented, meaning that different types of information about network elements are separated into independent, composable modules that follow simple guidelines for dependency. Aspects represent concerns that are relevant to some services and not others.

The core of CX defines five aspects:

"networkAttributes" element specify name-value pairs describing the network

"nodes" elements specify the identifiers for nodes in a network, optionally specifying a node name

"edges" elements specify edges that connect nodes, optionally specifying a interaction

"nodeAttributes" elements specify name-value pairs describing nodes

"edgeAttributes" elements specify name-value pairs describing edges

The "nodes" and "edges" contain no other information about the network, simply the identifiers of the nodes that the network contains and the edges that connect them.

Other aspects are defined as modules. Aspects can refer to nodes and edges – and other elements – by their aspect-unique IDs, annotating them with properties determined by the domain of the aspect. Aspects may also be self-contained data structures that annotate the network itself and do not refer to other elements.

Critically, when an aspect represents data that is required by a service to produce a result, that aspect is therefore part of the service's interface specification. A caller of the service must provide the aspects required by the service interface when calling the service. Conversely, a service may return its result as CX containing different aspects, depending on the service definition.

This structure makes it easy for a given application or service to make use of relevant aspects while ignoring others. Using a CX network is therefore a process of selection of the desired aspects followed by integration of the aspects in a task appropriate data structure. Note that CX is not intended to be used as an internal data structure for a service, although a service may choose to use it this way. A service accepting a CX network may also map it to an internal data structure suited to its purposes, and one of the design goals of CX is to enable mappings of this sort quick and simple.

Opaque Aspects

In addition to using or ignoring an aspect, a service may also handle it as "opaque". This means that the service accepts the data in the aspect and will store or transmit that data without loss or modification, but does not process the data. The opaque aspect strategy provides a pattern for cooperation – and separation – between services.

Aspects Enable Coexistence of Network Annotation Approaches

Aspects enable graceful coexistence of alternative approaches to network annotation. Consider the case in which a given network is presented by multiple graphic viewers, some emphasizing radically different styles and therefore different types of graphic markup. Rather than attempting to force a single standard of graphic properties, it is straightforward for the same network to be annotated with different graphics aspects. Each viewer that processes the network can look for the graphics or layout aspects that it recognizes and choose a scheme, ignoring others. This design for co-existence promotes innovation by isolating selected aspects as experimentation while preserving the network as a portable document.

CX Structure

Logical Structure Versus Physical Rendering as a Stream of Fragments

In this document, we distinguish between the logical structure of the CX format and its physical rendering. While the logical structure separates the base network from the aspects that annotate it, we specify a standard physical rendering that maintains the logical structure, but expresses it as a sequence of small fragments (Aspect Fragments) that can be assembled to realize the logical structure.

Aspects, Aspect Elements, and Aspect Fragments

Aspects are sets of Aspect Elements, each of the same type. The Aspect defines the data structure for its elements and can hold multiple instances of that data structure. An Aspect essentially amounts to a data type, defining the distinct key values and structure for its elements.

An aspect defined by a community may evolve over time, requiring versioning. This is handled simply by defining a new aspect name. Typically, the name includes the version. A program supporting CX must therefore know which aspects it handles by name.

CX Logical Structure

The logical structure of a CX network has the following schema:

{
"metadata" : [<aspect-metadata 1>, …],
<aspect name 1> : [<aspect-element 1>, …],
…,
<aspect name N> : [<aspect-element 1>, …]
}

CX Stream Structure

First, a pre-metadata object is transmitted, followed by a sequence of aspect fragments, and finally a post-metadata object is transmitted.

[
<pre-metadata>,
<aspect-fragment 1>,
….
<aspect-fragment N>,
<post-metadata>
]

The metadata for the CX stream is provided in two JSON objects, the pre-metadata and the post-metadata. The pre-metadata is the first object in the stream, and the post-metadata is the last object in the stream. They have the following schema, in which they break down into a set of Aspect Metadata objects, one for each Aspect present in the CX:

{"pre-metadata" : [ <aspect metadata 1>, <aspect metadata 2>, …]}
{"post-metadata" : [ <aspect metadata 1>, <aspect metadata 2>, …]}

Aspect Consistency Group IDs

When an application modifies a CX network, it may make changes that are inconsistent with the state of aspects that it treated as opaque. Subsequent operations may need to know which aspects are expected to be consistent with each other and which may be inconsistent.

To that end, we define "consistency groups" and in the metadata for each aspect, a consistencyGroup attribute assigns the aspect to one group. All aspects in a group are asserted to be consistent with each other.

An application that modifies a CX network should therefore set the consistency group assignments for the aspects that it changed, added, or can prove to be consistent such that they are distinguished from those that may have become inconsistent.

A simple case is where an aspect is added that only refers to nodes and/or edges. It should be assigned the same consistency group as the nodes and edges.

But, for example, in the case where edges are deleted, the application should also check consistency and potentially edit all non-opaque aspects to ensure that they have no references to deleted edges. All of the modified and checked aspects are assigned a new, unique consistencyGroup attribute. All opaque aspects retain their previous consistencyGroup and can be identified as potentially inconsistent with the nodes, edges, and other aspects.

The consistencyGroup attribute is a monotonically increasing value that increments when a change occurs that could make one or more aspects inconsistent.

  • When we add an aspect, it gets tagged with the current consistency group (assuming it's consistent with other aspects).
  • When we update an aspect, we increment the consistency group and tag the updated aspect(s) with it.
  • When we want to know what's consistent with what, we group aspects with the same consistency group … aspects in different groups are subject to deeper inspection and remediation by whatever service touches them next and cares.

Aspect Metadata

As a transfer format, Aspect Metadata is understood in the context of a network owner and a consumer, where the consumer may modify the network and return it to the owner. The owner is considered to have a complete picture of the network including all metadata and aspects associated with the network, and is considered to be authoritative as to the entire network and its parts. While the consumer can ask the owner for all or some of a network's aspects, for every aspect returned by the owner, the owner must also return the aspect's metadata. Additionally, for every aspect the consumer sends to the owner, it must supply the aspect's metadata.

The owner or consumer can send part of each aspect's metadata as pre-metadata and part as post-metadata — the aspect's metadata is considered to be the union of the pre-metadata and post-metadata. Both the pre-metadata and post-metadata must have name and version fields, and their values must be the same for pre- and post-metadata. For optional elements, the sender must include the element values, but is not required to if it doesn't have values for these elements. For optional and required fields (besides name and version), the sender is free to send each field as pre- or post-metadata, this choice of which is solely the sender's convenience. The receiver must be prepared to accept metadata values as pre-metadata, post-metadata, or (for optional fields) not at all.

Besides name and version, all attributes should only be specified at most one time — there should be no redundant attributes stated in both pre-metadata and post-metadata. The union of pre-metadata and post-metadata must always be equivalent to the aspect metadata – for example, it is valid for a system to receive CX, merge pre and post metadata and then output CX with all attributes specified as only pre-metadata.

When a sender has the choice of sending an element as either pre- or post-metadata, all things being equal, it should send it as pre-metadata.

An example of an owner is NDEx, and an example of a consumer is Cytoscape.

The full specification of Aspect Metadata:

{
name: string,
version: string,
idCounter: long,
properties: list of name value pairs in JSON object format.
elementCount: long,
consistencyGroup: long
}

Aspect Metadata attributes:

"name": Required. The name of the aspect.

"version": Required. The version of this aspect schema.Version is defined according to semantic versioning rules. That is, if a service requires aspect A version 1.1.0, it would not accept aspect version 1.0.0 or aspect 2.0.0. Essentially, the minor version number indicates that required values have been added but none have been removed or had semantic meaning changes – optional values don't figure into this discussion. The major version indicates that required values have been removed or had their semantics changed.

"idCounter": Required if the aspect exports IDs for its aspect elements. Integer (all Element IDs are integers). This is an integer monotonically increasing ID counter used for ID generation

"elementCount": Optional. Number of elements in this aspect.

"consistencyGroup": Required. An integer identifier shared by aspects to indicate that they are mutually consistent. Used to help track status of the network as different programs operate on different sets of aspects. See discussion of Aspect Consistency Group IDs.

"properties": Required. An aspect-defined property list. A list of name value pairs in JSON object format. (may be an empty list []) properties that need to be fetched or updated independently of aspect data.

Here is an example of pre-metadata list:

[
{
name:"nodes",
version: "1.0",
idCounter: 200,
lastUpdate: 1034334343,
elementCount: 32,
properties: [],
consistencyGroup: 1
},
{
name: "Citation",
Version: "1.0",
lastUpdate: 1034334343,
consistencyGroup: 1,
properties: [
{"name": "curator",
"value":"Ideker Lab"}
],
}
]

CX Rendering as Aspect Fragments

For both small and large networks, CX will be rendered as a sequence of Aspect Fragments, where one Aspect Fragment is a fragment of an aspect, and Aspect Fragments can be accumulated to form an aspect.

An Aspect Fragment has the same schema as a logical Aspect, but is a stand-alone object of with only a subset of the elements.

{
<aspect name 1> : [<aspect-element 1>, …]
}

This plan for rendering a CX network as a stream of Aspect Fragments addresses the design goal to enable incremental processing of CX, promoting the development of network processing services that are memory efficient and potentially parallelizable.

There is no fixed limit on the number of elements an Aspect Fragment can contain, though the number should be "small" — less than 100 is safe. The larger the Aspect Fragment, the less likely the sender or receiver may have the memory necessary to represent it.

Aspect Elements May Refer to Each Other by IDs

An Aspect may define an "@id" property for its elements. This is the id by which the element may be referenced by another element, either in the same aspect or in another aspect.

Referenceable IDs defined in an aspect must be unique for the aspect for the life of the network.

All Aspects must define the schema for their elements such that any references to elements are typed: it must explicitly define the Aspect of the referenced element. For example, if an Aspect can refer to both nodes and edges by their ids, it must use different keys to do so, otherwise the references would be ambiguous.

Note that this typing enables placeholder objects to be created by applications reading CX when they encounter a reference to an element before the element itself while processing the CX stream, updating the placeholder as the full information becomes available.

Aspect Element ids are integers and are assigned based on a monotonically increasing counter stored in the Aspect Metadata.

References between Aspect Elements pose challenges in the case where a program changes a CX network while treating some aspects as opaque. References between modified or deleted elements and elements in the opaque aspects may become inconsistent. For this reason, each application that modifies a CX network should designate the Aspects that it asserts to be consistent after the modifications, using the Aspect Consistency Group metadata (see below).

Note that streaming filters can easily be implemented if the operate on Aspects with elements that aren't referenced by other elements – elements can be removed incrementally without introducing inconsistencies. But in the case where the elements may be referenced by other elements, the participating Aspects must be loaded into memory to resolve inconsistencies before transmitting the filtered CX.

Note that in a given CX stream of Aspect Fragments, it is not necessary that a referenced element be defined before its reference. References will typically be resolved after the CX stream is parsed, but note that it is not required that the recipient resolve any references unless this is necessary for its function. A program might pass resolve reference only for aspects that it used and simply pass on or ignore all other aspects.

Best practice for a program that stores networks based on CX is that it should resolve all references between supported aspects and should error if there are any references that cannot be resolved, that leave incomplete "placeholder" elements.

Numbers in Aspects

Aspects may use numbers as supported by JSON. They are serialized as strings without quotation and are parsed by all implementations according to the JSON specification:

A number contains an integer component that may be prefixed with an optional minus sign, which may be followed by a fraction part and/or an exponent part.

Octal and hex forms are not allowed. Leading zeros are not allowed.

A fraction part is a decimal point followed by one or more digits.

An exponent part begins with the letter E in upper or lowercase, which may be followed by a plus or minus sign. The E and optional sign are followed by one or more digits.

Numeric values that cannot be represented as sequences of digits (such as Infinity and NaN) are not permitted.

The storage of these numbers for a given application parsing CX depends on the JSON implementation used. CX is only supported for implementations that pass the numeric range precondition check – they must correctly store and retrieve integers within that range. Any use of integers should be limited to that range.

An aspect may also be designed to store numbers as strings, placing the responsibility for parsing and otherwise handling these values on any CX implementations that supports the aspect.

A Simple Example: A Small Network with Cartesian Layout

The following example shows the usage of aspects at a conceptual level, a logical rendering, and a physical rendering.

Conceptual CX Representation

Conceptually, the network consists of three nodes, two of which are connected. The nodes aspect (named nodes) comprise the base aspect, while the edges (named edges) are an aspect composed onto the nodes, as are the cartesian coordinates (named cartesianLayout). The "CX Encoding" diagram shows all three aspects, focusing on how the edges and cartesianLayout annotate nodes.

Logical Textual CX Representation

The following JSON is a logical representation of the three aspects. It illustrates how the nodes aspect can be encoded, and how the other aspects can refer to specific nodes via references to node IDs.

{
"nodes": [
{
"@id": 1
},
{
"@id": 2
},
{
"@id": 3
}
],
"edges": [
{
"s": 1,
"@id": 4,
"t": 2
},
{
"s": 2,
"@id": 5,
"t": 3
},
],
"cartesianLayout": [
{
"x": 100,
"node": 1,
"y": 100
},
{
"x": 200,
"node": 2,
"y": 200
},
{
"x": 100,
"node": 3,
"y": 200
},
]
}
Physical Textual CX Representation

In this example, Aspect Fragments contain one or two data elements.

[
{"nodes": [{"@id": 1}, {"@id": 2}]},
{"edges": [{"source": 1, "@id": 4, "target": 2}]},
{"cartesianLayout": [{"x": 100, "node": 1, "y": 100}]},
{"cartesianLayout": [{"x": 200, "node": 2, "y": 300}]},
{"nodes": [{"@id": 3}]},
{"edges": [{"source": 2, "@id": 5, "target": 3}]},
{"cartesianLayout": [{"x": 100, "node": 3, "y": 200}]}
]

Core CX Aspects

These are specifications for the common aspects for CX v1.0, to be supported by most applications, where Cytoscape and NDEx are the first examples. (Some specialized applications do not need to support any aspects if they simply route the CX stream – i.e. a copier program).

Non-core aspects supported by NDEx are described in NDEx CX

Non-core aspects supported by Cytoscape are described in Cytoscape CX

nodes

Mandatory Aspect

Nodes are represented as (possibly multiple) lists of node key-value pairs, preceded by the keyword "nodes". For nodes the keys are "@id" and the values are the node identifier strings that parse as integers – "node ids".

Optionally, nodes can have a name (a single string), specified by the "n" key. Nodes can also have an optional represents attribute ( a single string), specified by the "r" key.

All node ids must be unique in the node aspect. A CX writer should not emit a node aspect in which node ids are repeated and it is good practice for any CX reader to test for uniqueness and handle malformed node aspects (either by erroring or by repairing, as appropriate to the application).

Example:

"nodes": [
{
"@id": 0
},
{
"@id": 1,
"n": "i am node 1",
"r": "HGNC:AKT1"
}
]

condition is that all node ids (as a matter of fact, this applies to all other aspects with ids) are unique (and not "empty"). At this point, it is the responsibility of the writer to make sure this is true, but we could easily add a check for uniqueness to our parser.

edges

Edges are represented as (possibly multiple) lists of dictionaries, preceded by the keyword "edges". Edge dictionaries have three keys: "source" and "target" which refer to the node identifiers connected by the edge and, and an identifier which is used by other elements to refer to the edge (the "edge id").

All edge ids must be unique in the edge aspect. A CX writer should not emit an edge aspect in which edge ids are repeated and it is good practice for any CX reader to test for uniqueness and handle malformed edge aspects (either by erroring or by repairing, as appropriate to the application).

Although a given CX network might not have any aspects that reference edges, the identifiers are always assigned for consistency and to simplify subsequent operations on the network.

Nodes can optionally also have a interaction field, specified by the "i" key.

Example:

"edges": [
{ "@id": 0,
"s": 0,
"t": 1,
"i": "binds"
}
]
nodeAttributes

nodeAttributes store attribute values associated with nodes.

Usage:

  • Cytoscape supports this aspect for both CX input and output. The nodeAttributes are mapped to the Cytoscape node table for an network.

nodeAttributes element attributes:

  • mandatory:
    • "po" – property of specifies the node to which the attribute applies.
    • "n" – text – attribute name
    • "v" – string or list of strings – the attribute value(s)
  • optional:
    • "d" – data type – attribute value data type (see below)
    • "s" – subnetwork id

Example:

"nodeAttributes": [

{
"n": "weight",
"po": 74,
"v": [ "2", "0.34", "2.3" ],
"d": "list_of_double"
},
{
"n": "name",
"po": 74,
"v": "Node 6"
},
{
"n": "selected",
"po": 74,
"d": "boolean",
"v": "true"
}
edgeAttributes

edgeAttributes store attribute values associated with edges.

Usage:

  • Cytoscape supports this aspect for both CX input and output. The edgeAttributes are mapped to the Cytoscape edge table for an network.
  • NDEx supports this aspect, storing it in a manner that enables queries to networks based on edge attributes.

edgeAttributes element attributes:

  • mandatory:
    • "po" – an edge id – specifies the edge to which the attribute applies.
    • "n" – text – attribute name
    • "v" – string or list of strings – the attribute value(s)
  • optional:
    • "d" – data type – attribute value data type (see below)
    • "s" – subnetwork id

Example:

"edgeAttributes": [
{
"n": "shared name",
"po": 84,
"v": "Node 5 (undirected) Node 6"
},
{
"n": "name",
"po": 84,
"v": "Node 5 (undirected) Node 6"
},
{
"n": "interaction",
"po": 84,
"v": "undirected"
},
{
"n": "shared interaction",
"po": 84,
"v": "undirected"
},
{
"n": "selected",
"po": 84,
"d": "boolean",
"v": "true"
}
]
networkAttributes

networkAttributes store attribute values associated with the entire network.

Usage:

  • Cytoscape supports this aspect for both CX input and output. The networkAttributes are mapped to the Cytoscape network table for an network.

networkAttributes element attributes:

  • mandatory:
    • "n" – text – attribute name
    • "v" – string or list of strings – the attribute value(s)
  • optional:
    • "d" – data type – attribute value data type (see below)

Example:

"networkAttributes": [
{
"n": "dc:title",
"v": "Result of heat diffusion analysis"
}
]

Data types for Attributes

Values for node, edge, network, and hidden attributes are always encoded as JSON strings. Their data type is determined by the value of "d" (string is the default data type).

The following data types are allowed:

  • boolean
  • byte
  • char
  • double
  • float
  • integer
  • long
  • short
  • string (default)
  • list_of_boolean
  • list_of_byte
  • list_of_char
  • list_of_double
  • list_of_float
  • list_of_integer
  • list_of_long
  • list_of_short
  • list_of_string

NDEx Specific CX

NDEx supports additional CX aspects that reflect the NDEx data model. These aspects are not core CX as of NDEx v1.3. NDEx parses and represents in the information from these aspects in the NDEx internal storage model in ways that enable efficient queries and updates as per the NDEx API.

NDEx Handling of Identifiers

All identifiers are interpreted by NDEx as either:

<prefix>:<id> format

a string without ‘:'

a URI

Network Attributes Treated Specially by NDEx

"version" – string – NDEx will treat this attribute as the version of the network. Format is not controlled but best practice is to use string conforming to Semantic Versioning.

"ndex:sourceFormat" – string – Used by NDEx to indicate format of an original file imported, can determine semantics as well. The NDEx UI will allow export options based on this value. Applications that alter a network such that it can no longer be exported in the format should remove the value.

"name" – the name of the network.

"description" – a description of the network.

Node Attributes Treated Specially by NDEx

"alias" – Alternative identifiers for the node. Same meaning as BioPAX "aliases".

"relatedTo" – Identifiers denoting concepts related to the node. Same meaning as BioPAX "relatedTerms"

NDEx Handling of Opaque Aspects

The NDEx server stores any aspect presented to it. Supported aspects are described in the next section. All others are stored as opaque aspects. For example, this means that queries to NDEx that retrieve subsets of the network cannot include only the corresponding portions of opaque aspects for the selected nodes and edges. Opaque aspects can only be retrieved as a whole or can be omitted.

For example, NDEx will store and retrieve graphic markup aspects of any type as opaque aspects. NDEx will not need to be updated when new graphic markup aspects are invented or when new versions are created.

NDEx CX Aspects

  • citations
  • nodeCitations
  • edgeCitations
  • supports
  • nodeSupports
  • edgeSupports
  • functionTerms
  • reifiedEdges
  • @context
  • provenanceHistory
  • ndexStatus
  • BELNamespaceFiles (Optionally archives BEL namespace files referenced by the network)
citations

citations aspect elements specify literature references or other sources of information that are relevant to the network. Other aspects, such as supports, edgeCitations, or nodeCitations can link them to specific nodes and edges in the network, indicating that the citation supports the assertion represented by the given node or edge.

Citations are primarily described by five dublin core terms http://purl.org/dc/terms. The "dc" prefix is implicitly interpreted as referencing dublin core in the context of the citations aspect.

The five primary dublin core terms defined for citations are:

dc:title http://dublincore.org/documents/2012/06/14/dcmi-terms/?v=terms#terms-title

dc:contributor http://dublincore.org/documents/2012/06/14/dcmi-terms/?v=terms#terms-contributor

dc:identifier http://dublincore.org/documents/2012/06/14/dcmi-terms/?v=terms#terms-identifier (Ideally citations make use of the "identifier" key to link to their source. This can be a URI, but might also use the "source:id" format, where source is usually "pmid" or "doi").

dc:type http://dublincore.org/documents/2012/06/14/dcmi-terms/?v=terms#terms-type

dc:description http://dublincore.org/documents/2012/06/14/dcmi-terms/?v=elements#description (This should be a description of the resource, and it is preferable that information that can be expressed in more specific attributes should not be in this attribute. The "description" attribute could contain the title, authors, and/or journal reference, but in that case it would not be expected to be machine parsable).

Additional attributes can be added to the citation using the "attributes" attribute, a collection of name-value pairs.

Usage:

Cytoscape treats this aspect as opaque.

The NDEx server supports this aspect. For example, queries that retrieve portions of a network can limit the included citations to those relevant to the nodes and edges retrieved.

Example:

"citations": [
{ "@id": 590,
"dc:identifier": "doi:10.1016/0092-8674(93)80066-N",
"dc:title": "Bcl-2 functions in an antioxidant pathway"
"dc:description": "Article from Cell, Volume 75, Issue 2, p241–251, 22 October 1993 ",
"attributes": [
{
"n" : "name1",
"v" : "value1",
},
{
"n" : "name2",
"v" : "26",
"t" : "integer",
}
]
}
]
nodeCitations

Each nodeCitations element links a collection of node ids to a collection of citation ids.

"nodeCitations": [
{
"citations": [590],
"po": [27]
}
]
edgeCitations

Each edgeCitations element links collection of edge ids to a collection of citation ids.

"edgeCitations": [
{
"citations": [590],
"po": [24]
}
]
supports

Each support element defines text that can be used to "support" – i.e. provide evidence for – one or more nodes or edges in the network. It optionally can also specify a citation id to indicate that the text is derived from the cited publication or data source. It may also have an optional attribute "attributes" which is a collection of name-value pairs.

"supports": [
{
"@id": 589,
"citation": 590,
"text": "Bcl-2 protected cells from H2O2- and menadione-induced oxidative deaths",
"attributes": [
{
"n" : "name1",
"v" : "value1",
},
{
"n" : "name2",
"v" : "26",
"t" : "integer",
}
]
}
]
edgeSupports

Each edgeSupports element links a collection of edge ids to a collection of support ids.

"edgeSupports": [
{
"supports": [589],
"po": [24]
}
]
nodeSupports

Each nodeSupports element links a collection of node ids to a collection of support ids.

"nodeSupports": [
{
"supports": [589],
"po": [27]
}
]
functionTerms

functionTerms aspect elements link nodes with expressions that define the meaning of the node in the network. The expressions compose external vocabulary terms to define concepts. Examples in BEL would include expressions that define complexes, reactions, protein activities and which distinguish proteins vs RNA vs genes.

Usage:

Cytoscape treats this aspect as opaque.

NDEx supports this aspect.

functionTerms element attributes:

  • mandatory:

"po" – an id – specifies the node which the function term defines.

"f" – string – the function, a name or an external vocabulary term specifying the composing function.

"args" – list of strings – ordered argument list to the function. Each argument can be either a literal value (string or number), an external vocabulary term, or a functionTerms expression.

reifiedEdges

A reifiedEdges Aspect Element designates that a node represents an edge. This is used to implement logic such as "A increases the inhibition of C by B" where the target of the "increases" edge is intended to be another edge, the "inhibits" edge from B to C.

The reifiedEdges aspect enables representation of this case by designating an additional node "D" to represent "B inhibits C". The CX edges attribute can then be populated with "A increases D" and "B inhibits C", a simple topology that should be handled by any network application. Applications that have internal data models supporting edge-edge interactions can parse the reifiedEdges aspect to determine which nodes are "standing in" for edges.

Usage:

Cytoscape treats this aspect as opaque.

NDEx supports this aspect, storing it in a manner that enables queries that retrieve subnetworks to include the reifiedEdges elements and edges that apply to the selected nodes.

reifiedEdges element attributes:

  • mandatory:

"edge" – an edge id – specifies the edge represented by the node.

"node" – a node id – specifies the node

"reifiedEdges": [
{
"node": 72,
"edge": 84,
},
{
"node": 77,
"edge": 88,
},
]
@context

The @context aspect elements are inspired by the JSON-LD @context (http://www.w3.org/TR/json-ld/#the-context) structures that define the vocabularies used in the CX document or stream.

@context maps terms to IRIs. Terms are case sensitive

This is a valuable feature of CX because it enables unambiguous, consistent reference to controlled vocabularies, when referencing both properties and values. It is possible to determine all namespaces and specific terms used in a network in a consistent fashion.

Usage:

Cytoscape treats this aspect as opaque, code controlling interpretation of attributes and values as controlled vocabulary references is embedded in the reader / writer for CX.

NDEx supports this aspect, storing it in a manner that facilitates indexing of content and translation of identifiers. NDEx has a related data structure, "Namespaces" that is part of the older NDEx JSON network structure and the NDEx internal storage model. Namespaces implement the storage of the @context aspect.

"@context": [
{
"MESHD": "http://resource.belframework.org/belframework/1.0/namespace/mesh-diseases.belns",
"BEL": "http://belframework.org/schema/1.0/xbel"
}
]
provenanceHistory

The provenanceHistory aspect is a JSON structure encoding meta-information about the network, describing the history of events and prior sources that led to the current state of the network. See the NDEx Network Provenance History for documentation on its structure.

Usage:

Cytoscape treats this aspect as opaque.

NDEx supports this aspect. In the current implementation, it is stored as an opaque data structure which is retrieved in full for any computation or manipulation.

ndexStatus

The ndexStatus aspect stores attributes that describe the state of the network when it was last stored in NDEx.

These attributes cannot be saved to NDEx with a network – they will be ignored on input if provided. They are computed by NDEx or they are managed by other NDEx API operations. The externalId property is a special: on input, for some API network update operations, the NDEx server may use the ndex:uuid property to identify the network to update.

Usage:

Cytoscape treats this aspect as opaque.

The NDEx server supports this aspect.

ndexStatus element attributes:

"externalId" – string – the CX network was derived from an NDEx network with this universally unique identifier (UUID) . The CX network may be a complete rendition of all the information that was stored on NDEx or it may be some subset of the network.

"creationTme" – timeStamp (string) – Time at which the network was created.

"modificationTime" – timeStamp – (string) – Time at which the network was last modified.

"readOnly" – boolean – Content modification not permitted only if true.

"visibility" – string – One of PUBLIC, PRIVATE. PUBLIC means it can be found or read by anyone, including anonymous users. PRIVATE is the default, means that it can only be found or read by users according to their permissions.

"published" – boolean – (planned for NDEx v1.4) If true, network is permanently readOnly but access privileges can be altered.

"nodeCount" – integer – the number of node objects in the network.

"edgeCount" – integer – the number of edge objects in the network.

"owner" – text – unique name of owner on the server.

"ndexServerURI" – URI identifying the NDEx server from which the network retrieved.

Example:

"ndexStatus": {
"externalId": ...,
"nodeCount" : 10,
"edgeCount" : 55,
...
}
BELNamespaceFiles

This aspect is used to optionally archive BEL namespace files referenced by the network. See the NDEx v1.3 BEL Support document for a full discussion.

NDEx Java API Extensions for CX

UUID createCXNetwork(InputStream cxStream);
create a network from CXStream.

UUID updateCXNetwork(UUID NetworkUUID, InputStream cxStream);
use the data in the input CX stream to update a given network in the server.

CXStream getAspects(String networkUUID, Collection<String> aspectNames);
get the subnetwork of given aspects. AspectNames must be not null, non empty.

CXStream getCompleteNetworkAsCX(String networkUUID);

CXStream getAspectElements(String networkUUID, String aspectName, int elementLimit);

CXStream queryNetworkAsCX(String networkUUID, SimplePathQuery query, Collection<String> aspectNames);
the query result is a subnetwork, it only has the aspect defined in the aspectNames list. If aspectNames is null or empty, only the node and edge aspect will be returned.

MetaDataCollection getNetworkCXMetadataCollection(String networkUUID);
Return the metadata of a given network as a MetaDataCollection Object.

Note: the NetworkSummary objects returned by the existing search API can be augmented to include aspect information ( aspect metadata), making it easier for users of the Web UI to understand the nature of the networks that they find.