This page should help familiarize you with GraphSpace's interface and basic features.
What is a graph?
A graph is a mathematical object containing nodes and edges which connect the nodes together.
Graphs may be used to represent many different types of models such as computer networks and biological pathways. A graph may contain nodes(vertices) and edges(lines). In GraphSpace, we utilize these two objects to layout biological networks. In these networks, nodes may be thought of as proteins, and edges may be thought of as interactions between two proteins. An edge that connects two proteins indicates an interaction between them.
Public vs. Private Graphs
When a registered user uploads a graph to GraphSpace either through the REST API call found in the Programmer's Guide or through the web interface, it is by default uploaded as a private graph. A private graph may only be viewed by the owner of the graph (registered user who uploaded the graph). The only way a private graph may be viewed by other registered GraphSpace users is if the private graph is shared with a group. If the owner of the graph is part of a group and shares their private graph with the group, all members of the group may view it as well as create their own layouts for the graph. (See Layouts Panel)
A public graph is viewable to any person that visits GraphSpace. In order to make a private graph public, it may be done so through the REST API. By making a graph public, it allows all registered users to share their layouts to the graph. (See Layouts Panel)
Viewing a GraphConsider the follow public graph below:
Embedded InformationElements (nodes and edges) inside of a graph may have information embedded in them. Upon clicking any element inside of a graph, the element's border color will turn red. If the clicked element contains information (see JSON reference), it will show up as part of a pop up box, otherwise no pop up will be shown. The image below shows the information that is contained inside of the node CCT6.
The information embedded inside elements may contain external links to sources as well.
Graph PanelsWhen viewing a graph, you'll notice that there are panels to the right of a graph. Some of these panels are hidden. Clicking on an individual panel will reveal information the panels contain.
Graph Details Panel: Contains information describing the graph e.g. legend
Searching Panel: Allows one to distinguish an element of a graph. If a user wants to distinguish a node, simply enter the text that is displayed on the node. If a user wants to distinguish an edge, enter a query in the following format: [tail: head], where the tail is a node that an edge is pointing from, and the head is a node which the arrow is pointing towards.
For example, if a user searched for the node 'TEM1', then the node will look like this:
TEM1 before searching
TEM1 after searching
If a user wants to search for edge connection from TEF4 to TEM1, they can do so with the following search command: TEF4:TEM1. The edge will look like this:
Before searching for edge
After searching for edge
GraphSpace allows users to send links which contain elements of a graph to be distinguished. If a user searches for an element and the element is found inside the graph, a link is generated on top of the search bar. This link provides a reference to this graph along with all of the elements to be distinguished. If a GraphSpace user sends this link to someone else, they can follow the link to see the current graph (including all distinguished elements) provided that they are able to access the graph. [See Groups below]
The Similar option under the search bar allows one to search for all elements within a graph which may have the search term as part of its value. For example, if there are two nodes CDC5 and CDC55 and the user does a similar search with the term 'CDC', then both CDC5 and CDC55 will be distinguished.
The Exact option under the search bar allows one to search for all elements within a graph that are identical to the search term. If there are two terms CDC5 and CDC55 and the user does an exact search with the term 'CDC5', only CDC5 will be distinguished. Note: If the user had searched for the term 'CDC', nothing would have been distinguished since there are no nodes in our example graph which have CDC as their entire value.
Export Panel: Allows one to export the entire image of the as a PNG. The JSON option allows a user to see the exact JSON that was used to render the current graph.
Owner Panel: shows the GraphSpace user whom the graph belongs to
Sharing Panel: Displays all the groups that a graph is shared with. If a user is the owner of a graph, they will also have an option to share this graph with all the groups that they are a member of or the own. [See Groups below]
Layouts Panel: Provides multiple methods to display or layout a graph. Note: a user must have an account with GraphSpace in order to save and share layouts they create.
The 'Auto' option provides methods to automatically layout a graph using their respective algorithms. If a person has created an account and logged into GraphSpace, they they will be allowed to save any changes to the positions of elements in the graph that they manually make. In addition, they will also be able to view layouts and share layouts with groups that they are a member of. [See Groups below]
If a user of GraphSpace saves their own layout, they are given the following functionalities for the layout through buttons presented in the following order: (i) a direct link to this layout, (ii) change name of layout, (iii) share this layout with other users who have access to this graph, (iv) delete this layout, and (v) make it the default layout, i.e., instruct GraphSpace to display this layout whenever a user visits the page for this graph.
Step through filtering Panel: There are graphs in GraphSpace which employ the use of Step through filtering. This concept allows one to see subgraphs of the entire graph. In addition, it allows a user to "step" through the connections of a graph in sequential order. The images below show a user stepping through a graph.
Max highly probable paths tells GraphSpace to display a subgraph up to the specified value.
Number of highly probably paths reveals interactions (connections) that occur at a certain value. For example, when Number of highly probable paths was 10, the red node was revealed, however, when Number of highly probable paths was 8, it was hidden.
Finding graphsDepending on the resolution of the computer that is used to access GraphSpace, one of two navigation bars may be shown at the top of the screen:
or depending on the resolution, may look like:
If the latter is shown, simply click on the toggle icon on the right of the navigation bar to reveal the links and buttons.
On your graphs page, you will see buttons at the top of the page called "My Graphs", "Shared with me" and "Public graphs".
- My Graphs will show graphs that you own (you have uploaded). (GraphSpace account required)
- Shared with me will show graphs that have been shared with you through groups [See groups below]. (GraphSpace account required)
- Public Graphs will show graphs that have been made publicly available on GraphSpace.
If a user is logged into GraphSpace, then the graphs link will take them to graphs which they own. If the user is not logged in, the graphs link will direct them to the public graphs page.
Via REST API
This approach allows one to be more flexible and utilize all of the CSS features by specifically referencing them in the JSON for the graph. Please refer to the Programmer's Guide for more information.
Via Web Interface
For users who don't want to use the REST API for uploading a graph, we provide an easy web interface for uploading individual graphs. This interface allows users to upload their graphs directly into their accounts on GraphSpace.
We allow for the upload of two types of files into GraphSpace using this interface: graphs that follow the JSON Reference (.json files) and graphs that are exported directly from Cytoscape 3.1 or later (.cyjs files).
Please follow these instructions to export your Cytoscape graph to .cyjs format.
Note: Files using the .cyjs format may only be uploaded via the web interface!
For users who are not registered on GraphSpace, we provide this upload functionality as a tool to obtain a unique URL that contains the content of any .json/.cyjs file that is uploaded via the web interface.
Note: all graphs that are uploaded for unregistered users of GraphSpace will be deleted after 30 days.
Searching for graphsWhile on the graphs page, there are two panels: Search and Tags [See Tags section]. The Search panel allows for any user of GraphSpace to search a graph that matches the criteria of ALL search queries. A user may search for graphs using its name as well as a node or an edge which a graph may contain.
The Similar option under the search bar allows one to search for all graphs that may contain that word in the graph itself. This option will return all the graphs that may have a node which contains parts of the term(s) being searching, graphs that may contain part of the searched term in its name, as well as if there are edges which contain part of the searched term(s).
The Exact option under the search bar allows one to search for all graphs that have exactly what is being searched for. Graphs returned from this option may have a node, graph name, or an edge which is identical to the searched term(s).
To search for graphs that match a graph name, simply type the name or a part of the name of the graph
To search for nodes, type the content inside of the node (text that is contained inside of a node)
To search for edges, search using the following syntax [tail: head] where tail is the name of the node where the arrow is coming from and head is the name of the node that the arrow is point to. For example, to search for the edge that connects YEF3 to SIR2, type YEF3:SIR2. All graphs that contain this edge will be presented to the user.
If searching for multiple values, separate all individual search terms with commas. Ex: AKT1, AKT3, JUN
Note:If there are multiple search terms (and/or tag terms), all graphs that are returned WILL match all of these terms. All graphs that are returned by the searches of a node and/or an edge will have all searched terms distinguished inside the graph.
GroupsNote: GraphSpace account required for this feature
Groups may be thought of as a collection of GraphSpace users. For example, if there are multiple researchers who are working on the same project, a group may be created containing all of the researchers. Once a GraphSpace user is within a group, they may share any graph which they own with the rest of the group. Only members of the group will be able to see the graph.
A group owner is the creator of the group. They may
- Invite any GraphSpace user that has an account to be a member of their group
- Remove any member from their group
- Unshare any graph that has already been shared by the members of their group
- Share their graphs with a group
- Unshare the graphs that they own from the group
Sharing graphs with group(s)
Sharing layouts with group(s)
Similar to a graph, a layout may also be shared with a group. In order for a layout to be shared with a group, the graph (and implicitly the graph owner) must already be shared with a group. It would make no sense to share a layout with a group if that graph may not be viewed by any of the group's members.
When you first create a layout, only the creator of the layout is allowed to see it. If the graph is publicly available on GraphSpace, then if the user shares the layout they created, the layout will also be made publicly available. If the graph is privately shared, then if the user decides to share a layout they created, every group that has both the creator of the layout as well as the graph which the layout references will have access to that layout.
See Layout Panel.
Tags are used to categorize graphs. For example, if a user is uploading multiple graphs to GraphSpace for a specific paper, a tag would be used to categorize all the graphs related to the paper. On the graphs page, a user can search for graphs that match a tag. A graph may have any amount of tags that the user sees fit. It is advantageous for users to group all graphs they upload using tags as it allows for clear organization of work on GraphSpace. Tags are used to organize graphs for a user of GraphSpace, whereas groups are used to share graphs amongst multiple users of GraphSpace.
Currently, one has to know the exact tag to search for in order to retrieve all graphs that a user has permission to see which match the searched tag. If you are searching for multiple tags, separate each individual tag value with commas. Ex: help, tutorial, guide
All tags associated with a graph must be defined in the metadata for the graph itself. Refer to JSON Reference.