--- a/primer/Primer.html Sun Nov 13 17:30:00 2011 -0500
+++ b/primer/Primer.html Mon Nov 14 11:38:50 2011 +0000
@@ -369,14 +369,16 @@
</p>
<p>The Prov data includes the assertions:</p>
<pre class="turtle example">
- ex1:dataSet1 a prov:Entity .
- ex1:aggregate1 a prov:Entity .
- ex1:chart1 a prov:Entity .
+ ex1:dataSet1 a prov:Entity .
+ ex1:regionList1 a prov:Entity .
+ ex1:aggregate1 a prov:Entity .
+ ex1:chart1 a prov:Entity .
</pre>
<p>
These statements, in order, assert that the original data set is an entity (<code>ex1:dataSet1</code>),
- the data aggregated by region is an entity (<<code>ex1:aggregate1</code>), and
- the chart (ex1:chart1) is an entity.
+ the list of regions
+ (<code>ex1:regionList1</code>) is an entity, the data aggregated by region is an entity (<code>ex1:aggregate1</code>),
+ and the chart (<code>ex1:chart1</code>) is an entity.
</p>
</section>
@@ -411,6 +413,25 @@
or the generation of an entity by a process.
</p>
<p>
+ For example, the data below states that the aggregation process execution
+ (<code>ex1:aggregated</code>) used the data set, that it used the list of
+ regions, and that the aggregated data was generated by this process.
+ </p>
+ <pre class="turtle example">
+ ex1:aggregated prov:used ex1:dataSet1 ;
+ prov:used ex1:regionList1 .
+ ex1:aggregate1 prov:wasGeneratedBy ex1:aggregated .
+ </pre>
+ <p>
+ Similarly, the chart graphic creation process (<code>ex1:illustrated</code>)
+ used the aggregated data, and the chart was generated by this process.
+ </p>
+ <pre class="turtle example">
+ ex1:illustrated prov:used ex1:aggregate1 .
+ ex1:chart1 prov:wasGeneratedBy ex1:illustrated .
+ </pre>
+
+ <!-- p>
For example, the provenance declares the event (of type <code>prov:Usage</code>)
where the aggregation process execution used the GovData data set, and the event
(of type <code>prov:Generation</code>) where the same process execution generated
@@ -441,12 +462,6 @@
ex1:illustrated prov:qualifiedGeneration ex1:chart1Generation .
ex1:aggregate1Usage prov:entity ex1:aggregate1 .
ex1:chart1Generation prov:entity ex1:chart1 .
- </pre>
-
- <!--pre class="turtle example">
- ex1:chart1 prov:wasGeneratedBy ex1:compiled .
- ex1:compiled prov:used ex1:dataSet1 .
- ex1:chart1 prov:wasDerivedFrom ex1:dataSet1 .
</pre -->
<p>
From this information Betty can see that
@@ -459,8 +474,26 @@
<section>
<h3>Agents</h3>
- <p><i>Suggested example:</i> Digging deeper, Betty wants to know who compiled
- the chart. This turns out to be an independent analyst, Derek.</p>
+ <p>
+ Digging deeper, Betty wants to know who compiled the chart. Betty sees
+ that both the aggregation and chart creation process executions were controlled
+ by the Derek.
+ </p>
+ <pre class="turtle example">
+ ex1:aggregated prov:wasControlledBy ex1:derek .
+ ex1:illustrated prov:wasControlledBy ex1:derek .
+ </pre>
+ <p>
+ The record for Derek provides the
+ following information, of which the first line is a Prov-DM statement that
+ Derek is an agent.
+ </p>
+ <pre class="turtle example">
+ ex1:derek a prov:Agent ;
+ a foaf:Person ;
+ foaf:givenName "Derek"^^xsd:string ;
+ foaf:mbox <mailto:dererk@example.org> .
+ </pre>
</section>
<!-- section>
@@ -476,11 +509,69 @@
<section>
<h3>Roles</h3>
- <p><i>Suggested example:</i> For Betty to know where the error lies, she needs
- to understand what other information the compilation process was based on. The
- aggregation step of the process used a list of regions not present in the original
- data, but determined by the analyst. How does she distinguish the roles played by
- the two inputs to the aggregation process?</p>
+ <p>
+ For Betty to understand where the error lies, she needs to have more detailed
+ information on how entities have been used in, participated in, and generated
+ by process executions. Betty has determined that <code>ex1:aggregated</code> used
+ entities <code>ex1:regionList1</code> and <code>ex1:dataSet1</code>, but she does not
+ know what function these entities played in the processing. Betty
+ also knows that <code>ex1:derek</code> controlled the process executions, but she does
+ not know if Derek was the analyst responsible for determining how the data
+ should be aggregated.
+ </p>
+ <p>
+ The above information is described as roles in the provenance data. The aggregation
+ process involved entities in four roles: the data to be aggregated (<code>ex1:dataToAggregate</code>),
+ the regions to aggregate by (<code>ex1:regionsToAggregateBy</code>), the
+ resulting aggregated data (<code>ex1:aggregatedData</code>), and the
+ analyst doing the aggregation (<code>ex1:analyst</code>).
+ </p>
+ <pre class="turtle example">
+ ex1:dataToAggregate a prov:Role .
+ ex1:regionsToAggregateBy a prov:Role .
+ ex1:aggregatedData a prov:Role .
+ ex1:analyst a prov:Role .
+ </pre>
+ <p>
+ In addition to the simple facts that the aggregation process used, generated or
+ was controlled by entities/agents as described in the sections above, the
+ provenance data contains more details of <i>how</i> these entities and agents
+ were involved, i.e. the roles they played. For example, the data below states
+ that the aggregation process (<code>ex1:aggregated</code>) included the usage
+ of the GovData data set (<code>ex1:dataSet1</code>) in the role of the data
+ to be aggregated (<code>ex1:dataToAggregate</code>).
+ </p>
+ <pre class="turtle example">
+ ex1:aggregated prov:hadQualifiedUsage [ a prov:Usage ;
+ prov:hadQualifiedEntity ex1:dataSet1 ;
+ prov:roleOfQualifiedEntity ex1:dataToAggregate ] .
+ </pre>
+ <p>
+ This can then be distinguished from the same execution's usage of the list of
+ regions because the roles played are different.
+ </p>
+ <pre class="turtle example">
+ ex1:aggregated prov:hadQualifiedUsage [ a prov:Usage ;
+ prov:hadQualifiedEntity ex1:regionList1 ;
+ prov:roleOfQualifiedEntity ex1:regionsToAggregateBy ] .
+ </pre>
+ <p>
+ Similarly, the provenance includes assertions that the same process was
+ controlled in a particular way (<code>ex1:analyst</code>) by Derek, and that
+ the entity <code>ex1:aggregate1</code> took the role of the aggregated
+ data in what the process generated.
+ </p>
+ <pre class="turtle example">
+ ex1:aggregated
+ prov:hadQualifiedControl [ a prov:Control ;
+ prov:hadQualifiedEntity ex1:derek ;
+ prov:roleOfQualifiedEntity ex1:analyst
+ ] ;
+ prov:hadQualifiedGeneration [ a prov:Generation ;
+ prov:hadQualifiedEntity ex1:aggregate1 ;
+ prov:roleOfQualifiedEntity ex1:aggregatedData
+ ] .
+ </pre>
</section>
<section>