Add Feature Descriptions Rebase Clean (#1316)

Co-authored-by: Jan van Rijn <[email protected]>

Author: LennartPurucker

openml/datasets/data_feature.py

@@ -23,6 +23,10 @@ class OpenMLDataFeature:
         list of the possible values, in case of nominal attribute
     number_missing_values : int
         Number of rows that have a missing value for this feature.
+    ontologies : list(str)
+        list of ontologies attached to this feature. An ontology describes the
+        concept that are described in a feature. An ontology is defined by an
+        URL where the information is provided.
     """
 
     LEGAL_DATA_TYPES: ClassVar[Sequence[str]] = ["nominal", "numeric", "string", "date"]
@@ -34,6 +38,7 @@ def __init__(  # noqa: PLR0913
         data_type: str,
         nominal_values: list[str],
         number_missing_values: int,
+        ontologies: list[str] | None = None,
     ):
         if not isinstance(index, int):
             raise TypeError(f"Index must be `int` but is {type(index)}")
@@ -67,6 +72,7 @@ def __init__(  # noqa: PLR0913
         self.data_type = str(data_type)
         self.nominal_values = nominal_values
         self.number_missing_values = number_missing_values
+        self.ontologies = ontologies
 
     def __repr__(self) -> str:
         return "[%d - %s (%s)]" % (self.index, self.name, self.data_type)

openml/datasets/dataset.py

@@ -1069,6 +1069,7 @@ def _parse_features_xml(features_xml_string: str) -> dict[int, OpenMLDataFeature
             xmlfeature["oml:data_type"],
             xmlfeature.get("oml:nominal_value"),
             int(nr_missing),
+            xmlfeature.get("oml:ontology"),
         )
         if idx != feature.index:
             raise ValueError("Data features not provided in right order")

openml/datasets/functions.py

@@ -1061,6 +1061,59 @@ def fork_dataset(data_id: int) -> int:
     return int(data_id)
 
 
+def data_feature_add_ontology(data_id: int, index: int, ontology: str) -> bool:
+    """
+    An ontology describes the concept that are described in a feature. An
+    ontology is defined by an URL where the information is provided. Adds
+    an ontology (URL) to a given dataset feature (defined by a dataset id
+    and index). The dataset has to exists on OpenML and needs to have been
+    processed by the evaluation engine.
+
+    Parameters
+    ----------
+    data_id : int
+        id of the dataset to which the feature belongs
+    index : int
+        index of the feature in dataset (0-based)
+    ontology : str
+        URL to ontology (max. 256 characters)
+
+    Returns
+    -------
+    True or throws an OpenML server exception
+    """
+    upload_data: dict[str, int | str] = {"data_id": data_id, "index": index, "ontology": ontology}
+    openml._api_calls._perform_api_call("data/feature/ontology/add", "post", data=upload_data)
+    # an error will be thrown in case the request was unsuccessful
+    return True
+
+
+def data_feature_remove_ontology(data_id: int, index: int, ontology: str) -> bool:
+    """
+    Removes an existing ontology (URL) from a given dataset feature (defined
+    by a dataset id and index). The dataset has to exists on OpenML and needs
+    to have been processed by the evaluation engine. Ontology needs to be
+    attached to the specific fearure.
+
+    Parameters
+    ----------
+    data_id : int
+        id of the dataset to which the feature belongs
+    index : int
+        index of the feature in dataset (0-based)
+    ontology : str
+        URL to ontology (max. 256 characters)
+
+    Returns
+    -------
+    True or throws an OpenML server exception
+    """
+    upload_data: dict[str, int | str] = {"data_id": data_id, "index": index, "ontology": ontology}
+    openml._api_calls._perform_api_call("data/feature/ontology/remove", "post", data=upload_data)
+    # an error will be thrown in case the request was unsuccessful
+    return True
+
+
 def _topic_add_dataset(data_id: int, topic: str) -> int:
     """
     Adds a topic for a dataset.

tests/test_datasets/test_dataset.py

@@ -330,6 +330,47 @@ def test_tagging(self):
         datasets = openml.datasets.list_datasets(tag=tag, output_format="dataframe")
         assert datasets.empty
 
+    def test_get_feature_with_ontology_data_id_11(self):
+        # test on car dataset, which has built-in ontology references
+        dataset = openml.datasets.get_dataset(11)
+        assert len(dataset.features) == 7
+        assert len(dataset.features[1].ontologies) >= 2
+        assert len(dataset.features[2].ontologies) >= 1
+        assert len(dataset.features[3].ontologies) >= 1
+
+    def test_add_remove_ontology_to_dataset(self):
+        did = 1
+        feature_index = 1
+        ontology = 'https://www.openml.org/unittest/' + str(time())
+        openml.datasets.functions.data_feature_add_ontology(did, feature_index, ontology)
+        openml.datasets.functions.data_feature_remove_ontology(did, feature_index, ontology)
+
+    def test_add_same_ontology_multiple_features(self):
+        did = 1
+        ontology = 'https://www.openml.org/unittest/' + str(time())
+
+        for i in range(3):
+            openml.datasets.functions.data_feature_add_ontology(did, i, ontology)
+
+
+    def test_add_illegal_long_ontology(self):
+        did = 1
+        ontology = 'http://www.google.com/' + ('a' * 257)
+        try:
+            openml.datasets.functions.data_feature_add_ontology(did, 1, ontology)
+            assert False
+        except openml.exceptions.OpenMLServerException as e:
+            assert e.code == 1105
+
+    def test_add_illegal_url_ontology(self):
+        did = 1
+        ontology = 'not_a_url' + str(time())
+        try:
+            openml.datasets.functions.data_feature_add_ontology(did, 1, ontology)
+            assert False
+        except openml.exceptions.OpenMLServerException as e:
+            assert e.code == 1106
+
 @pytest.mark.production()
 class OpenMLDatasetTestSparse(TestBase):
     _multiprocess_can_split_ = True