oracle-ads 2.13.9rc0__py3-none-any.whl → 2.13.10__py3-none-any.whl

ads/feature_store/service/oci_feature_store.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+
+# Copyright (c) 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+import datetime
+from functools import wraps
+from typing import Callable
+
+from feature_store_client.feature_store.models import (
+    CreateFeatureStoreDetails,
+    UpdateFeatureStoreDetails,
+    FeatureStore,
+)
+
+from ads.feature_store.mixin.oci_feature_store import OCIFeatureStoreMixin
+import logging
+
+logger = logging.getLogger(__name__)
+
+FEATURE_STORE_NEEDS_TO_BE_SAVED = (
+    "Feature store needs to be saved before it can be accessed."
+)
+
+
+class FeatureStoreNotSavedError(Exception):
+    """
+    An exception raised when attempting to access a feature store that has not been saved.
+    """
+
+    def __init__(self, message="Feature store has not been saved."):
+        """
+        Initializes a new FeatureStoreNotSavedError exception with the specified message.
+
+        Args:
+            message (str): Optional. The message to include with the exception.
+        """
+        self.message = message
+        super().__init__(self.message)
+
+
+def check_for_feature_store_id(msg: str = FEATURE_STORE_NEEDS_TO_BE_SAVED):
+    """The decorator helping to check if the ID attribute sepcified for a datascience feature store.
+
+    Parameters
+    ----------
+    msg: str
+        The message that will be thrown.
+
+    Raises
+    ------
+    FeatureStoreNotSavedError
+        In case if the ID attribute not specified.
+
+    Examples
+    --------
+    >>> @check_for_feature_store_id(msg="Some message.")
+    ... def test_function(self, name: str, last_name: str)
+    ...     pass
+    """
+
+    def decorator(func: Callable):
+        @wraps(func)
+        def wrapper(self, *args, **kwargs):
+            if not self.id:
+                raise FeatureStoreNotSavedError(msg)
+            return func(self, *args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+class OCIFeatureStore(OCIFeatureStoreMixin, FeatureStore):
+    """Represents an OCI Data Science feature store.
+    This class contains all attributes of the `oci.data_science.models.FeatureStore`.
+    The main purpose of this class is to link the `oci.data_science.models.FeatureStore`
+    and the related client methods.
+    Linking the `FeatureStore` (payload) to Create/Update/Get/List/Delete methods.
+
+    The `OCIFeatureStore` can be initialized by unpacking the properties stored in a dictionary:
+
+    .. code-block:: python
+
+        properties = {
+            "compartment_id": "<compartment_ocid>",
+            "display_name": "<feature_store_name>",
+            "description": "<feature_store_description>",
+        }
+        feature_store_model = OCIFeatureStore(**properties)
+
+    The properties can also be OCI REST API payload, in which the keys are in camel format.
+
+    .. code-block:: python
+
+        payload = {
+            "compartmentId": "<compartment_ocid>",
+            "displayName": "<feature_store_name>",
+            "description": "<feature_store_description>",
+        }
+        feature_store_model = OCIFeatureStore(**payload)
+
+    Methods
+    -------
+    create(self) -> "OCIFeatureStore"
+        Creates feature store.
+    delete(self):
+        Deletes feature store.
+    update(self) -> "OCIFeatureStore":
+        Updates feature store.
+    from_id(cls, ocid: str) -> "OCIFeatureStore":
+        Gets feature store by OCID.
+    Examples
+    --------
+    >>> oci_feature_store = OCIFeatureStore.from_id("<feature store_id>")
+    >>> oci_feature_store.description = "A brand new description"
+    >>> oci_feature_store.delete()
+    """
+
+    def create(self) -> "OCIFeatureStore":
+        """Creates feature store resource.
+        !!! note "Lazy"
+            This method is lazy and does not persist any metadata or feature data in the
+            feature store on its own. To persist the feature group and save feature data
+            along the metadata in the feature store, call the `materialise()` method with a
+            DataFrame or with a Datasource.
+
+        Returns
+        -------
+        OCIFeatureStore
+            The `OCIFeatureStore` instance (self), which allows chaining additional method.
+        """
+        if not self.display_name:
+            timestamp = datetime.datetime.now().strftime("%Y%m%d-%H%M")
+            self.display_name = f"feature-store-{timestamp}"
+
+        if not self.compartment_id:
+            raise ValueError(
+                "`compartment_id` must be specified for the feature store."
+            )
+
+        feature_store_details = self.to_oci_model(CreateFeatureStoreDetails)
+        return self.update_from_oci_model(
+            self.client.create_feature_store(feature_store_details).data
+        )
+
+    def update(self) -> "OCIFeatureStore":
+        """Updates feature store.
+
+        Returns
+        -------
+        OCIFeatureStore
+            The `OCIFeatureStore` instance (self).
+        """
+        return self.update_from_oci_model(
+            self.client.update_feature_store(
+                self.id, self.to_oci_model(UpdateFeatureStoreDetails)
+            ).data
+        )
+
+    def delete(self):
+        """Removes feature store"""
+        self.client.delete_feature_store(self.id)
+
+    @classmethod
+    def from_id(cls, id: str) -> "OCIFeatureStore":
+        """Gets feature store resource  by id.
+
+        Parameters
+        ----------
+        id: str
+            The id of the feature store resource.
+
+        Returns
+        -------
+        OCIFeatureStore
+            An instance of `OCIFeatureStore`.
+        """
+        if not id:
+            raise ValueError("Feature store id not provided.")
+        return super().from_ocid(id)

ads/feature_store/service/oci_lineage.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+
+# Copyright (c) 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+import logging
+
+import feature_store_client.feature_store as fs
+
+from ads.feature_store.mixin.oci_feature_store import OCIFeatureStoreMixin
+
+from feature_store_client.feature_store.models import (
+    Lineage,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class OCILineage(OCIFeatureStoreMixin, Lineage):
+    """Represents an OCI Data Science Lineage Resource Class.
+    This class contains all attributes of the `oci.data_science.models.Lineaage`.
+    The main purpose of this class is to link the `oci.data_science.models.Lineaage`
+    and the related client methods.
+    Linking the `Lineaage` (payload) to Create methods.
+
+    The `OCILineage` can be initialized by unpacking the properties stored in a dictionary:
+
+    .. code-block:: python
+
+        properties = {
+            "id": "Feature Store Resource Id, It can be dataset or feature group",
+            "constructType": "Feature store lineage construct type for which lineage is supported",
+        }
+        Lineage = OCILineage(**properties)
+
+    The properties can also be OCI REST API payload, in which the keys are in camel format.
+
+    .. code-block:: python
+
+        properties = {
+            "id": "Feature Store Resource Id",
+            "constructType": "Feature store lineage construct type for which lineage is supported",
+        }
+        Lineage = OCILineage(**properties)
+
+    Methods
+    -------
+    create(self) -> "Lineage"
+        Creates Lineage.
+    from_id(cls, ocid: str) -> "Lineage":
+        Gets existing Lineage by Id.
+    Examples
+    --------
+    >>> lineage = OCILineage.from_id("<feature_store_construct_id>")
+    >>> lineage.create()
+    """
+
+    def __init__(self, **kwargs) -> None:
+        """Initialize a Lineage object.
+
+        Parameters
+        ----------
+        kwargs:
+            Same as kwargs in feature_store.models.Lineage.
+            Keyword arguments are passed into OCI feature group Lineage model to initialize the properties.
+
+        """
+
+        super().__init__(**kwargs)
+
+    def from_id(self, feature_store_lineage_resource_id: str, **kwargs) -> Lineage:
+        """Gets lineage resource  by feature store id.
+
+        Parameters
+        -----------
+        feature_store_lineage_resource_id: str
+            The id of the feature store lineage resource.
+
+        Returns
+        -------
+        Lineage
+            Feature store lineage information.
+        """
+        if not feature_store_lineage_resource_id:
+            raise ValueError("feature store lineage resource id not provided.")
+        return super().client.get_lineage(feature_store_lineage_resource_id, **kwargs)

ads/feature_store/service/oci_transformation.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+
+# Copyright (c) 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+from feature_store_client.feature_store.models import (
+    CreateTransformationDetails,
+    Transformation,
+)
+
+from ads.feature_store.mixin.oci_feature_store import OCIFeatureStoreMixin
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class OCITransformation(OCIFeatureStoreMixin, Transformation):
+    """Represents an OCI Data Science Transformation.
+    This class contains all attributes of the `oci.data_science.models.Transformation`.
+    The main purpose of this class is to link the `oci.data_science.models.Transformation`
+    and the related client methods.
+    Linking the `Transformation` (payload) to Create/Update/Get/List/Delete methods.
+
+    The `OCITransformation` can be initialized by unpacking the properties stored in a dictionary:
+
+    .. code-block:: python
+
+        properties = {
+            "compartment_id": "<compartment_ocid>",
+            "display_name": "<feature_store_name>",
+            "description": "<feature_store_description>",
+            "transformation_mode":"<transformation_mode>",
+            "source_code":"<transformation_source_code>"
+        }
+        transformation_model = OCITransformation(**properties)
+
+    The properties can also be OCI REST API payload, in which the keys are in camel format.
+
+    .. code-block:: python
+
+        properties = {
+            "compartment_id": "<compartment_ocid>",
+            "display_name": "<feature_store_name>",
+            "description": "<feature_store_description>",
+            "transformation_mode":"<transformation_mode>",
+            "source_code":"<transformation_source_code>"
+        }
+        transformation_model = OCITransformation(**properties)
+
+    Methods
+    -------
+    create(self) -> "OCITransformation"
+        Creates transformation.
+    delete(self) -> "OCITransformation":
+        Deletes transformation.
+    from_id(cls, ocid: str) -> "OCITransformation":
+        Gets existing transformation by Id.
+    Examples
+    --------
+    >>> oci_transformation = OCITransformation.from_id("<transformation_id>")
+    >>> oci_transformation.delete()
+    """
+
+    def create(self) -> "OCITransformation":
+        """Creates transformation resource.
+
+        Returns
+        -------
+        OCITransformation
+            The `OCITransformation` instance (self), which allows chaining additional method.
+        """
+        if not self.compartment_id:
+            raise ValueError("The `compartment_id` must be specified.")
+
+        if not self.feature_store_id:
+            raise ValueError("The `feature_store_id` must be specified.")
+
+        transformation_details = self.to_oci_model(CreateTransformationDetails)
+        return self.update_from_oci_model(
+            self.client.create_transformation(transformation_details).data
+        )
+
+    def delete(self):
+        """Removes transformation"""
+        self.client.delete_transformation(self.id)
+
+    @classmethod
+    def from_id(cls, id: str) -> "OCITransformation":
+        """Gets transformation resource  by id.
+
+        Parameters
+        ----------
+        id: str
+            The id of the transformation resource.
+
+        Returns
+        -------
+        OCIFeatureStore
+            An instance of `OCITransformation`.
+        """
+        if not id:
+            raise ValueError("Transformation id not provided.")
+        return super().from_ocid(id)

ads/feature_store/statistics/abs_feature_value.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+# Copyright (c) 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+from abc import abstractmethod
+from typing import Union
+
+from ads.common.decorator.runtime_dependency import OptionalDependency
+
+try:
+    from plotly.graph_objs import Figure
+except ModuleNotFoundError:
+    raise ModuleNotFoundError(
+        f"The `plotly` module was not found. Please run `pip install "
+        f"{OptionalDependency.FEATURE_STORE}`."
+    )
+
+
+class AbsFeatureValue:
+    CONST_METRIC_DATA = "metric_data"
+
+    def __init__(self):
+        self.__validate__()
+
+    @abstractmethod
+    def __validate__(self):
+        pass
+
+    @classmethod
+    @abstractmethod
+    def __from_json__(cls, json_dict: dict, version: int):
+        pass
+
+    @classmethod
+    @abstractmethod
+    def __from_json_v2__(cls, json_dict: dict):
+        pass
+
+    @classmethod
+    def from_json(
+        cls, json_dict: dict, version: int, ignore_errors: bool = False
+    ) -> Union["AbsFeatureValue", None]:
+        try:
+            return cls.__from_json__(json_dict=json_dict, version=version)
+        except Exception as e:
+            if ignore_errors:
+                return None
+            else:
+                raise e

ads/feature_store/statistics/charts/abstract_feature_plot.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+# Copyright (c) 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+import abc
+
+from abc import abstractmethod
+from ads.feature_store.statistics.abs_feature_value import AbsFeatureValue
+from ads.common.decorator.runtime_dependency import OptionalDependency
+
+try:
+    from plotly.graph_objs import Figure
+except ModuleNotFoundError:
+    raise ModuleNotFoundError(
+        f"The `plotly` module was not found. Please run `pip install "
+        f"{OptionalDependency.FEATURE_STORE}`."
+    )
+
+
+class AbsFeaturePlot(abc.ABC, AbsFeatureValue):
+    @abstractmethod
+    def add_to_figure(self, fig: Figure, xaxis: int, yaxis: int):
+        pass
+
+    @classmethod
+    @abstractmethod
+    def __from_json__(cls, json_dict: dict, version: int):
+        pass
+
+    @staticmethod
+    def get_x_y_str_axes(xaxis: int, yaxis: int) -> ():
+        return (
+            ("xaxis" + str(xaxis + 1)),
+            ("yaxis" + str(yaxis + 1)),
+            ("x" + str(xaxis + 1)),
+            ("y" + str(yaxis + 1)),
+        )

ads/feature_store/statistics/charts/box_plot.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+# Copyright (c) 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+from typing import List, Union
+
+from ads.feature_store.statistics.abs_feature_value import AbsFeatureValue
+
+from ads.common.decorator.runtime_dependency import OptionalDependency
+from ads.feature_store.statistics.charts.abstract_feature_plot import AbsFeaturePlot
+from ads.feature_store.statistics.charts.frequency_distribution import (
+    FrequencyDistribution,
+)
+from ads.feature_store.statistics.generic_feature_value import GenericFeatureValue
+
+try:
+    from plotly.graph_objs import Figure
+except ModuleNotFoundError:
+    raise ModuleNotFoundError(
+        f"The `plotly` module was not found. Please run `pip install "
+        f"{OptionalDependency.FEATURE_STORE}`."
+    )
+
+
+class BoxPlot(AbsFeaturePlot):
+    CONST_MIN = "Min"
+    CONST_MAX = "Max"
+    CONST_QUARTILES = "Quartiles"
+    CONST_SD = "StandardDeviation"
+    CONST_MEAN = "Mean"
+    CONST_BOX_PLOT_TITLE = "Box Plot"
+    CONST_IQR = "IQR"
+    CONST_BOX_POINTS = "box_points"
+
+    class Quartiles(AbsFeatureValue):
+        CONST_Q1 = "q1"
+        CONST_Q2 = "q2"
+        CONST_Q3 = "q3"
+
+        def __init__(self, q1: float, q2: float, q3: float):
+            self.q1 = q1
+            self.q2 = q2
+            self.q3 = q3
+            super().__init__()
+
+        @classmethod
+        def __from_json__(
+            cls, json_dict: dict, version: int = 1
+        ) -> "BoxPlot.Quartiles":
+            if version == 2:
+                return cls.__from_json_v2__(json_dict)
+            return cls(
+                json_dict.get(cls.CONST_Q1),
+                json_dict.get(cls.CONST_Q2),
+                json_dict.get(cls.CONST_Q3),
+            )
+
+        @classmethod
+        def __from_json_v2__(cls, json_dict: dict) -> "BoxPlot.Quartiles":
+            metric_data = json_dict.get(AbsFeatureValue.CONST_METRIC_DATA)
+            return cls(metric_data[0], metric_data[1], metric_data[2])
+
+        def __validate__(self):
+            assert type(self.q1) == type(self.q2) == type(self.q3) == int or float
+            assert self.q3 >= self.q2 >= self.q1
+
+    def __init__(
+        self,
+        mean: float,
+        median: float,
+        sd: float,
+        q1: float,
+        q3: float,
+        box_points: List[float],
+    ):
+        self.mean = mean
+        self.median = median
+        self.q1 = q1
+        self.q3 = q3
+        self.sd = sd
+        self.iqr = self.q3 - self.q1
+        self.box_points = box_points
+        super().__init__()
+
+    def __validate__(self):
+        assert self.q1 is not None
+        assert self.q3 is not None
+        assert self.iqr is not None
+        assert self.q3 is not None
+        assert self.median is not None
+        assert self.mean is not None
+        assert type(self.box_points) is list
+        assert len(self.box_points) > 0
+
+    def add_to_figure(self, fig: Figure, xaxis: int, yaxis: int):
+        xaxis_str, yaxis_str, x_str, y_str = self.get_x_y_str_axes(xaxis, yaxis)
+        fig.add_box(
+            notched=False,
+            boxmean=False,
+            mean=[self.mean],
+            median=[self.median],
+            q1=[self.q1],
+            q3=[self.q3],
+            sd=[self.sd],
+            y=[self.box_points],
+            upperfence=[self.q3 + 1.5 * self.iqr],
+            lowerfence=[self.q1 - 1.5 * self.iqr],
+            xaxis=x_str,
+            yaxis=y_str,
+            name="",
+            jitter=0,
+        )
+        fig.layout.annotations[xaxis].text = self.CONST_BOX_PLOT_TITLE
+        fig.layout[yaxis_str]["title"] = "Values"
+
+    @staticmethod
+    def get_box_points_from_frequency_distribution(
+        frequency_distribution: FrequencyDistribution,
+    ) -> List[float]:
+        # box_points = []
+        if (
+            frequency_distribution is not None
+            and frequency_distribution.frequency is not None
+            and frequency_distribution.bins is not None
+        ):
+            return [
+                bin_dist
+                for frequency, bin_dist in zip(
+                    frequency_distribution.frequency, frequency_distribution.bins
+                )
+                if frequency > 0
+            ]
+        else:
+            return []
+
+    @classmethod
+    def __from_json__(cls, json_dict: dict, version: int = 1) -> "BoxPlot":
+        quartiles = cls.Quartiles.from_json(json_dict.get(cls.CONST_QUARTILES), version)
+        return cls(
+            mean=GenericFeatureValue.from_json(
+                json_dict.get(cls.CONST_MEAN), version
+            ).val,
+            median=quartiles.q2,
+            sd=GenericFeatureValue.from_json(json_dict.get(cls.CONST_SD), version).val,
+            q1=quartiles.q1,
+            q3=quartiles.q3,
+            box_points=json_dict.get(cls.CONST_BOX_POINTS),
+        )

ads/feature_store/statistics/charts/frequency_distribution.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+# Copyright (c) 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+from typing import List
+from ads.common.decorator.runtime_dependency import OptionalDependency
+from ads.feature_store.statistics.abs_feature_value import AbsFeatureValue
+from ads.feature_store.statistics.charts.abstract_feature_plot import AbsFeaturePlot
+
+try:
+    from plotly.graph_objs import Figure
+except ModuleNotFoundError:
+    raise ModuleNotFoundError(
+        f"The `plotly` module was not found. Please run `pip install "
+        f"{OptionalDependency.FEATURE_STORE}`."
+    )
+
+
+class FrequencyDistribution(AbsFeaturePlot):
+    CONST_FREQUENCY = "frequency"
+    CONST_BINS = "bins"
+    CONST_FREQUENCY_DISTRIBUTION_TITLE = "Frequency Distribution"
+
+    def __init__(self, frequency: List, bins: List):
+        self.frequency = frequency
+        self.bins = bins
+        super().__init__()
+
+    def __validate__(self):
+        assert type(self.frequency) == list
+        assert type(self.bins) == list
+        assert 0 < len(self.frequency)
+        assert len(self.bins) > 0
+
+    @classmethod
+    def __from_json__(
+        cls, json_dict: dict, version: int = 1
+    ) -> "FrequencyDistribution":
+        if version == 2:
+            return cls.__from_json_v2__(json_dict)
+        return FrequencyDistribution(
+            frequency=json_dict.get(cls.CONST_FREQUENCY),
+            bins=json_dict.get(cls.CONST_BINS),
+        )
+
+    @classmethod
+    def __from_json_v2__(cls, json_dict: dict) -> "FrequencyDistribution":
+        metric_data = json_dict.get(AbsFeatureValue.CONST_METRIC_DATA)
+        return FrequencyDistribution(bins=metric_data[0], frequency=metric_data[1])
+
+    def add_to_figure(self, fig: Figure, xaxis: int, yaxis: int):
+        xaxis_str, yaxis_str, x_str, y_str = self.get_x_y_str_axes(xaxis, yaxis)
+        if (
+            type(self.frequency) == list
+            and type(self.bins) == list
+            and 0 < len(self.frequency)
+            and 0 < len(self.bins)
+        ):
+            fig.add_bar(
+                x=self.bins, y=self.frequency, xaxis=x_str, yaxis=y_str, name=""
+            )
+            fig.layout.annotations[xaxis].text = self.CONST_FREQUENCY_DISTRIBUTION_TITLE
+            fig.layout[xaxis_str]["title"] = "Bins"
+            fig.layout[yaxis_str]["title"] = "Frequency"