Help

SBGN Layout draws SBGN maps automatically: process description (PD), entity relationship (ER) and activity flow (AF). You upload an SBGN-ML file, the server runs a constraint-based layout pipeline made for that language (built on VANTED with SBGN-ED and the Adaptagrams libraries), shows the result in the browser and gives you the drawing as SVG and the map as laid-out SBGN-ML. The service is free for academic and non-commercial use; the software is open source under the GPL-3.0 (see licence).

On this page: a quick tour · sample data · how to read the results · result links, privacy and cookies · limits · troubleshooting · licence and citation. Scripts and batch jobs use the HTTP API.

Quick tour

1. Load a map. Click Upload a map on the start page or Upload SBGN-ML in the sidebar, drop a file anywhere on the page, or pick one of the examples on the start page. Accepted are SBGN-ML files (.sbgn, .sbgnml or .xml) up to 40 MB. The SBGN language is read from the map; Map language in the sidebar overrides it.
2. Lay out again if you need to. Compartment frames distort the layout, so they are removed and the map is laid out as a whole. Lay out again runs the map once more; after a change of the map language the button reads Lay out with new settings.
3. Watch the run. The card shows the upload, the position in the queue and the progress of the layout. Your layouts in the sidebar lists the maps you laid out in this browser, including the ones still running. The address bar now carries the job id (/?job=…): bookmark it or use the link button next to the file name to come back later, see result links. You may also close the tab; the server finishes the layout anyway.
4. Explore the drawing. Zoom with the wheel or +/−, pan by dragging, 0 fits the drawing to the window. The button with the half-filled circle shows the drawing on a dark sheet.
5. Inspect the result in advanced mode: the details panel on the right holds Statistics, Conflicts and Log, explained under reading the results.
6. Download. Download in the top bar gives the final drawing as SVG; the arrow next to it offers the laid-out SBGN-ML, the PNG, in advanced mode the JSON report, and a ZIP with everything.

Press ? in the app for the list of keyboard shortcuts.

Try it with sample data

The bundled maps below are also the examples on the start page. Open laid out loads the map and runs the layout right away, so you see a real, interactive result exactly as for your own upload (most maps take seconds, the large Reactome maps one to three minutes). Download gives the unchanged input file, which also shows the expected file format. The smaller maps are the example maps distributed with SBGN and SBGN-ED; the maps named “Reactome” are Homo sapiens pathways from Reactome, exported as SBGN-ML.

Reading the results

The drawing

The result keeps every glyph of your map except the compartment frames and changes only positions and the course of the arcs. What a good result looks like depends on the language:

• Process description. Every process has its substrates on one side and its products on the opposite side, on a common axis; cofactors sit on the diagonals of that axis and the enzyme (catalysis) perpendicular to it, which gives each reaction the same star-shaped template. Metabolic cycles are drawn as rectangles, chains of reactions along straight lines, and parallel reactions as lenses or fans. Arcs are routed orthogonally around the glyphs.
• Entity relationship. Entities and the nodes of their relationships lie on horizontal, vertical or 45° lines with equal gaps; the outcomes and ports of a relationship (its hyperedge nodes) sit on the straight line between its two ends; influences (stimulation, inhibition, modulation) leave such a node at a right angle with a short straight stub, so their arrowheads stay readable; the output of a logical operator points towards its target and the inputs arrive on the opposite side.
• Activity flow. The influences form a hierarchy drawn top to bottom: a longest path of the flow is the central column, every other activity stands below the activities that influence it, feedback arcs (the few that had to be cut to make the flow acyclic) run upwards, and trees of logical operators are placed as units with their inputs on the input side.

The pipeline section of the API page lists every step of the three pipelines.

The three tabs below appear in advanced mode: switch on Advanced in the top bar, and the details panel opens next to the drawing.

Statistics tab

• Nodes, edges, processes, compartments — what the engine read from your map. Compartment frames are always removed before the layout.
• Constraints — the geometric rules the pipeline generated and the solver kept: separations (one node left of, right of, above or below another with at least a given gap), horizontal alignments (nodes on one row) and vertical alignments (nodes in one column). The line below counts the rules that were dropped as infeasible or left unsatisfied, the same items as in the Conflicts tab. A large total with zero conflicts is the normal case.
• Timings — reading the map, the layout itself and the export, as measured by the engine; waiting time in the queue is not included.
• Map — the language the pipeline used (and the one declared in the file if it differs), how many steps ran, the size of the drawing in pixels, and the job id.
• Warnings — appear only when something was not fully possible, most often that the laid-out map could not be written as SBGN-ML for an unusual construct. The SVG drawing is complete in that case; the SBGN-ML download is greyed out.

Conflicts tab

The pipelines generate constraints from templates (process stars, straight relationships, the flow hierarchy). In a dense map some of them contradict each other, for example when separations and alignments would close a cycle, or two nodes would have to occupy the same point. Such contradictions are found before the solver runs; the contradicting constraint is removed and listed as a dropped conflict. The drawing is still correct, but that one rule is not enforced: the nodes it names may not be aligned or ordered as the template intended. Unsatisfied means the solver accepted the rule but could not meet it exactly, for example because keeping nodes from overlapping took priority. Every entry names the step that added the rule, the kind of rule, the reason, and the nodes involved; the crosshair rings those nodes in the result so you can judge the spot yourself. A handful of conflicts in a large map is normal and needs no action; a map with many conflicts is usually very densely connected, and splitting the map can help.

Log tab

The engine's own log, line by line, with a filter and a copy button. It is useful when a layout fails or looks wrong: copy it into a bug report together with the job id from the Statistics tab.

Output files

• <name>_layout.svg — the final drawing, with a viewBox around the map plus a 40 px border; opens in any browser or vector editor.
• <name>_layout.sbgn — your map as SBGN-ML 0.3 with the new positions, ports and the bend points of the routed arcs. It opens in SBGN-ML editors and viewers such as SBGN-ED (VANTED) or Newt; a viewer that ignores bend points draws the arcs as straight lines.
• <name>_layout.png — a raster image (longest side 4000 px).
• <name>_original.svg, <name>_stepN.svg — the input and the state after every step, written only when an API request asks for them (original, perStep); for a PD map, step 1 is <name>_skeleton.svg, the reduced skeleton graph that step builds.
• <name>_result.json — the report behind the Statistics and Conflicts tabs: language, counts, steps with times and constraints, conflicts with reasons and node labels, timings, drawing bounds and warnings. Its fields are described on the API page.

Result links, privacy and cookies

Result links. As soon as a job is created, the address bar shows /?job=<id>. Bookmark it or copy it with Copy link in the top bar; opening it later shows the job's status (queued, running, done) and then the result. Results are kept for 7 days (under sustained heavy load the oldest finished jobs can go earlier). Your layouts in the sidebar lists them as well. A link opens only in the browser that started the job: jobs are tied to the cookie described below, so nobody else can open your result, not even with the link. To give a result to someone else, send them the downloaded files.

Privacy. Uploaded maps and results stay on this server and are processed by a local layout engine; they are not sent to any third party, not used for anything but your job, and are deleted after 7 days. Other visitors cannot list or open your jobs; a foreign job id answers like an unknown one. Jobs can also be deleted earlier through the API. The site uses no analytics and no accounts, and never asks for an e-mail address. Traffic passes through Cloudflare, which provides the domain's TLS and DNS.

Cookies and local storage. The site sets one first-party cookie, sbgn_owner: a random token (HttpOnly, 30 days) that marks your jobs as yours. It is strictly functional; there are no tracking and no third-party cookies. Your browser's local storage keeps the colour theme, the panel state, advanced mode, your settings, the list of your layouts and whether you have dismissed the cookie notice; nothing of this leaves the browser. API clients hold the same cookie in a cookie jar.

Limits

• Files up to 40 MB. One layout runs per Java process; many run in parallel (32 on sbgn-layout.org), further requests wait in a queue that takes turns between visitors.
• Each visitor may have 5 jobs queued or running at a time; a sixth upload is refused until one of them finishes.
• A layout is aborted after 30 minutes. Maps with more than about 1000 nodes spend most of their time in the edge-routing step; the largest bundled Reactome map takes two to three minutes.
• Results are deleted after 7 days.

Troubleshooting

• “That is not an SBGN-ML file” — only .sbgn, .sbgnml and .xml are accepted. Export your map as SBGN-ML from your editor (SBGN-ED, Newt, CellDesigner with the SBGN-ML plugin, …).
• “Layout failed” — the engine could not read or lay out the map; the card shows the engine's last messages and the Log tab (advanced mode) the full log. Check that the file opens in an SBGN-ML editor, then try again; if it keeps failing, report it with the log and the job id.
• “That job has expired, never existed, or was started in another browser” — the link is older than 7 days, or you opened it in a different browser or private window (see result links).
• “The layout engine is unavailable” — a red bar at the top; the server's Java engine is not running. Wait a moment and press Try again.
• The drawing is cut off or empty in another program — the SVG uses a viewBox; make sure the program honours it. The SBGN-ML carries bend points which some viewers ignore (arcs then appear straight).

Licence and citation

The service is free for academic and non-commercial use. Its software — this web application, the Constraint SBGN Layout add-on and the headless layout runner — is open source under the GNU General Public License v3.0 (GPL-3.0). It builds on VANTED and SBGN-ED (GPL), the Adaptagrams libraries libcola and libavoid (LGPL) and Next.js (MIT). The sample maps keep the licences of their sources (SBGN examples; Reactome, CC BY 4.0).

A manuscript describing the service is in preparation. Until it is published, please cite this website, https://sbgn-layout.org, when you use results in a publication.