Skip to content

vsr2.xsl

Jump to bottom Edit New page
Tim L edited this page Jul 5, 2014 · 114 revisions

What is first

What we will cover

  • How to use vsr2grf.sh to convert RDF to OmniGraffle files.
  • How to create a new Visual Strategy for particular RDF vocabularies, so that your RDF data can be rendered as OmniGraffle, SVG, or (yED-flavored) GraphML.

Let's get to it

Invoking VSR

bin/vsr2grf.sh:

bash-3.2$ vsr2grf.sh --help
usage: vsr2grf.sh {pml, owl, rdf, rdf-literal, path/to/some.vsr} {graffle, graphml} [-w] [-od path/to/dir] some.rdf+

bash-3.2$ curl -sLO http://dig.csail.mit.edu/2008/webdav/timbl/foaf.rdf

bash-3.2$ vsr2grf.sh rdf graffle -w foaf.rdf 
Transforming foaf.rdf to ./foaf.rdf.graffle

bash-3.2$ head foaf.rdf.graffle 
<plist version="1.0">
   <dict>
      <key>ActiveLayerIndex</key>
      <integer>0</integer>
      <key>ApplicationVersion</key>
      <array>
         <string>com.omnigroup.OmniGrafflePro</string>

Existing Visual Strategies (i.e. "the first half")

To create a new visual strategy, copy and work from template.vsr.xsl. Replace "template" and "TEMPLATE" with the name of your input visual strategy. For example, if the visual strategy is intended for VoID instance data, use "VOID" (though, we already have one that reproduces the lodcloud diagram).

XSLTDoc of these visual strategies is at vsr/doc/xsltdoc/index.html

template.vsr.xsl depends on rdf2.xsl and rdf-abbrev.xsl (using these imports), discussed below.

Once 2grph.xsl defers to the visual strategy, rdf2.xsl will pick up the initial domain form processing (here) by listing prefix mappings (here) and then deferring to a higher-level visual strategy for each resource occurrence, sorted by namespace precedence (here). Note that the visual strategy is called for each mention of a resource, i.e. if the resource is the subject of 3 triples and the object of 3 other triples, the visual strategy will be asked to render the resource six times. It is up to the visual strategy to determine how many visual elements are formed from these six calls (it could be 1, or 6, or anywhere in between).

If you haven't added any special handling, template.vsr.xsl will pickup rdf2.xsl's deferral here with <xsl:template match="rdf:Description/*" priority="-.25">. The template announces its arrival at the triple using acv:arriveTriple($owl:sameAs,$subject,$predicate,$object,$deferrer), then defers to the contextualized view template using a "global view context". The contextualized view template in turn defers to rdf2.xsl's core Blacklist Checker, passing it 20 or so of the rdf:Property and rdfs:Class General Strategies for Visualizing RDF Graphs classifications.

A summary of the default processing stream:

rdf-abbrev visual strategy

src/xsl/from/rdf-abbrev.xsl implements an abbreviated but relatively naive visual strategy for RDF graphs. It consolidates rdf:Lists and reification, tucks labels, lat/long, and dateTimes into the label of the URI, filters to show only a single language, swaps the "force directionality" of certain properties to lead to a nicer layout, subdues edge colors, colors labels by datatypes, abbreviates blank nodes, implements blacklisting by type, and abbreviates many RDFS axioms and some OWL cardinalities. It depends on rdf2.xsl, described below.

rdf visual strategy

src/xsl/from/rdf2.xsl implements a direct, naive visual strategy for RDF graphs, and also provides a variety of functionality for use by higher-level visual strategies. It handles logging provenance to a Sesame repository (either local in-memory or to a remote), provides RDF indexing, handles namespace prefixes, a visual node identity mapper, blacklist checker, provides utility functions, and provenance logger (implementation here).

OWL visual strategy

src/xsl/from/owl2.vsr.xsl

PML visual strategy

src/xsl/from/pml.vsr.xsl

PROV visual strategy

src/xsl/from/prov.vsr.xsl

VoID Linksets / datahub.io visual strategy

src/xsl/from/linksets.vsr.xsl

Target graphical systems (i.e. "the second half")

The vsr2grph API enables visual strategies to be developed regardless of the target concrete graphical representation. So, once a visual strategy is written, it can be reapplied to create new formats (such as SVG, OmniGraffle, GraphML, GraphViz, etc.) without any modifications. This is achieved through the minimal coupling that the vsr2grph uses. See 2grph.xsl for details of the "second half" of the vsr2grph API: writing output graphical serializations.

Mating x2 to 2y (i.e. composing the "two halves")

vsr2grf.sh constructs a root XSL based on the requested visual strategy (i.e. "x2") and the target graphical system (i.e. "2y"). For example, the following is created when vsr2grf.sh rdf graffle is used:

<xsl:transform version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
   <xsl:include href="/Users/me/vsr/src/xsl/from/rdf-abbrev.xsl"/> <!-- this is the "x2" -->
   <xsl:include href="/Users/me/vsr/src/xsl/to/2graffle5.xsl"/>    <!-- this is the "2y" -->
</xsl:transform>

(demo2graffle5.xsl shows the first prototype of this pattern, using direct calls to the node creation templates without walking the host input format.)

The following diagram shows the execution flow between a "x2" and a "y2", which we describe in stages below.

2y.xsl flowing to 2x.xsl and back
Stage 1) y2 captures initial control

2y.xsl is responsible for capturing initial control by matching on the document root (/).

  • First, 2y should provide any "header setup" before turning to focus on serializing nodes and edges. This should include a GRDDL transformation pointer in a location thtat will survive "pass through" editing in the native graphical format.

to, which defers to x2.xsl's mode="visual-element" templates, back to 2y.xsl's templates for the node and edge in the appropriate target graphical format.

d2v.xsl aka domain to visual?

Provenance logging during the visualization process

(see also Provenance Capture in vsr2.xsl)

The following functions should be called by the visual strategy to provide justification for decisions about visual mappings of the input data. A shorthand notation is used in the log to distinguish among the kinds of explanations being provided (® is "Resource", x is "explain" (no x implies a pre-explanation "arrival"), ~ is some (known) predicate, o is an object (either literal or resource), A is some named "action", ^_ is an "attribute-value" of the visual form). Calls to these functions result in a "human readable" log to stderr that can be helpful while developing the visual strategy, AND the calls result in a PROV-O record about the visual mapping decision into a local or remote Sesame repository. The local repository is appended at the end of the "human readable" log.

The following two lists of explanation functions lead to their implementation, and facilitate a comparison of their the arguments, respectively.

  • ® : arriveResource - a visual strategy is "visiting" a particular resource and will either defer to another handler or make the visual mapping decision about this data element.
  • ®~ : arriveTriple(s,p) - a visual strategy is "visiting" a particular property of a particular resource and will either defer to another handler or make the visual mapping decision about this data property.
  • ®~o : arriveTriple(s,p,o) - a visual strategy is "visiting" a particular property value of a particular resource and will either defer to another handler or make the visual mapping decision about this data property.
    • x®~oA : explainTriple(action) - the visual strategy handler made a decision to act on the visited resource's data property value in a particular "blackbox" way.
    • x®~o^_ : explainTriple(property,value) - the visual strategy handler made a decision to apply a property-value to the graphic base on the visited resource's data property value.
The different arguments to the explain functions

Namespaces

The files in src/xsl/ns contain variables for all terms in a variety of vocabularies.

<xsl:transform version="2.0"
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   xmlns:xd="http://www.pnp-software.com/XSLTdoc"
   xmlns:dc="http://purl.org/dc/elements/1.1/"
   xmlns:dcterms="http://purl.org/dc/terms/">

<xd:doc type="stylesheet">
   <xd:short>Vocabulary terms.</xd:short>
   <xd:detail></xd:detail>
   <xd:author>Timothy Lebo</xd:author>
   <xd:copyright></xd:copyright>
   <xd:svnId></xd:svnId>
</xd:doc>

<!-- The namespace itself -->
<xsl:variable name="dcterms"                select="'http://purl.org/dc/terms/'"/>

<!-- Terms within the namespace -->
<xsl:variable name="dcterms:rightsHolder"   select="concat($dcterms,'rightsHolder')"/>
<xsl:variable name="dcterms:isReferencedBy" select="concat($dcterms,'isReferencedBy')"/>
<xsl:variable name="dcterms:identifier"     select="concat($dcterms,'identifier')"/>
<xsl:variable name="dcterms:description"    select="concat($dcterms,'description')"/>

<xsl:variable name="dcterms:ALL" select="(
   $dcterms:rightsHolder, $dcterms:isReferencedBy, $dcterms:identifier, $dcterms:description
)"/>

</xsl:transform>

Utilities

Some utilities that the "to" and "from" scripts use.

/vsr/src/xsl/util/atoid.xsl
/vsr/src/xsl/util/bestQNameLabelFor.xsl
/vsr/src/xsl/util/nameFactory.xsl
/vsr/src/xsl/util/ns-precedence.xsl
/vsr/src/xsl/util/rtf-function.xsl
/vsr/src/xsl/util/string-if-true.xsl
/vsr/src/xsl/util/string-variables.xsl
/vsr/src/xsl/util/uri.xsl
/vsr/src/xsl/util/xsd-datatype-abbreviations.xsl

Patterns

Edge thickness

What is next

  • A 2grph.xsl is written for each concrete graphical format (e.g. svg, graphml, etc.)
Add a custom footer
Add a custom sidebar
Clone this wiki locally