|
| 1 | +# Usage |
| 2 | + |
| 3 | +The main usage for owlapy is to use it for class expression construction. Class |
| 4 | +expression learning algorithms require such basic structure to work upon. Let's walk |
| 5 | +through an example of constructing some class expressions. |
| 6 | + |
| 7 | +In this example we will be using the _family_ ontology, |
| 8 | +a simple ontology with namespace: `http://example.com/family#`. |
| 9 | +Here is a hierarchical diagram that shows the classes and their relationship: |
| 10 | + |
| 11 | + Thing |
| 12 | + | |
| 13 | + person |
| 14 | + / | |
| 15 | + male female |
| 16 | + |
| 17 | +It contains only one object property which is `hasChild` and in total there |
| 18 | +are six persons (individuals), of which four are males and two are females. |
| 19 | + |
| 20 | +## Atomic Classes |
| 21 | + |
| 22 | +To represent the classes `male`, `female`, and `person` we can simply use the |
| 23 | +class [OWLClass](https://dice-group.github.io/owlapy/autoapi/owlapy/class_expression/owl_class/index.html#owlapy.class_expression.owl_class.OWLClass): |
| 24 | + |
| 25 | +```python |
| 26 | +from owlapy.class_expression import OWLClass |
| 27 | +from owlapy.iri import IRI |
| 28 | + |
| 29 | +namespace = "http://example.com/family#" |
| 30 | + |
| 31 | +male = OWLClass(IRI(namespace, "male")) |
| 32 | +female = OWLClass(IRI(namespace, "female")) |
| 33 | +person = OWLClass(IRI(namespace, "person")) |
| 34 | + |
| 35 | +``` |
| 36 | + |
| 37 | +Notice that we created an `IRI` object for every class. [IRI](https://dice-group.github.io/owlapy/autoapi/owlapy/iri/index.html#owlapy.iri.IRI) |
| 38 | +is used to represent an _IRI_. Every named entity requires an IRI, whereas Anonymous entities does not. |
| 39 | +However, in owlapy you can create an _OWLClass_ by passing the _IRI_ directly as a string, like so: |
| 40 | + |
| 41 | +```python |
| 42 | +male = OWLClass("http://example.com/family#male") |
| 43 | +``` |
| 44 | + |
| 45 | +## Object Property |
| 46 | + |
| 47 | +To represent the object property `hasChild` we can use the class |
| 48 | +[OWLObjectProperty](https://dice-group.github.io/owlapy/autoapi/owlapy/owl_property/index.html#owlapy.owl_property.OWLObjectProperty): |
| 49 | + |
| 50 | +```python |
| 51 | +from owlapy.owl_property import OWLObjectProperty |
| 52 | + |
| 53 | +hasChild = OWLObjectProperty("http://example.com/family#hasChild") |
| 54 | +``` |
| 55 | + |
| 56 | +> **Tip:** In owlapy the naming of the classes is made in accordance with the notations from |
| 57 | +> OWL 2 specification but with the word _"OWL"_ in the beginning. Example: _"OWLObjectProperty"_ |
| 58 | +> represents the notation _"ObjectProperty"_. |
| 59 | +
|
| 60 | +## Complex class expressions |
| 61 | + |
| 62 | +Now that we have these atomic entities, we can construct more complex class |
| 63 | +expressions. Let's say we want to represent all individuals which are `male` |
| 64 | +and have at least 1 child. |
| 65 | + |
| 66 | +We already have the concept of `male`. We need to find the appropriate class |
| 67 | +for the second part: _"have at least 1 child"_. In OWL 2 specification that would be |
| 68 | +[ObjectMinCardinality](https://www.w3.org/TR/owl2-syntax/#Minimum_Cardinality). In owlapy, |
| 69 | +as we said, we simply add the word _"OWL"_ upfront to find the correct class: |
| 70 | + |
| 71 | +```python |
| 72 | +from owlapy.class_expression import OWLObjectMinCardinality |
| 73 | + |
| 74 | +has_at_least_one_child = OWLObjectMinCardinality( |
| 75 | + cardinality = 1, |
| 76 | + property = hasChild, |
| 77 | + filler = person |
| 78 | +) |
| 79 | +``` |
| 80 | +As you can see, to create an object of class [OWLObjectMinCardinality](https://dice-group.github.io/owlapy/autoapi/owlapy/class_expression/restriction/index.html#owlapy.class_expression.restriction.OWLObjectMinCardinality) |
| 81 | +is as easy as that. You specify the cardinality which in this case is `1`, the object property where we apply this |
| 82 | +cardinality restriction and the filler class in case you want to restrict the domain of the class expression. In this |
| 83 | +case we used `person`. |
| 84 | + |
| 85 | +Now let's merge both class expressions together using [OWLObjectIntersectionOf](https://dice-group.github.io/owlapy/autoapi/owlapy/class_expression/nary_boolean_expression/index.html#owlapy.class_expression.nary_boolean_expression.OWLObjectIntersectionOf): |
| 86 | + |
| 87 | +```python |
| 88 | +from owlapy.class_expression import OWLObjectIntersectionOf |
| 89 | + |
| 90 | +ce = OWLObjectIntersectionOf([male, has_at_least_one_child]) |
| 91 | +``` |
| 92 | + |
| 93 | +## Convert to SPARQL, DL or Manchester syntax |
| 94 | + |
| 95 | +Owlapy is not just a library to represent OWL entities, you can also |
| 96 | +use it to convert owl expressions into other formats: |
| 97 | + |
| 98 | +```python |
| 99 | +from owlapy import owl_expression_to_sparql, owl_expression_to_dl, owl_expression_to_manchester |
| 100 | + |
| 101 | +print(owl_expression_to_dl(ce)) |
| 102 | +# Result: male ⊓ (≥ 1 hasChild.person) |
| 103 | + |
| 104 | +print(owl_expression_to_sparql(expression=ce)) |
| 105 | +# Result: SELECT DISTINCT ?x WHERE { ?x a <http://example.com/family#male> . { SELECT ?x WHERE { ?x <http://example.com/family#hasChild> ?s_1 . ?s_1 a <http://example.com/family#person> . } GROUP BY ?x HAVING ( COUNT ( ?s_1 ) >= 1 ) } } |
| 106 | + |
| 107 | +print(owl_expression_to_manchester(ce)) |
| 108 | +# Result: male and (hasChild min 1 person) |
| 109 | +``` |
| 110 | + |
| 111 | +To parse a DL or Manchester expression to owl expression you can use the |
| 112 | +following convenient methods: |
| 113 | + |
| 114 | +```python |
| 115 | +from owlapy import dl_to_owl_expression, manchester_to_owl_expression |
| 116 | + |
| 117 | +print(dl_to_owl_expression("∃ hasChild.male", namespace)) |
| 118 | +# Result: OWLObjectSomeValuesFrom(property=OWLObjectProperty(IRI('http://example.com/family#','hasChild')),filler=OWLClass(IRI('http://example.com/family#','male'))) |
| 119 | + |
| 120 | +print(manchester_to_owl_expression("female and (hasChild max 2 person)", namespace)) |
| 121 | +# Result: OWLObjectIntersectionOf((OWLClass(IRI('http://example.com/family#','female')), OWLObjectMaxCardinality(property=OWLObjectProperty(IRI('http://example.com/family#','hasChild')),2,filler=OWLClass(IRI('http://example.com/family#','person'))))) |
| 122 | + |
| 123 | +``` |
| 124 | + |
| 125 | +In these examples we showed a fraction of **owlapy**. You can explore the |
| 126 | +[api documentation](owlapy) to learn more about all classes in owlapy. |
0 commit comments