4. GraphSpace Network Model

GraphSpace networks follow a Cytoscape.js supported JSON format that separates the specification of the network structure (nodes and edges) from the description of the visual styles of the nodes and edges (e.g., colors, widths, shapes, labels).

  1. CYJS Format - Format is defined by Cytoscape.js for storing network structure and data information.
  2. Stylesheet JSON format - Format is defined by Cytoscape.js for storing the visual styles of the nodes and edges (e.g., colors, widths, shapes, labels) in CSS-based JSON format.

Graph information in these formats can be exported from or imported to Cytoscape (version 3.1.1 or greater).

4.1. CYJS Format

GraphSpace only supports one of the Cytoscape.js supported JSON formats for storing network structure and data information:

{
    "elements":{  // Elements JSON
        "nodes":[ // List of Node Objects
            {  
                "data": { // Node Data Attributes
                    "id": ...
                },
                "position": { // Node Position Attributes
                    "x": ...
                    "y": ...
                }
            }, 
            .
            .
        ],
        "edges":[ // List of Edge Objects
            {
                "data": { // Edge Data Attributes
                    "source": ..., 
                    "target": ...
                }
            }, 
            .
            .
        ]
    },
    "data": {   // Graph Data Attributes
        "title": ...,       
        "tags": [..],       
        "description": ... 
    }
}

A Cytoscape (v3.1 or later) user can easily export their graph in the above mentioned JSON format. We call the format as CYJS format because the extension of the exportable JSON file from Cytoscape App is .cyjs.

CYJS format structure consists of two core parts:

  1. Elements JSON - An object specifying the list of nodes and edges in the graph.
  2. Graph Data Attributes - An object specifying name-value pairs describing the graph.

Note: Any deviation from this format may result in GraphSpace rejecting the graph or problems in rendering the graph.

4.1.1. Elements JSON

The elements JSON object contains two types of lists:

  1. Nodes: An array of node objects describing the nodes in the graph.
  2. Edges: An array of edge objects describing the edges in the graph.

4.1.2. Graph Data Attributes

Cytoscape.js supports a network-level data section in the JSON file specifying name-value pairs describing the graph. In this section, GraphSpace gives users the freedom to include any attributes such as name, title, description, and tags that best characterize the network. GraphSpace displays the name attribute to identify networks in the list that a user can access and in the list that match search results. When the user accesses a specific network, GraphSpace displays the title above the layout of the graph and the content of the description attribute in the tab called Graph Information. The Graph Information tab for an individual network displays all its attributes and their values.

Graph also allows the users to search for networks with specific attribute values as described here. Cytoscape supports Graph Data Attributes for both import and export. The Graph Data Attributes are mapped to the Cytoscape network table for a network on import.

Please refer to the list of graph data attributes treated specially by GraphSpace to make the best use of GraphSpace’s features.

4.1.3. Node Object

{
    "data": {     // Node Data Attributes
        "id": ... // unique identifier for the node
    },
    "position": { // Position Attributes
        "x": ...
        "y": ...
    }
}           

The Node Object describes a node in the graph. A Node Object typically contains two types of attributes:

  1. Node Data Attributes:

    Node Data Attributes specify name-value pairs describing the node. Cytoscape requires that each Node Object should have an id or name data attribute which can uniquely identify the element in the graph. The users can define more data-attributes to describe the node. But, if the attributes are not specially treated by GraphSpace, they will be treated as “opaque”. This means that GraphSpace will store or transmit the data without any processing. Please refer to list of node data attributes treated specially by GraphSpace to make the best use of GraphSpace’s features.

    Note: GraphSpace uses id and name attributes interchangeably. If both attributes are specified, we overwrite the name attribute with the value provided in id attribute.

  2. Position Attributes:

    Position Attributes specify the model position of the node in the graph layout. For example, { x: 100, y: 100 } specifies a point 100 pixels to the right and 100 pixels down from the top-left corner of the viewport at zoom 1 and pan (0,0).

4.1.4. Edge Object

{
    "data": {     // Node Data Attributes
        "source": ..., // identifier for the source node
        "target": ...  // identifier for the target node
    }
}           

The Edge Object describes an edge in the graph. An Edge Object typically contains a data object which is defined as following:

  • Edge Data Attributes:

    Edge Data Attributes specify name-value pairs describing the edge. Cytoscape requires that each Edge Object should have source and target data attributes which can respectively identify the source and target nodes for the edge in the graph. The users can define more data-attributes to describe the edge. But, if the attributes are not specially treated by GraphSpace, they will be treated as “opaque”. This means that GraphSpace will store or transmit the data attributes without any processing. Please refer to list of edge data attributes treated specially by GraphSpace to make the best use of GraphSpace’s features.

4.1.5. Graph Data Attributes Attributes Treated Specially by GraphSpace

GraphSpace gives users the freedom to include any attributes that best characterize the network. If the attributes are not specially treated by GraphSpace, they will be treated as “opaque”. This means that GraphSpace will store or transmit the data without any processing.

4.1.6. Node Data Attributes Attributes Treated Specially by GraphSpace

GraphSpace gives users the freedom to include any attributes that best characterize the node. If the attributes are not specially treated by GraphSpace, they will be treated as “opaque”. This means that GraphSpace will store or transmit the data without any processing.

  • required:
    • id or name – text – A unique id representing the node. If both attributes are specified, we overwrite the name attribute with the value provided in id attribute. GraphSpace uses it to search for nodes with a matching name.
  • optional:
    • label – text – The text that is displayed inside of the node unless it is overidden by the content style-attribute in the stylesheet JSON. GraphSpace uses it to search for nodes with a matching name.
    • aliases - list of strings - A list of alternative identifiers for the node. GraphSpace uses it to search for nodes with a matching name.
    • popup - text - A string that will be displayed in a popup window when the user clicks the node. This string can be HTML-formatted information, e.g., Gene Ontology annotations and database links for a protein; or types, mechanism, and database sources for an interaction.
    • k - integer - An integer-valued attribute for this node, which denotes a rank. Through this attribute, GraphSpace allows the user to filter nodes and edges in a network visualization.

4.1.7. Edge Data Attributes Attributes Treated Specially by GraphSpace

GraphSpace gives users the freedom to include any attributes that best characterize the edge. If the attributes are not specially treated by GraphSpace, they will be treated as “opaque”. This means that GraphSpace will store or transmit the data without any processing.

  • required:
    • source – text – The id of the node where the edge is coming from.
    • target – text – The id of the node where edge is going to.
  • optional:
    • popup - text - A string that will be displayed in a popup window when the user clicks the edge. This string can be HTML-formatted information, e.g., Gene Ontology annotations and database links for a protein; or types, mechanism, and database sources for an interaction.
    • k - integer - An integer-valued attribute for this edge, which denotes a rank. Through this attribute, GraphSpace allows the user to filter nodes and edges in a network visualization.

4.2.2. Sample JSON

The following example is a CYJS formatted JSON accepted by GraphSpace.

{
    "elements": {
        "nodes": [ 
            {
                "data": {
                    "id":"P4314611",
                    "label": "DCC",
                    "k": 0
                }
            }, 
            {
                "data": {
                    "id":"P0810711",
                    "label": "This is an example\n of how to use new lines for the content of\n a node.",
                    "k": 0
                }
            }
        ],
        "edges": [
            {
                "data": {
                    "source": "P4314611",
                    "target": "P0810711",
                    "k": 0
                }
            }
        ]

    },
    "data": {
        "title": "Graph Name",
        "description": "Description of graph.. can also point to an image hosted elsewhere",
        "tags": [
            "tutorial"
        ]
    }
}

4.2. Stylesheet JSON Format

Cytoscape and Cytoscape.js are sharing a concept called Style. This is a collection of mappings from data point to network property. Cytoscape can export its Styles into CSS-based Cytoscape.js JSON.

Style in Cytoscape.js follows CSS conventions as closely as possible. In most cases, a property has the same name and behaviour as its corresponding CSS namesake. However, the properties in CSS are not sufficient to specify the style of some parts of the graph. In that case, additional properties are introduced that are unique to Cytoscape.js. For simplicity and ease of use, specificity rules are completely ignored in stylesheets by Cytoscape.js. For a given style property for a given element, the last matching selector wins.

A Cytoscape (v3.1 or later) user can export all Styles into one JSON file from File | Export | Style and select Cytoscape.js JSON as its format.

Note: Cytoscape.js does not support all of Cytoscape Network Properties. Those properties will be ignored or simplified when you export to JSON Style file.

4.2.1. Style Properties

Please refer to CytoscapeJS documentation for list of style properties supported by Cytoscape.js. We thank them for the excellent documentation of their framework.

4.2.2. Sample JSON

{
    "style": [
        {
            "selector": "node[name='P4314611']",
            "style": {
                "border-color": "#888",
                "text-halign": "center",
                "text-valign": "center",
                "border-width": "2px",
                "height": "50px",
                "width": "50px",
                "shape": "ellipse",
                "background-blacken": "0.1",
                "background-color": "yellow"
            }
        },
        {
            "selector": "node[name='P0810711']",
            "style": {
                "text-halign": "center",
                "text-valign": "center",
                "text-outline-color": "#888",
                "text-outline-width": "2px",
                "border-color": "black",
                "border-width": "5px",
                "height": "150px",
                "shape": "ellipse",
                "color": "black",
                "border-style": "double",
                "text-wrap": "wrap",
                "background-blacken": "0",
                "width": "150px",
                "background-color": "red"
            }
        },
        {
            "selector": "edge[name='P4314611-P0810711']",
            "style": {
                "curve-style": "bezier",
                "line-style": "dotted",
                "width": "12px",
                "line-color": "blue",
                "source-arrow-color": "yellow",
                "target-arrow-shape": "triangle"
            }
        }
    ]
}