Each ptools-xml document is enclosed in a ptools-xml tag. The ptools-version attribute indicates which version of Pathway Tools was used to generate the document. This is important because the Pathway Tools schema (or the ptools-xml format) can change from version to version, and the changes may not always be backwards-compatible.
The PGDB tag contains the orgid attribute. It is this attribute that is used to link an object in the body of the document to the database to which it belongs. The orgid attribute can also be used when constructing further queries against this database. The PGDB element also contains elements that identify the organism it describes, including, where appropriate, a link to the NCBI Taxonomy Database.
The num_results element records the number of top-level object elements (including error elements) in the body of the document. An exception is made for queries that return PGDBs rather than objects (such as with the BioVelo dbs query). In that case, information about the returned PGDBs is included in the metadata section rather than in the document body, and those PGDBs are counted in the num_results field.
Sample Metadata section:
The names of the class elements correspond roughly to the top-level classes in the Pathway Tools schema, using the following mapping (in general, ptools-xml element names are singularized versions of the plural Pathway Tools class names):
|ptools-xml Element Name||Pathway Tools Class Name|
Class elements all contain the orgid and frameid attributes. The orgid attribute should match the orgid attribute of one of the PGDB elements in the metadata section, and identifies the database to which the object belongs. The frameid attribute is the internal Pathway Tools unique identifier for the object. The combination of the orgid and frameid attributes is sufficient to uniquely identify the object.
If this is an element that has been inlined, i.e. all the slot-value data is included within the element, then the element tag will include the ID attribute, which is simply a string of the form [orgid]:[frameid]. Alternatively, if this is an element that does not include all its data, then the element tag will instead include the resource tag, which will provide a link to retrieving the object data. The link can point somewhere within the same document, referencing an element by its ID attribute, or to another URL.
The Pathway Tools schema distinguishes between objects that are classes and objects that are instances. A ptools-xml document can include both kinds of objects. Objects that are classes will have the class attribute set to true.
Examples of class element tags for assorted objects, including examples of both inlined elements and resource elements:
In most cases, the name of the slot element is identical to the name of the corresponding slot in the Pathway Tools schema. There are a handful of cases, however, in which the names differ. These are listed in the following table:
|ptools-xml Element Name||Pathway Tools Slot Name|
One slot element, parent, is not actually a slot in the underlying schema at all. Many of the top-level classes in Pathway Tools organize their instances into a hierarchical ontology. Thus, a particular pathway might be represented with a Pathway element, but its actual direct parent might be the class of all cofactor biosynthesis pathways. In such a case, if an object is not a direct child of its element class (i.e. a direct child of the Pathways class, Proteins class, etc.), then the parent element will link to its actual parent class. Similarly, if we are retrieving the data for a class object that has its own subclasses and instances, the subclass and instance elements will link to those.
Some slot values in Pathway Tools are neither simple datatypes nor object references, but rather a structured list (or string) which is interpreted a certain way by the Pathway Tools software. Examples include the dblinks slot, whose values are a structured list indicating the linked-to database, the object identifier in that database, and the relationship type, or the citations slot, whose values are a string that optionally incorporates a PubMed identifier and/or an evidence code and supporting information. In these cases, we create structured elements, specifically for ptools-xml, that directly encode the meaning of the different fields. Slots for which this is done are the following: alternative-cofactors, alternative-substrates, citations, credits, dblinks, isozyme-sequence-similarity, km, reaction-layout, pathway-links, predecessors, and splice-form-introns. Note that the citations slot can be represented by either a citation element or an evidence element, depending on whether or not an evidence code is associated with the citation.
However, at this time, issuing a BioVelo query that generates an error (meaning a malformed query, not just a query that returns no results) may not cause a well-formed ptools-xml document to be generated -- more typically it will redirect to a web page that describes the problem with the query.