0
# Relationships and Assertions
1
2
PROV relationship classes that connect elements together, representing the provenance graph structure. Relationships capture how entities, activities, and agents are related through generation, usage, derivation, attribution, and influence connections.
3
4
## Capabilities
5
6
### Base Relationship Class
7
8
```python { .api }
9
class ProvRelation(ProvRecord):
10
def __init__(self, bundle, identifier, attributes):
11
"""
12
Base class for all PROV relationships.
13
14
Args:
15
bundle (ProvBundle): Containing bundle
16
identifier (QualifiedName, optional): Relation identifier
17
attributes (dict): Relation attributes including formal arguments
18
"""
19
20
def is_relation(self):
21
"""
22
Check if this is a PROV relation.
23
24
Returns:
25
bool: Always True for relations
26
"""
27
28
def is_element(self):
29
"""
30
Check if this is a PROV element.
31
32
Returns:
33
bool: Always False for relations
34
"""
35
```
36
37
### Generation and Usage
38
39
Relationships between activities and entities they generate or use.
40
41
```python { .api }
42
class ProvGeneration(ProvRelation):
43
"""
44
Generation relationship: wasGeneratedBy(entity, activity, time, attributes).
45
46
Formal attributes:
47
- PROV_ATTR_ENTITY: Generated entity
48
- PROV_ATTR_ACTIVITY: Generating activity
49
- PROV_ATTR_TIME: Generation time (optional)
50
"""
51
52
class ProvUsage(ProvRelation):
53
"""
54
Usage relationship: used(activity, entity, time, attributes).
55
56
Formal attributes:
57
- PROV_ATTR_ACTIVITY: Using activity
58
- PROV_ATTR_ENTITY: Used entity
59
- PROV_ATTR_TIME: Usage time (optional)
60
"""
61
62
class ProvInvalidation(ProvRelation):
63
"""
64
Invalidation relationship: wasInvalidatedBy(entity, activity, time, attributes).
65
66
Formal attributes:
67
- PROV_ATTR_ENTITY: Invalidated entity
68
- PROV_ATTR_ACTIVITY: Invalidating activity
69
- PROV_ATTR_TIME: Invalidation time (optional)
70
"""
71
```
72
73
### Activity Relationships
74
75
Relationships between activities.
76
77
```python { .api }
78
class ProvCommunication(ProvRelation):
79
"""
80
Communication relationship: wasInformedBy(informed, informant, attributes).
81
82
Formal attributes:
83
- PROV_ATTR_INFORMED: Informed activity
84
- PROV_ATTR_INFORMANT: Informing activity
85
"""
86
87
class ProvStart(ProvRelation):
88
"""
89
Start relationship: wasStartedBy(activity, trigger, starter, time, attributes).
90
91
Formal attributes:
92
- PROV_ATTR_ACTIVITY: Started activity
93
- PROV_ATTR_TRIGGER: Starting entity
94
- PROV_ATTR_STARTER: Starting activity (optional)
95
- PROV_ATTR_TIME: Start time (optional)
96
"""
97
98
class ProvEnd(ProvRelation):
99
"""
100
End relationship: wasEndedBy(activity, trigger, ender, time, attributes).
101
102
Formal attributes:
103
- PROV_ATTR_ACTIVITY: Ended activity
104
- PROV_ATTR_TRIGGER: Ending entity
105
- PROV_ATTR_ENDER: Ending activity (optional)
106
- PROV_ATTR_TIME: End time (optional)
107
"""
108
```
109
110
### Derivation Relationships
111
112
Relationships showing how entities are derived from other entities.
113
114
```python { .api }
115
class ProvDerivation(ProvRelation):
116
"""
117
Derivation relationship: wasDerivedFrom(generatedEntity, usedEntity, activity, generation, usage, attributes).
118
119
Formal attributes:
120
- PROV_ATTR_GENERATED_ENTITY: Derived entity
121
- PROV_ATTR_USED_ENTITY: Source entity
122
- PROV_ATTR_ACTIVITY: Deriving activity (optional)
123
- PROV_ATTR_GENERATION: Generation record (optional)
124
- PROV_ATTR_USAGE: Usage record (optional)
125
"""
126
```
127
128
### Attribution and Responsibility
129
130
Relationships connecting entities and activities to responsible agents.
131
132
```python { .api }
133
class ProvAttribution(ProvRelation):
134
"""
135
Attribution relationship: wasAttributedTo(entity, agent, attributes).
136
137
Formal attributes:
138
- PROV_ATTR_ENTITY: Attributed entity
139
- PROV_ATTR_AGENT: Responsible agent
140
"""
141
142
class ProvAssociation(ProvRelation):
143
"""
144
Association relationship: wasAssociatedWith(activity, agent, plan, attributes).
145
146
Formal attributes:
147
- PROV_ATTR_ACTIVITY: Associated activity
148
- PROV_ATTR_AGENT: Associated agent
149
- PROV_ATTR_PLAN: Plan entity (optional)
150
"""
151
152
class ProvDelegation(ProvRelation):
153
"""
154
Delegation relationship: actedOnBehalfOf(delegate, responsible, activity, attributes).
155
156
Formal attributes:
157
- PROV_ATTR_DELEGATE: Delegated agent
158
- PROV_ATTR_RESPONSIBLE: Responsible agent
159
- PROV_ATTR_ACTIVITY: Delegating activity (optional)
160
"""
161
```
162
163
### Influence and Entity Relationships
164
165
General influence and specialized entity relationships.
166
167
```python { .api }
168
class ProvInfluence(ProvRelation):
169
"""
170
Influence relationship: wasInfluencedBy(influencee, influencer, attributes).
171
172
Formal attributes:
173
- PROV_ATTR_INFLUENCEE: Influenced element
174
- PROV_ATTR_INFLUENCER: Influencing element
175
"""
176
177
class ProvSpecialization(ProvRelation):
178
"""
179
Specialization relationship: specializationOf(specificEntity, generalEntity, attributes).
180
181
Formal attributes:
182
- PROV_ATTR_SPECIFIC_ENTITY: Specific entity
183
- PROV_ATTR_GENERAL_ENTITY: General entity
184
"""
185
186
class ProvAlternate(ProvRelation):
187
"""
188
Alternate relationship: alternateOf(alternate1, alternate2, attributes).
189
190
Formal attributes:
191
- PROV_ATTR_ALTERNATE1: First alternate entity
192
- PROV_ATTR_ALTERNATE2: Second alternate entity
193
"""
194
195
class ProvMention(ProvSpecialization):
196
"""
197
Mention relationship: mentionOf(specificEntity, generalEntity, bundle, attributes).
198
199
Formal attributes:
200
- PROV_ATTR_SPECIFIC_ENTITY: Specific entity
201
- PROV_ATTR_GENERAL_ENTITY: General entity
202
- PROV_ATTR_BUNDLE: Contextual bundle
203
"""
204
```
205
206
### Collection Relationships
207
208
Relationships for collection entities and their members.
209
210
```python { .api }
211
class ProvMembership(ProvRelation):
212
"""
213
Membership relationship: hadMember(collection, entity, attributes).
214
215
Formal attributes:
216
- PROV_ATTR_COLLECTION: Collection entity
217
- PROV_ATTR_ENTITY: Member entity
218
"""
219
```
220
221
## Bundle-Level Relationship Creation
222
223
Bundles provide convenient methods for creating relationships directly:
224
225
```python { .api }
226
class ProvBundle:
227
# Generation relationships
228
def generation(self, entity, activity, time=None, identifier=None, other_attributes=None):
229
"""Create a generation relationship."""
230
231
def usage(self, activity, entity, time=None, identifier=None, other_attributes=None):
232
"""Create a usage relationship."""
233
234
def invalidation(self, entity, activity, time=None, identifier=None, other_attributes=None):
235
"""Create an invalidation relationship."""
236
237
# Activity relationships
238
def communication(self, informed, informant, identifier=None, other_attributes=None):
239
"""Create a communication relationship."""
240
241
def start(self, activity, trigger, starter=None, time=None, identifier=None, other_attributes=None):
242
"""Create a start relationship."""
243
244
def end(self, activity, trigger, ender=None, time=None, identifier=None, other_attributes=None):
245
"""Create an end relationship."""
246
247
# Derivation relationships
248
def derivation(self, generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None):
249
"""Create a derivation relationship."""
250
251
def revision(self, generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None):
252
"""Create a revision derivation relationship."""
253
254
def quotation(self, generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None):
255
"""Create a quotation derivation relationship."""
256
257
def primary_source(self, generatedEntity, usedEntity, activity=None, generation=None, usage=None, identifier=None, other_attributes=None):
258
"""Create a primary source derivation relationship."""
259
260
# Attribution relationships
261
def attribution(self, entity, agent, identifier=None, other_attributes=None):
262
"""Create an attribution relationship."""
263
264
def association(self, activity, agent, plan=None, identifier=None, other_attributes=None):
265
"""Create an association relationship."""
266
267
def delegation(self, delegate, responsible, activity=None, identifier=None, other_attributes=None):
268
"""Create a delegation relationship."""
269
270
# Influence and entity relationships
271
def influence(self, influencee, influencer, identifier=None, other_attributes=None):
272
"""Create an influence relationship."""
273
274
def specialization(self, specificEntity, generalEntity, identifier=None, other_attributes=None):
275
"""Create a specialization relationship."""
276
277
def alternate(self, alternate1, alternate2, identifier=None, other_attributes=None):
278
"""Create an alternate relationship."""
279
280
def mention(self, specificEntity, generalEntity, bundle, identifier=None, other_attributes=None):
281
"""Create a mention relationship."""
282
283
# Collection relationships
284
def membership(self, collection, entity, identifier=None, other_attributes=None):
285
"""Create a membership relationship."""
286
```
287
288
## Usage Examples
289
290
### Creating Relationships Through Elements
291
292
```python
293
from prov.model import ProvDocument
294
295
doc = ProvDocument()
296
297
# Create elements
298
dataset = doc.entity('ex:dataset')
299
analysis = doc.activity('ex:analysis')
300
result = doc.entity('ex:result')
301
researcher = doc.agent('ex:researcher')
302
303
# Create relationships through element methods
304
analysis.used(dataset, time='2023-01-01T10:00:00')
305
result.wasGeneratedBy(analysis, time='2023-01-01T11:00:00')
306
result.wasAttributedTo(researcher)
307
analysis.wasAssociatedWith(researcher)
308
```
309
310
### Creating Relationships Through Bundle Methods
311
312
```python
313
# Same relationships using bundle methods
314
doc.usage(analysis, dataset, time='2023-01-01T10:00:00')
315
doc.generation(result, analysis, time='2023-01-01T11:00:00')
316
doc.attribution(result, researcher)
317
doc.association(analysis, researcher)
318
```
319
320
### Derivation Relationships
321
322
```python
323
# Simple derivation
324
processed_data = doc.entity('ex:processedData')
325
processed_data.wasDerivedFrom(dataset)
326
327
# Detailed derivation with activity
328
doc.derivation(
329
generatedEntity=processed_data,
330
usedEntity=dataset,
331
activity=analysis,
332
other_attributes={'ex:method': 'statistical_analysis'}
333
)
334
335
# Specialized derivations
336
revised_data = doc.entity('ex:revisedData')
337
doc.revision(revised_data, processed_data, analysis)
338
339
quoted_data = doc.entity('ex:quotedData')
340
doc.quotation(quoted_data, dataset)
341
```
342
343
### Entity Relationships
344
345
```python
346
# Specialization and alternates
347
specific_dataset = doc.entity('ex:specificDataset')
348
general_dataset = doc.entity('ex:generalDataset')
349
alternate_dataset = doc.entity('ex:alternateDataset')
350
351
doc.specialization(specific_dataset, general_dataset)
352
doc.alternate(dataset, alternate_dataset)
353
354
# Collection membership
355
collection = doc.entity('ex:dataCollection', {'prov:type': 'prov:Collection'})
356
doc.membership(collection, dataset)
357
doc.membership(collection, processed_data)
358
```
359
360
### Agent Relationships
361
362
```python
363
# Delegation
364
supervisor = doc.agent('ex:supervisor')
365
student = doc.agent('ex:student')
366
367
doc.delegation(student, supervisor, analysis)
368
369
# Multiple associations
370
tool = doc.agent('ex:analysisTool', {'prov:type': 'prov:SoftwareAgent'})
371
plan = doc.entity('ex:analysisPlan')
372
373
doc.association(analysis, researcher)
374
doc.association(analysis, tool, plan)
375
```
376
377
### Activity Communication
378
379
```python
380
# Activity communication
381
data_collection = doc.activity('ex:dataCollection')
382
data_analysis = doc.activity('ex:dataAnalysis')
383
384
doc.communication(data_analysis, data_collection)
385
386
# Activity start/end
387
trigger_event = doc.entity('ex:triggerEvent')
388
doc.start(analysis, trigger_event, data_collection)
389
doc.end(analysis, result, data_analysis)
390
```
391
392
### Working with Relationship Attributes
393
394
```python
395
# Add custom attributes to relationships
396
usage_rel = doc.usage(analysis, dataset,
397
other_attributes={
398
'ex:accessMethod': 'database_query',
399
'ex:queryTime': '0.5s'
400
})
401
402
# Access relationship attributes
403
attrs = usage_rel.attributes
404
formal_attrs = usage_rel.formal_attributes
405
extra_attrs = usage_rel.extra_attributes
406
407
print(f"Used entity: {usage_rel.get_attribute('prov:entity')}")
408
print(f"Using activity: {usage_rel.get_attribute('prov:activity')}")
409
```