0
# PROV Elements
1

2
Classes representing the core PROV elements: entities (things), activities (processes), and agents (responsible parties). Each element supports relationship creation and attribute management following the W3C PROV Data Model.
3

4
## Capabilities
5

6
### ProvElement (Base Class)
7

8
Base class for all PROV elements providing common functionality.
9

10
```python { .api }
11
class ProvElement(ProvRecord):
12
    def __init__(self, bundle, identifier, attributes=None):
13
        """
14
        Base class for PROV elements.
15
        
16
        Args:
17
            bundle (ProvBundle): Containing bundle
18
            identifier (QualifiedName): Element identifier
19
            attributes (dict, optional): Element attributes
20
        """
21
    
22
    def is_element(self):
23
        """
24
        Check if this is a PROV element.
25
        
26
        Returns:
27
            bool: Always True for elements
28
        """
29
    
30
    def is_relation(self):
31
        """
32
        Check if this is a PROV relation.
33
        
34
        Returns:
35
            bool: Always False for elements
36
        """
37
```
38

39
### ProvEntity
40

41
Represents entities - things in the world (physical, digital, conceptual, or otherwise).
42

43
```python { .api }
44
class ProvEntity(ProvElement):
45
    def wasGeneratedBy(self, activity, time=None, attributes=None):
46
        """
47
        Assert that this entity was generated by an activity.
48
        
49
        Args:
50
            activity (ProvActivity or QualifiedName): Generating activity
51
            time (datetime or str, optional): Generation time
52
            attributes (dict, optional): Additional attributes
53
            
54
        Returns:
55
            ProvGeneration: Created generation record
56
        """
57
    
58
    def wasInvalidatedBy(self, activity, time=None, attributes=None):
59
        """
60
        Assert that this entity was invalidated by an activity.
61
        
62
        Args:
63
            activity (ProvActivity or QualifiedName): Invalidating activity
64
            time (datetime or str, optional): Invalidation time
65
            attributes (dict, optional): Additional attributes
66
            
67
        Returns:
68
            ProvInvalidation: Created invalidation record
69
        """
70
    
71
    def wasDerivedFrom(self, other_entity, activity=None, generation=None, usage=None, attributes=None):
72
        """
73
        Assert that this entity was derived from another entity.
74
        
75
        Args:
76
            other_entity (ProvEntity or QualifiedName): Source entity
77
            activity (ProvActivity or QualifiedName, optional): Deriving activity
78
            generation (ProvGeneration or QualifiedName, optional): Generation record
79
            usage (ProvUsage or QualifiedName, optional): Usage record
80
            attributes (dict, optional): Additional attributes
81
            
82
        Returns:
83
            ProvDerivation: Created derivation record
84
        """
85
    
86
    def wasAttributedTo(self, agent, attributes=None):
87
        """
88
        Assert that this entity was attributed to an agent.
89
        
90
        Args:
91
            agent (ProvAgent or QualifiedName): Responsible agent
92
            attributes (dict, optional): Additional attributes
93
            
94
        Returns:
95
            ProvAttribution: Created attribution record
96
        """
97
    
98
    def alternateOf(self, alternate2):
99
        """
100
        Assert that this entity is an alternate of another entity.
101
        
102
        Args:
103
            alternate2 (ProvEntity or QualifiedName): Alternate entity
104
            
105
        Returns:
106
            ProvAlternate: Created alternate record
107
        """
108
    
109
    def specializationOf(self, general_entity):
110
        """
111
        Assert that this entity is a specialization of another entity.
112
        
113
        Args:
114
            general_entity (ProvEntity or QualifiedName): General entity
115
            
116
        Returns:
117
            ProvSpecialization: Created specialization record
118
        """
119
    
120
    def hadMember(self, entity):
121
        """
122
        Assert that this collection entity had a member.
123
        
124
        Args:
125
            entity (ProvEntity or QualifiedName): Member entity
126
            
127
        Returns:
128
            ProvMembership: Created membership record
129
        """
130
```
131

132
### ProvActivity
133

134
Represents activities - processes or functions that act upon or with entities.
135

136
```python { .api }
137
class ProvActivity(ProvElement):
138
    def __init__(self, bundle, identifier, startTime=None, endTime=None, other_attributes=None):
139
        """
140
        Create a PROV activity.
141
        
142
        Args:
143
            bundle (ProvBundle): Containing bundle
144
            identifier (QualifiedName): Activity identifier
145
            startTime (datetime or str, optional): Activity start time
146
            endTime (datetime or str, optional): Activity end time
147
            other_attributes (dict, optional): Additional attributes
148
        """
149
    
150
    def set_time(self, startTime=None, endTime=None):
151
        """
152
        Set the time bounds for this activity.
153
        
154
        Args:
155
            startTime (datetime or str, optional): Start time
156
            endTime (datetime or str, optional): End time
157
        """
158
    
159
    def get_startTime(self):
160
        """
161
        Get the start time of this activity.
162
        
163
        Returns:
164
            datetime: Start time or None
165
        """
166
    
167
    def get_endTime(self):
168
        """
169
        Get the end time of this activity.
170
        
171
        Returns:
172
            datetime: End time or None
173
        """
174
    
175
    def used(self, entity, time=None, attributes=None):
176
        """
177
        Assert that this activity used an entity.
178
        
179
        Args:
180
            entity (ProvEntity or QualifiedName): Used entity
181
            time (datetime or str, optional): Usage time
182
            attributes (dict, optional): Additional attributes
183
            
184
        Returns:
185
            ProvUsage: Created usage record
186
        """
187
    
188
    def wasInformedBy(self, other_activity, attributes=None):
189
        """
190
        Assert that this activity was informed by another activity.
191
        
192
        Args:
193
            other_activity (ProvActivity or QualifiedName): Informing activity
194
            attributes (dict, optional): Additional attributes
195
            
196
        Returns:
197
            ProvCommunication: Created communication record
198
        """
199
    
200
    def wasStartedBy(self, trigger, starter=None, time=None, attributes=None):
201
        """
202
        Assert that this activity was started by a trigger entity.
203
        
204
        Args:
205
            trigger (ProvEntity or QualifiedName): Starting entity
206
            starter (ProvActivity or QualifiedName, optional): Starting activity
207
            time (datetime or str, optional): Start time
208
            attributes (dict, optional): Additional attributes
209
            
210
        Returns:
211
            ProvStart: Created start record
212
        """
213
    
214
    def wasEndedBy(self, trigger, ender=None, time=None, attributes=None):
215
        """
216
        Assert that this activity was ended by a trigger entity.
217
        
218
        Args:
219
            trigger (ProvEntity or QualifiedName): Ending entity
220
            ender (ProvActivity or QualifiedName, optional): Ending activity
221
            time (datetime or str, optional): End time
222
            attributes (dict, optional): Additional attributes
223
            
224
        Returns:
225
            ProvEnd: Created end record
226
        """
227
    
228
    def wasAssociatedWith(self, agent, plan=None, attributes=None):
229
        """
230
        Assert that this activity was associated with an agent.
231
        
232
        Args:
233
            agent (ProvAgent or QualifiedName): Associated agent
234
            plan (ProvEntity or QualifiedName, optional): Plan entity
235
            attributes (dict, optional): Additional attributes
236
            
237
        Returns:
238
            ProvAssociation: Created association record
239
        """
240
```
241

242
### ProvAgent
243

244
Represents agents - entities that bear responsibility for activities or other agents' actions.
245

246
```python { .api }
247
class ProvAgent(ProvElement):
248
    def actedOnBehalfOf(self, other_agent, activity=None, attributes=None):
249
        """
250
        Assert that this agent acted on behalf of another agent.
251
        
252
        Args:
253
            other_agent (ProvAgent or QualifiedName): Responsible agent
254
            activity (ProvActivity or QualifiedName, optional): Delegating activity
255
            attributes (dict, optional): Additional attributes
256
            
257
        Returns:
258
            ProvDelegation: Created delegation record
259
        """
260
```
261

262
### ProvRecord (Base Class)
263

264
Base class for all PROV records providing common record functionality.
265

266
```python { .api }
267
class ProvRecord:
268
    def get_type(self):
269
        """
270
        Get the PROV type of this record.
271
        
272
        Returns:
273
            QualifiedName: PROV type
274
        """
275
    
276
    def get_asserted_types(self):
277
        """
278
        Get all asserted types for this record.
279
        
280
        Returns:
281
            set[QualifiedName]: Asserted types
282
        """
283
    
284
    def add_asserted_type(self, type_identifier):
285
        """
286
        Add an asserted type to this record.
287
        
288
        Args:
289
            type_identifier (QualifiedName): Type to assert
290
        """
291
    
292
    def get_attribute(self, attr_name):
293
        """
294
        Get attribute values by name.
295
        
296
        Args:
297
            attr_name (QualifiedName or str): Attribute name
298
            
299
        Returns:
300
            set: Attribute values
301
        """
302
    
303
    def add_attributes(self, attributes):
304
        """
305
        Add multiple attributes to this record.
306
        
307
        Args:
308
            attributes (dict or iterable): Attributes to add
309
        """
310
    
311
    def copy(self):
312
        """
313
        Create a copy of this record.
314
        
315
        Returns:
316
            ProvRecord: Copied record
317
        """
318
    
319
    def get_provn(self):
320
        """
321
        Get PROV-N representation of this record.
322
        
323
        Returns:
324
            str: PROV-N string
325
        """
326
    
327
    # Properties
328
    @property
329
    def identifier(self):
330
        """Record identifier (QualifiedName or None)."""
331
        
332
    @property
333
    def attributes(self):
334
        """List of (name, value) attribute pairs."""
335
        
336
    @property
337
    def args(self):
338
        """Tuple of formal arguments."""
339
        
340
    @property
341
    def formal_attributes(self):
342
        """Tuple of formal attributes."""
343
        
344
    @property
345
    def extra_attributes(self):
346
        """Tuple of extra attributes."""
347
        
348
    @property
349
    def bundle(self):
350
        """Containing bundle."""
351
        
352
    @property
353
    def label(self):
354
        """Human-readable label."""
355
        
356
    @property
357
    def value(self):
358
        """Primary value of this record."""
359
```
360

361
## Usage Examples
362

363
### Creating Entities
364

365
```python
366
from prov.model import ProvDocument
367

368
doc = ProvDocument()
369

370
# Create entities with attributes
371
entity1 = doc.entity('ex:dataset1', {
372
    'prov:label': 'My Dataset',
373
    'prov:type': 'prov:Collection',
374
    'ex:size': 1000
375
})
376

377
entity2 = doc.entity('ex:derivedDataset', {
378
    'prov:label': 'Processed Dataset'
379
})
380

381
# Entities can be derived from other entities
382
entity2.wasDerivedFrom(entity1)
383
```
384

385
### Creating Activities
386

387
```python
388
import datetime
389

390
# Create activity with time bounds
391
activity = doc.activity('ex:analysis', 
392
    startTime=datetime.datetime(2023, 1, 1, 10, 0, 0),
393
    endTime=datetime.datetime(2023, 1, 1, 12, 0, 0),
394
    other_attributes={
395
        'prov:label': 'Data Analysis Process',
396
        'ex:tool': 'Python'
397
    }
398
)
399

400
# Activities use entities and generate new ones
401
activity.used(entity1)
402
entity2.wasGeneratedBy(activity)
403
```
404

405
### Creating Agents
406

407
```python
408
# Create different types of agents
409
person = doc.agent('ex:researcher', {
410
    'prov:type': 'prov:Person',
411
    'foaf:name': 'Dr. Jane Smith',
412
    'foaf:mbox': 'jane@example.org'
413
})
414

415
organization = doc.agent('ex:university', {
416
    'prov:type': 'prov:Organization', 
417
    'foaf:name': 'Example University'
418
})
419

420
software = doc.agent('ex:script', {
421
    'prov:type': 'prov:SoftwareAgent',
422
    'ex:version': '1.0'
423
})
424

425
# Agents can be associated with activities
426
activity.wasAssociatedWith(person)
427
activity.wasAssociatedWith(software, plan=doc.entity('ex:analysisScript'))
428

429
# Agents can act on behalf of other agents
430
person.actedOnBehalfOf(organization)
431
```
432

433
### Working with Attributes
434

435
```python
436
# Add attributes after creation
437
entity1.add_attributes({
438
    'dc:creator': 'Data Collection System',
439
    'dc:created': '2023-01-01T09:00:00'
440
})
441

442
# Get specific attributes
443
labels = entity1.get_attribute('prov:label')
444
types = entity1.get_asserted_types()
445

446
# Check record type
447
if entity1.is_element():
448
    print("This is a PROV element")
449
    print(f"Element type: {entity1.get_type()}")
450
```