webANIMO: Improving the accessibility of ANIMO

Implementation

One of the most important aspects of the architecture of webANIMO (see Figure 1) is the task division between client and server. Since web browsers have limited memory and processing power, the tasks of the client are kept to a minimum. The main task for the browser is visualization, while all the calculations are kept server-side and are delegated to a headless version of ANIMO. Cytoscape JS 2.6.1⁷ is used to handle the visualization of networks. However, in order to give the web version the same functionality as the desktop version of ANIMO, many additions and modifications were necessary. webANIMO gives the user most of the features that the desktop version also provides, for example, the ability to add, edit and delete nodes or edges in the network and visualize the changes of activity level over time, using a graph and changing the colours of nodes. Major features of ANIMO that are not included in webANIMO are parameter fitting, model checking and a history of previous simulations.

Figure 1. Architecture diagram for webANIMO.

User interface

Since the interface of the desktop version of ANIMO is relatively complex, the decision has been made to make the web interface different, but effort has been spent to maintain all the features of the desktop version. The interface of the web version in general still resembles the desktop version. The upper section of the page is used for a taskbar, which contains submenus. The left of the page is used for the legend and the analyse options. The rest of the page is used by the network view and the result view. The width of these two views can be adjusted to the users need. Figure 2 and Figure 3 show the desktop and the web versions, respectively, for visual comparison.

Figure 2. Screenshot of desktop ANIMO⁸.

Figure 3. Screenshot of webANIMO.

Editor (network view)

The editor has been built using Cytoscape-JS⁷, which provides the basic functionality for loading a network and displaying the nodes and the edges. The functionality to add, edit and delete nodes and edges has been added, using jQuery 1.12⁹ in order to make it easier to program this functionality. Cytoscape-JS provides events for tapping on nodes and edges: these events hide and show the Edit window. Changes made are shown instantaneously. jQuery change() events have been bound to all the input fields that can be edited in order to provide instant feedback to the user. For example, when the user changes the activity level of a node, the colour will change simultaneously. The webANIMO editor also provides undo- and redo-functionality to let the user manage changes to the network. Furthermore, the webANIMO editor has support for hot keys: users are able to use common hot keys for undo, redo, escape, enter, zoom-in and zoom-out.

When first starting with webANIMO, the only thing presented to the user is an empty network. In order to better guide the user, the editor has a toolbar with all features: the user can press the buttons in order to add nodes and edges, or to zoom and fit the network to the view. Moreover, the buttons serve as a quick guide. The qTip 2.2.1 library¹⁰ was used to create clear tool tips: when the user hovers over the tool bar buttons, quick tips about using the editor are shown.

Result view

The result view was built using the D3 line-chart plugin¹¹. After a network has been analysed, the webANIMO front-end receives from the back-end the analysed data in JSON format, which is then presented to the user as a graph. Similar to the desktop version of ANIMO, the graph has a slider on top which allows the user to see the activity levels of nodes at different time points: while the user drags the slider along the graph, nodes in the network are colored depending on their activity level at the corresponding time points. A legend is shown at the bottom of the graph: by clicking on the relevant node, users are able to hide and show plot data. The graph also has zoom features, allowing the user to take a closer look at specific points of the graph in more detail.

Import and export

One of the earliest requirements of webANIMO was that it must be compatible with desktop ANIMO so that users can switch back and forth between the online and desktop environment without too much effort and technical know-how.

To make this possible, the functionality of importing and exporting of Cytoscape session files was implemented. Import and export functionality gives the user the option to choose the appropriate working environment. If the user prefers the improved UI and does not mind the reduced feature set of webANIMO the user can avoid installation issues and choose webANIMO. Once the user needs more processing power or more advanced features, the user can choose to export their progress to the native Cytoscape format and continue working in desktop ANIMO. Furthermore, once the user decides (s)he is finished with the advanced feature set of desktop ANIMO and wants to move back to the minimal interface of webANIMO, (s)he is free to do so.

For the sake of usability, the import feature can handle both Cytoscape 2 and Cytoscape 3 session files. For the same reason it was decided to export to the Cytoscape 2 format, because this format is also supported by Cytoscape 3 and it was a simpler export target. The concrete functionality of importing and exporting was written in Javascript and is executed completely client side, which makes it fast even given bigger networks since the networks do not have to be uploaded. This also reduces the workload of the server. The downside to this design choice is that if one of the file format specifications changes, the import feature might need to be updated.

Analysis

When the user presses the ‘Analyse’ button, a request containing the current model is sent to the server, which simulates that model and sends a response back containing the results of the simulation. The UI is disabled during the analysis and the waiting time is limited to one minute, after which the simulation is forced to terminate and no result is sent back. The use of a simulation time-out also reduces server load. The choice to perform the analysis on the server was made so the user is not required to install the tools that are needed to perform the simulation. As an added benefit this may improve the simulation time for the user if the device sending the request has slower hardware than the server (which is usually the case if the user accesses webANIMO through a tablet or smartphone).

The data is sent to the server with an HTTP POST request, containing request data formatted as JSON, as shown in Figure 4 and Figure 5. This JSON document has two required fields, “model”, which describes the biological network, and “minutesToSimulate’, which specifies how many minutes should be simulated. The PHP program that handles the POST request sends the JSON document to the ANIMO back-end Java program. This program performs the simulation and formats the simulation results as JSON, which is printed to standard output. The PHP program reads the results and sends them back to the client.

Figure 4. Architecture diagram for the backend of webANIMO.

Figure 5. Simplified request text for simulation.

The code that performs the simulation is an extension of the desktop version of ANIMO. A JSON input is converted to an ANIMO network object, where all fields in the “data” JSON object are converted to properties in the ANIMO network. The back-end of webANIMO is an addition to the original ANIMO source code, so any changes to the simulation logic will be supported by webANIMO as well.

ANIMO transforms the input model to a timed automata model, which is simulated with UPPAAL 4.1⁴. The output of the simulation is a textual description of the changes in node activity levels over time. This result is converted to a JSON document similar to the one shown in Figure 6, and sent back to the client.

Figure 6. Simplified response text for simulation.

CSV export and import

Users of webANIMO may desire other ways of analysing the results of a simulation. To facilitate this, a feature to export the data to the CSV (comma-separated values) format was added. This allows the users to import the results into, for example, a spreadsheet editor and perform additional calculations or visualise the data. In the exported CSV data, there is a column with time values in minutes, and a column for every plotted node with the activity levels at the corresponding minute. It is possible that one node has an activity value at some time point, where another node does not. In this case the missing value is omitted.

Figure 7. Plot before and after exporting.

In order to confirm that the model of a biological process produces the same results as in real life, biologists can import experimental data in the CSV format. This data is added to the plot window together with the analysis data. For consistency, the format of the imported CSV data must be the same as the exported CSV data.

Persistent session

When a user is working with webANIMO, (s)he would not want to lose their work when they accidentally close their browser. To prevent this loss, webANIMO saves the current state of the network on the user’s device whenever a change is made. The last saved state is loaded again when one revisits the webANIMO application. This functionality was implemented using the new HTML5 web storage API¹². To account for web browsers that do not yet fully support this API, webANIMO uses Mozilla’s backwards compatibility code¹³, which relies on cookies to store data locally.

Plot export

webANIMO plots can also be exported as images. The plot export feature works on the basis that the plot is inherently a Scalable Vector Graphics (SVG) element. This means that the plot is easily modifiable in the browser and it can be converted to a wide range of image formats. These two reasons allow for a robust implementation of exporting the SVG plot to a downloadable image. For an improved user experience the user can choose to directly download an image, or show the exported image in the browser first. The plot export feature is implemented as follows. First the SVG plot element is cloned, to avoid changing the actual plot in the interface. Then, a legend is added, several superfluous elements are removed, and the element as a whole is resized to accommodate a slightly bigger font. Then the SVG is rendered to an HTML5 canvas, which subsequently is exported to the PNG (portable network graphics image) format. This is then, depending on the choice of the user, either presented in a new tab or available for download directly.

Included examples

Although webANIMO is designed to be as intuitive as possible, it might be possible that a potential user does not immediately see all modelling possibilities by just “playing” with their own networks. To provide the user with a more complete overview of everything one can do with webANIMO, the application has packed two example models. The examples can be found as entries of menu-item ‘Examples’: they are called ‘Model base’ and ‘Chrondrocyte’ and were presented in 14 and 5 respectively.

Revision history

When the user changes the current network not only the new network is saved, but also the change that the user performed is saved. During a session (which is ended when the page is reloaded) these changes are accumulated and called a revision. In the “show revisions” view (Figure 8) these revisions are listed and can be clicked in order to view the changes that happened in each of them. The changes are visualized instead of just displayed as text, to allow visualisation of all the new changes in a quick glance. Modifications to edges and nodes are indicated with light blue, creations with green, deletions with red and the unchanged sections of the graph are grey. This makes collaborative work on bigger networks simpler to manage.

Figure 8. Opened the revisions list and displaying changes of revision #2.

Node “Erk” is selected.

Online shared networks

webANIMO allows to share networks with other people. The networks made in webANIMO will by default be saved to the browser’s local storage, so that when reloading or revisiting webANIMO the same network is loaded again. However, when a user wants to share the current network with another user, the network (including its revisions and changes) is stored on the web-server. When the network is first sent to the server for saving, the server creates a random (unused) filename and stores the network in a file with this name. This filename is a random 128-bit value in hexedecimal form, so that guessing filenames is not feasible. The user is then redirected to ./?network=N, where N is the filename of the file that stores the network. This filename is also the network identifier and is unique. The user can then share this link with other users: upon opening the link the associated network is loaded. The changes to the network are regularly saved to the file and can be seen as revisions (Figure 8).

To prevent multiple users editing the same network simultaneously and overwriting each other’s changes, a lock file is created on the server for each network. In this lock file the ip-address of the user editing the file is stored. When opening a link for a network a comparison is performed on the last time the lock was used and the current time. If the file is recently used by another ip-address, the network will be loaded, but an error is displayed indicating that changes will not be saved to the server.

Operation

To run webANIMO, the user needs any internet connected device with an (up-to-date) modern browser. Browsers such as Chrome 51, Firefox 47, Safari 9.1, Edge 25 and Internet Explorer 9+ are capable of running webANIMO, although it has been most extensively tested on Chrome and Firefox.

Installing webANIMO on a server requires PHP version 5.2 or higher, Java version 8 or higher and an UPPAAL 4.1 installation.