GraphSpace: Implement a machine-readable graph legend interface

[adbharadwaj]

Background

GraphSpace is an easy-to-use web-based platform collaborating research groups can use for storing, interacting with, and sharing networks. A GraphSpace user can upload graphs through a REST API, import graphs created in Cytoscape, interact with graphs (view them, customize layouts, and save layouts), share graphs (create groups and add collaborators, share graphs among all members of a group or with the world), search graphs, and organize graphs using tags. GraphSpace has a comprehensive REST API that allows users to communicate programmatically with it.

Currently GraphSpace allows users to add a legend to each graph by providing a HTML table in the description of the graph. However, this implementation has many issues:

• Including the legend as an HTML table in the description is tedious.
• The legend cannot be parsed programmatically.
• GraphSpace cannot learn or understand the legend of a graph uploaded to GraphSpace.
• Users cannot use the legend interactively.
• There is no widget/tool in the layout editor that allow users to quickly change/update the legend.

Goal

This project has three main goals:

1. Simplify the process of providing a legend for a graph. This can be done by representing legend data in JSON format, hence it will be programmatically parsable and users will be able to interact with the legend in easier ways.

   One possible solution would be include the legend data in the graph meta-data in json format. The data field in graph_json that contains metadata about the graph will also contain the legend data. A new field legend will be included in the data field. It will be a dictionary having two main fields: nodes and edges. nodes field will have the legend data for nodes and edges field for edges. Each key in the nodes or edges field will represent a legend key. The label of the legend key will be the key name. The definition of each legend key will be in form of a dictionary which will contain the style of the legend key.

   Example:

{
   "legend":{
      "nodes":{
         "Complementary Genes":{
            "node-shape":"ellipse",
            "color":"#fff"
         },
         "Polymer Genes":{
            "node-shape":"triangle",
            "color":"grey"
         }
      },
      "edges":{
         "Activating Interaction":{
            "edge-type":"haystack",
            "color":"green"
         }
      }
   }
}

2. Build graphical user interface on top of new legend format. Legend can be shown on top of the canvas for a graph (like the zoom-in/zoom-out scale is shown). The space on the top-right corner can be utilized for showing the legend. The legend can be constructed using the legend data available in the graph meta-data. Additionally, this goal involves developing following features:

   • Interactive legend - Users should be able to interact with the legend upon graph visualization. For example, the interface should allow users to select nodes or edges using the legend interface.
   • Edit the legend - Users should be able to edit the legend seamlessly from the layout editor tool. The current interface allows users to select nodes by color and shape but they cannot select edges by their edge-style and color.

3. API interface - Users should be able to update the legend using the graphspace-python package. To be specific, the GSGraph class in graphspace-python package should include methods to add, modify and remove legend data. Here is a sample set of API signatures to be implemented.

   add_legend_key(element_type, label, style):

   Add an individual legend key to the legend data.
   
   Args:
       element_type(str): Either node or edge.
       label(str): Label of legend key. Passing an already existing label as param will update that legend key.
       style(dict): Style dict of the legend key. Will contain attributes like node shape or edge type, color.

   remove_legend_key(element_type, label):

   Remove an individual legend key from the legend data.
   
   Args:
       element_type(str): Either node or edge.
       label(str): Label of legend key to be deleted.

   set_legend(legend_json):

   Set the json representation of legend for the graph.
   
   Args:
        legend_json(dict): JSON representation of the legend data.

   get_legend():

   Get the json representation of legend of graph.
   
   Returns:
        dict: JSON representation of legend data.

Difficulty Level

Level 2

Skills

List skills/technologies that the student should be familiar with.

• Python, Django, HTML, JS, Jquery, CSS (essential)
• Databases (SQL), Git, Cytoscape.js (nice to have)

Public Repository

https://github.com/Murali-group/GraphSpace/

Gitter chat room

https://gitter.im/graphspace/gsoc2019students

Potential Mentors

Aditya Bharadwaj T. M. Murali

Contact

adb@vt.edu murali@cs.vt.edu

[adbharadwaj]

To all prospective applicants,

Please refer to instructions for potential GSoC students to get started.

[sanket0211]

Hi Sir, My name is Sanket Shah. I am keen to take up this project.

About Myself My name is Sanket Shah. I am currently pursuing Bachelor of Technology in Computer Science and MS by Research in Bioinformatics at International Institute of Information Technology, Hyderabad, India. I am currently in my pre-final year.

Why I want to take up this project Sir, I am pursuing research in the field of bioinformatics. I am currently developing a web tool for studying response to abiotic stress in Rice. I have integrated Cytoscape application with this tool for network visualization. The next step is to import this graph in Graphspace and interact with them. Since I am using Graphspace for my project, I am interested to contribute to its development.

Skills Sir, I am proficient in C++, Python, HTML, Javascript, Jquery, Php, Mysql, HTML, CSS, Django.

Where do I stand Sir, I have installed Graphspace on my local machine and as per the instructions, I am trying to enhance the documentation and also preparing a video of how to install Graphspace locally for potential contributors.

Thank you.

Regards, Sanket Shah

[adbharadwaj]

@sanket0211 Thanks for showing an interest. Its great to see a student with a background in Bioinformatics showing interest in this project. Can you send an email with your CV/Resume to me and @tmmurali.

Additionally, as mentioned here, we are looking forward to see some code contribution on GraphSpace.

[sanket0211]

@adbharadwaj Sir, @tmmurali Sir, I have sent you an email with my CV. I would be honored to contribute to this project. I have started to understand the code-base and currently trying to solve issues with the tag "good first issue".

Sir, I went through the project description properly again and want to know more about how the legend shall look like and what information shall it provide about the Graph. It would be great if you could give me some insights on it.

Thank you.

[adbharadwaj]

@sanket0211 Currently, GraphSpace allows users to provide legend information in HTML format. This gives them a lot of freedom on how to format their legend. Because legend is in free text format, it is very hard for us to parse and provide interactive functionalities. For example, clicking on a node type in the legend should allow the user to select all nodes.

To find out what kind of information should be available in legend interface, please refer to one of the public graphs on GraphSpace. Here is a sample:

Screenshot taken from http://graphspace.org/graphs/23790#graph_details_tab

This is just an example, we look forward to suggestions from students as well.

[manishkk]

Cross-posting from https://github.com/Murali-group/GraphSpace/issues/357 Hi, I'm Manish Kumar, a master's student at TU Kaiserslautern, currently writing my thesis at Max Planck Institute for Software Systems in Kaiserslautern, Germany. I have been using Python for quite some time for my academic and hobby projects and also have a fair amount of experience in Django. I have also contributed to Mozilla.

GraphSpace as a tool seems very interesting to me and I would like to contribute as part of Google Summer of Code 2018. I'm interested in the idea titled 'Implement a machine-readable graph legend interface'.

I have already set up GraphSpace dev environment on my local machine and was looking at issues to get used to the workflow and codebase. I found https://github.com/Murali-group/GraphSpace/issues/322 interesting and have already commented on the issue.

Thank you

[sanket0211]

@adbharadwaj Sir and Prof. @tmmurali, I have understood this project well and I have a few suggestions.

Legend will contain elements. An element can be a node or an edge.

A node can be uniquely represented by following: a. Colour b. Width c. Height d. Shape

An edge can be represented by the following: a. Line Color b. Width (px) c. Line Style d. Source Arrow Shape e. Target Arrow Shape

The above attributes for creating the legend are already with us(Graph JSON).

1. We create another side-bar on the left side of the layout side-bar. That means the graph canvas size becomes smaller horizontally. This new sidebar will contain legend elements as described above. The elements will be created from the graph JSON data and thus will be mapped to the corresponding nodes and edges. We do not require the user to explicitly provide legend data along with Graph JSON. Creating another sidebar for the legend will not disturb the graph canvas. UI wise it won't make much of difference.

2. Just above the beginning of the legend, we will have a button to edit the legend. Editing the legend means that the user can change labels for each legend element and press save. The legend can also be saved exactly as we save the layout for the graph. I mean that the graph can have multiple legends. A user can create his own legend(Not ignoring the rules of public and private graphs.)No doubt the legend will be saved in JSON format.

3. The Graph Legend will be in sync with Graph Layout. Every time the graph layout is loaded, the legend will be formed dynamically. The labels will be intact if and only if the elements are intact. Else new elements will be formed and the labels for them will be by default undefined. [This point needs to be understood and handled with care. Please let me know if there is any difficulty understanding this.]

I was going through the code and I feel that the layout editor code can be reused for creating Graph legend. There is quite a bit of similarity between these two.

I have actually tried to explain my idea on the surface level. Sorry for using text for explaining, I was having difficulties creating UI images. Once I am done creating UI images, I will be able to explain better.

Meanwhile, let me know if my idea of the Graph Legend makes sense.

Thank you.

[sanket0211]

@adbharadwaj Sir and prof. @tmmurali, I am in the process of writing Gsoc'18 Proposal for this project. Is there anything I need to keep in mind while creating the proposal? Are there any key points with respect to this project which I need to keep in mind? Are there any guidelines Gsoc aspirants are supposed to follow while writing the proposal? Thank you.

[matthiaskoenig]

Here some thoughts/points I find important:

Basically what you have to do is write a full serialization of the VisualMapping, i.e., how VisualAttributes Map on Node/Edge Attributes. I would have a look at the Cytoscape Visual Mapper and the VisualMappings/VisualStyle which are possible to get a feeling for what must be included. This works very well and is already thought out.

Until now I only saw here in the discussion the very simple use cases, but this can be much more complicated, especially you can have more complicated mapping types.

• simple mappings (single node/edge attribute mapped to visual attribute)
• pathtrough mappings (list of node/edge attributes mapped to list of visual attributes),
• continuous mappings (mapping of double/integer attribute to respective node/edge values, sometimes nonlinear), for instance node size to some node attribute, edge width to some edge attribute. The mappings can be linear or log and have multiple points for their definition.

There can be global defined styles on the full graph. Something like default visual styles. This are not used as a mapping, but have to be taken into account when generating the legend information, e.g. global edge width, node size.

I would recommend looking at: http://manual.cytoscape.org/en/stable/Styles.html Also at the exported XML files for styles from Cytoscape which give you a feeling of what information is available in Visual Mapping.

Is the rendering of the legend part of this project? Or only the serialization? Why not just use the Cytoscape XML formats for styles? This is machine-readable and contains all the information. You could just serialize it to JSON, but keep it interchangeable. This would than also allow to easily generate exchangable legends from Cytoscape.

[AdamStuart]

Matthias,

FYI, I am working on an app called legend-creator, that seems to overlap this project. https://github.com/cytoscape/legend-creator https://github.com/cytoscape/legend-creator

My approach was to put the legend onto the canvas as group annotations, but this didn’t work out because the system to select, move, edit annotations is currently too cumbersome. Revising that system is on the list for 3.7, but its hard to see that legends can be very useful before then.

I am about to go back to this project in light of improvements in the current develop branch of Cytoscape, so I’d be interested to hear what you think of my current control panel, and what you’d like to see. I’m planning on writing this up as a tutorial on app construction, so your thoughts on do’s and don’ts of Cytoscape development would be most welcome.

I’m happy to contribute as a mentor or pass this project on if you get a GSOC candidate, or do the implementation myself if you don’t.

Adam

On Mar 2, 2018, at 1:15 AM, Matthias König notifications@github.com wrote:

Here some thoughts/points I find important:

Basically what you have to do is write a full serialization of the VisualMapping, i.e., how VisualAttributes Map on Node/Edge Attributes. I would have a look at the Cytoscape Visual Mapper and the VisualMappings/VisualStyle which are possible to get a feeling for what must be included. This works very well and is already thought out.

Until now I only saw here in the discussion the very simple use cases, but this can be much more complicated, especially you can have more complicated mapping types.

simple mappings (single node/edge attribute mapped to visual attribute) pathtrough mappings (list of node/edge attributes mapped to list of visual attributes), continuous mappings (mapping of double/integer attribute to respective node/edge values, sometimes nonlinear), for instance node size to some node attribute, edge width to some edge attribute. The mappings can be linear or log and have multiple points for their definition. There can be global defined styles on the full graph. Something like default visual styles. This are not used as a mapping, but have to be taken into account when generating the legend information, e.g. global edge width, node size.

I would recommend looking at: http://wiki.cytoscape.org/Cytoscape_User_Manual/Visual_Styles http://wiki.cytoscape.org/Cytoscape_User_Manual/Visual_Styles Also at the exported XML files for styles from Cytoscape which give you a feeling of what information is available in Visual Mapping. https://user-images.githubusercontent.com/900538/36891445-f7a840e8-1e01-11e8-9ac4-cd68687b7f10.png Is the rendering of the legend part of this project? Or only the serialization? Why not just use the Cytoscape XML formats for styles? This is machine-readable and contains all the information. You could just serialize it to JSON, but keep it interchangeable. This would than also allow to easily generate exchangable legends from Cytoscape.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/nrnb/GoogleSummerOfCode/issues/114#issuecomment-369865286, or mute the thread https://github.com/notifications/unsubscribe-auth/AHSv7XTcOJuZzfdKNAHnkentOG9S7_qEks5taQ3PgaJpZM4REPbM.

[tmmurali]

@matthiaskoenig Thank you for the valuable ideas. I am sorry for the delayed reply. We are already using Cytoscape.js XML formats for the styles of graphs in GraphSpace. We will look in detail at the links you have provided, although I am not sure to what extent the XML format supported by Cytoscape.js matches exactly with the format supported by Cytoscape.

When a GraphSpace user creates a graph on GraphSpace, they can specify in a legend for each node/edge style in the graph what that style corresponds to biologically, e.g., a yellow rectangle is a transcription factor or a red edge with an arrowhead corresponds to a phosphorylation reaction. We want the information in this type of legend to be specifiable programmatically, perhaps using the GraphSpace REST API.

We also want to render the legend when the user is seeing the graph on GraphSpace.

[tmmurali]

@AdamStuart Thank you for the pointer to your Cytoscape app. This particular project is related to GraphSpace. I think there may be sufficient difference between the two projects for us to continue development separately while continuing to consult with and learn from each other. We can discuss further depending on whether this GSoC project is selected.

[matthiaskoenig]

Trying to understand a bit more what is going on with styles in GraphSpace and cytoscape.js. Basically the information I could get was in summary:

• GraphSpace and cytoscape.js support a JSON style format (probably the same format)
• This JSON style format translates to CSS for a given node or edge
• The styles are defined for individual nodes or edges, but no global visual mappings exist

So what I take away from this is that the style system of cytoscape.js and GraphSpace is inherently very limited and not sufficient. I.e., there is nothing like style rules (which you would use for the legend, but every node and edge style is listed individually). Please correct me if I am wrong, but this is what I took away so far.

What one normally is doing with visual styles in networks is mapping certain node and edge attributes to certain classes of nodes and edges via different kind of mappings (continous/pass through). E.g. given users want to say that one attribute like node shape codes for one type of node (retangle-reaction, circle - species, triangle - regulation), the size for something else (for instance node degree encoded as continous mapping on node degree), the color for something else (for instance location: green cytosol, blue extracellular, ...). This is basically how visual attributes are used to encode information in networks and these mappings are what the legend should inform the user about. It looks to me that cytoscape.js as well as GraphSpace don't have support for these VisualMappings, so I don't understand what should be displayed in the legend?

As I understand it the user would have to write additional JSON for the legend to define all the node and edge classes? This works for discrete mappings like shown in your example (but still misses the whole point of visual styles). But this does not work for continous mappings? How would you display in the legend that the node-size is representing the node degree?

Best M

Here the sources of my information:

http://manual.graphspace.org/en/latest/Uploading_Graphs.html

Cytoscape users may export their visually-coded networks from Cytoscape and import them directly into GraphSpace. This functionality works as follows. Since v3.1, Cytoscape has supported export of the structure of networks into JSON files and the visual elements of networks in JSON-based style files. GraphSpace can import both these types of files at http://graphspace.org/upload.

http://manual.graphspace.org/en/latest/GraphSpace_Network_Model.html#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.

[tmmurali]

@matthiaskoenig Thanks for the follow up questions. Since you have raised many points and GitHub does not support inline responses, I have highlighted your statements in blue.

• GraphSpace and cytoscape.js support a JSON style format (probably the same format)

Yes, GraphSpace relies entirely on Cytoscape.js for graph layout and specifying styles.

• This JSON style format translates to CSS for a given node or edge

Yes, we believe this is true.

• The styles are defined for individual nodes or edges, but no global visual mappings exist

This statement is not entirely correct. Something like a global visual mapping is possible using the concept of mappers http://js.cytoscape.org/#style/mappers, e.g., by specifying that the node size be proportional to the node degree.

So what I take away from this is that the style system of cytoscape.js and GraphSpace is inherently very limited and not sufficient. I.e., there is nothing like style rules (which you would use for the legend, but every node and edge style is listed individually). Please correct me if I am wrong, but this is what I took away so far.

I hope it is clear that mappers in Cytoscape.js do what style rules accomplish in Cytoscape. Please correct me if I am wrong.

The way I look at it, there are two issues here:

(i) Specify how each node/edge should be drawn. Mappers are very powerful in this regard and are akin to visual style rules.

(ii) Tell a person viewing a graph on GraphSpace what each visual style means biologically, e.g., that all blue rectangles correspond to transcription factors or red edges correspond to phosphorylation reactions This is the information we want to specify in the legend.

We are not aware of how to create a legend for a graph programmaticallu using any functionality in Cytoscape.js. (Is this possible in Cytoscape?)

The goal of this GSoC project is to provide the user an API and a user-interface (on GraphSpace) to create a legend for a graph.

Having said that, the title of the project is misleading. We should say "Implement an API and user-interfacre to create a graph legend on GraphSpace."

Please let me know what you think about the overall project now.

On Mon, Mar 12, 2018 at 5:23 AM, Matthias König notifications@github.com wrote:

Trying to understand a bit more what is going on with styles in GraphSpace and cytoscape.js. Basically the information I could get was in summary:

• GraphSpace and cytoscape.js support a JSON style format (probably the same format)
• This JSON style format translates to CSS for a given node or edge
• The styles are defined for individual nodes or edges, but no global visual mappings exist

So what I take away from this is that the style system of cytoscape.js and GraphSpace is inherently very limited and not sufficient. I.e., there is nothing like style rules (which you would use for the legend, but every node and edge style is listed individually). Please correct me if I am wrong, but this is what I took away so far.

What one normally is doing with visual styles in networks is mapping certain node and edge attributes to certain classes of nodes and edges via different kind of mappings (continous/pass through). E.g. given users want to say that one attribute like node shape codes for one type of node (retangle-reaction, circle - species, triangle - regulation), the size for something else (for instance node degree encoded as continous mapping on node degree), the color for something else (for instance location: green cytosol, blue extracellular, ...). This is basically how visual attributes are used to encode information in networks and these mappings are what the legend should inform the user about. It looks to me that cytoscape.js as well as GraphSpace don't have support for these VisualMappings, so I don't understand what should be displayed in the legend?

As I understand it the user would have to write additional JSON for the legend to define all the node and edge classes? This works for discrete mappings like shown in your example (but still misses the whole point of visual styles). But this does not work for continous mappings? How would you display in the legend that the node-size is representing the node degree?

Best M

Here the sources of my information:

http://manual.graphspace.org/en/latest/Uploading_Graphs.html

Cytoscape users may export their visually-coded networks from Cytoscape and import them directly into GraphSpace. This functionality works as follows. Since v3.1, Cytoscape has supported export of the structure of networks into JSON files and the visual elements of networks in JSON-based style files. GraphSpace can import both these types of files at http://graphspace.org/upload.

http://manual.graphspace.org/en/latest/GraphSpace_Network_ Model.html#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.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/nrnb/GoogleSummerOfCode/issues/114#issuecomment-372242545, or mute the thread https://github.com/notifications/unsubscribe-auth/AGkWUNHcNUN7E2OE488SXy2aX7r_jOU0ks5tdj6NgaJpZM4REPbM .

[tmmurali]

Well... "blue" text does not appear in blue. Sorry about that.

[adbharadwaj]

This project is open for GSoC 2019.

Please refer to instructions for potential GSoC students to get started.

[sanket0211]

Hi Aditya,

I am interested in working on this project for GSoC 2019. How should I proceed? I have Graphspace installed on my PC. I have also made myself well versed with the code.

-Sanket

On Mon, 7 Jan 2019 at 14:01, Aditya Bharadwaj notifications@github.com wrote:

This project is open for GSoC 2019.

Please refer to instructions for potential GSoC students https://github.com/Murali-group/GraphSpace/wiki/Instructions-for-Potential-GSoC-Students to get started.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/nrnb/GoogleSummerOfCode/issues/114#issuecomment-451857977, or mute the thread https://github.com/notifications/unsubscribe-auth/AJXSydY61XdI92LfOfDwxUzr7HUqqs7wks5vAwXKgaJpZM4REPbM .

[adbharadwaj]

@sanket0211 Please refer to instructions for potential GSoC students to get started.

[khanspers]

Active GSoC 2019 project.