Primer: Fully integrated PROV-N examples with supporting text, removed appendix
authorSimon Miles <simon.miles@kcl.ac.uk>
Mon, 28 May 2012 15:44:57 +0100
changeset 3018 352ac2fa3ae4
parent 3017 4b967d238bee
child 3020 4a5a3f1740c2
Primer: Fully integrated PROV-N examples with supporting text, removed appendix
primer/Primer.html
--- a/primer/Primer.html	Mon May 28 15:35:06 2012 +0100
+++ b/primer/Primer.html	Mon May 28 15:44:57 2012 +0100
@@ -472,6 +472,26 @@
  <section>
   <h2>Examples of Key Concepts in PROV</h2>
 
+  <p>
+   In the following sections, we show how PROV can be used to model 
+   provenance in a specific example scenario. Samples of PROV data are given.
+   These samples use the namespace prefix <b>prov</b> denotes 
+   terms from the PROV ontology, while <b>ex</b> denotes terms specific to the example.
+   We illustrate in these examples how PROV can be used in combination with other
+   languages, such as FOAF and Dublin Core (with namespace prefix <b>foaf</b> and 
+   <b>dcterms</b> respectively).
+  </p>
+  <p>
+   The samples can be displayed in one or more of the following formats.
+  </p>
+  <ul>
+   <li>[[PROV-O]] RDF triples, expressed using the [[TURTLE]] notation.</li>
+   <li>[[PROV-N]] productions.</li>
+  </ul>
+  <p>
+   Select the formats to display using the buttons below. Note that if all formats
+   are hidden, the worked examples may not make sense!
+  </p>
   <form action="#"><p> 
     <input id="hide-turtle-examples" type="button" value="Hide Turtle Examples" 
            onclick="
@@ -500,24 +520,6 @@
    </p> 
   </form>
 
-  <p>
-   In the following sections, we show how PROV can be used to model 
-   provenance in a specific example scenario.
-  </p>
-  <p>
-   We include samples of how the formal ontology (PROV-O)
-   can be used to represent the PROV descriptions as RDF triples.
-   These are shown using the Turtle notation [[TURTLE]]. In 
-   the latter depictions, the namespace prefix <b>prov</b> denotes 
-   terms from the PROV ontology, while <b>ex</b> denotes terms specific to the example.
-   We illustrate in these examples how PROV can be used in combination with other
-   languages, such as FOAF and Dublin Core (with namespace prefix <b>foaf</b> and 
-   <b>dcterms</b> respectively). </p>
-
-  <p>We also provide a representation of the examples in the Provenance
-   Notation, PROV-N, used in the data model document. The full PROV-N data 
-   for the examples in this section is
-   included in the appendix.</p>
 
   <section>
    <h3>Entities</h3>
@@ -531,7 +533,7 @@
     A blogger, Betty, looking at the article, spots what she thinks to be an error in the chart.
     Betty retrieves a record of the provenance of the article, describing how it was created.
    </p>
-   <p>Betty finds the following descriptions of entities in the provenance:</p>
+   <p>Betty finds the following descriptions of entities in the provenance.</p>
    <div class="turtle example">
     <div class="exampleheader">
      <span class="exampleheader"><b>Turtle Example</b></span></div>
@@ -587,6 +589,13 @@
   ex:compile a prov:Activity .
     </pre>
    </div>
+   <div class="provn example" style="display:none">
+    <div class="exampleheader">
+     <span class="exampleheader"><b>PROV-N Example</b></span></div>
+    <pre>
+     activity(ex:compile)
+    </pre>
+   </div>
    <p>
     The provenance also includes reference to the more specific steps involved in this compilation,
     which are first composing the data by region (<code>ex:compose</code>) and then generating the
@@ -604,7 +613,6 @@
     <div class="exampleheader">
      <span class="exampleheader"><b>PROV-N Example</b></span></div>
     <pre>
-     activity(ex:compile)
      activity(ex:compose)
      activity(ex:illustrate)
     </pre>
@@ -638,6 +646,15 @@
      ex:composition  prov:wasGeneratedBy ex:compose .
     </pre>
    </div>
+   <div class="provn example" style="display:none">
+    <div class="exampleheader">
+     <span class="exampleheader"><b>PROV-N Example</b></span></div>
+    <pre>
+     used(ex:compose, ex:dataSet1, -)
+     used(ex:compose, ex:regionList, -)
+     wasGeneratedBy(ex:composition, ex:compose, -)
+    </pre>
+   </div>
    <p>
     Similarly, the chart graphic creation activity (<code>ex:illustrate</code>)
     used the composed data, and the chart was generated by this activity.
@@ -654,10 +671,6 @@
     <div class="exampleheader">
      <span class="exampleheader"><b>PROV-N Example</b></span></div>
     <pre>
-     used(ex:compose, ex:dataSet1, -)
-     used(ex:compose, ex:regionList, -)
-     wasGeneratedBy(ex:composition, ex:compose, -)
-
      used(ex:illustrate, ex:composition, -)
      wasGeneratedBy(ex:chart1, ex:illustrate, -)
     </pre>
@@ -695,9 +708,9 @@
    </div>
    <p>
     The record for Derek provides the
-    following information, of which the first lines are PROV-O statements that
-    Derek is an agent, specifically a person, followed by (non-PROV) statements
-    giving general properties of Derek.
+    following description that
+    Derek is an agent, specifically a person, followed by non-PROV information
+    giving attributes of Derek.
    </p>
    <div class="turtle example">
     <div class="exampleheader">
@@ -795,35 +808,31 @@
      ex:composedData         a prov:Role .
      ex:analyst              a prov:Role .
     </pre>
-   </div>
-   <p>
-    Examples in the sections above show descriptions of the simple facts that the
-    composition activity used, generated and was enacted by entities/agents.
-    For example, the usage of the data set by the compose activity is expressed
-    as follows.
-   </p>
-   <div class="turtle example">
+    <p>
+     Examples in the sections above show descriptions of the simple facts that the
+     composition activity used, generated and was enacted by entities/agents.
+     For example, the usage of the data set by the compose activity is expressed
+     as follows.
+    </p>
     <div class="exampleheader">
      <span class="exampleheader"><b>Turtle Example</b></span></div>
     <pre>
      ex:compose prov:used ex:dataSet1 .
     </pre>
-   </div>
-   <p>     
-    The
-    provenance can contain more details of exactly how these entities and agents
-    were involved in the activity. 
-    To express this, PROV-O refers to <i>qualified usage</i>, <i>qualified generation</i>, etc.,
-    which are descriptions consisting of several statements about how use, generation, etc. took place.
-    For example, we may describe the plan followed by an agent in performing an activity, or
-    the time at which an activity generated an entity, both illustrated later.
-    Another example of qualified involvement is the role an entity played in an activity.
-    The descriptions below state
-    that the composition activity (<code>ex:compose</code>) included the usage
-    of the government data set (<code>ex:dataSet1</code>) in the role of the data
-    to be composed (<code>ex:dataToCompose</code>).
-   </p>
-   <div class="turtle example">
+    <p>     
+     The
+     provenance can contain more details of exactly how these entities and agents
+     were involved in the activity. 
+     To express this, PROV-O refers to <i>qualified usage</i>, <i>qualified generation</i>, etc.,
+     which are descriptions consisting of several statements about how use, generation, etc. took place.
+     For example, we may describe the plan followed by an agent in performing an activity, or
+     the time at which an activity generated an entity, both illustrated later.
+     Another example of qualified involvement is the role an entity played in an activity.
+     The descriptions below state
+     that the composition activity (<code>ex:compose</code>) included the usage
+     of the government data set (<code>ex:dataSet1</code>) in the role of the data
+     to be composed (<code>ex:dataToCompose</code>).
+    </p>
     <div class="exampleheader">
      <span class="exampleheader"><b>Turtle Example</b></span></div>
     <pre>
@@ -835,6 +844,10 @@
     </pre>
    </div>
    <div class="provn example" style="display:none">
+    <p>
+     In PROV-N, the role is expressed as one of the list of attributes in the used
+     expression, with the attribute name <code>prov:role</code>.
+    </p>
     <div class="exampleheader">
      <span class="exampleheader"><b>PROV-N Example</b></span></div>
     <pre>
@@ -885,6 +898,14 @@
      ] .
     </pre>
    </div>
+   <div class="provn example" style="display:none">
+    <div class="exampleheader">
+     <span class="exampleheader"><b>PROV-N Example</b></span></div>
+    <pre>
+     wasAssociatedWith(ex:compose, ex:derek, -, [ prov:role = "ex:analyst"])
+     wasGeneratedBy(ex:composition, ex:compose, -, [ prov:role = "ex:composedData"])
+    </pre>
+   </div>
    <p>
     Depicting the above visually, we have the following.
    </p>
@@ -916,6 +937,7 @@
     <div class="exampleheader">
      <span class="exampleheader"><b>PROV-N Example</b></span></div>
     <pre>
+     entity(ex:dataSet2)
      wasRevisionOf(ex:dataSet2, ex:dataSet1, -)
     </pre>
    </div>
@@ -950,6 +972,14 @@
                  prov:wasRevisionOf ex:chart1 .
     </pre>
    </div>
+   <div class="provn example" style="display:none">
+    <div class="exampleheader">
+     <span class="exampleheader"><b>PROV-N Example</b></span></div>
+    <pre>
+     entity(ex:chart2)
+     wasRevisionOf(ex:chart2, ex:chart1)
+    </pre>
+   </div>
    <p>
     Derivation and revision are connections between entities, and so depicted
     with arrows in our visualization.
@@ -977,12 +1007,21 @@
      ex:instructions a prov:Plan .
     </pre>
    </div>
-   <p>
-    The connection between them is expressed in PROV-O using a qualified association giving details of
-    how Edith was associated with the correction activity,
-    including that she followed the above correction instructions.
-   </p>
+   <div class="provn example" style="display:none">
+    <div class="exampleheader">
+     <span class="exampleheader"><b>PROV-N Example</b></span></div>
+    <pre>
+     activity(ex:correct)
+     agent(ex:edith, [ prov:type="prov:Person" ])
+     entity(ex:instructions)
+    </pre>
+   </div>
    <div class="turtle example">
+    <p>
+     The connection between them is expressed in PROV-O using a qualified association giving details of
+     how Edith was associated with the correction activity,
+     including that she followed the above correction instructions.
+    </p>
     <div class="exampleheader">
      <span class="exampleheader"><b>Turtle Example</b></span></div>
     <pre>
@@ -995,6 +1034,9 @@
     </pre>
    </div>
    <div class="provn example" style="display:none">
+    <p>
+     In PROV-N, the plan is an optional parameter to wasAssociatedWith descriptions.
+    </p>
     <div class="exampleheader">
      <span class="exampleheader"><b>PROV-N Example</b></span></div>
     <pre>
@@ -1118,9 +1160,6 @@
     <pre>
      entity(ex:articleV1)
      specializationOf(ex:articleV1, ex:article)
-
-     specializationOf(ex:articleV2, ex:article)
-     alternateOf(ex:articleV1, ex:articleV2)
     </pre>
    </div>
    <p>
@@ -1165,124 +1204,6 @@
  </section>
 
  <section class="appendix">
-  <h2>PROV-N Examples</h2>
-  <p>
-   Below we give translations of the working example snippets into the Provenance
-   Notation (PROV-N).
-  </p>
-  <section>
-   <h3>Entities</h3>
-   <pre class = "provn example">
-     entity(ex:article, [dcterms:title="Crime rises in cities"])
-     entity(ex:dataSet1)
-     entity(ex:regionList)
-     entity(ex:composition)
-     entity(ex:chart1)
-   </pre>
-  </section>
-
-  <section>
-   <h3>Activities</h3>
-   <pre class="provn example">
-     activity(ex:compile)
-     activity(ex:compose)
-     activity(ex:illustrate)
-   </pre>
-  </section>
-
-  <section>
-   <h3>Use and Generation</h3>
-   <pre class="provn example">
-     used(ex:compose, ex:dataSet1, -)
-     used(ex:compose, ex:regionList, -)
-     wasGeneratedBy(ex:composition, ex:compose, -)
-
-     used(ex:illustrate, ex:composition, -)
-     wasGeneratedBy(ex:chart1, ex:illustrate, -)
-   </pre>
-  </section>
-
-  <section>
-   <h3>Agents and Responsibility</h3>
-   <pre class="provn example">
-     agent(ex:derek, [ prov:type="prov:Person", foaf:givenName = "Derek", 
-            foaf:mbox= "&lt;mailto:derek@example.org&gt;"])
-     wasAssociatedWith(ex:compose, ex:derek, -)
-     wasAssociatedWith(ex:illustrate, ex:derek, -)
-
-     agent(ex:chartgen, [ prov:type="prov:Organization",
-            foaf:name = "Chart Generators Inc"])
-     actedOnBehalfOf(ex:derek, ex:chartgen, ex:compose)
-
-     wasAttributedTo(ex:chart1, ex:derek)
-   </pre>
-  </section>
-
-  <section>
-   <h3>Roles</h3>
-   <p>
-    Roles are not declared directly in PROV, rather they are attributes of 
-    relations. Thus, the entire Turtle example in Section 3.5 is rendered as follows:
-   </p>
-   <pre class="provn example">
-     used(ex:compose, ex:dataSet1,   -, [ prov:role = "ex:dataToCompose"])
-     used(ex:compose, ex:regionList, -, [ prov:role = "ex:regionsToAggregateBy"])
-   </pre>
-   <p>
-    In the first description above, note that this adds a "role" attribute to the first 'used' description of A.3.
-    Similarly in the second description, we have added a "role" attribute to the second  'used' description of A.3.
-   </p>
-  </section>
-
-  <section>
-   <h3>Derivation and Revision</h3>
-   <pre class="provn example">
-     wasRevisionOf(ex:dataSet2, ex:dataSet1, -)
-   </pre>
-
-   <pre class="provn example">
-     wasDerivedFrom(ex:chart2, ex:dataSet2)
-   </pre>
-  </section>
-
-  <section>
-   <h3>Plans</h3>
-   <p>
-    Similarly to roles, plans are attributes of relations, specifically association relations.
-   </p>
-   <pre class="provn example">
-     wasAssociatedWith(ex:correct, ex:edith, ex:instructions)
-   </pre>
-  </section>
-
-  <section>
-   <h3>Time</h3>
-   <pre class="provn example">
-     wasGeneratedBy(ex:chart1, ex:compile,  2012-03-02T10:30:00)
-     wasGeneratedBy(ex:chart2, ex:compile2, 2012-04-01T15:21:00)
-
-     activity(ex:correct, 2012-03-31T09:21:00, 2012-04-01T15:21:00)
-   </pre>
-  </section>
-
-  <section>
-   <h3>Alternate Entities and Specialization</h3>
-   <pre class="provn example">
-     entity(ex:blogEntry)
-     wasQuotedFrom(ex:blogEntry, ex:article)
-     
-     entity(ex:articleV1)
-     wasDerivedFrom(ex:articleV1, ex:dataSet1)
-
-     specializationOf(ex:articleV1, ex:article)
-
-     specializationOf(ex:articleV2, ex:article)
-     alternateOf(ex:articleV1, ex:articleV2)
-   </pre>
-  </section>
- </section>
-
- <section class="appendix">
   <h2>Acknowledgements</h2>
   <p>
    The Provenance Working Group members.
@@ -1292,7 +1213,9 @@
  <section class="appendix"> 
   <h2>Changes Since Second Public Working Draft</h2> 
   <ul>
-   <li>Added selection between Turtle and PROV-N examples.</li>
+   <li>Added selection between Turtle and PROV-N examples with supporting text.</li>
+   <li>Removed PROV-N appendix.</li>
+   <li>Clarifications and improvements throughout the text.</li>
   </ul>
  </section>