User documentation

General functioning

MetExploreViz is a tool to visualize metabolic network. It allows to map "omics" data and to interact with metabolic networks. It is usable as a javascript library via the MetExplore web server or within your website.

MetExploreViz works by taking as input:

JSON must have a particular format to work in MetExploreViz. The format of this JSON must follow this template:
    {
        nodes:
        [
            {
                "name":"RE1473",
                "dbIdentifier":"R_RE1473C",
                "ec":"2.3.2.2",
                "id":"938355",
                "reactionReversibility":true,
                "biologicalType":"reaction"
            },
            {
                "name":"Coenzyme A",
                "compartment":"m",
                "dbIdentifier":"M_coa_m",
                "id":"1109601",
                "isSideCompound":false,
                "biologicalType":"metabolite",
            }
        ],
        links:
        [
            {
                "id":"938355 -- 1109601",
                "source":1,
                "target":0,
                "interaction":"in",
                "reversible":"true"
            }
        ]
    }
    


Soon other attributes can be used to have more informations on the visualisation.

Visualisation from JSON file

To used a JSON file you should use the browse button on the top left corner. Choose a JSON file which follows MetExploreViz requirement. And the visualisation will be launched.

Basic features

After created the network representation, you will be able to:

  • Move or zoom in the drawing via mouse interactions;
  • Once the algorithm is providing a relevant drawing you can pause the animation.

Mouse interaction: Zoom and pan

Panning: By pressing the mouse wheel you can then translate the drawing.
Zooming: using mouse wheel you can zoom in and out. Zoom will be centered on the mouse position

We also provide zoom for laptop mouse pads.
  • Zoom in the drawing via this button:
  • Zoom out the drawing via this button:
  • Pan the drawing via this button:

Force directed animation

The default way to draw the metabolic network is by using a force directed algorithm. This algorithm simulates a forces on edges between nodes. It allows animation.

Click on the button to stop the animation.

Click on the button to start the animation.

Interactive visualisation

MetExploreViz provides direct interactions with nodes. So, you can:

  • Remove node with right click;
  • Select node by:
    • clicking on node;
    • grouped selection.
  • Select a node and its nearest neighbours by clicking on node with "N" key:
  • Drag and drop nodes. You can also move all selected node with "ctrl" key.

Remove node

MetExploreViz provides a function to remove nodes with right click.

Mining networks

Networks may be quite dense and can involve reactions and metabolites that are of no interest for the current study. To lower the complexity of the representation we are developing “mining” methods based on graph algorithms.

The aim is, given a set of nodes, to try to compute relevant paths between each pair of nodes. A path is a set of reactions that allows to go from one element in the network to another.

Remark: not that reactions can be used only once, avoiding artificial loops on paths.

This function can have two kinds of inputs:

  • A selection of nodes: by left clicking on nodes you can select some of them and then start the computation;
  • Mapped data: if there is no manual selection, nodes with mapped data will be used for the computation.

Extract subnetwork

This function allows to keep only links and nodes in the subnetwork. All other will be removed.

Drawing

Curvy drawing

Since version 2.0 MetExploreViz allows to draw metabolic networks with a curvy style. It is classic style to visualise metabolic pathways.

To ease visualization and interpretation of metabolic networks, MetExploreViz allows to duplicate or remove side compounds, change nodes position or highlight compartments or pathways.

Side compounds

In metabolic networks compounds are considered of variable important in metabolism flow. Taking into account this heterogeneity is important to avoid interpretation mistakes and to facilitate visualization. MetExploreViz allows to:

  • Duplicate side compounds;
  • Remove side compounds.

To do this the attribute value "isSideCompound" of metabolite must be set to "true", and the action can be picked from the drawing menu.

Highlight pathways or compartments

To facilitate visualization of pathways or compartments MetExploreViz allows to draw convex hull around it. So you can choose the pathways or compartments to display.

To see only particular pathways you can abstract pathways

To facilitate visualization of network MetExploreViz allows to replace all reaction present in a pathway by a node. So open Network Manager and Pathways tab, check highlight pathways, right click on convex hull drawn and click on collapse selected pathway(s).

Highlight pathways enrichment on pathways abstraction

To have global and statistical representation of network you can abstract all pathways and map pathway enrichment of your mapping on pathways abstraction So right click on visualisation and click "collapse all pathways". Map your data with "PathwayEnrichment" and "PathwayCoverave" conditions. And select your mapping in the top left.

Layouts

To group substrates and products on each side of a reaction, click on "Reaction components direction" in the drawing menu.

Align nodes

To make vertical or horizontal alignment on selected nodes.

Shortcuts are implemented click V key vertical or click H key horizontal alignment on selected nodes.

Export

These drop-down menu allow you to export the visualization in SVG, PNG, JPG or as HTML link.

Export visualisation as HTML link

This feature provides a full range of methods for creating, sharing and managing visualisations via HTML links.

Indeed, this feature allows users to create an HTML link for the current visualisation. This link, which is shareable, allows you to return to your visualisation in state. This means that the different mappings (omics or images), the style, the position of the nodes or labels, etc ... will be restored in the export.

This feature also contains a panel to manage your different exports. This panel provides you with a complete list of the different exports you have made and a set of methods to manage them. This panel is accessible in the MetExplore interface. (see MetExplore documentation)

Moreover, if you access an export which is in “Write” mode. You can save modifications you do on this export.

You can also share a visualisation for local use. This option allows you to download the visualisation and the necessary environment into an archive. Once the archive is downloaded, simply unzip it and open the index.html in a browser.

First of all, if you want to use this feature, you need to create an account and log in. Furthermore, you can only create 20 exports per user.

Create a HTML export

Once you are satisfied with your visualisation, in the header, in the export menu, you will have an option called “Export Viz as HTML link”. This button will allow you to save the current visualisation.

Then, you will have to enter the name of your export. (Tabulation is forbidden)

Once you have named your export, you will get the confirmation panel allowing you to access your export or to copy the link from it.

Manage your HTML exports

In order to allow you to manage your different exports, a table has been added to the “User Profile” tab.

This table allows you to have the main information on your exports: name of the export, BioSource used, its mode (Access = Write or Read) and the last modification date which also corresponds to its creation date.

By selecting an export in the table, you unlock the buttons allowing you to perform the different actions possible on your exports:

  • Get link: allows you to get the link of the selected export
  • Copy export: allows you to copy the selected export
  • Change export name: allows you to change the name of the selected export
  • Block / Unblock modification: switches the mode of the selected export
  • Export local version: allows you to download the export in an archive with the necessary environment for local usage (without internet connection)
  • Delete: allows you to delete the selected export
  • You can also double-click on a row to open the export in a new tab.

    Modify a HTML export

    When you access an export that is in “Write” mode, you will be able to make changes to the export and save them.

    In the “Export” drop-down menu, instead of the button for exporting, you will find a “Save modification(s)” button which will allow you to save the visualisation as is.

    To avoid any problems, I invite you to share only the exports that are read-only. Keep the writable links for yourself, so you can adjust your exports if necessary.

    Import

    You can import files to enrich your network.

    Images

    To map an image side of node you can select multiple files to map it. You just have to put the same name that nodes to assign it.



    It is possible to change colors. To do this change the hexadecimal value or select a color in the color picker, and click on refresh button .

    Side Compounds

    The side compounds import allows you to assign metabolites as a side compounds. After this import, it's possible to duplicate side compounds. The text file must contain metabolite identifiers.



    Mapping

    The mapping import allows you to import data on metabolites or reactions and highlights/colors the nodes according to the provided numerical values.

    First you could import tab file with some requirements:

    • "identifier"
    • "conditionName."
    • "identifierN."
    • "x" values

    identifier    conditionName1  conditionName2 ...
    identifierN1   x    x1 ...
    identifierN2   x2   x3 ...
    identifierN3   x4   x5 ...
    identifierN4   x6   x7 ...
        


    "identifier" allows MetExploreViz to identify the corresponding nodes. The following identifiers are currently supported:

    • "reactionDBIdentifier"
    • "metaboliteDBIdentifier"
    • "inchi"
    • under development:
      • "name"
      • "your attribute"

    "conditionName." can arbitrarily chosen.

    "identifierN." allows to MetExploreViz to recognize nodes on data.

    "x" are the values given to one component under each condition.


    In order to import your file, click on mapping button.

    Flux data

    MetExploreViz allows you to import data on reactions to visualize flux values on links according to the provided numerical values.

    Optional: You can also import your standard deviation (sd) values to visualise them on your network.

    First you need to import a tabulated file containing the flux values with the following columns :

    • "reaction identifier"
    • "conditionName" (one or several columns with flux values)
    • "sd_name" (optional: one or several columns with sd values)

    identifier    conditionName1  conditionName2 ... sd_name1  sd_name2 ...
    identifierN1   x    x1 ... y     y1 ...
    identifierN2   x2   x3 ... y2    y3 ...
    identifierN3   x4   x5 ... y4    y5 ...
    identifierN4   x6   x7 ... y6    y7 ...
                            


    Downloadable example can be used on MetExplore2 biosource #1808

    The "identifier" column allows MetExploreViz to identify the corresponding reaction nodes. The following identifiers for the column header are currently supported:

    • "Identifier"
    • "Name"

    And should correspond the reactions identifiers or names as specified in the "network data" > "reactions" grid.

    "conditionName." can arbitrarily chosen.

    "x" are the values for each reaction under each condition.

    To define a column of sd values, you need to add the label "sd_" before the name

    "y" are the sd values for each reaction under each sd columns.

    All values must be separated from each other by a tab


    In order to import your file, click on "Import > flux data" button.

    Customization

    MetExploreViz allow you to custom your visualization by settings metabolites, reactions and links styles.

    All these styles can be updated throught 3 modes:

    • Default : Style will be apply to all nodes or links.
    • Mapping : Style will be apply to nodes or links mapped by selected data, it override default.
    • Bypass : Style will be apply to nodes or links selected in visualisation, it override defaultand mapping.
    JSON can be used to save your work. It can be reloaded in MetExploreViz Styles.

    Mapping

    After choosing a file, MetExploreViz maps values on nodes and open the "Network Manager" window.

    To apply mapping :

    • Expand the "Styles" menu in the left panel
    • Expand a menu in fonction of the mapped component
    • Expand a menu corresponding to style to map
    • Select your dataset in the “Select a condition” dropdown menu
    • Select the type of data in function of the type of data mapped

    Discrete

    To apply mapping on Metabolites background node :

    • Expand the "Styles" menu in the left panel
    • Expand the "Metabolite" menu
    • Expand the "Node background" menu
    • Select your dataset in the “Select a condition” dropdown menu
    • Select the type of data “Discrete”
    When you choosing discrete values, a color/value is assigned to each data mapped on the network. So, if 3 differents numbers as -1 0 1 as assigned to mapped components, 3 captions are generated.

    Identified in mapping

    This option will apply a visual style (color/value) only on nodes identified in a mapping, not considering the values associated to this mapping.

    Continuous

    To apply mapping on Metabolites background node :

    • Expand the "Styles" menu in the left panel
    • Expand the "Metabolite" menu
    • Expand the "Node background" menu
    • Select your dataset with continuous values like folds in the “Select a condition” dropdown menu
    • Select the type of data “Continuous”

    When you choosing continuous values, a linear grandient is assigned from min to max values of data mapped on the network.

    New scale editor allows you to adjust the value scale to your data so click on scale caption to open it.

    To adapt mapping to your data you can click on each triangles to update values. The "Add" button allows you to add intermediary point to customize scale.

    For example to fit with folds data :
    • Click on Min triangle
    • Set value to 0
    • Set color to red
    • Click on top left triangle
    • Set color to red
    • Set value to 2
    • Click on Add button
    • Set value to 1
    • Click on OK button
    Color scale and mapping ids updated.

    Do the same for width and height:

    • Map fake folds on metabolites
    • Expand the "Node background" menu
    • Select your dataset in the “Select a condition” dropdown menu
    • Select the type of data “Continuous”
    Basic linear scale between your min max values appears.
    • Click on value scale
    • Click on 2nd left circle
    • Set value to 0
    • Set number to 50
    • Click on 1st left triangle
    • Set number to 50
    • Click on 2nd right circle
    • Set value to 2
    • Set number to 50
    • Click on 1st right triangle
    • Set number to 50
    • Click on Add button
    • Set value to 1
    • Set number to 10
    • Click on OK button

    Number scale and mapping ids updated.

    Flux

    MetExploreViz allows you to manage your visualization of flux data on your network.

    After a successful flux data import, the flux panel is enabled in the "Network Manager" panel and allows you to manage and display your visualization :

    • Select an imported file to use (all flux data files imported during the session will be listed here)
    • Select the number of conditions you want to display on your network (one or two, corresponding to the file columns)
    • Select your condition(s) and the color associated
    • Select the scale to apply: automatic, proportional or manual

    Each scale mode computes links width differently.


    Automatic scale

    For this mode, three markers are created; one for the minimum width value, which corresponds to the minimum flux value; one for the maximum width value, which corresponds to the maximum flux value; and the last one for the intermediate width value, which corresponds to the median, first or third quartile (depending on the dataset distribution). Between these three markers, width value is proportional to the flux value.


    Proportional scale

    For this mode, only two markers are created; one for the minimum flux value and one for the maximum flux value. Between these two markers, width value is proportional to the flux value.


    Manual scale

    Manual scale allows you to manage the scale that will be applied on your network. As for the mapping, you can edit scale parameters from a scale editor.


    After selecting parameters, you can click on Display button to create flux data visualization and a distribution graph of your dataset.

    If you change some parameters, you can click on refresh button to recreate new visualization with new parameters.

    MetExploreViz provides you a distribution graph of your dataset in use.

    For automatic and manual scale, vertical lines appear on the distribution graph. These vertical bars represent markers (intermediate width values) used to compute links width.

    The distribution graph is computed from all the data present in your file for the selected condition. But if you delete some nodes and you want to see distribution only for the remaining part of your data, you can click on "Distribution graph : only displayed data" and your distribution graph is compute with only the data of the nodes present in the current network.


    You can also add labels with flux values or sd values on your network. You can change font size and reaction label to use (Name, identifier or nothing).

    Save

    These functions allow you to save the visualization in JSON, DOT or GML.

    • JSON can be used to save your work. It can be reloaded in MetExploreViz.
    • DOT and GML are simple ways of describing graphs that both humans and computer programs can use.

    Network comparison

    MetExploreViz allows the comparison of a metabolic network under several conditions.

    Duplicate network

    It is possible to duplicate network in another frame to visualise separately two conditions.


    To do this click on this button and give a name to the network.

    Link and compare representations

    After duplication you can link by clicking this button the two representations of network to have the nodes in the same position of the original graph. If data have been mapped onto the original network the same colors are assigned to the nodes. So you can compare easily a network with different data.

    Example

    Search node

    MetExploreViz allows you to search nodes in metabolic network.

    To do this, enter the name, id, compartment of a node and click on the "search" button .

    Set node name

    MetExploreViz allows you set node name in visualisation.

    To do this right click on a node and select 'Change name' menu.

    Set select neighbours

    MetExploreViz allows you select neighbours of a node in visualisation.

    To do this right click on a node and select 'Select neighbours' menu.