EDXML Ontologies¶
When reading an EDXML data stream, the parser consumes both events and ontology information and provides an interface to access both. On the other hand, EDXML writers require providing an ontology matching the events that are written. In the EDXML SDK, ontology information is represented by instances of the Ontology class. This class is supported by several peripheral classes representing event types, event properties, object types, data types and event sources.
Ontologies can be populated by using the various named constructors of the Ontology class. Alternatively, ontology elements can be fetched from an Ontology Brick. or generated using an event type factory.
Ontology Description & Visualization¶
EDXML data sources can provide a wealth of knowledge. Learning if and how that knowledge will help you in your data analysis tasks requires studying its output ontology and how it fits into other domain ontologies that you might use. Unless an EDXML data source can just tell you.
The describe_producer_rst()
function can do just that. Given an ontology it will list the object types and concepts that it uses and how it aids reasoning about data. For example, the description might say: Identifies computers as network routers or Relates IP addresses to host names. The name of the function indicates that the generated descriptions are meant for describing EDXML data producers such as data sources or data processors.
When designing an EDXML ontology, getting the relations and concept associations right is critical. A picture can be most helpful to review your design. Using the generate_graph_property_concepts()
function you can generate a visualization showing the reasoning paths provided by a given ontology. It displays the concepts and object types and how they are connected.
API Documentation¶
The API documentation can be found below.
Ontology Elements
- Ontology
- EventType
- EventTypeAttachment
- EventProperty
- PropertyConcept
- ObjectType
- Concept
- DataType
- EventSource
Base Classes
Functions
Ontology¶
-
class
edxml.ontology.
Ontology
¶ Bases:
edxml.ontology.ontology_element.OntologyElement
Class representing an EDXML ontology
-
clear
()¶ Removes all event types, object types, concepts and event source definitions from the ontology.
Returns: The ontology Return type: edxml.ontology.Ontology
-
get_version
()¶ Returns the current ontology version. The initial version of a newly created empty ontology is zero. On each change, the version is incremented.
Note that this has nothing to do with versioning, upgrading and downgrading of EDXML ontologies. EDXML ontologies have no global version. The version that we return here is for change tracking.
Returns: Ontology version Return type: int
-
is_modified_since
(version)¶ Returns True if the ontology is newer than the specified version. Returns False if the ontology version is equal or older.
Returns: Return type: bool
-
classmethod
register_brick
(brick)¶ Registers an ontology brick with the Ontology class, allowing Ontology instances to use any definitions offered by that brick. Ontology brick packages expose a register() method, which calls this method to register itself with the Ontology class.
Parameters: brick (edxml.ontology.Brick) – Ontology brick
-
create_object_type
(name, display_name_singular=None, display_name_plural=None, description=None, data_type='string:0:mc:u')¶ Creates and returns a new ObjectType instance. When no display names are specified, display names will be created from the object type name. If only a singular form is specified, the plural form will be auto-generated by appending an ‘s’.
The object type is not validated on creation. This allows for creating a crude initial definition using this method and finish the definition later. If you do intend to create a valid definition from the start, it is recommended to validate it immediately.
Parameters: - name (str) – object type name
- display_name_singular (str) – display name (singular form)
- display_name_plural (str) – display name (plural form)
- description (str) – short description of the object type
- data_type (str) – a valid EDXML data type
Returns: The ObjectType instance
Return type:
-
create_concept
(name, display_name_singular=None, display_name_plural=None, description=None)¶ Creates and returns a new Concept instance. When no display names are specified, display names will be created from the concept name. If only a singular form is specified, the plural form will be auto-generated by appending an ‘s’.
The concept is not validated on creation. This allows for creating a crude initial definition using this method and finish the definition later. If you do intend to create a valid definition from the start, it is recommended to validate it immediately.
Parameters: - name (str) – concept name
- display_name_singular (str) – display name (singular form)
- display_name_plural (str) – display name (plural form)
- description (str) – short description of the concept
Returns: The Concept instance
Return type:
-
create_event_type
(name, display_name_singular=None, display_name_plural=None, description=None)¶ Creates and returns a new EventType instance. When no display names are specified, display names will be created from the event type name. If only a singular form is specified, the plural form will be auto-generated by appending an ‘s’.
The event type is not validated on creation. This allows for creating a crude initial definition using this method and finish the definition later. If you do intend to create a valid definition from the start, it is recommended to validate it immediately.
Parameters: - name (str) – Event type name
- display_name_singular (str) – Display name (singular form)
- display_name_plural (str) – Display name (plural form)
- description (str) – Event type description
Returns: The EventType instance
Return type:
-
create_event_source
(uri, description='no description available', acquisition_date=None)¶ Creates a new event source definition.
The source is not validated on creation. This allows for creating a crude initial definition using this method and finish the definition later. If you do intend to create a valid definition from the start, it is recommended to validate it immediately.
If the URI is missing a leading and / or trailing slash, these will be appended automatically.
Parameters: - uri (str) – The source URI
- description (str) – Description of the source
- acquisition_date (Optional[str]) – Acquisition date in format yyyymmdd
Returns: Return type:
-
delete_object_type
(object_type_name)¶ Deletes specified object type from the ontology, if it exists.
Warning
Deleting object types may result in an invalid ontology.
Parameters: object_type_name (str) – An EDXML object type name Returns: The ontology Return type: edxml.ontology.Ontology
-
delete_concept
(concept_name)¶ Deletes specified concept from the ontology, if it exists.
Warning
Deleting concepts may result in an invalid ontology.
Parameters: concept_name (str) – An EDXML concept name Returns: The ontology Return type: edxml.ontology.Ontology
-
delete_event_type
(event_type_name)¶ Deletes specified event type from the ontology, if it exists.
Warning
Deleting event types may result in an invalid ontology.
Parameters: event_type_name (str) – An EDXML event type name Returns: The ontology Return type: edxml.ontology.Ontology
-
delete_event_source
(source_uri)¶ Deletes specified event source definition from the ontology, if it exists.
Parameters: source_uri (str) – An EDXML event source URI Returns: The ontology Return type: edxml.ontology.Ontology
-
get_event_types
()¶ Returns a dictionary containing all event types in the ontology. The keys are the event type names, the values are EventType instances.
Returns: EventType instances Return type: Dict[str, edxml.ontology.EventType]
-
get_object_types
()¶ Returns a dictionary containing all object types in the ontology. The keys are the object type names, the values are ObjectType instances.
Returns: ObjectType instances Return type: Dict[str, edxml.ontology.ObjectType]
-
get_concepts
()¶ Returns a dictionary containing all concepts in the ontology. The keys are the concept names, the values are Concept instances.
Returns: Concept instances Return type: Dict[str, edxml.ontology.Concept]
-
get_event_sources
()¶ Returns a dictionary containing all event sources in the ontology. The keys are the event source URIs, the values are EventSource instances.
Returns: EventSource instances Return type: Dict[str, edxml.ontology.EventSource]
-
get_event_type_names
()¶ Returns the list of names of all defined event types.
Returns: List of event type names Return type: List[str]
-
get_object_type_names
()¶ Returns the list of names of all defined object types.
Returns: List of object type names Return type: List[str]
-
get_event_source_uris
()¶ Returns the list of URIs of all defined event sources.
Returns: List of source URIs Return type: List[str]
-
get_concept_names
()¶ Returns the list of names of all defined concepts.
Returns: List of concept names Return type: List[str]
-
get_event_type
(name)¶ Returns the EventType instance having specified event type name, or None if no event type with that name exists.
Parameters: name (str) – Event type name Returns: The event type instance Return type: edxml.ontology.EventType
-
get_object_type
(name, import_brick=True)¶ Returns the ObjectType instance having specified object type name, or None if no object type with that name exists.
When the ontology does not contain the requested concept it will attempt to find the concept in any registered ontology bricks and import it. This can be turned off by setting import_brick to False.
Parameters: - name (str) – Object type name
- import_brick (bool) – Brick import flag
Returns: The object type instance
Return type:
-
get_concept
(name, import_brick=True)¶ Returns the Concept instance having specified concept name, or None if no concept with that name exists.
When the ontology does not contain the requested concept it will attempt to find the concept in any registered ontology bricks and import it. This can be turned off by setting import_brick to False.
Parameters: - name (str) – Concept name
- import_brick (bool) – Brick import flag
Returns: The Concept instance
Return type:
-
get_event_source
(uri)¶ Returns the EventSource instance having specified event source URI, or None if no event source with that URI exists.
Parameters: uri (str) – Event source URI Returns: The event source instance Return type: edxml.ontology.EventSource
-
validate
()¶ Checks if the defined ontology is a valid EDXML ontology.
Raises: EDXMLOntologyValidationError
Returns: The ontology Return type: edxml.ontology.Ontology
-
classmethod
create_from_xml
(ontology_element)¶ Parameters: ontology_element (lxml.etree.Element) – Returns: The ontology Return type: edxml.ontology.Ontology
-
update
(other_ontology, validate=True)¶ Updates the ontology using the definitions contained in another ontology. The other ontology may be specified in the form of an Ontology instance or an lxml Element containing a full ontology element.
Parameters: - other_ontology (Union[lxml.etree.Element,edxml.ontology.Ontology]) –
- validate (bool) – Validate the resulting ontology
Raises: EDXMLOntologyValidationError
Returns: The ontology
Return type:
-
generate_xml
()¶ Generates an lxml etree Element representing the EDXML <ontology> tag for this ontology.
Returns: The element Return type: etree.Element
-
EventType¶
-
class
edxml.ontology.
EventType
(ontology, name, display_name_singular=None, display_name_plural=None, description=None, summary='no description available', story='no description available', parent=None)¶ Bases:
edxml.ontology.ontology_element.VersionedOntologyElement
,collections.abc.MutableMapping
Class representing an EDXML event type. The class provides access to event properties by means of a dictionary interface. For each of the properties there is a key matching the name of the event property, the value is the property itself.
-
relations
¶ Iterable[PropertyRelation]
Type: Returns
-
get_name
()¶ Returns the event type name
Returns: Return type: str
-
get_description
()¶ Returns the event type description
Returns: Return type: str
-
get_display_name_singular
()¶ Returns the event type display name, in singular form.
Returns: Return type: str
-
get_display_name_plural
()¶ Returns the event type display name, in plural form.
Returns: Return type: Optional[str]
-
get_timespan_property_name_start
()¶ Returns the name of the property that defines the start of the time span of the events. Returns None when the start of the event time span is the smallest of the event timestamps.
Returns: Return type: Optional[str]
-
get_timespan_property_name_end
()¶ Returns the name of the property that defines the end of the time span of the events. Returns None when the end of the event time span is the largest of the event timestamps.
Returns: Return type: str
-
get_version_property_name
()¶ Returns the name of the property that defines the version of the events that is used to merge colliding events. Returns None when the event type does not define an event version.
Returns: Return type: Optional[str]
-
get_sequence_property_name
()¶ Returns the name of the property that defines the sequence numbers of the events. Returns None when the event type does not define a sequence number.
Returns: Return type: Optional[str]
-
get_properties
()¶ Returns a dictionary containing all properties of the event type. The keys in the dictionary are the property names, the values are the EDXMLProperty instances.
Returns: Properties Return type: Dict[str,EventProperty]
-
get_hashed_properties
()¶ Returns a dictionary containing all properties of the event type that are used to compute event hashes. The keys in the dictionary are the property names, the values are the EDXMLProperty instances.
Returns: Properties Return type: Dict[str, EventProperty]
-
get_property_relations
(relation_type=None, source=None, target=None)¶ Returns a dictionary containing the property relations that are defined in the event type. The keys are relation IDs that should be considered opaque.
Optionally, the relations can be filtered on type, source and target.
Parameters: - relation_type (str) – Relation type
- source (str) – Name of source property
- target (str) – Name of target property
Returns: Return type: Dict[str,PropertyRelation]
-
get_attachment
(name)¶ Returns the specified attachment definition.
Raises: KeyError
Returns: Return type: EventTypeAttachment
-
get_attachments
()¶ Returns a dictionary containing the attachments that are defined for the event type. The keys are attachment IDs.
Returns: Return type: Dict[str,EventTypeAttachment]
-
get_timespan_property_names
()¶ Returns a tuple containing the names of the properties that determine the start and end of the event time spans, in that order. Note that either may be None.
Returns: Tuple[Optional[str], Optional[str]]
-
is_timeless
()¶ Returns True when the event type is timeless, which means that it has no properties that are associated with the datetime data type. Returns False otherwise.
Returns: Return type: bool
-
is_timeful
()¶ Returns True when the event type is timeful, which means that it has at least one property that is associated with the datetime data type. Returns False otherwise.
Returns: Return type: bool
-
get_summary_template
()¶ Returns the event summary template.
Returns: Return type: str
-
get_story_template
()¶ Returns the event story template.
Returns: Return type: str
-
get_parent
()¶ Returns the parent event type, or None if no parent has been defined.
Returns: The parent event type Return type: EventTypeParent
-
get_version
()¶ Returns the version of the source definition.
Returns: Return type: int
-
create_property
(name, object_type_name, description=None)¶ Create a new event property.
Note
The description should be really short, indicating which role the object has in the event type.
Parameters: - name (str) – Property name
- object_type_name (str) – Name of the object type
- description (str) – Property description
Returns: The EventProperty instance
Return type:
-
add_property
(prop)¶ Add specified property
Parameters: prop (EventProperty) – EventProperty instance Returns: The EventType instance Return type: edxml.ontology.EventType
-
remove_property
(property_name)¶ Removes specified property from the event type.
Notes
Since the EventType class has a dictionary interface for accessing event type properties, you can also use the del operator to delete a property.
Parameters: property_name (str) – The name of the property Returns: The EventType instance Return type: edxml.ontology.EventType
-
create_relation
(relation_type, source, target, description=None, predicate=None, source_concept_name=None, target_concept_name=None, confidence=None)¶ Create a new property relation
Parameters: - relation_type (str) – Relation relation_type (‘inter’, ‘intra’, …)
- source (str) – Name of source property
- target (str) – Name of target property
- description (Optional[str]) – Relation description, with property placeholders
- predicate (Optional[str]) – free form predicate
- source_concept_name (Optional[str]) – Name of the source concept
- target_concept_name (Optional[str]) – Name of the target concept
- confidence (Optional[float]) – Relation confidence [0.0,1.0]
Returns: The PropertyRelation instance
Return type: PropertyRelation
-
add_relation
(relation)¶ Add specified property relation. It is recommended to use the methods from the EventProperty class in stead, to create property relations using a syntax that yields more readable code.
Parameters: relation (PropertyRelation) – Property relation Returns: The EventType instance Return type: edxml.ontology.EventType
-
create_attachment
(name)¶ Create a new attachment and add it to the event type. The description and singular display name are set to the attachment name. The plural form of the display name is constructed by appending an ‘s’ to the singular form.
Parameters: name (str) – attachment name Returns: EventTypeAttachment
-
add_attachment
(attachment)¶ Add specified attachment definition to the event type.
Parameters: attachment (EventTypeAttachment) – attachment definition Returns: The EventType instance Return type: edxml.ontology.EventType
-
make_child
(siblings_description, parent)¶ Marks this event type as child of the specified parent event type. In case all hashed properties of the parent also exist in the child, a default property mapping will be generated, mapping properties based on identical property names.
Notes
You must call is_parent() on the parent before calling make_children()
Parameters: - siblings_description (str) – EDXML siblings-description attribute
- parent (edxml.ontology.EventType) – Parent event type
Returns: The event type parent definition
Return type:
-
make_parent
(parent_description, child)¶ Marks this event type as parent of the specified child event type.
Notes
To be used in conjunction with the make_children() method.
Parameters: - parent_description (str) – EDXML parent-description attribute
- child (edxml.ontology.EventType) – Child event type
Returns: The EventType instance
Return type:
-
set_description
(description)¶ Sets the event type description
Parameters: description (str) – Description Returns: The EventType instance Return type: edxml.ontology.EventType
-
set_parent
(parent)¶ Set the parent event type
Notes
It is recommended to use the make_children() and is_parent() methods in stead whenever possible, which results in more readable code.
Parameters: parent (EventTypeParent) – Parent event type Returns: The EventType instance Return type: edxml.ontology.EventType
-
set_name
(event_type_name)¶ Sets the name of the event type.
Parameters: event_type_name (str) – Event type name Returns: The EventType instance Return type: edxml.ontology.EventType
-
set_display_name
(singular, plural=None)¶ Configure the display name. If the plural form is omitted, it will be auto-generated by appending an ‘s’ to the singular form.
Parameters: - singular (str) – Singular display name
- plural (str) – Plural display name
Returns: The EventType instance
Return type:
-
set_summary_template
(summary)¶ Set the event summary template
Parameters: summary (str) – The event summary template Returns: The EventType instance Return type: edxml.ontology.EventType
-
set_story_template
(story)¶ Set the event story template.
Parameters: story (str) – The event story template Returns: The EventType instance Return type: edxml.ontology.EventType
-
set_version
(version)¶ Sets the concept version
Parameters: version (int) – Version Returns: The Concept instance Return type: edxml.ontology.Concept
-
set_timespan_property_name_start
(property_name)¶ Sets the name of the property that defines the start of the time spans of the events.
Parameters: property_name (str) – Returns: The EventType instance Return type: edxml.ontology.EventType
-
set_timespan_property_name_end
(property_name)¶ Sets the name of the property that defines the end of the time spans of the events.
Parameters: property_name (str) – Returns: The EventType instance Return type: edxml.ontology.EventType
-
set_version_property_name
(property_name)¶ Sets the name of the property that defines the versions of the events that is used to merge colliding events.
Parameters: property_name (str) – Returns: The EventType instance Return type: edxml.ontology.EventType
-
set_sequence_property_name
(property_name)¶ Sets the name of the property that defines the sequence numbers of the events.
Parameters: property_name (str) – Returns: The EventType instance Return type: edxml.ontology.EventType
-
evaluate_template
(edxml_event, which='story', capitalize=True, colorize=False)¶ Evaluates the event story or summary template of an event type using specified event, returning the result.
By default, the story template is evaluated, unless which is set to ‘summary’.
By default, we will try to capitalize the first letter of the resulting string, unless capitalize is set to False.
Optionally, the output can be colorized. At his time this means that, when printed on the terminal, the objects in the evaluated string will be displayed using bold white characters.
Parameters: - edxml_event (edxml.EDXMLEvent) – the EDXML event to use
- which (bool) – which template to evaluate
- capitalize (bool) – Capitalize output or not
- colorize (bool) – Colorize output or not
Returns: Return type: str
-
validate
()¶ Checks if the event type definition is valid. Since it does not have access to the full ontology, the context of the event type is not considered. For example, it does not check if the event type definition refers to a parent event type that actually exists. Also, templates are not validated.
Raises: EDXMLOntologyValidationError
Returns: The EventType instance Return type: EventType
-
update
(event_type)¶ Updates the event type to match the EventType instance passed to this method, returning the updated instance.
Parameters: event_type (edxml.ontology.EventType) – The new EventType instance Returns: The updated EventType instance Return type: edxml.ontology.EventType
-
generate_xml
()¶ Generates an lxml etree Element representing the EDXML <event-type> tag for this event type.
Returns: The element Return type: etree.Element
-
get_singular_property_names
()¶ Returns a list of properties that cannot have multiple values.
Returns: List of property names Return type: list(str)
-
get_mandatory_property_names
()¶ Returns a list of properties that must have a value
Returns: List of property names Return type: list(str)
-
validate_event_structure
(edxml_event)¶ Validates the structure of the event by comparing its properties and their object count to the requirements of the event type. Generates exceptions that are much more readable than standard XML validation exceptions.
Parameters: edxml_event (edxml.EDXMLEvent) – Raises: EDXMLEventValidationError
Returns: The EventType instance Return type: edxml.ontology.EventType
-
validate_event_objects
(event, property_name=None)¶ Validates the object values in the event by comparing the values with their data types. Generates exceptions that are much more readable than standard XML validation exceptions.
Optionally the validation can be limited to a specific property only by setting the property_name argument.
Parameters: - event (edxml.EDXMLEvent) –
- property_name (str) –
Raises: EDXMLEventValidationError
Returns: The EventType instance
Return type:
-
validate_event_attachments
(event, attachment_name=None)¶ Validates the attachment values in the event by comparing to the event type definition. Generates exceptions that are much more readable than standard XML validation exceptions.
Optionally the validation can be limited to a specific attachment only by setting the attachment_name argument.
Parameters: - event (edxml.EDXMLEvent) –
- attachment_name (str) –
Raises: EDXMLEventValidationError
Returns: The EventType instance
Return type:
-
normalize_event_objects
(event, property_names)¶ Normalizes the object values in the event, resulting in valid EDXML object value strings. Raises an exception in case an object value cannot be normalized.
Parameters: - event (edxml.EDXMLEvent) –
- property_names (List[str]) –
Raises: EDXMLEventValidationError
Returns: The EventType instance
Return type:
-
generate_relax_ng
(ontology, namespaced=True)¶ Returns an ElementTree containing a RelaxNG schema for validating events of this event type. It requires an Ontology instance for obtaining the definitions of objects types referred to by the properties of the event type.
By default, the schema expects the events to be namespaced. This can be turned off for validating events that will be added into an EDXML data stream that has a default namespace that events will inherit.
Parameters: - ontology (Ontology) – Ontology containing the event type
- namespaced (bool) – Require a namespace specification or not
Returns: The schema
Return type: lxml.etree.RelaxNG
-
merge_events
(events)¶ Merges the specified events and returns the merged event. The merged event is an instance of the same class as the first input event.
Parameters: events (List[edxml.EDXMLEvent]) – List of events Returns: Merged event Return type: edxml.EDXMLEvent
-
EventTypeAttachment¶
-
class
edxml.ontology.
EventTypeAttachment
(event_type, name='default', media_type='text/plain', display_name_singular=None, display_name_plural=None, description=None, encode_base64=False)¶ Bases:
edxml.ontology.ontology_element.OntologyElement
Class representing an EDXML event attachment definition
Creates a new event attachment definition.
When no description is given, the name is used as description. When no singular display name is given, the name is used as singular display name. When no plural display name is given, it is constructed by appending an ‘s’ to the singular form.
Parameters: - event_type (edxml.ontology.EventType) – The event type containing the attachment definition
- name (str) – Name of the attachment
- media_type (str) – RFC 6838 media type
- display_name_singular (str) – display name (singular)
- display_name_plural (str) – display name (plural)
- description (str) – Description (EDXML template)
- encode_base64 (bool) – Encode as base64 string yes / no
-
set_description
(description)¶ Sets the EDXML attachment description
Parameters: description (str) – description Returns: The EventTypeAttachment instance Return type: edxml.ontology.EventTypeAttachment
-
set_display_name
(singular, plural=None)¶ Configure the display name. If the plural form is omitted, it will be auto-generated by appending an ‘s’ to the singular form.
Parameters: - singular (str) – Singular display name
- plural (str) – Plural display name
Returns: The EventTypeAttachment instance
Return type:
-
set_media_type
(media_type)¶ Configure the media type. This must be a valid RFC 6838 media type.
Parameters: media_type (str) – Media type Returns: The EventTypeAttachment instance Return type: edxml.ontology.EventTypeAttachment
-
set_encoding
(encoding)¶ Sets the encoding to either ‘unicode’ or ‘base64’.
Returns: The EventTypeAttachment instance Return type: edxml.ontology.EventTypeAttachment
-
set_encoding_unicode
()¶ Sets the encoding to unicode, which means that the attachment must be a valid unicode string. This is the default encoding for attachments.
Returns: The EventTypeAttachment instance Return type: edxml.ontology.EventTypeAttachment
-
set_encoding_base64
()¶ Sets the encoding to base64, which means that the attachment must be a valid base64 encoding string.
Returns: The EventTypeAttachment instance Return type: edxml.ontology.EventTypeAttachment
-
get_name
()¶ Returns the attachment name
Returns: Return type: str
-
get_description
()¶ Returns the attachment description
Returns: Return type: str
-
get_display_name_singular
()¶ Returns the display name, in singular form.
Returns: Return type: str
-
get_display_name_plural
()¶ Returns the display name, in plural form.
Returns: Return type: str
-
get_media_type
()¶ Returns the media type.
Returns: Return type: str
-
get_encoding
()¶ Returns the encoding, either ‘unicode’ or ‘base64’.
Returns: Return type: str
-
is_unicode_string
()¶ Returns True when the attachment is a unicode encoded string, returns False otherwise.
Returns: Return type: bool
-
is_base64_string
()¶ Returns True when the attachment is a base64 encoded string, returns False otherwise.
Returns: Return type: bool
-
validate
()¶ Checks if the event type attachment is valid. It only looks at the attributes of the definition itself. For example, it does not check that the attachment has an id that is unique within the event type.
Raises: EDXMLOntologyValidationError
Returns: The EventTypeAttachment instance Return type: edxml.ontology.EventTypeAttachment
-
update
(attachment)¶ Updates the attachment to match the EventTypeAttachment instance passed to this method, returning the updated instance.
Parameters: attachment (edxml.ontology.EventTypeAttachment) – The new EventTypeAttachment instance Returns: The updated EventTypeAttachment instance Return type: edxml.ontology.EventTypeAttachment
-
generate_xml
()¶ Generates an lxml etree Element representing the EDXML <attachment> tag for this event type attachment.
Returns: The element Return type: etree.Element
EventTypeParent¶
-
class
edxml.ontology.
EventTypeParent
(child_event_type, parent_event_type_name, property_map, parent_description='belonging to', siblings_description='sharing')¶ Bases:
edxml.ontology.ontology_element.OntologyElement
Class representing an EDXML event type parent
-
classmethod
create
(child_event_type, parent_event_type_name, property_map, parent_description='belonging to', siblings_description='sharing')¶ Creates a new event type parent. The PropertyMap argument is a dictionary mapping property names of the child event type to property names of the parent event type.
Note
All hashed properties of the parent event type must appear in the property map.
Note
The parent event type must be defined in the same EDXML stream as the child.
Parameters: - child_event_type (EventType) – The child event type
- parent_event_type_name (str) – Name of the parent event type
- property_map (Dict[str, str]) – Property map
- parent_description (Optional[str]) – The EDXML parent-description attribute
- siblings_description (Optional[str]) – The EDXML siblings-description attribute
Returns: The EventTypeParent instance
Return type:
-
set_parent_description
(description)¶ Sets the EDXML parent-description attribute
Parameters: description (str) – The EDXML parent-description attribute Returns: The EventTypeParent instance Return type: edxml.ontology.EventTypeParent
-
set_siblings_description
(description)¶ Sets the EDXML siblings-description attribute
Parameters: description (str) – The EDXML siblings-description attribute Returns: The EventTypeParent instance Return type: edxml.ontology.EventTypeParent
-
map
(child_property_name, parent_property_name=None)¶ Add a property mapping, mapping a property in the child event type to the corresponding property in the parent. When the parent property name is omitted, it is assumed that the parent and child properties are named identically.
Parameters: - child_property_name (str) – Child property
- parent_property_name (str) – Parent property
Returns: The EventTypeParent instance
Return type:
-
get_event_type_name
()¶ Returns the name of the parent event type.
Returns: Return type: str
-
get_property_map
()¶ Returns the property map as a dictionary mapping property names of the child event type to property names of the parent.
Returns: Return type: Dict[str,str]
-
get_parent_description
()¶ Returns the EDXML ‘parent-description’ attribute.
Returns: Return type: str
-
get_siblings_description
()¶ Returns the EDXML ‘siblings-description’ attribute.
Returns: Return type: str
-
validate
()¶ Checks if the event type parent is valid. It only looks at the attributes of the definition itself. Since it does not have access to the full ontology, the context of the parent is not considered. For example, it does not check if the parent definition refers to an event type that actually exists.
Raises: EDXMLOntologyValidationError
Returns: The EventTypeParent instance Return type: edxml.ontology.EventTypeParent
-
update
(parent)¶ Updates the event type parent to match the EventTypeParent instance passed to this method, returning the updated instance.
Parameters: parent (edxml.ontology.EventTypeParent) – The new EventTypeParent instance Returns: The updated EventTypeParent instance Return type: edxml.ontology.EventTypeParent
-
generate_xml
()¶ Generates an lxml etree Element representing the EDXML <parent> tag for this event type parent.
Returns: The element Return type: etree.Element
-
classmethod
EventProperty¶
-
class
edxml.ontology.
EventProperty
(event_type, name, object_type, description=None, optional=False, multivalued=False, merge='any', similar='', confidence=10)¶ Bases:
edxml.ontology.ontology_element.OntologyElement
Class representing an EDXML event property
-
MERGE_MATCH
= 'match'¶ Merge strategy ‘match’
-
MERGE_ANY
= 'any'¶ Merge strategy ‘any’
-
MERGE_ADD
= 'add'¶ Merge strategy ‘add’
-
MERGE_SET
= 'set'¶ Merge strategy ‘set’
-
MERGE_REPLACE
= 'replace'¶ Merge strategy ‘replace’
-
MERGE_MIN
= 'min'¶ Merge strategy ‘min’
-
MERGE_MAX
= 'max'¶ Merge strategy ‘max’
-
get_name
()¶ Returns the property name.
Returns: Return type: str
-
get_description
()¶ Returns the property description.
Returns: Return type: str
-
get_object_type_name
()¶ Returns the name of the associated object type.
Returns: Return type: str
-
get_merge_strategy
()¶ Returns the merge strategy.
Returns: Return type: str
-
get_similar_hint
()¶ Get the EDXML ‘similar’ attribute.
Returns: Return type: str
-
get_confidence
()¶ Returns the property confidence.
Returns: Return type: int
-
get_object_type
()¶ Returns the ObjectType instance that is associated with the property.
Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
get_data_type
()¶ Returns the DataType instance that is associated with the object type of the property.
Returns: The DataType instance Return type: edxml.ontology.DataType
-
get_concept_associations
()¶ Returns a dictionary containing the names of all associated concepts as keys and the PropertyConcept instances as values.
Returns: Return type: Dict[str,edxml.ontology.PropertyConcept]
-
relate_to
(type_predicate, target_property_name, reason=None, confidence=10)¶ Creates and returns a relation between this property and the specified target property.
When no reason is specified, the reason is constructed by wrapping the type predicate with the place holders for the two properties.
Parameters: - type_predicate (str) – free form predicate
- target_property_name (str) – Name of the related property
- reason (str) – Relation description, with property placeholders
- confidence (int) – Relation confidence [00,10]
Returns: The EventPropertyRelation instance
Return type: edxml.ontology.EventPropertyRelation
-
relate_inter
(type_predicate, target_property_name, source_concept_name=None, target_concept_name=None, reason=None, confidence=10)¶ Creates and returns a relation between this property and the specified target property. The relation is an ‘inter’ relation, indicating that the related objects belong to different, related concept instances.
When any of the related properties is associated with more than one concept, you are required to specify which of the associated concepts is involved in the relation.
When no reason is specified, the reason is constructed by wrapping the type predicate with the place holders for the two properties.
Parameters: - type_predicate (str) – free form predicate
- target_property_name (str) – Name of the related property
- source_concept_name (str) – Name of the source concept
- target_concept_name (str) – Name of the target concept
- reason (str) – Relation description, with property placeholders
- confidence (int) – Relation confidence [0,10]
Returns: The EventPropertyRelation instance
Return type: edxml.ontology.EventPropertyRelation
-
relate_intra
(type_predicate, target_property_name, source_concept_name=None, target_concept_name=None, reason=None, confidence=10)¶ Creates and returns a relation between this property and the specified target property. The relation is an ‘intra’ relation, indicating that the related objects belong to the same concept instance.
When no reason is specified, the reason is constructed by wrapping the type predicate with the place holders for the two properties.
Parameters: - target_property_name (str) – Name of the related property
- source_concept_name (str) – Name of the source concept
- target_concept_name (str) – Name of the target concept
- reason (str) – Relation description, with property placeholders
- type_predicate (str) – free form predicate
- confidence (float) – Relation confidence [0,10]
Returns: The EventPropertyRelation instance
Return type: edxml.ontology.EventPropertyRelation
-
relate_name
(target_property_name)¶ Creates and returns a relation between this property and the specified target property. The relation is a ‘name’ relation, indicating that the property provides names for the values of the target property.
Parameters: target_property_name (str) – Name of the related property Returns: The EventPropertyRelation instance Return type: edxml.ontology.EventPropertyRelation
-
relate_description
(target_property_name)¶ Creates and returns a relation between this property and the specified target property. The relation is a ‘description’ relation, indicating that the property provides descriptions for the values of the target property.
Parameters: target_property_name (str) – Name of the related property Returns: The EventPropertyRelation instance Return type: edxml.ontology.EventPropertyRelation
-
relate_container
(target_property_name)¶ Creates and returns a relation between this property and the specified target property. The relation is a ‘container’ relation, indicating that the values of the property contain the values of the target property. In other words, the values of the target property are conceptually a part of the values of this property.
Parameters: target_property_name (str) – Name of the related property Returns: The EventPropertyRelation instance Return type: edxml.ontology.EventPropertyRelation
-
relate_original
(target_property_name)¶ Creates and returns a relation between this property and the specified target property. The relation is an ‘original’ relation, indicating that the value of the property contains the original version of the value of the target property.
Parameters: target_property_name (str) – Name of the related property Returns: The EventPropertyRelation instance Return type: edxml.ontology.EventPropertyRelation
-
add_associated_concept
(concept_association)¶ Add the specified concept association.
Parameters: concept_association (edxml.ontology.PropertyConcept) – Property concept association Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
set_merge_strategy
(merge_strategy)¶ Set the merge strategy of the property. This should be one of the MERGE_* attributes of this class.
Automatically makes the property mandatory or single valued when the merge strategy requires it.
Parameters: merge_strategy (str) – The merge strategy Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
set_description
(description)¶ Set the description of the property. This should be really short, indicating which role the object has in the event type.
Parameters: description (str) – The property description Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
set_confidence
(confidence)¶ Configure the property confidence
Parameters: confidence (int) – Property confidence [1,10] Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
make_optional
()¶ Make the property optional.
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
make_mandatory
()¶ Make the property mandatory.
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
set_optional
(is_optional)¶ Set the optional flag for the property to True (property is optional) or False (property is mandatory).
Parameters: is_optional (bool) – Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
make_single_valued
()¶ Make the property single-valued.
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
make_multivalued
()¶ Make the property multi-valued.
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
make_hashed
()¶ Changes the property into a hashed property by setting its merge strategy to ‘match’.
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
is_hashed
()¶ Returns True if property has merge strategy ‘match’, which means that it is included in event hashes
Returns: Return type: bool
-
is_optional
()¶ Returns True if property is optional, returns False otherwise
Returns: Return type: bool
-
is_mandatory
()¶ Returns True if property is mandatory, returns False otherwise
Returns: Return type: bool
-
is_multi_valued
()¶ Returns True if property is multi-valued, returns False otherwise
Returns: Return type: bool
-
is_single_valued
()¶ Returns True if property is single-valued, returns False otherwise
Returns: Return type: bool
-
identifies
(concept_name, confidence=10, cnp=128)¶ Marks the property as an identifier for specified concept, with specified confidence.
Parameters: - concept_name (str) – concept name
- confidence (int) – concept identification confidence [0, 10]
- cnp (int) – concept naming priority [0,255]
Returns: The PropertyConcept association
Return type:
-
set_multi_valued
(is_multivalued)¶ Configures the property as multi-valued or single-valued
Parameters: is_multivalued (bool) – Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
hint_similar
(similarity)¶ Set the EDXML ‘similar’ attribute.
Parameters: similarity (str) – similar attribute string Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
merge_add
()¶ Set merge strategy to ‘add’.
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
merge_replace
()¶ Set merge strategy to ‘replace’.
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
merge_set
()¶ Set merge strategy to ‘set’.
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
merge_any
()¶ Set merge strategy to ‘any’, which is the default merge strategy.
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
merge_min
()¶ Set merge strategy to ‘min’.
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
merge_max
()¶ Set merge strategy to ‘max’.
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
validate
()¶ Checks if the property definition is valid. It only looks at the attributes of the property itself. Since it does not have access to the full ontology, the context of the property is not considered. For example, it does not check if the object type in the property actually exist.
Raises: EDXMLOntologyValidationError
Returns: The EventProperty instance Return type: edxml.ontology.EventProperty
-
update
(event_property)¶ Updates the event property to match the EventProperty instance passed to this method, returning the updated instance.
Parameters: event_property (edxml.ontology.EventProperty) – The new EventProperty instance Returns: The updated EventProperty instance Return type: edxml.ontology.EventProperty
-
generate_xml
()¶ Generates an lxml etree Element representing the EDXML <property> tag for this event property.
Returns: The element Return type: etree.Element
-
PropertyConcept¶
-
class
edxml.ontology.
PropertyConcept
(event_type, event_property, concept_name, confidence=10, naming_priority=128)¶ Bases:
edxml.ontology.ontology_element.OntologyElement
Class representing an association between a property and a concept
-
get_concept_name
()¶ Returns the name of the associated concept.
Returns: Return type: str
-
get_property_name
()¶ Returns the name of the event property.
Returns: Return type: str
-
get_confidence
()¶ Returns the concept confidence of the association, indicating how strong the property values are as identifiers of instances of the associated concept.
Returns: Return type: int
-
get_concept_naming_priority
()¶ Returns the concept naming priority.
Returns: Return type: int
-
get_attribute_name
()¶ Returns the full name of the concept attribute, which includes the object type name, a colon and its extension.
Returns: Return type: str
-
get_attribute_name_extension
()¶ Returns the attribute name extension.
Returns: Return type: str
-
get_attribute_display_name_singular
()¶ Returns the display name of the concept attribute (singular form). When the attribute does not have a custom display name, the display name of the object type of the associated property is used.
Returns: Return type: str
-
get_attribute_display_name_plural
()¶ Returns the display name of the concept attribute (plural form) When the attribute does not have a custom display name, the display name of the object type of the associated property is used.
Returns: Return type: str
-
set_confidence
(confidence)¶ Configure the concept confidence of the association, indicating how strong the property values are as identifiers of instances of the associated concept.
Parameters: confidence (int) – Confidence [1,10] Returns: The PropertyConcept instance Return type: edxml.ontology.PropertyConcept
-
set_concept_naming_priority
(priority)¶ Configure the concept naming priority.
Parameters: priority (int) – Naming priority [1,10] Returns: The PropertyConcept instance Return type: edxml.ontology.PropertyConcept
-
set_attribute
(extension, display_name_singular='', display_name_plural='')¶ Set the name extension of the concept attribute. By default, concept attributes are named after the object type of their associated property by taking the object type name, appending a colon and appending a concept name extension.
If the plural form of the display name is omitted, it will be auto-generated by appending an ‘s’ to the singular form.
Parameters: - extension (str) –
- display_name_singular (str) –
- display_name_plural (str) –
Returns: The PropertyConcept instance
Return type:
-
validate
()¶ Checks if the concept association is valid. It only looks at the attributes of the association itself. Since it does not have access to the full ontology, the context of the association is not considered. For example, it does not check if the concept actually exist.
Raises: EDXMLOntologyValidationError
Returns: The PropertyConcept instance Return type: edxml.ontology.PropertyConcept
-
update
(property_concept)¶ Updates the concept association to match the PropertyConcept instance passed to this method, returning the updated instance.
Parameters: property_concept (edxml.ontology.PropertyConcept) – The new PropertyConcept instance Returns: The updated PropertyConcept instance Return type: edxml.ontology.PropertyConcept
-
generate_xml
()¶ Generates an lxml etree Element representing the EDXML <property-concept> tag for this property concept association
Returns: The element Return type: etree.Element
-
ObjectType¶
-
class
edxml.ontology.
ObjectType
(ontology, name, display_name_singular=None, display_name_plural=None, description=None, data_type='string:0:mc:u', unit_name=None, unit_symbol=None, prefix_radix=None, compress=False, xref=None, fuzzy_matching=None, regex_hard=None, regex_soft=None)¶ Bases:
edxml.ontology.ontology_element.VersionedOntologyElement
Class representing an EDXML object type
-
get_name
()¶ Returns the name of the object type.
Returns: The object type name Return type: str
-
get_display_name_singular
()¶ Returns the display name of the object type, in singular form.
Returns: Return type: str
-
get_display_name_plural
()¶ Returns the display name of the object type, in plural form.
Returns: Return type: str
-
get_description
()¶ Returns the description of the object type.
Returns: Return type: str
-
get_data_type
()¶ Returns the data type of the object type.
Returns: The data type Return type: edxml.ontology.DataType
-
get_unit_name
()¶ Returns the name of the measurement unit or None in case the object type does not have any associated unit.
Returns: unit name Return type: Optional[str]
-
get_unit_symbol
()¶ Returns the symbol of the measurement unit or None in case the object type does not have any associated unit.
Returns: unit symbol Return type: Optional[str]
-
get_prefix_radix
()¶ Returns the natural radix that should be used for metric prefixes of numerical object types.
Returns: radix Return type: Optional[int]
-
is_compressible
()¶ Returns True if compression is advised for the object type, returns False otherwise.
Returns: Return type: bool
-
get_xref
()¶ Returns the external reference to additional information about the object type or None in case it does not define any.
Returns: xref Return type: Optional[str]
-
get_fuzzy_matching
()¶ Returns the EDXML fuzzy-matching attribute for the object type or None in case it does not define any.
Returns: Return type: Optional[str]
-
get_regex_hard
()¶ Returns the regular expression that object values must match. Returns None in case no hard regular expression is associated with the object type.
Note that the regular expression is not anchored to the start and end of the object value string even though object values must fully matches the expression from start to end. Be sure to wrap the expression in anchors where full string matching is needed.
Returns: Return type: Optional[str]
-
get_regex_soft
()¶ Returns the regular expression that can be used to identify valid object values or generate synthetic values. Returns None in case no soft regular expression is associated with the object type.
Note that the regular expression is not anchored to the start and end of the object value string even though the expression should match full object values from start to end. Be sure to wrap the expression in anchors before use.
Returns: Return type: Optional[str]
-
get_version
()¶ Returns the version of the source definition.
Returns: Return type: int
-
set_description
(description)¶ Sets the object type description
Parameters: description (str) – Description Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
set_data_type
(data_type)¶ Configure the data type.
Parameters: data_type (edxml.ontology.DataType) – DataType instance Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
set_unit
(unit_name, unit_symbol)¶ Configure the measurement unit name and symbol.
Parameters: - unit_name (str) – Unit name
- unit_symbol (str) – Unit symbol
Returns: The ObjectType instance
Return type:
-
set_prefix_radix
(radix)¶ Configure the natural radix that should be used for metric prefixes of numerical object types
Parameters: radix (int) – Radix Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
set_xref
(url)¶ Configure the URL pointing to additional information about the object type.
Parameters: url (int) – URL Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
set_display_name
(singular, plural=None)¶ Configure the display name. If the plural form is omitted, it will be auto-generated by appending an ‘s’ to the singular form.
Parameters: - singular (str) – display name (singular form)
- plural (str) – display name (plural form)
Returns: The ObjectType instance
Return type:
-
set_regex_hard
(pattern)¶ Configure a regular expression that object values must match.
Parameters: pattern (str) – Regular expression Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
set_regex_soft
(pattern)¶ Configure a regular expression that should match values that are valid for the object type.
Parameters: pattern (str) – Regular expression Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
set_fuzzy_matching_attribute
(attribute)¶ Sets the EDXML fuzzy-matching attribute.
Notes
It is recommended to use the FuzzyMatch…() methods in stead to configure fuzzy matching.
Parameters: attribute (str) – The attribute value Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
set_version
(version)¶ Sets the object type version
Parameters: version (int) – Version Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
upgrade
()¶ Verifies if the current instance is a valid upgrade of the instance as it was when the version was last changed. When successful the version number is incremented.
This method is used for fluent upgrading of ontology bricks, allowing definitions of object types to be changed in a single call chain while making sure that no backward incompatible changes are made.
Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
fuzzy_match_head
(length)¶ Configure fuzzy matching on the head of the string (only for string data types).
Parameters: length (int) – Number of characters to match Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
fuzzy_match_tail
(length)¶ Configure fuzzy matching on the tail of the string (only for string data types).
Parameters: length (int) – Number of characters to match Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
fuzzy_match_substring
(pattern)¶ Configure fuzzy matching on a substring (only for string data types).
Parameters: pattern (str) – Regular expression Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
fuzzy_match_phonetic
()¶ Configure fuzzy matching on the sound of the string (phonetic fingerprinting).
Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
compress
(is_compressible=True)¶ Enable or disable compression for the object type.
Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
validate_object_value
(value)¶ Validates the provided object value against the object type definition as well as its data type, raising an EDXMLValidationException when the value is invalid.
Parameters: value (str) – Object value Raises: EDXMLEventValidationError
Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
validate
()¶ Checks if the object type is valid. It only looks at the attributes of the definition itself. Since it does not have access to the full ontology, the context of the event type is not considered. For example, it does not check if other, conflicting object type definitions exist.
Raises: EDXMLOntologyValidationError
Returns: The ObjectType instance Return type: edxml.ontology.ObjectType
-
update
(object_type)¶ Parameters: object_type (edxml.ontology.ObjectType) – The new ObjectType instance Returns: The updated ObjectType instance Return type: edxml.ontology.ObjectType
-
generate_xml
()¶ Generates an lxml etree Element representing the EDXML <object-type> tag for this object type.
Returns: The element Return type: etree.Element
-
Concept¶
-
class
edxml.ontology.
Concept
(ontology, name, display_name_singular=None, display_name_plural=None, description=None)¶ Bases:
edxml.ontology.ontology_element.VersionedOntologyElement
Class representing an EDXML concept
Returns True when concept name a is a specialization of b or the other way around. This is true when both share the same branch in the concept name hierarchy. For example concept names a.b and a.b.c share the same branch while a.b and a.c do not.
Parameters: - a (str) –
- b (str) –
Returns: Return type: bool
-
classmethod
concept_name_is_specialization
(concept_name, specialization_concept_name)¶ Returns True when the one concept name a is a specialization of the other. This is true when the specialization extends the concept name by appending to it.
Parameters: - concept_name (str) –
- specialization_concept_name (str) –
Returns: Return type: bool
-
get_name
()¶ Returns the name of the concept.
Returns: The concept name Return type: str
-
get_display_name_singular
()¶ Returns the display name of the concept, in singular form.
Returns: Return type: str
-
get_display_name_plural
()¶ Returns the display name of the concept, in plural form.
Returns: Return type: str
-
get_description
()¶ Returns the description of the concept.
Returns: Return type: str
-
get_version
()¶ Returns the version of the concept definition.
Returns: Return type: int
-
set_description
(description)¶ Sets the concept description
Parameters: description (str) – Description Returns: The Concept instance Return type: edxml.ontology.Concept
-
set_display_name
(singular, plural=None)¶ Configure the display name. If the plural form is omitted, it will be auto-generated by appending an ‘s’ to the singular form.
Parameters: - singular (str) – display name (singular form)
- plural (str) – display name (plural form)
Returns: The Concept instance
Return type:
-
set_version
(version)¶ Sets the concept version
Parameters: version (int) – Version Returns: The Concept instance Return type: edxml.ontology.Concept
-
upgrade
()¶ Verifies if the current instance is a valid upgrade of the instance as it was when the version was last changed. When successful the version number is incremented.
This method is used for fluent upgrading of ontology bricks, allowing definitions of concepts to be changed in a single call chain while making sure that no backward incompatible changes are made.
Returns: The Concept instance Return type: edxml.ontology.Concept
-
validate
()¶ Checks if the concept is valid. It only looks at the attributes of the definition itself. Since it does not have access to the full ontology, the context of the ontology is not considered. For example, it does not check if other, conflicting concept definitions exist.
Raises: EDXMLOntologyValidationError
Returns: The Concept instance Return type: edxml.ontology.Concept
-
update
(concept)¶ Update the concept using information from the provided concept and validate the result.
Parameters: concept (edxml.ontology.Concept) – The new Concept instance Returns: The updated Concept instance Return type: edxml.ontology.Concept
-
generate_xml
()¶ Generates an lxml etree Element representing the EDXML <concept> tag for this concept.
Returns: The element Return type: etree.Element
-
classmethod
generate_specializations
(concept_name, parent_concept_name=None)¶ Generator yielding specializations of a given concept. For example, when given a concept name ‘a.b.c’ it will generate concept names ‘a’, ‘a.b’ and ‘a.b.c’.
Optionally a parent concept can be specified. In that case the specializations will be generated starting at the parent concept.
Parameters: - concept_name (str) – Concept for which to generate specializations
- parent_concept_name (Optional[str]) – First yielded concept name
Yields: str
-
classmethod
generate_generalizations
(concept_name)¶ Generator yielding generalizations of a given concept. For example, when given a concept name ‘a.b.c’ it will generate concept names ‘a.b’ and ‘a’.
Parameters: concept_name (str) – Concept for which to generate generalizations Yields: str
DataType¶
-
class
edxml.ontology.
DataType
(data_type)¶ Bases:
object
Class representing an EDXML data type. Instances of this class can be cast to strings, which yields the EDXML data-type attribute.
-
classmethod
boolean
()¶ Create a boolean value DataType instance.
Returns: Return type: edxml.ontology.DataType
-
classmethod
tiny_int
(signed=True)¶ Create an 8-bit tinyint DataType instance.
Parameters: signed (bool) – Create signed or unsigned number Returns: Return type: edxml.ontology.DataType
-
classmethod
small_int
(signed=True)¶ Create a 16-bit smallint DataType instance.
Parameters: signed (bool) – Create signed or unsigned number Returns: Return type: edxml.ontology.DataType
-
classmethod
medium_int
(signed=True)¶ Create a 24-bit mediumint DataType instance.
Parameters: signed (bool) – Create signed or unsigned number Returns: Return type: edxml.ontology.DataType
-
classmethod
int
(signed=True)¶ Create a 32-bit int DataType instance.
Parameters: signed (bool) – Create signed or unsigned number Returns: Return type: edxml.ontology.DataType
-
classmethod
big_int
(signed=True)¶ Create a 64-bit bigint DataType instance.
Parameters: signed (bool) – Create signed or unsigned number Returns: Return type: edxml.ontology.DataType
-
classmethod
float
(signed=True)¶ Create a 32-bit float DataType instance.
Parameters: signed (bool) – Create signed or unsigned number Returns: Return type: edxml.ontology.DataType
-
classmethod
double
(signed=True)¶ Create a 64-bit double DataType instance.
Parameters: signed (bool) – Create signed or unsigned number Returns: Return type: edxml.ontology.DataType
-
classmethod
decimal
(total_digits, fractional_digits, signed=True)¶ Create a decimal DataType instance.
Parameters: - total_digits (int) – Total number of digits
- fractional_digits (int) – Number of digits after the decimal point
- signed (bool) – Create signed or unsigned number
Returns: Return type:
-
classmethod
currency
()¶ Create a currency DataType instance.
Returns: Return type: edxml.ontology.DataType
-
classmethod
string
(length=0, lower_case=True, upper_case=True, require_unicode=True, reverse_storage=False)¶ Create a string DataType instance.
Parameters: - length (int) – Max number of characters (zero = unlimited)
- lower_case (bool) – Allow lower case characters
- upper_case (bool) – Allow upper case characters
- require_unicode (bool) – String may contain UTF-8 characters
- reverse_storage (bool) – Hint storing the string in reverse character order
Returns: Return type:
-
classmethod
base64
(length=0)¶ Create a base64 DataType instance.
Parameters: length (int) – Max number of bytes (zero = unlimited) Returns: Return type: DataType
-
classmethod
enum
(*choices)¶ Create an enumeration DataType instance.
Parameters: *choices (str) – Possible string values Returns: Return type: edxml.ontology.DataType
-
classmethod
uri
(path_separator='/')¶ Create an URI DataType instance.
Parameters: path_separator (str) – URI path separator Returns: Return type: edxml.ontology.DataType
-
classmethod
hex
(length, separator=None, group_size=None)¶ Create a hexadecimal number DataType instance.
Parameters: - length (int) – Number of hex digits
- separator (str) – Separator character
- group_size (int) – Number of hex digits per group
Returns: Return type:
-
classmethod
geo_point
()¶ Create a geographical location DataType instance.
Returns: Return type: edxml.ontology.DataType
-
classmethod
file
()¶ Create a file DataType instance.
Returns: Return type: edxml.ontology.DataType
-
classmethod
ip_v4
()¶ Create an IPv4 DataType instance
Returns: Return type: edxml.ontology.DataType
-
classmethod
ip_v6
()¶ Create an IPv6 DataType instance
Returns: Return type: edxml.ontology.DataType
-
get
()¶ Returns the EDXML data-type attribute. Calling this method is equivalent to casting to a string.
Returns: Return type: str
-
get_family
()¶ Returns the data type family.
Returns: Return type: str
-
get_split
()¶ Returns the EDXML data type attribute, split on the colon (‘:’), yielding a list containing the individual parts of the data type.
Returns: Return type: List[str]
-
is_numerical
()¶ Returns True if the data type is of data type family ‘number’. Returns False for all other data types.
Returns: Return type: boolean
-
is_datetime
()¶ Returns True if the data type is ‘datetime’. Returns False for all other data types.
Returns: Return type: boolean
-
is_valid_upgrade_of
(other)¶ Checks if the data type is a valid upgrade of another data type.
Parameters: other (DataType) – The other data type Returns: Return type: bool
-
normalize_objects
(values)¶ Normalize values to valid EDXML object value strings
Converts each of the provided values into valid string representations for the data type. It takes an iterable as input and returns a set of normalized strings.
The object values must be appropriate for the data type. For example, numerical data types require values that can be cast into a number, string data types require values that can be cast to a string. Values of datetime data type may be datetime instances or any string that dateutil can parse. When inappropriate values are encountered, an EDXMLEventValidationError will be raised.
Parameters: values (Iterable[Any]) – The input object values Raises: EDXMLEventValidationError
Returns: Set[str]. The normalized object values
-
validate_object_value
(value)¶ Validates the provided object value against the data type, raising an EDXMLValidationException when the value is invalid. The value may be a native type like an integer or a boolean. The value may also be a unicode encoded string, as it would appear in EDXML data.
Parameters: value – Object value Raises: EDXMLEventValidationError
Returns: Return type: edxml.ontology.DataType
-
validate
()¶ Validates the data type definition, raising an EDXMLValidationException when the definition is not valid.
Raises: EDXMLOntologyValidationError
Returns: Return type: edxml.ontology.DataType
-
classmethod
format_utc_datetime
(date_time)¶ Formats specified dateTime object into a valid EDXML datetime string.
Notes
The datetime object must have its time zone set to UTC.
Parameters: date_time (datetime.datetime) – datetime object Returns: EDXML datetime string Return type: str
-
classmethod
EventSource¶
-
class
edxml.ontology.
EventSource
(ontology, uri, description='no description available', acquisition_date=None)¶ Bases:
edxml.ontology.ontology_element.VersionedOntologyElement
Class representing an EDXML event source
-
get_uri
()¶ Returns the source URI
Returns: Return type: str
-
get_description
()¶ Returns the source description
Returns: Return type: str
-
get_acquisition_date
()¶ Returns the acquisition date as a datetime object or None in case no acquisition date is set.
Returns: The date Return type: Optional[datetime.datetime]
-
get_acquisition_date_string
()¶ Returns the acquisition date as a string of None in case not acquisition date is set.
Returns: The date in yyyymmdd format Return type: Optional[str]
-
get_version
()¶ Returns the version of the source definition.
Returns: Return type: int
-
set_description
(description)¶ Sets the source description
Parameters: description (str) – Description Returns: The EventSource instance Return type: edxml.ontology.EventSource
-
set_acquisition_date
(date_time)¶ Sets the acquisition date
Parameters: date_time (datetime.datetime) – Acquisition date Returns: The EventSource instance Return type: edxml.ontology.EventSource
-
set_acquisition_date_string
(date_time)¶ Sets the acquisition date from a string value
Parameters: date_time (str) – The date in yyyymmdd format Returns: The EventSource instance Return type: edxml.ontology.EventSource
-
set_version
(version)¶ Sets the concept version
Parameters: version (int) – Version Returns: The Concept instance Return type: edxml.ontology.Concept
-
validate
()¶ Checks if the event source definition is valid.
Raises: EDXMLOntologyValidationError
Returns: The EventSource instance Return type: edxml.ontology.EventSource
-
update
(source)¶ Updates the event source to match the EventSource instance passed to this method, returning the updated instance.
Parameters: source (edxml.ontology.EventSource) – The new EventSource instance Returns: The updated EventSource instance Return type: edxml.ontology.EventSource
-
generate_xml
()¶ Generates an lxml etree Element representing the EDXML <source> tag for this event source.
Returns: The element Return type: etree.Element
-
OntologyElement¶
-
class
edxml.ontology.
OntologyElement
¶ Bases:
abc.ABC
Class representing an EDXML ontology element
VersionedOntologyElement¶
-
class
edxml.ontology.
VersionedOntologyElement
¶ Bases:
edxml.ontology.ontology_element.OntologyElement
An ontology element that is versioned, such as an object type, concept, event type or an event source.
-
get_version
()¶ Returns the version of the ontology element
Returns: Element version Return type: int
-
describe_producer_rst()¶
-
edxml.ontology.description.
describe_producer_rst
(ontology, producer_name, input_description)¶ Returns a reStructuredText description for a producer of an ontology, such as a transcoder or a processor.
Parameters: - ontology (edxml.ontology.Ontology) – The ontology
- producer_name (str) – Name of the ontology producer
- input_description (str) – Short description of the data used as input by producer
Returns: reStructuredText description
Return type: str
generate_graph_property_concepts()¶
-
edxml.ontology.visualization.
generate_graph_property_concepts
(ontology, graph)¶ Appends nodes and edges to specified Digraph that show possible concept mining reasoning paths.
Parameters: - ontology (edxml.ontology.Ontology) –
- graph (graphviz.Digraph) –
-
edxml.ontology.visualization.
parent_child_hierarchy
(ontology, graph)¶ Appends nodes and edges to specified Digraph that show parent-child relations between all event types in the ontology.
Parameters: - ontology (edxml.ontology.Ontology) –
- graph (graphviz.Digraph) –