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

OntologyElement
VersionedOntologyElement

Functions

generate_graph_property_concepts
describe_producer_rst

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:	edxml.ontology.ObjectType

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:	edxml.ontology.Concept

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:	edxml.ontology.EventType

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:	edxml.ontology.EventSource

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:	edxml.ontology.ObjectType

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:	edxml.ontology.Concept

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:	edxml.ontology.Ontology

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:	EventProperty

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:	EventTypeParent

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:	edxml.ontology.EventType

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:	edxml.ontology.EventType

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:	edxml.ontology.EventType

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:	edxml.ontology.EventType

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:	edxml.ontology.EventType

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:	edxml.ontology.EventTypeAttachment

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:	edxml.ontology.EventTypeParent

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:	edxml.ontology.EventTypeParent

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

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:	edxml.ontology.PropertyConcept

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:	edxml.ontology.PropertyConcept

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:	edxml.ontology.ObjectType

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:	edxml.ontology.ObjectType

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

classmethod concept_names_share_branch(a, b)¶

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:	edxml.ontology.Concept

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 datetime()¶

Create a datetime DataType instance.

Returns:
Return type:	DataType

classmethod sequence()¶

Create a sequence DataType instance.

Returns:
Return type:	DataType

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:	edxml.ontology.DataType

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:	edxml.ontology.DataType

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:	edxml.ontology.DataType

classmethod uuid()¶

Create a uuid DataType instance.

Returns:
Return type:	DataType

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

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) –