Making high-level-pathways illustrations interactive

Introduction

The Enhanced High Level Diagrams (EHLD) project aims to improve the graphical representation of higher-level pathways in the Reactome events hierarchy, e.g., “signal transduction”, “apoptosis”, or “metabolism” whose pathway diagrams consist of green boxes labeled with the names of sub-events, optionally located in cellular compartments and connected by arrows. These green-box diagrams feature limited navigation: clicking on a green box takes the user to that sub-event. In some cases, an illustrator has also created a graphic representation of the event. However, these illustrator diagrams offer no navigation functionality.

There was a general agreement that green-box diagrams are not that appealing, and put off users accustomed to textbook-quality illustrations of biological processes with striking, intuitively clear iconography. Meanwhile, while our illustrations often are up to textbook standards, they are static images. The project included generation of scalable vector graphic (SVG) versions of illustrations, and the development of software that will make these SVG images navigable in the way that the green-box figures are now, and also to provide user interactivity by progressive zoom in/out, actions when hovering over the items or selecting them and showing the associated content in the details panel for the selected items.

This project has also driven the development of a consistent iconography, a controlled visual vocabulary for biological processes like the controlled word vocabularies we already have for names of physical entities and reactions.

This document includes two main sections. The first section describes in detail the process that should be followed to create an EHLD. The second section of this document provides guide through the process of creating and including new graphic elements into the Reactome EHLD icons library.

Enhanced High Level Diagrams guidelines

This section aims to guide you through the process of creating an EHLD. The following paragraphs aim to summarise the set of requirements and guidelines the illustrator should follow in order to produce EHLDs that are compatible with Reactome Pathway Browser v3.4.

Generic guidelines

In Reactome, an EHLD is an interactive graphical representation of a higher level pathway diagram, typically containing two or more subpathways as active regions. An active region refers to a group of shapes representing a single subpathway. In particular, users can interact with active regions by hovering or selecting them, as well as use them to navigate to the subpathways they represent.

 

EHLD representing the Hemostasis branch of the Reactome event hierarchy. (a) Pathway hierarchy view for Hemostasis. (b) Hemostasis as an EHLD representation. (c) Hemostasis EHLD overlaid with pathway enrichment analysis results.

Generic guidelines

To make all these possible, there is a set of initial requirements to be taken into account during the generation of the EHLDs.

  • EHLDs must be in SVG format. Illustrators are free to use the design tool of their preference but at the end their diagram must be exported to SVG.
  • The use of raster graphics is strongly discouraged as it results in larger file sizes and it has a negative impact on software performance. Also, by including bitmap images we cancel out resolution-independent zooming, which is one of SVG’s main advantage.  
  • All exported SVG files should include the styles in an internal CSS stylesheet. Please make use of this option when exporting from Adobe Illustrator: Export As -> SVG -> Styling: Internal CSS. If you are using another application to create the EHLDs, you will need to configure it appropriately.
  • The name of each EHLD file has to be the Reactome Identifier of the corresponding pathway diagram, followed by “.svg”. For example, the Apoptosis EHLD should be named as R-HSA-109581.svg. Please keep in mind that only one EHLD should be created per high level pathway diagram.
  • Active regions are annotated using the id attribute of their group element (inside the SVG file) and can be classified in the following two groups:
    • Regions containing a group of irregular shapes (including text) that can be selected (and hovered) in order to navigate to the respective pathway diagram. These regions should be annotated by setting their id attribute to “REGION-+ Reactome Identifier of their represented subpathway, e.g. “REGION-R-HSA-109581”. This type of active regions may include arrows pointing to or from them and they are not mandatory.
    • Regions containing the label of the represented subpathway in a box-like shape that can be not only selected but also overlaid with the results of the analysis. These regions should be annotated by setting their id attribute to “OVERLAY-+ Reactome Identifier of their represented subpathway, e.g. “OVERLAY-R-HSA-109581”. Regions of this category must not include arrows pointing to or from them, and they are mandatory.
    • Please keep in mind that if we need to annotate both types of active regions for a given subpathway, the region (“REGION-R-HSA-109581”) has to include the overlay component (“OVERLAY-R-HSA-109581”). In other words, the group of the selectable shapes has to include the group of shapes that can be overlaid.
  • Any group of shapes, text or graphical elements that are not annotated as active regions are considered decorators and users cannot interact with them. They have pure esthetic value and they cannot be selected, hovered or overlaid.   
  • If possible, no background covering the whole image should be put in place. Please note that compartments or other necessary backgrounds can be kept, but we suggest to avoid “unnecessary” backgrounds. In case a background is required, but it is too big to fit in the illustration, it is suggested to draw only a small part of it with clear and well defined boundaries (See the blood vessel in the EHLD of Hemostasis above).
  • Text elements should not be converted to groups of shapes. Instead, use the normal <text> SVG element.

Example illustrating the two types of active regions. Selectable regions (annotated with “REGION-” + Reactome Identifier) are highlighted in red, while regions that can be overlaid are highlighted in brown. Shapes and text that are not annotated as active regions are considered decorators (presented in blue) and users cannot interact with them.

Taking the aforementioned requirements into consideration, the EHLD of the figure above should have the following structure:

  • REGION-Pathway A # The whole pathway will be selectable #
    • OVERLAY-Pathway A # Only the label will be overlaid #
  • REGION-Pathway B # The whole pathway will be selectable including the arrow #
    • OVERLAY-Pathway B # Only the label will be overlaid #
  • REGION-Pathway C # The whole pathway will be selectable including the arrow #
    • OVERLAY-Pathway C # Only the label will be overlaid #
  • OVERLAY-Pathway D   # The whole pathway will be selectable and overlaid #
  • DECORATORS # None of the shapes are selectable or can be overlaid #

Creating an EHLD step by step

We suggest starting a new EHLD by creating an Adobe Illustrator document with 1366px in width and 768px in height and using the RGB colour mode.

Pathway Labels should have centered, white, uppercased, text using Arial Bold font at 12pt inside a rounded rectangle with 8pt radius, minimum width of 170px and height of 30px for single lines or 43px for double lines. The colour of the rounded rectangle should be #0F82BC (R:15 G:130 B:188). We suggest writing the name of the subpathway it represents as it appears in the Reactome hierarchy. In case of a discrepancy, or any kind of oddity, please contact the author or the curator related to the pathway.

Please use the same specifications for any other written element except for:

  • Descriptions of a process should always be black and in lowercase letters.
  • Any written element that belongs to a compound, protein or cell (generically inside of any coloured shape) should be white and in uppercase letters (when possible).
  • Any written element that belongs to a receptor and/or describes a cell element or a process (generically outside of any shape) should be black and in lowercase letters (when possible, usually receptors are named by acronyms and capital letters should be used in these cases).
  • Greek or other Unicode characters must be avoided in text elements. Thus, names with greek characters should include the whole word (e.g. alpha instead of α) written in lowercase.
  • Reactome logo should always have 50% opacity.

Every pathway label should have one Analysis Information Label. The latter is used to display additional details about the hit elements and the false discovery rate (FDR). All analysis information labels should be annotated as “ANALINFO” in the Layer Hierarchy Panel. Place “XXX/YYY” as a text placeholder inside it. Text should be centered and uppercased in Arial Bold 9pt, and in white colour. The box should be a rounded rectangle with 8px radius, minimum width of 170px and 20px height. Its fill colour should be #C6C6C6 (R:198 G:198 B:198). Also, set the opacity of the group to 0%, but make sure you leave the opacity of the shapes and text inside the group to 100%. Each analysis information label should be placed beside its pathway label and in the opposite side of the content for that pathway. For instance, if the pathway label is above its content, the analysis information label should be placed above the pathway label and vice versa.

In order to better shape the active region (or the clickable area) of a pathway we can add a white shape with 0% opacity under any element of the Pathway in the Layer Hierarchy Panel. In this way we can extent the clickable area and improve the overall user experience while navigating the EHLDs. In particular, we should try to surround the elements of the subpathway covering the gaps within the individual graphic elements, and thus, avoiding the inconvenient situation where the mouse cursor changes from the usual arrow shape to the hand constantly. Additionally, in EHLDs where elements of a particular subpathway are too thin and users find it difficult to select them, this technique can provide a bigger and more convenient clickable area around them. However, we should use this with caution, as creating too large clickable areas can mislead users.

It is recommended to place all arrows and neutral text elements in a group at the top of the layer hierarchy. As well, all decorators and elements in the background that we do not want to highlight or be clickable, we recommend to place them in a group at the bottom of the layer hierarchy.

Reactome displays EHLDs in a blank zoomable space. For a better user experience we suggest to have all shapes and elements portrayed in full. However, we understand that some pathways are large and contain too many and too big elements to fit in one image. In cases where the illustrator needs to cut an element and it is difficult to make a clean representation of the cut, we suggest the addition of a gradient so that elements vanish keeping the limits of the canvas clear.

In order to export an EHLD we should use the “Export as” option and save the file as an SVG with the following options:

  • Styling: Internal CSS.
  • Font: SVG.
  • Images: Preserve.
  • Object IDs: Layer Names.
  • Decimal Points: 3.
  • Minify and Responsive, both ticked.

The Reactome EHLD icons library guidelines

This section will guide you through the process of creating and including your own graphic elements into the Reactome Library and become a part of this growing community.

Since Reactome is a free and open-source project, the Reactome Library is under a Creative Commons license. As a result, if your creations are included in our library, they will follow the same policy. Feel free to use any tool or application that allows you to create vector graphics and, please, make sure that the following specifications are implemented in the files you will be creating.

Generic guidelines

  • Every element should be placed into a separate file, 200 by 200px in size, with RGB colour mode and White background.
  • Use only Arial Bold 12pt. Text colour should be chosen depending on the text’s position. In case the text is inside a coloured shape, its colour should be White, while in case the text is outside of a coloured shape, its colour should be Black.
  • All text should be Uppercased except for words describing greek characters (e.g alpha, beta, gamma, etc.). In that case those words should be written in Lowercase. It should be noted that Greek or other Unicode characters must be avoided, as they are not  supported for the moment.
  • Your elements should only comprise vector graphics. Please make sure that you have not included any bitmap image in it. Including raster images often results in larger file sizes and thus negatively impacts software performance.  
  • You can place your new element in any of the seven categories of the Reactome Library; Cell elements, Cell types, Compounds, Human tissue, Ion channels, Proteins and Receptors.

Cell elements

Keeping simplicity is one of our targets so we recommend the use of simple figures, such as circles, squares and triangles as a base. For colouring we suggest the use of shades of Primary Colours (Red, Blue and Yellow) and Secondary Colours (Purple, Green and Orange).

Vector graphic applications allow you to use Gradient tools to blend two or more colours for the same shape. We recommend you to use these tools so you can create more appealing graphics. See the Mitochondrion below:

(a) Without the use of gradients, the Mitochondrion element looks plain while in

(b) through the correct use of gradients the element looks more 3D-like,

resulting in a more attractive and playful image.

aCell types

In order to ensure a sense of unity and a consistent look and feel, we suggest applying the same principles; simple shapes and colours.

For representing types of cells, please keep in mind that we are not using scale to portray the different organelles and elements inside the cell cytoplasm. Additionally, to maintain simplicity, try to avoid overloading the the overall design with too much detail. The following table features 3 examples:


Screen Shot 2017-03-28 at 11.57.55.png

This Microbe element is formed by a circle with a radial gradient of two colours. To represent the membrane, we have added an outline with a different gradient. To convey the idea of danger we use this squares as spikes and a red shade in their gradients.


We have drawn this Macrophage element with shaky tentacles and we have used a not uniform outline (membrane) to give it a soft and flexible feeling.


For this Pathogen element we used a large light gradient to represent a shiny and hard capsule.

To show its death we draw holes on its surface and play with a darkened, sad colour.

Compounds

Compounds are represented by very geometrical elements, following more specific guidelines.

Simple chemical elements or compounds are usually portrayed in the Library with their chemical element symbol (e.g. Ca for Calcium) or the name of the compound (e.g. IFN-gamma) using Arial bold 12pt in White colour.

Simple chemical elements are represented by an octagon of 28px height and two plain colours, one for the fill and a different one for the stroke (2pt). In case the text of the compound is too long to fit in the octagon, we suggest stretching the shape until it fits the name, respecting its lateral edges, like follows:

An example of a simple chemical element.

Complex compounds can be represented with a variety of shapes, always simple and easy to differentiate one from each other.


We can use circles with or without outline.


We can use hexagons, in the same way as for the simple compounds, just adding a gradient on their stroke.

Human tissue

Human tissue elements are mainly used as backgrounds in our diagrams and the way of representing these organs depends on the illustrator’s skills and taste. To ensure unity in the Reactome Library we suggest to keep these illustrations as simple as possible and visualise them as toys; so they convey a nice, soft feeling, with a plastic-like, very friendly and approachable look.

Screen Shot 2017-03-28 at 14.33.14.png

Examples of human tissue elements; Liver and Blood vessel.

Ion channels

These representations are quite simplified and, thus, elements are designed to look like small funnels that cross through the membrane, allowing elements to move from inside of the cell to outside and vice versa. There are hundreds of different ion channels and we suggest differentiating them with the use of colours in various combinations.

Examples of ion channels.

Proteins

There are tens of thousands of different proteins, some of them with specific shapes. Proteins in the Reactome Library follow the standard representation as rounded rectangle shapes. As a result, we suggest using the Rounded Rectangle Tool to draw a shape with 10px radius for the corners and 20px height for single line of text, or 30px for a double line. The stroke should be 3pt and we suggest choosing an irregular profile (in Adobe Illustrator, use the default Width Profile 2). For the name of the proteins we suggest to follow the same guides as before, White Uppercase Arial Bold 12pt.

The shape will contain the simplified name of the protein following the general instructions for Reactome Library. It should be filled with a simple gradient of two colours. One of the  colours of this gradient should also be used as the stroke colour.

Examples of protein elements in their rounded rectangle representation.

In case a protein has a specific shape, we suggest keeping the standard representation as long as it is not too complicated. Otherwise, we suggest opting for a more simplified version.

Examples of protein elements represented in their standard representation.

Receptors

Like proteins, there is a huge number of receptors. In cases where there is a standard, but quite complex, way to represent them, we suggest adopting a more simplified version. If this is too difficult we suggest finding a more simple representation.

Examples of receptor elements

Metadata

You are encouraged to accompany your element with more information including a short description and extra details about its designer and curator. Upon inclusion of your element into the Reactome Library, all metadata information will be available to the public through our landing page.

In order to do so, you need to create an additional metadata file using your favorite text editor. The file should have the following structure:

<metadata>
   <person role="curator" orcid="{ORCID}" url="{URL}">{C_NAME}</person>
   <person role="designer" orcid="{ORCID}" url="{URL}">{D_NAME}</person>
   <description>{DESCRIPTION}</description>
</metadata>

Please follow these steps:

  1. Create a new file using your favorite text editor (TextEdit, NotePad, etc.).
  2. Copy and Paste the text above into your file.
  3. Edit the file and:
    1. Fill {ORCID} and/or {URL} for the curator and designer roles. This is how to find ORCID. In case both URL and ORCID are provided, the link for that person will point to the URL.
    2. Fill {C_NAME} and {D_NAME} as the curator and designer name, respectively.
    3. Fill {DESCRIPTION}.  
  4. Save the file using the same name as the element but make sure to use .xml as its extension. For example if your graphic element is stored with the name “Element.svg” then your metadata file should be named as “Element.xml”.
  5. Make sure to submit your metadata file along with the graphics file.

Export Settings

Currently, every element in the Reactome Library is available in 3 different formats, SVG, EMF and PNG. Therefore, you are kindly requested to export your work into these formats and include them in your submission.

How to submit your work

To include your graphic elements in the Reactome Library, you need to contact our helpdesk (This email address is being protected from spambots. You need JavaScript enabled to view it.). We will then review your submitted files and, depending on the outcome, we will include them in our Library.