momapy: A Python Library to Work with Molecular Maps

1. Introduction

Molecular maps are graphical representations of the molecular mechanisms underlying biological systems. They are detailed, curated, and exchangeable graphical knowledge bases that help to understand the mechanisms driving phenotypes of interest (e.g., diseases [1], induced cellular responses [2,3]). They may also support a variety of analyses, including analysis of omics data and dynamical modeling [4].

Molecular maps are supported by a rich software ecosystem. The available tools allow users to edit (CellDesigner™ [5], SBGN-ED [6], Newt [7]), visualise (MINERVA [8]), render (Newt, MINERVA, SBMLDiagrams [9]), format and convert (libSBGN [10], MINERVA, cd2sbgnml [11]), query (STONPy [12]) or model (SBGN2AN [13], CasQ [14]) maps. However, operations required for advanced programmatic analysis and processing are not supported by any of these tools. For example, it is currently not possible to extract the biological concepts represented by a map or to compare two maps automatically.

Here we introduce momapy, a generic Python library for working with molecular maps efficiently. At its core, momapy separates the model of a map from its layout: while the model of a map describes what biological concepts it represents, its layout describes how they are represented graphically. This distinction is borrowed from the Systems Biology Markup Language (SBML) [15], where a model defines a set of reactions and their associated mathematical equations, but may be augmented with a graphical layout using the layout and render packages [16,17]. momapy generalises this distinction and applies it to the Systems Biology Graphical Notation (SBGN) [18] and CellDesigner™ [5], two of the main standard languages to represent maps graphically.

2. A momapy Map: A Model, a Layout, and a Layout-Model Mapping

In momapy, a map is made up of three distinct elements: a model; a layout; and a layout-model mapping. The model of a map is a structured collection of model elements that encode the biological concepts represented in the map. momapy defines a hierarchical data model for each type of map it supports (SBGN PD [19], SBGN AF [20], and CellDesigner™ [5], see Section 3.1 for more details), formed of class and subclass relations encoding the biological concepts based on the map type and their hierarchy in the Systems Biology Ontology [21]. The encoded biological concepts include entity pools, processes and modulations for process description types of maps (SBGN PD, CellDesigner™), or activities and modulations for activity types (SBGN AF). The layout of a map is a structured collection of layout elements encoding the glyphs (graphical symbols) of the map. Each layout element encodes a specific shape (e.g., a circle, a rectangle with rounded corners) whose attributes define how it may be rendered (e.g., its position, dimensions, fill color). A layout element may itself contain other layout elements, giving a tree-like structure to the layout, similar to DOM-based documents such as HTML or SVG. Finally, the layout-model mapping associates each layout element of the map with the model element it represents.

3. momapy’s Features

At its core, momapy allows users to extract a map’s model and layout, and work with them programmatically through a variety of features. These are summarised in Figure 1A, and detailed below.

3.1. Supported Map Formats

momapy currently supports SBGN (PD and AF) and CellDesigner™, two of the main languages used to draw molecular maps. SBGN maps may be read and written from/to SBGN-ML, and CellDesigner™ maps read from the CellDesigner™ exchange format (based on SBML).

3.2. Exploring and Manipulating Maps

momapy elements (maps, models, layouts, and their sub-elements) are made readily available as Python objects, that can be easily explored and manipulated programmatically. Notes and annotations (as defined by SBML) are made accessible outside of the map they describe, complying with the FAIR principles on the separation of metadata from data [22].

3.3. Comparing Maps

momapy elements are implemented in a way they can be easily compared programmatically. This implementation also allows users to check whether a momapy element belongs to a given set of objects efficiently, which is crucial for some applications where one needs to compare large sets of maps (e.g., sets of SBGN bricks instances [23]).

3.4. Styling and Style Sheets

Using momapy, the graphical style of layout elements may be extensively customised. momapy supports the modification of common presentation attributes such as stroke and fill colors or line width, but also the application of advanced graphical effects such as shadows. These custom styles may be applied directly to the individual layout element objects, or using user-defined CSS-like style sheets (see Figure 1B, C). momapy also includes a set of predefined style sheets, that mimic the graphical style of several common map editors such as Newt [7], SBGN-ED [6], or CellDesigner™ [5].

3.5. Rendering of Maps

momapy may be used to render layouts of maps to images (e.g., SVG, PNG, JPEG, PDF files) or directly to the screen (e.g., OpenGL windows). The rendering is done offline using different alternative common backends (SVG-native, Skia (https://skia.org/), Cairo (https://www.cairographics.org/)), enabling the embedding of momapy in other applications on all platforms. Rendering with momapy supports all the aforementioned styles, including advanced graphical effects (depending on the backend).

3.6. Extending momapy with New Formats and Functionalities

momapy offers a set of abstract and concrete classes that may be easily extended for the fast development of new data models and glyphs. An example of such an extension is momapy-bel (available at https://github.com/adrienrougny/momapy_bel), which adds support for BEL models [24] to momapy. Since momapy is built as a library, it can be freely used by third-party tools to work with molecular maps. Examples of such tools include momapy-kb (available at https://github.com/adrienrougny/momapy_kb), which allows users to integrate molecular maps into a graph database, and momapy-draw (available at https://github.com/adrienrougny/momapy_draw), a tool based on momapy’s rendering capabilities to draw SBGN and CellDesigner™ maps programmatically.

4. Software Implementation and Availability

momapy is implemented in Python (RRID:SCR_008394). Its code is freely available from https://github.com/adrienrougny/momapy under a GPLv3 license. Complete documentation and a user manual are available at https://adrienrougny.github.io/momapy.