change method names

README.md

@@ -35,22 +35,89 @@ nlp.add_pipe(entityLinker, last=True, name="entityLinker")
 
 doc = nlp("I watched the Pirates of the Carribean last silvester")
 
-
 #returns all entities in the whole document
 all_linked_entities=doc._.linkedEntities
 #iterates over sentences and prints linked entities
 for sent in doc.sents:
     sent._.linkedEntities.pretty_print()
+    
+#OUTPUT:
+#https://www.wikidata.org/wiki/Q194318         194318     Pirates of the Caribbean        Series of fantasy adventure films                                                                   
+    #https://www.wikidata.org/wiki/Q12525597   12525597   Silvester                       the day celebrated on 31 December (Roman Catholic Church) or 2 January (Eastern Orthodox Churches)                
+
+```
 
-'''
-https://www.wikidata.org/wiki/Q194318     194318     Pirates of the Caribbean        Series of fantasy adventure films                                                                   
-https://www.wikidata.org/wiki/Q12525597   12525597   Silvester                       the day celebrated on 31 December (Roman Catholic Church) or 2 January (Eastern Orthodox Churches)  
+### EntityCollection
+contains an array of entity elements. It can be accessed like an array but also implements the following 
+helper functions:
+- <code>pretty_print()</code> prints out information about all contained entities
+- <code>print_super_classes()</code> groups and prints all entites by their super class
 
-'''
+```python
+doc = nlp("Elon Musk was born in South Africa. Bill Gates and Steve Jobs come from the United States")
+doc._.linkedEntities.print_super_entities()
+#OUTPUT:
+#human (3) : Elon Musk,Bill Gates,Steve Jobs
+#country (2) : South Africa,United States of America
+#sovereign state (2) : South Africa,United States of America
+#federal state (1) : United States of America
+#constitutional republic (1) : United States of America
+#democratic republic (1) : United States of America
 ```
+### EntityElement
+each linked Entity is an object of type <code>EntityElement</code>. Each entity contains the methods
+
+- <code>get_description()</code> returns description from Wikidata
+- <code>get_id()</code> returns Wikidata ID
+- <code>get_label()</code> returns Wikidata label
+- <code>get_span()</code> returns the span from the spacy document that contains the linked entity
+- <code>get_url()</code> returns the url to the corresponding Wikidata item
+- <code>pretty_print()</code> prints out information about the entity element
+- <code>get_sub_entities(limit=10)</code> returns EntityCollection of all entities that derive from the current entityElement (e.g. fruit -> apple, banana, etc.)
+- <code>get_super_entities(limit=10)</code> returns EntityCollection of all entities that the current entityElement derives from (e.g. New England Patriots -> Football Team))
 
 ## Example
-In the following example we will use SpacyEntityLinker to extract all 
+In the following example we will use SpacyEntityLinker to find find the mentioned Football Team in our text
+and explore other football teams of the same type
+
+```python
+
+doc = nlp("I follow the New England Patriots")
+
+patriots_entity=doc._.linkedEntities[0]
+patriots_entity.pretty_print()
+#OUTPUT:
+#https://www.wikidata.org/wiki/Q193390
+#193390     
+#New England Patriots            
+#National Football League franchise in Foxborough, Massachusetts                    
+
+football_team_entity=patriots_entity.get_super_entities()[0]
+football_team_entity.pretty_print()
+#OUTPUT:
+#https://www.wikidata.org/wiki/Q17156793   
+#17156793   
+#American football team          
+#organization, in which a group of players are organized to compete as a team in American football   
+
+
+for child in football_team_entity.get_sub_entities(limit=32):
+  print(child)
+  #OUTPUT:
+  #New Orleans Saints
+  #New York Giants
+  #Pittsburgh Steelers
+  #New England Patriots
+  #Indianapolis Colts
+  #Miami Seahawks
+  #Dallas Cowboys
+  #Chicago Bears
+  #Washington Redskins
+  #Green Bay Packers
+  #...
+```
+
+</pre>
 
 
 ### Entity Linking Policy

spacyEntityLinker/DatabaseConnection.py

@@ -11,7 +11,7 @@ conn = None
 entity_cache = {}
 chain_cache = {}
 
-DB_DEFAULT_PATH = os.path.abspath('../data_spacy_entity_linker/wikidb_filtered.db')
+DB_DEFAULT_PATH = os.path.abspath(__file__ + '/../../data_spacy_entity_linker/wikidb_filtered.db')
 
 wikidata_instance = None
 
@@ -93,11 +93,11 @@ class WikidataQueryController:
 
         if res and len(res):
             if res[0] == None:
-                self._append_chain_elements("name", item_id, 'no label')
+                self._add_to_cache("name", item_id, 'no label')
             else:
-                self._append_chain_elements("name", item_id, res[0])
+                self._add_to_cache("name", item_id, res[0])
         else:
-            self._append_chain_elements("name", item_id, '<none>')
+            self._add_to_cache("name", item_id, '<none>')
 
         return self._get_cached_value("name", item_id)
 

spacyEntityLinker/EntityCollection.py

@@ -27,7 +27,7 @@ class EntityCollection:
 
         return categories
 
-    def print_categories(self, max_depth=1, limit=10):
+    def print_super_entities(self, max_depth=1, limit=10):
         wikidataInstance = get_wikidata_instance()
 
         all_categories = []
@@ -49,7 +49,7 @@ class EntityCollection:
         for entity in self.entities:
             entity.pretty_print()
 
-    def grouped_by_category(self, max_depth=1):
+    def grouped_by_super_entities(self, max_depth=1):
         counter = Counter()
         counter.update(self.get_categories(max_depth))
 
@@ -57,9 +57,3 @@ class EntityCollection:
 
     def get_distinct_categories(self, max_depth=1):
         return list(set(self.get_categories(max_depth)))
-
-    def most_frequent_categories(self):
-        pass
-
-    def get_most_significant_categories(self, priors):
-        pass

spacyEntityLinker/EntityElement.py

@@ -1,4 +1,5 @@
 from spacyEntityLinker.DatabaseConnection import get_wikidata_instance
+from spacyEntityLinker.EntityCollection import EntityCollection
 
 
 class EntityElement:
@@ -61,11 +62,13 @@ class EntityElement:
     def get_categories(self, max_depth=10):
         return self.wikidata_instance.get_categories(self.identifier, max_depth=max_depth)
 
-    def get_children(self, limit=10):
-        return [EntityElement(row, None) for row in self.wikidata_instance.get_children(self.get_id(), limit)]
+    def get_sub_entities(self, limit=10):
+        return EntityCollection(
+            [EntityElement(row, None) for row in self.wikidata_instance.get_children(self.get_id(), limit)])
 
-    def get_parents(self, limit=10):
-        return [EntityElement(row, None) for row in self.wikidata_instance.get_parents(self.get_id(), limit)]
+    def get_super_entities(self, limit=10):
+        return EntityCollection(
+            [EntityElement(row, None) for row in self.wikidata_instance.get_parents(self.get_id(), limit)])
 
     def get_subclass_hierarchy(self):
         chain = self.wikidata_instance.get_chain(self.identifier, max_depth=5, property=279)
@@ -122,3 +125,6 @@ class EntityElement:
             return label
         else:
             return ""
+
+    def __eq__(self, other):
+        return isinstance(other, EntityElement) and other.get_id() == self.get_id()

spacyEntityLinker/__init__.py

@@ -1,4 +1,4 @@
 from .EntityLinker import EntityLinker
 
-__version__ = '0.0.2'
+__version__ = '0.0.5'
 __all__ = [EntityLinker]

tests/test_EntityLinker.py

@@ -14,10 +14,11 @@ class TestEntityLinker(unittest.TestCase):
 
         self.nlp.add_pipe(entityLinker, last=True, name="entityLinker")
 
-        doc = self.nlp("I watched the Pirates of the Caribbean last silvester. Then I saw a snake. It was great.")
+        doc = self.nlp(
+            "Elon Musk was born in South Africa. Bill Gates and Steve Jobs come from in the United States")
 
         doc._.linkedEntities.pretty_print()
-
+        doc._.linkedEntities.print_super_entities()
         for sent in doc.sents:
             sent._.linkedEntities.pretty_print()