Automatic extraction of reverse edges

docs/readme_sections/how_to.rst

@@ -10,7 +10,7 @@ an existing node, use the ``to_property`` predicate, for example:
 .. code:: yaml
 
    row:
-      map:
+      rowIndex:
          to_subject: phenotype
    transformers:
        - map:
@@ -275,3 +275,26 @@ information see the ``Information Fusion`` section.
 
 An edge of type ``protein_protein_interaction``, will be created from
 node ``A`` to node ``B``, as well as from node ``C`` to node ``A``.
+
+How to Extract Reverse Relations For Declared Edges
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Reverse relations can be extracted for each edge in a declarative manner.
+Let's assume you have a mapping file mapping each row index to the node type `disease`, and each cell value from the
+`patient` column to the node type `patient`. The two nodes are connected via a relation `disease_affects_patient`, but you
+would also wish to indicate a reverse edge of type `patient_has_disease`.
+
+This can be done by using the `reverse_relation` keyword, which extracts the reverse edge of the type you declared. You
+may consult the ``Keyword Synonyms`` section for more synonyms.
+
+.. code:: yaml
+
+   row:
+      rowIndex:
+         to_subject: disease
+   transformers:
+       - map:
+           column: patient
+           to_object: patient
+           via_relation: disease_affects_patient
+           reverse_relation: patient_has_disease

docs/readme_sections/mapping_api.rst

@@ -736,7 +736,7 @@ You can have a look at the transformers provided by OntoWeaver to get
 inspiration for your own implementation:
 `ontoweaver/src/ontoweaver/transformer.py <https://github.com/oncodash/ontoweaver/blob/main/src/ontoweaver/transformer.py>`__
 
-Keywords Synonyms
+Keyword Synonyms
 ~~~~~~~~~~~~~~~~~
 
 Because several communities gathered around semantic knowledge graphs,
@@ -755,3 +755,4 @@ Here is the list of available synonyms:
 - ``to_property`` = ``to_properties``
 - ``for_object`` = ``for_objects``
 - ``final_type`` = ``final_object`` = ``final_label`` = ``final_node`` = ``final_target`` = ``final_subject``
+- ``reverse_relation`` = ``reverse_edge`` = ``reverse_predicate``

src/ontoweaver/base.py

@@ -579,15 +579,16 @@ def create(self, returned_value, row):
         Create the output of the transformer, using the label_maker of the transformer instance.
 
         Returns:
-            Extracted cell value (can be node ID, property value, edge ID), edge type and target node type.
+            Extracted cell value (can be node ID, property value, edge ID), edge type, target node type, and
+            reverse relation in case declared in the mapping.
         """
         result_object = self.label_maker(self.validate, returned_value, self.multi_type_dict, self.branching_properties, row)
         if result_object.target_node_type:
             self.target_type = result_object.target_node_type.__name__
         if result_object.target_element_properties is not None:
             self.properties_of = result_object.target_element_properties
         self.final_type = result_object.final_type
-        return result_object.extracted_cell_value, result_object.edge_type, result_object.target_node_type
+        return result_object.extracted_cell_value, result_object.edge_type, result_object.target_node_type, result_object.reverse_relation
 
 
 class All:

src/ontoweaver/make_labels.py

@@ -11,7 +11,7 @@ class ReturnCreate:
     and properties of the target node type.
     """
 
-    def __init__(self, extracted_cell_value = None, edge_type = None, target_node_type = None, properties_of = None, final_type = None):
+    def __init__(self, extracted_cell_value = None, edge_type = None, target_node_type = None, properties_of = None, final_type = None, reverse_relation = None):
         """
         Initializes the ReturnCreate object.
 
@@ -21,13 +21,15 @@ def __init__(self, extracted_cell_value = None, edge_type = None, target_node_ty
             target_node_type: The type of the target node.
             properties_of: The properties of the returned target node type.
             final_type: The final type of the target node.
+            reverse_relation: The reverse relation of the current edge.
         """
 
         self.extracted_cell_value = extracted_cell_value # Can serve as ID of the node, ID of the edge, or value of property.
         self.edge_type = edge_type
         self.target_node_type = target_node_type
         self.target_element_properties = properties_of
         self.final_type = final_type
+        self.reverse_relation = reverse_relation
 
 class LabelMaker(errormanager.ErrorManager, metaclass=abc.ABCMeta):
     """Interface for defining the correct labels (types) for each extracted value.
@@ -75,7 +77,8 @@ def __call__(self, validate, returned_value, multi_type_dict, branching_properti
             if multi_type_dict:
                 if "None" in multi_type_dict.keys():
                     # No branching needed. The transformer is not a branching transformer.
-                    return ReturnCreate(res, multi_type_dict["None"]["via_relation"], multi_type_dict["None"]["to_object"], None, multi_type_dict["None"]["final_type"])
+                    return ReturnCreate(res, multi_type_dict["None"]["via_relation"], multi_type_dict["None"]["to_object"],
+                                        None, multi_type_dict["None"]["final_type"], multi_type_dict["None"]["reverse_relation"])
             else:
                 # No multi-type dictionary. The transformer returns only the extracted value of the cell. Used for properties.
                 return ReturnCreate(res)
@@ -101,7 +104,8 @@ def __call__(self, validate, returned_value, multi_type_dict = None, branching_p
                             properties_of = branching_properties.get(types["to_object"].__name__, {})
                         else:
                             properties_of = {}
-                        return ReturnCreate(res, types["via_relation"], types["to_object"], properties_of, types["final_type"])
+                        return ReturnCreate(res, types["via_relation"], types["to_object"], properties_of,
+                                            types["final_type"], types["reverse_relation"])
                     else:
                         logger.info(f"          Branching key `{key}` does not match extracted value `{res}`.")
                         continue
@@ -132,7 +136,8 @@ def __call__(self, validate, returned_value, multi_type_dict = None, branching_p
                             properties_of = branching_properties.get(types["to_object"].__name__, {})
                         else:
                             properties_of = {}
-                        return ReturnCreate(res, types["via_relation"], types["to_object"], properties_of, types["final_type"])
+                        return ReturnCreate(res, types["via_relation"], types["to_object"], properties_of,
+                                            types["final_type"], types["reverse_relation"])
                     else:
                         logger.info(f"          Branching key `{key}` does not match extracted value `{row[self.match_type_from_column]}`.")
                         continue