1. SEDML editor help
   1. New in this version
      1. What's new in 0.9.9
      2. What's new in 0.9.7
      3. What's new in 0.9.5
      4. What's new in 0.9.4
   2. Licence
   3. Creating a new SED-ML file:
      1. Creating a SED-ML document from scratch.
      2. Basic editor operations
      3. Adding Notes to an element.
      4. Creating a simulation element
      5. Creating a Model element.
         1. Defining changes to a model.
      6. Creating a Task
      7. Creating a Data generator
      8. Creating a Variable
      9. Creating an Output
   4. Editing existing elements
   5. Searching for elements.
      1. Restricting the view:
      2. Highlighting elements in the editor using the file view:
   6. Working with SED-ML archive files
   7. Working with existing SED-ML documents
   8. Graphical layout of elements.
   9. Connections reference
   10. Levels of validation - syntax vs semantics
       1. Syntax validation
       2. Semantic validation
       3. Validation for execution

SEDML editor help

This document describes how to use the SED-ML graphical editor plugin for SBSI, for the creation, viewing and editing of SED-ML files. This documentation is valid for version 0.9 onwards.

New in this version

What’s new in 0.9.9

1. Models can now be retrieved from standard URLs as well as Miriam URNs.
2. XPath generation now uniquely defines elements. Where possible, the generated XPath will use a unique combination of attributes. If this is not possible, then then indices of elements will be used. This is less preferable,though, as the ordering of elements could change without affecting the meaning of the model.

Thanks to the reviewers of the SED-ED paper for suggesting these improvements.

What’s new in 0.9.7

1. Element IDs are now editable.
2. HTML note editor now provides HTML wrapper for content.
3. You can now view the SED-ML file as an HTML document by selecting a SED-ML file and clicking 'View in Browser'.

What’s new in 0.9.5

1. ‘Cut’ editing functionality added.
2. You can now copy and paste between diagrams.
3. Bugfix for editing Miriam URNs which caused application to hang.

What’s new in 0.9.4

1. Improved navigation of SED-ML using the file view.
2. Retrieval of model files via MIRIAM URNs.
3. Filtering the display of large SED-ML files by output.
4. Highlighting changes applied to models in the model content.
5. ‘Cut’ editing feature added.

Licence

This editor is available under an MIT open source license:

Creating a new SED-ML file:

From the File->New menu, choose the option SED-ML->SED-ML editor :

This will create a new SED-ML file and open the editor:

Creating a SED-ML document from scratch.

This section describes the use of the graphical editor to create components of a SED-ML document.

• Top-level elements are added from the palette and can be laid out in the editor window by dragging.
• Double-clicking on an object will open a dialog to configure it.
• Elements that are not yet correctly configured will be highlighted in red. This means that insufficient information is included for the element to be saved, and it will be omitted from the saved SED-ML file.
• The diagram can be saved at any time as a regular SED-ML file; graphical information is persisted as annotations to the elements and layout will be restored when the diagram is re-opened.
• For elements that use identifiers, these should be globally unique in the document, and are added automatically by the software. Human-readable names for elements can be added, which is highly recommended as an aid to understanding the document.
• Cross references can be made by drawing a Connection between two elements. See section Cross references

Basic editor operations

Standard editing operations are enabled in the editor such as :

• Copy/paste/delete of selected items using Ctrl-C /Ctrl-V/Delete, or via the Edit menu. To paste from the clipboard, click on an empty region of the diagram, or make sure no element on the diagram is selected.
• Undo /redo using Ctr-Z/Y, or via the Edit menu.
• Select-All using Ctrl-A or via the Edit menu.
• The view can be panned while holding the spacebar down to get a ‘hand’ icon then dragging with the mouse.

Adding Notes to an element.

Any element can have an HTML note added by selecting an element and choosing Add /Edit/View Note from the context menu. This will open a dialog like this:

The HTML that you add should be contained in a single container element such as a div or body element. A preview of the HTML is displayed on the right-hand panel, and error messages inform if the HTML is badly formed.

Once you’ve added a note to an element, it will show a little icon to indicate this. E.g.,

The Remove Note button removes a note from an element.

Creating a simulation element

From the editor palette, choose ‘Simulation’ and then click on the canvas to add a Simulation object.
A dialog will pop up for you to configure the simulation. SED-ML level 1 version 1 is restricted to uniform time courses. By default, a simulation will defined as running for 10 time units, using a general ODE solver, with 100 output time points.

Creating a Model element.

From the editor palette, choose ‘Model’ and then click on the canvas to add a Model object.
Choose the modelling language of your model, and its source. This can be a location on the file-system chosen from the file browser or you can enter a stable URN such as a MIRIAM identifier. Currently the editor can retrieve SBML models from Biomodels, if the source is specificed with
the appropriate URN (e.g., urn:miriam:biomodels.db:BIOMD0000000012).

You can preview a model by clicking on the Preview Model button. This will be enabled if the model itself can be retrieved based on the ‘source’ attribute of the SED-ML model element. Preview Model will apply all changes and show the model as an XML tree for you to browse to check that the changes are as you expect. You can also access this from within the ‘Edit Change’ dialog when you double click on a Change element.

Defining changes to a model.

In SED-ML, there are several method to apply changes to an XML based model:

• Changing the value of an individual attribute.
• Adding new XML.
• Removing an XML element.
• Changing an XML element ( replacing one XML element with another ).

In this editor, you can add a change to a model by choosing the Add Change context menu item when you have a model element selected:

This opens a dialog:

The Change type drop-down menu enables you to choose what sort of change you want to apply.
The Replacement Value text field is where you insert the changes to make.

If you choose to change an attribute, the replacement value should be a numerical value. If you choose to Add XML or Change XML, then the replacement value should be some well formed XML. If you choose Remove XML the content of the replacement value is irrelevant and is ignored.

The TargetXPath field is where you specify the XML to be changed, using an XPath expression. This can be added manually, or by using the Get XPath from Model feature. If this is enabled, it helps to create the XPath expressions from an XML view of your model. The button is enabled if the editor can get hold of the actual model, specified in the source attribute of the Model element to which this change is being added.

Currently, two operations are supported by Get XPath from Model. Firstly, if you wish to change an attribute:

1. Expand the XML view to the element with an attribute that you want to change.
2. Select two attributes of that element. The first selected attribute is the attribute whose value you want to change. The second selected element will be used to identify that element. For SBML elements, for example, the ‘id’ attribute would be an ideal choice. E.g.,

In the above example. the initialConcentration attribute was selected first, which is what we want to change, then the id attribute, . The XPath expression is previewed in the bottom text field.

Secondly, if you choose to add/remove/change XML, choose an identifying attribute of the element which is to be the target of the modification, and an XPath expression will be generated. If the element you wish to target has no attributes, then the element is chosen with no identifiers inserted into the XPath expression, which should be sufficient if an element is unique within its parent element.

In the above example, we might have chosen this element to be removed.

XPath expressions must always be prefixed, in such a way that they can be mapped to a namespace when they are evaluated. In this editor, XPath prefixes are generated according to the following rules.

1. If the namespace declaration in the model specifies a prefix, then that prefix is used for XPath components in that namespace.
2. If the namespace declaration in the mode does NOT specify a prefix, then the name of the element containing the xmlns attribute declaring the namespace is used as an XPath prefix.

Creating a Task

Task elements connect a Model to a Simulation. From the editor palette, choose ‘Task’ and then click on the canvas to add a Task object. Task elements need no mandatory configuration from a dialog, but must be connected to a Model and a Simulation to be valid.
E.g.,

is invalid as the task is not connected. But in

the task is no longer highlighted in red, as it is connected correctly.

Creating a Data generator

DataGenerator elements define one output of a simulation. To create a DataGenerator, from the editor palette, choose ‘DataGenerator’ and then click on the canvas to add a DataGenerator object.

In the dialog, you need to enter a mathematical expression for a column of data from the simulation. For example, to just specify unchanged output, enter the ID of the variable you want to display.

Creating a Variable

To define variable, select a DataGenerator element and choose Add Variable from the context menu.
A Variable is the only SED-ML data type in this editor whose ID is editable – this gives you the chance to use a meaningful ID ( so long as it is alphanumeric and unique in the SED-ML document ). The reason for this is that the variable and parameter names occurring in the maths section of a DataGenerator must be the IDs of Variable and Parameter elements. Variables can also refer to symbols. In SEDML L1V1, ‘Time’ is the only symbol. If ‘No symbol’ is chosen, you need to specify an XPath expression to locate the variable in the model whose value you want to display. As with Changes, if your model is accessible, the Get XPath From Model button will be enabled, which
helps generate the XPath expression for you.

Creating an Output

Output elements define how the simulation results will be presented. To create a Output, from the editor palette, choose either ‘Plot2D ’ or ‘Report’ and then click on the canvas to add it.

If you create a Plot2d you will need to add Curve elements using the Add Curve menu item. When you create a Curve, it will first appear highlighted in red. You now need to connect the Curve to 2 DataGenerators, one for the X axis and one for the Y axis.

If you create a Report you will need to add Dataset elements using the Add Dataset menu item. When you create a Dataset, it will first appear highlighted in red. You now need to connect the Dataset to a DataGenerator element.

Editing existing elements

To edit an existing element, just double-click on the element to obtain the configuration dialog. You can undo or redo edits by clicking Ctrl-Z and Ctrl-Y, respectively.

Searching for elements.

SEDML documents can be quite long, if there are many output descriptions and many variables are output, so the graph view can be tricky to navigate by itself. SED-ED provides some help, though:

Restricting the view:

From a particular Output, it’s possible to work out all the simulations and models needed to generate the output. If you select an Output in the editor ( i.e., a Plot or Report ) and click
Toggle Restricted View
then only the resources used to generate that output will be shown, all other elements will disappear from view ( although they’re NOT deleted and remain in the SED-ML model).

For example, here’s a screenshot of a SED-ML document with two outputs:

Choose the output whose information you want to keep displayed.

Now, click Toggle Restricted View

and the elements not needed to reproduce your output are now hidden. To get these restored, repeat the action.

Highlighting elements in the editor using the file view:

If you have the editor open, you can use the content outline in the resource viewer to scroll
and highlight the SEDML element in the editor. Simply select the item in the content viewer. For example,

This feature works with SEDX Archives as well as SEDML files.
Currently though, mapping is only made using the element’s ID – so if you have multiple editors open on different versions of the SEDML document, you will highlight the element in the currently active editor, which might not edit the same file as that from which you selected the element. To circumvent this, ensure that the currently active editor refers to the same file as that from which you selected an element.

Working with SED-ML archive files

SED-ED supports the proposed SED-ML archive format (SEDX) , described in appendix D of the SED-ML level 1 version 1 specification. This format bundles the SED-ML files and the models it needs in a single archive format.

Features include:

• You can export your SED-ML file to SEDX if the model files can be retrieved based on the value of the source references in the Model elements in SED-ML. At present it just supports file paths but in future we hope to support access from online repositories such as BioModels. To do this, click the blue button here at the top-left corner of the toolbar, which will be active when you are when you have a SED-ML editor pane active:

• You can inspect the contents of a SED-ML archive by expanding it in the resource viewer ( if it has the .sedx extension).
• You can open, edit and save an archive format in the same way as a regular file ( if it has the .sedx extension).
• You can expand a SEDX file by selecting it, then right-clicking and choosing 'Expand SED-ML archive' from the file menu. This will write files into the same folder as the archive, and the archive will be preserved ( if it has the .sedx extension).

Working with existing SED-ML documents

To open an existing SED-ML document using this editor, select it in the Resource View, and from the context menu, choose

Open->Open With->SED-ML editor

If the SED-ML document has been imported from another source, or not yet edited in the SED-ML Editor, you’ll be prompted for some layout options.

1. Manually layout. All elements with no Location/Size information will be positioned at (0,0)
2. Layout all. All elements will be laid out afresh, ignoring previous layout information
3. Layout some. This option fixes the location of elements with existing positions but lays out all others.

Graphical layout of elements.

To automatically layout some or all elements, click on the drawing canvas, and from the context menu, choose Layout . This will layout all un-selected elements. So, to layout all elements, make sure no elements are selected in the editor. Be warned that auto-layout is not undoable, so only do it if you really want to!.

Layout runs in a background thread and can be stopped at any time by clicking cancel in the progress monitor ( the red square in the bottom right-hand corner of the screen-shot below).

Connections reference

Two sorts of relationships are represented by edges (connections ) in the SED-ED editor. Firstly, the reference relations specified in section 2.3.5 of the level1 version1 specification, namely:

• Variable ->Task
• Task->Model
• Task ->Simulation
• Output -> Datagenerators
• Variable->Model ( in ComputeChange elements, not yet supported).

Secondly, containment or aggregation relations, such as:

• Model->Changes
• DataGenerator->Variables
• DataGenerator->Parameters
• Report->Datasets
• Plot2d -> Curves

The reference relations need to be drawn explicitly using the Connection tool in the palette, whereas the aggregation relations are automatically added when a child element is added.

Levels of validation – syntax vs semantics

Any editor needs to provide freedom to enter data in a non-specified order, to be usable, while at the same time ensuring persisted data is not corrupt or meaningless. This section explains some of the levels of validity checking in a SED-ML document.

Syntax validation

The editor allows for the creation of SED-ML data structures in memory that lack essential information, but any aberrant elements will not be persisted. For example, a Task icon that is not connected to a Model and a Simulation will not be saved to file.

These elements are highlighted in red in the editor.

Semantic validation

A document may be syntactically valid but still useless – for example if XPath expressions don’t refer elements in a model properly, or if a model cannot be found from the information in a SED-ML Model element. If a model can be retrieved, feedback will be given if an XPath expression does not identify any model element. Other errors are reported in the ‘Problems’ view or in the expanded tree view of a SED-ML document in the System View. E.g.,

Validation for execution

This is the highest level of validation, and this is not checked in SED-ED. Such validation would include, for example, that a simulation algorithm is available which supports the modelling language specified in the SED-ML document.