The PathVisio-Validator plugin

The PathVisio-Validator plugin is aimed at producing standard biological pathway diagrams in PathVisio. The plugin makes it easier for the users to create pathways adhering to a standard (e.g. MIM and SBGN). This validation tool gives a detailed analysis as to which particular elements in the pathway are not diagrammed according to the standard. It basically helps the users of PathVisio to create pathways, which then could be shared among the biologists without any ambiguity. The standard against which PathVisio-Validator validates a pathway, is basically an MIM/SBGN based ruleset or a more generic GPML ruleset, in the form of ".sch/.xml" files ( Schematron file). There is also support for rulesets written in Groovy (".groovy" file).

Q: Who are the intended users of the PathVisio-Validator plugin?

Normally, the researchers would want their pathways to be created according to a standard notation, but it is a painstaking task to abide by the specifications which could go beyond 50 or more pages. Thus to draw the diagrams according to the rules of these notations, whilst keeping the entire process simple and easy, one needs a mechanism which makes sure that the diagrams are drawn according to these rules. This plugin provides such a mechanism which makes it much easier for the users to create unambiguous biological pathway diagrams.

Q: What are the main features of the PathVisio-Validator plugin?

• Hassle-free validation of pathways with just the click of a button.
• Support for different ruleset formats, i.e. rulesets written in Schematron and Groovy.
• An interface to choose the ruleset, based on which the pathways are validated.
• Support for rulesets based on MIM & SBGN notations.(SBGN feature is not yet ready)
• Support for group-specific validation of pathways.
• Option to generate an SVRL report file containing raw validation results.
• Free and open source

Q: Which pathway formats are supported by the PathVisio-Validator plugin?

Currently, the plugin supports the  MIM notation through the MIM Schematron ruleset in which specifications are encoded in Schematron, in the form of rules. And the support for  SBGN is expected when PathVisio SBGN support is completed. Users have the option to choose the ruleset (which can be a GPML/MIM/SBGN schema file or a groovy file) for validation.

---

Q: How do I install the PathVisio-Validator plugin?

 JAVA is required for the usage of PathVisio and must be installed before PathVisio can be installed or used.

The PathVisio-Validator plugin requires the installation of PathVisio, freely available diagram editor for biological systems, found  here for Linux, Windows, or MacOS. There are two ways of installing the plugin in PathVisio:

Option 1: First-Time PathVisio Users: The easiest installation option is to use our Installer for PathVisio with MIM and PathVisio-Validator plugins. This will install PathVisio with MIM plugin and PathVisio-Validator plugin. This cross-platform installer has been tested on Windows, MacOS, and Linux (Ubuntu). The installer should start by clicking on it. If it does not start by clicking, then try the following command-line method:

Note: make sure to replace VERSION with the appropriate version number (e.g. 2.0.11).

java -jar PathVisio-MIM_VERSION-Setup_w_ValidatorPlugin.jar

Note: If the installer still does not work with the command line, then users should install PathVisio separately by following the instructions below, and then use Option 2 for the installation.

• On Windows, the installer will add a new shortcut in Start Menu->Programs->PathVisio-MIM with the name "PathVisio" that should be used to start PathVisio with the MIM and PathVisio-Validator plugins.

• On MacOS, files will be placed in Applications, users should click on "pathvisio.jar" in the PathVisio-MIM folder to start PathVisio with the MIM and PathVisio-Validator plugins.

• On Linux, the installer will add a new shortcut in a program group called "PathVisio-MIM" with the name "PathVisio" that should be used to start PathVisio with the MIM and PathVisio-Validator plugins. Note: If this does not work make sure the shortcut points to INSTALL_PATH/pathvisio.sh (INSTALL_PATH is the path where PathVisio was installed, e.g. "/home/user/PathVisio-MIM", usually this setting is found in the right-click "Properties" option).

Option 2: Users with PathVisio Already Installed:

Note: The webstart version of PathVisio (downloaded from  http://www.pathvisio.org/wiki/PathVisioDownload) currently does not support PathVisio-Validator plugin. Please use a  non-webstart version of PathVisio to use the plugin.

The plugin comes packaged in a ValidatorPlugin.jar file that can be downloaded here. This jar file must be placed in the "plugins" folder which is in the USER directory under the ".Pathvisio" folder:

Step 1 :

In Windows XP, make sure that you have downloaded the jar file to the following location. The word USER should be the name of the user for whom the plugin will be installed.

  C:\Documents and Settings\USER\.PathVisio\plugins

In Windows Vista/7, make sure that you have downloaded the jar file to the following location. The word USER should be the name of the user for whom the plugin will be installed.

  C:\Users\USER\.PathVisio\plugins

In MacOS/Unix/Linux, make sure that you have downloaded the jar file to the following location. The ~ symbol represents the home directory of the user for whom the plugin will be installed.

  ~/.PathVisio/plugins

Step 2 : Start PathVisio by running "pathvisio.bat" (Windows) or "pathvisio.sh" (MacOS/Unix/Linux)

Note: Any errors in loading the jar file will be logged in the Pathvisio.log file located in the .PathVisio folder.

---

Q: How is the PathVisio-Validator plugin used?

After the ValidatorPlugin.jar file is installed correctly, its loaded whenever PathVisio is run. Now, one should be able to find a tab named "Validator" among the other tabs in the panel present on the right side of the PathVisio's main window. Following are the steps, illustrated with screenshots on how to use the PathVisio-Validator plugin:

screenshot: 1 --> When PathVisio is run, after installing the PathVisio-Validator plugin; The plugin's interface is present under the tab "Validator":

---

screenshot: 2 --> Open a pathway diagram for which the validation is to be done, using File -> Open command:

---

screenshot: 3 --> Choose a Ruleset ( ".sch/.xml" or ".groovy" file ) with the "Choose Ruleset" button. This automatically does the validation if there's a pathway already open:

Note:  gpml_best_practices.sch, a basic GPML ruleset is used in the examples that follow:

---

screenshot: 4 --> The "Validate" button can be used to validate the current pathway diagram against a ruleset chosen in the above step; The validation messages are show in the panel above the "Validate" button and the respective nodes are highlighted in Blue:

---

screenshot: 5 --> Left-click on a Validation message should highlight the corresponding element in Red provided it has an associated Graph-Id:

Note: The Yellow circle-and-dot indicates a left or right mouse-click:

---

screenshot: 6 --> The combo-box present in the lower right corner of the plugin's panel can be set to "Errors only", or "Warnings only", or "Errors & Warnings". This allows filtering the validation messages based on Errors or Warnings:

---

screenshot: 7 --> "Generate SVRL file" check-box provides an option to generate an SVRL file containing the raw validation results:

---

screenshot: 8 --> The file-name and location of the SVRL file can be changed in Edit -> Preferences in PathVisio.

---

screenshot: 9 --> The combo-box present in the upper right corner of the plugin's panel, can be set to a particular "Group" from the ruleset. This allows validating the pathway based on the rules associated with this group:

---

screenshot: 10 --> The "Highlight All" button is used to re-highlight all the pathway elements (containing Graph-Ids) that fail validation.

---

screenshot: 11 --> The right-click menu options can be used to hide/un-hide particular validation messages or types of messages. Usage of Option "Ignore this Error/Warning Type" is demonstrated below, which hides all the validation messages that match a particular type:

---

screenshot: 12 --> Un-hiding (reconsider) the hidden (ignored) rules, using the right-click option is shown below.

Note: The SVRL file gets generated in the USER directory with the name "svrlOutput.svrl" if this option is selected. An option to choose the location and file-name of this SVRL file is provided in the "Preferences" section of PathVisio's "Edit" menu (Edit -> Preferences).

 SVRL (Schematron Validation Report Language) is a simple report language defined as part of ISO Schematron. It provides a fairly full set of information from validating a document, and can be used as the basis of subsequent transformations. In fact, the result obtained after validating a pathway against a Schematron ruleset (using the plugin), is an XML formatted report based on SVRL. It is this raw validation result which gets stored in the file "svrlOutput.svrl". This result is then parsed and displayed in the plugin's side-panel.

---

Rulesets

Included Rulesets

Rulesets are provided for the convenience of users. Users should validate their diagrams only against the rulesets appropriate for the intended use case of the diagram (e.g. users should not validate a diagram drawn using Notation A with a ruleset meant for Notation B and vice versa). The rules in each ruleset are summarized in the respective "RuleList" pages.

• Molecular Interaction Map (MIM) notation (MimRuleList): This ruleset validates diagrams in PathVisio developed with the  PathVisio-MIM plugin to ensure they are in accordance with the MIM notation.
• WikiPathways best practices (GpmlRuleList): A ruleset developed for users wishing to validate their diagrams prior to uploading to the  WikiPathways database. Rules were taken from the WikiPathways  curation tags.

Difference between Schematron and Groovy rulesets:

The plugin supports rulesets written either in Schematron or Groovy.  Schematron is a rule-based XML validation language that uses XSL Transformations (XSLT). It also involves the usage of Xpath expressions. The result of validation is a simple XML formatted report using the Schematron Validation Report Language (SVRL). This validation report is parsed and error or warning messages for the current diagram are displayed under the "Validator" tab. An advantage in using Schematron rulesets is that validation support can be added, using the same ruleset, in any project where an XSLT processor is accessible.

Schematron validation works according to the following procedure: First, the current diagram is exported in the background to a format appropriate for the ruleset. For instance, MIM diagrams are exported to MIMML when using the MIM Schematron ruleset. This step makes the diagram amenable for XSL transformation. Secondly, the ruleset is transformed against an SVRL skeleton file to produce an XML stylesheet (XSL). Lastly, the XML output of step 1 is transformed using the XSL from step 2 to generate an SVRL report, which is then parsed to produce validation messages in the plugin’s panel. These XSL transformations are done using  SAXON, an XSLT and XQuery processor.

 Groovy is an Object-Oriented scripting language providing dynamic integration capabilities to the Java Virtual Machine. It absorbs most of the syntax from Java. So creating rulesets in Groovy is easy for users with a basic understanding of Java. The Groovy ruleset is basically a collection of methods (where each method corresponds to a rule) with specific signature for them to be recognized as valid Groovy rules. These are run directly against the internal memory representation of the pathway diagram in PathVisio, producing results in the form of strings which are then parsed and displayed in the plugin's side-panel. Validation against a Groovy ruleset, consumes less time than its Schematron counterpart, since it does not require any XSL transformations to take place. However, the downside to this approach is that the Groovy rules are tied to the internal workings of PathVisio.

Tutorials

Q: How do I create a PathVisio-Validator plugin ruleset in Schematron?

A tutorial is provided on creating a ruleset using the included WikiPathways curation ruleset as the basis of the tutorial.

Note: "Graph-Id" (e.g. "vis-id" or "inter-vis-id") required for highlighting elements that violate rules, must be present as the first entry in "diagnostics" attribute inside the "<iso:assert>" tags in the Schematron ruleset, so they get picked up by the plugin for highlighting elements.

Q: How do I create a PathVisio-Validator plugin ruleset in Groovy?

This tutorial explains how to create a ruleset in Groovy which could be used by the plugin for validating pathways. The rules can come from specific notations or based on author’s requirements.

---

Rule Examples

Groovy

• An example of a rule written in Groovy:

  //This rule checks for unattached lines by checking each of the "Line" element's first and last "GraphRef" attributes.
  ArrayList<String[ ]> ruleUnattachedLines(Pathway pw) {
  	   String[ ] result = null; // the intermediate result to be added to the final result
   	   ArrayList<String[ ]> totalResultForThisRule = null; // the final resullt which is sent to PathVisio-Validator
  	   for(PathwayElement pwe: pw.getDataObjects()){
   	   	   if(pwe.getObjectType()==ObjectType.LINE &&  // check if the Pathway element is of the type : "Line" 
   				   ( pwe.getStartGraphRef()==null | pwe.getEndGraphRef()==null // check its "GraphRef" values 
   						| pwe.getEndGraphRef().equals("") | pwe.getStartGraphRef().equals("") ) ){
   			   if(totalResultForThisRule==null){
   				   totalResultForThisRule=new ArrayList<String[ ]>(); 
   			   }
  			   //result[0]: "error" / "warning"; result[1]: diagnostic message; result[2]: element's Graph-Id
  				   result = ["error", "Lines should be attached at both ends.", pwe.getGraphId()];
  				   totalResultForThisRule.add(result);
   		   }
   	   }
   	   if(totalResultForThisRule==null) System.out.println("All the lines are attached");
   	   return totalResultForThisRule; // this final result is passed to PathVisio-Validator
   }
  

Schematron

• The equivalent Schematron code:

  <!-- Check that all lines are attached at both ends -->
  	<iso:pattern name="check-unattached-lines" id="check-unattached-lines">
  		<!-- Check "Line" elements -->
  		<iso:rule context="gpml:Line" role="error">
  			<!-- Get the unique identifier for the line -->
  			<iso:let name="graph-id" value="@GraphId"/>
  
  			<!-- Get the GraphRefs (these indicate the GraphIds of the objects the line is connected to) of the first and last points for a line -->
  			<iso:let name="start-graph-ref" value="gpml:Graphics/gpml:Point[position()=1]/@GraphRef"/>
  			<iso:let name="end-graph-ref" value="gpml:Graphics/gpml:Point[last()]/@GraphRef"/>
  			
  			<!-- Assert that the GraphRef attributes on the first and last points are present and not empty, otherwise output error message and identifier -->
  			<iso:assert test="$start-graph-ref and $end-graph-ref and not($start-graph-ref='') and not($end-graph-ref='')" diagnostics="graph-id">Lines should not be unattached.</iso:assert>
  		</iso:rule> 
  	</iso:pattern> 
  
  

Both the example rules above should produce a similar validation result as below, for a given pathway:

The highlighted validation message above indicates the violation of the rule "Unattached Lines" in the pathway diagram. The respective violating element (i.e. Line) is highlighted in red.

---

Specific Graphical Notations

Any diagram loaded in PathVisio may be validated against any ruleset, but users should be aware of the notation they are using and then use only the appropriate ruleset.

Loading Molecular Interaction Map (MIM) Notation MIMML Files

First, ensure that the Molecular Interaction Map (MIM) plugin is installed; refer to the MIM plugin page for  installation information. MIM diagrams are loaded into PathVisio using the "Import" functionality; a  video tutorial is provided showing how to do this.

---

Downloads

Q: Where can I download the PathVisio-Validator plugin and its source code?

•  Download PathVisio with installer for MIM and PathVisio-Validator plugins - Example rulesets are included in the folder "rulesets" in the installation directory.
•  Download just the jar file of PathVisio-Validator plugin
•  An online subversion repository for the plugin's source code
•  Download the MIMML Schematron ruleset
•  Download an example of the Groovy Ruleset
•  Download an example for a basic GPML Schematron Ruleset
•  Learn about PathVisio and Wikipathways

Q: Where can I download example diagrams?

We provide example diagrams that can be used to try out the plugin. The format for the filenames in the test sets below is [NAME]_[VALIDATION_STATUS]_[ERROR_COUNT] where

• NAME is the base name of the diagram
• VALIDATION_STATUS is "pass" or "fail" denoting whether the diagram is considered as having passed or failed validation
• ERROR_COUNT the number of errors that user should expect to see

MIMML Diagrams

•  MIMML diagrams test set

GPML Diagrams

•  GPML diagrams test set
•  GPML diagrams can be downloaded from WikiPathways Note: Some of these diagrams may contain errors.

Links

•  Schematron
•  Groovy

---