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

ads/feature_engineering/feature_type/handler/feature_warning.py

@@ -0,0 +1,319 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2021, 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+"""
+The module that helps to register custom warnings for the feature types.
+
+Classes
+-------
+    FeatureWarning
+        The Feature Warning class. Provides functionality to register
+        warning handlers and invoke them.
+
+Examples
+--------
+    >>> warning = FeatureWarning()
+    >>> def warning_handler_zeros_count(data):
+    ...    return pd.DataFrame(
+    ...        [['Zeros', 'Age has 38 zeros', 'Count', 38]],
+    ...        columns=['Warning', 'Message', 'Metric', 'Value'])
+    >>> def warning_handler_zeros_percentage(data):
+    ...    return pd.DataFrame(
+    ...        [['Zeros', 'Age has 12.2% zeros', 'Percentage', '12.2%']],
+    ...        columns=['Warning', 'Message', 'Metric', 'Value'])
+    >>> warning.register(name="zeros_count", handler=warning_handler_zeros_count)
+    >>> warning.register(name="zeros_percentage", handler=warning_handler_percentage)
+    >>> warning.registered()
+                        Name                               Handler
+        ----------------------------------------------------------
+        0         zeros_count          warning_handler_zeros_count
+        1    zeros_percentage     warning_handler_zeros_percentage
+
+    >>> warning.zeros_percentage(data_series)
+                 Warning               Message         Metric      Value
+        ----------------------------------------------------------------
+        0          Zeros      Age has 38 zeros          Count         38
+
+    >>> warning.zeros_count(data_series)
+                 Warning               Message         Metric      Value
+        ----------------------------------------------------------------
+        1          Zeros   Age has 12.2% zeros     Percentage      12.2%
+
+    >>> warning(data_series)
+            Warning                    Message         Metric      Value
+        ----------------------------------------------------------------
+        0          Zeros      Age has 38 zeros          Count         38
+        1          Zeros   Age has 12.2% zeros     Percentage      12.2%
+
+    >>> warning.unregister('zeros_count')
+    >>> warning(data_series)
+                 Warning               Message         Metric      Value
+        ----------------------------------------------------------------
+        0          Zeros   Age has 12.2% zeros     Percentage      12.2%
+"""
+from typing import Callable
+import pandas as pd
+from ads.feature_engineering.exceptions import WarningNotFound, WarningAlreadyExists
+
+
+def _validate_warning_handler(handler: Callable) -> bool:
+    """Validates warning handler.
+
+    Handler should get pd.Series as a parameter and return pd.DataFrame as result.
+    Dataframe should have four columns: Warning, Message, Metric and Value.
+
+    Parameters
+    ----------
+    handler: Callable
+        The handler to validate.
+
+    Returns
+    -------
+    bool
+        True if handler compatible with Feature Warning, False otherwise.
+    """
+    result = True
+    try:
+        handler_result = handler(pd.Series([]))
+        assert isinstance(handler_result, pd.DataFrame)
+        assert list(handler_result.columns) == ["Warning", "Message", "Metric", "Value"]
+    except AssertionError:
+        result = False
+    return result
+
+
+class FeatureWarning:
+    """The Feature Warning class.
+
+    Provides functionality to register warning handlers and invoke them.
+
+    Methods
+    -------
+    register(self, name: str, handler: Callable) -> None
+        Registers a new warning for the feature type.
+    unregister(self, name: str) -> None
+        Unregisters warning.
+    registered(self) -> pd.DataFrame
+        Gets the list of registered warnings.
+
+    Examples
+    --------
+    >>> warning = FeatureWarning()
+    >>> def warning_handler_zeros_count(data):
+    ...    return pd.DataFrame(
+    ...        [['Zeros', 'Age has 38 zeros', 'Count', 38]],
+    ...        columns=['Warning', 'Message', 'Metric', 'Value'])
+    >>> def warning_handler_zeros_percentage(data):
+    ...    return pd.DataFrame(
+    ...        [['Zeros', 'Age has 12.2% zeros', 'Percentage', '12.2%']],
+    ...        columns=['Warning', 'Message', 'Metric', 'Value'])
+    >>> warning.register(name="zeros_count", handler=warning_handler_zeros_count)
+    >>> warning.register(name="zeros_percentage", handler=warning_handler_percentage)
+    >>> warning.registered()
+                      Warning                              Handler
+        ----------------------------------------------------------
+        0         zeros_count          warning_handler_zeros_count
+        1    zeros_percentage     warning_handler_zeros_percentage
+
+    >>> warning.zeros_percentage(data_series)
+                 Warning               Message         Metric      Value
+        ----------------------------------------------------------------
+        0          Zeros      Age has 38 zeros          Count         38
+
+    >>> warning.zeros_count(data_series)
+                  Warning              Message         Metric      Value
+        ----------------------------------------------------------------
+        1          Zeros   Age has 12.2% zeros     Percentage      12.2%
+
+    >>> warning(data_series)
+                 Warning               Message         Metric      Value
+        ----------------------------------------------------------------
+        0          Zeros      Age has 38 zeros          Count         38
+        1          Zeros   Age has 12.2% zeros     Percentage      12.2%
+
+    >>> warning.unregister('zeros_count')
+    >>> warning(data_series)
+                 Warning               Message         Metric      Value
+        ----------------------------------------------------------------
+        0          Zeros   Age has 12.2% zeros     Percentage      12.2%
+    """
+
+    def __init__(self):
+        """Initializes the FeatureWarning."""
+        self._data = None
+        self._handlers = {}
+
+    def register(self, name: str, handler: Callable, replace: bool = False) -> None:
+        """Registers a new warning.
+
+        Parameters
+        ----------
+        name : str
+            The warning name.
+        handler: callable
+            The handler associated with the warning.
+        replace: bool
+            The flag indicating if the registered warning should be replaced with the new one.
+
+        Returns
+        -------
+        None
+            Nothing
+
+        Raises
+        ------
+        ValueError
+            If warning name is empty or handler not defined.
+        TypeError
+            If handler is not callable.
+        WarningAlreadyExists
+            If warning is already registered.
+        """
+        if not name:
+            raise ValueError("Warning name is not provided.")
+        if name in self._handlers and not replace:
+            raise WarningAlreadyExists(name)
+        if not handler:
+            raise ValueError("Handler is not provided.")
+        if not callable(handler):
+            raise TypeError("Handler should be a function.")
+        self._handlers[name] = handler
+
+    def unregister(self, name: str) -> None:
+        """Unregisters warning.
+
+        Parameters
+        -----------
+        name: str
+            The name of warning to be unregistered.
+
+        Returns
+        -------
+        None
+            Nothing.
+
+        Raises
+        ------
+        ValueError
+            If warning name is not provided or empty.
+        WarningNotFound
+            If warning not found.
+        """
+        if not name:
+            raise ValueError("Warning name is not provided.")
+        if name not in self._handlers:
+            raise WarningNotFound(name)
+        del self._handlers[name]
+
+    def registered(self) -> pd.DataFrame:
+        """Gets the list of registered warnings.
+
+        Returns
+        -------
+        pd.DataFrame
+
+        Examples
+        --------
+        >>>    The list of registerd warnings in DataFrame format.
+                             Name                               Handler
+            -----------------------------------------------------------
+            0         zeros_count           warning_handler_zeros_count
+            1    zeros_percentage      warning_handler_zeros_percentage
+        """
+        result = []
+        for name, handler in self._handlers.items():
+            result.append((name, handler.__name__))
+        return pd.DataFrame(result, columns=["Warning", "Handler"])
+
+    def _bind_data(self, data: pd.Series) -> None:
+        """Binds data to the feature warning.
+
+        Parameters
+        ----------
+        data: pd.Series
+            The data to be bound.
+        """
+        self._data = data
+
+    def _process(self) -> pd.DataFrame:
+        """Invokes the all registered warnings.
+
+        Returns
+        -------
+        pd.DataFrame
+        >>>    The result of invoked warning handlers.
+                 Warning               Message       Metric    Value
+            --------------------------------------------------------
+                   Zeros      Age has 38 zeros        Count       38
+                   Zeros   Age has 12.2% zeros   Percentage    12.2%
+        Raises
+        ------
+        ValueError
+            If data is not provided or result of warning has a wrong format.
+        """
+        if self._data is None:
+            raise ValueError("Data is not provided.")
+
+        if not self._handlers:
+            return None
+
+        expected_columns = ["Warning", "Message", "Metric", "Value"]
+        result_df = pd.DataFrame([], columns=expected_columns)
+        for name, handler in self._handlers.items():
+            try:
+                handler_result = handler(self._data)
+            except Exception as ex:
+                raise ValueError(
+                    f"An error occurred while executing the '{name}'. "
+                    f"Details: {str(ex)}."
+                ) from ex
+            if handler_result is not None:
+                if not isinstance(handler_result, pd.DataFrame) or (
+                    not handler_result.empty
+                    and set(list(handler_result.columns)) != set(expected_columns)
+                ):
+                    raise ValueError(
+                        f"An error occurred while executing the '{name}'. "
+                        f"Details: '{name}' should return a DataFrame "
+                        f"with columns: {expected_columns}."
+                    )
+                result_df = pd.concat([result_df, handler_result])
+        result_df.reset_index(drop=True, inplace=True)
+        return result_df
+
+    def __call__(self, *args) -> pd.DataFrame:
+        """Makes class instance callable.
+
+        Parameters
+        ----------
+        *args
+            Variable length argument list.
+
+        Returns
+        -------
+        pd.DataFrame
+            The result of processing the all registered warnings.
+
+        Raises
+        ------
+        ValueError
+            If data is not provided,
+        TypeError
+            If data has wrong format.
+        """
+        if args and len(args) > 0:
+            self._data = args[0]
+        if self._data is None:
+            raise ValueError("Data is not provided.")
+        if not isinstance(self._data, pd.Series):
+            raise TypeError("Wrong data format. Data should be Series.")
+        return self._process()
+
+    def __getattr__(self, attr):
+        """Makes it possible to invoke registered warning as a regular method."""
+        if attr in self._handlers:
+            return self._handlers[attr]
+        raise AttributeError(attr)

ads/feature_engineering/feature_type/handler/warnings.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2021, 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+"""
+The module with all default warnings provided to user. These are registered to relevant feature
+types directly in the feature type files themselves.
+"""
+
+import pandas as pd
+
+
+def missing_values_handler(s: pd.Series) -> pd.DataFrame:
+    """
+    Warning for > 5 percent missing values (Nans) in series.
+
+    Parameters
+    ----------
+    s : pd.Series
+        Pandas series - column of some feature type.
+
+    Returns
+    -------
+    pd.Dataframe
+        Dataframe with 4 columns 'Warning', 'Message', 'Metric', 'Value'
+        and 2 rows, where first row is count of missing values and second is
+        percentage of missing values.
+    """
+    num_missing = s.isna().sum()
+    pct_missing = 100 * num_missing / len(s)
+    df = pd.DataFrame([], columns=["Warning", "Message", "Metric", "Value"])
+    if pct_missing >= 5:
+        df.loc[0] = ["missing", f"{num_missing} missing values", "count", num_missing]
+        df.loc[1] = [
+            "missing",
+            f"{pct_missing:.1f}% missing values",
+            "percentage",
+            round(pct_missing, 2),
+        ]
+    return df
+
+
+def skew_handler(s: pd.Series) -> pd.DataFrame:
+    """
+    Warning if absolute value of skew is greater than 1.
+
+    Parameters
+    ----------
+    s : pd.Series
+        Pandas series - column of some feature type, expects continuous values.
+
+    Returns
+    -------
+    pd.Dataframe
+        Dataframe with 4 columns 'Warning', 'Message', 'Metric', 'Value'
+        and 1 rows, which lists skew value of that column.
+    """
+    series_skew = s.skew()
+    df = pd.DataFrame([], columns=["Warning", "Message", "Metric", "Value"])
+    if abs(series_skew) > 1:
+        df.loc[0] = ["skew", f"{series_skew:.3f} skew", "skew", round(series_skew, 2)]
+    return df
+
+
+def high_cardinality_handler(s: pd.Series) -> pd.DataFrame:
+    """
+    Warning if number of unique values (including Nan) in series is greater than or equal to 15.
+
+    Parameters
+    ----------
+    s : pd.Series
+        Pandas series - column of some feature type.
+
+    Returns
+    -------
+    pd.Dataframe
+        Dataframe with 4 columns 'Warning', 'Message', 'Metric', 'Value'
+        and 1 rows, which lists count of unique values.
+    """
+    num_unique = s.nunique(dropna=False)
+    df = pd.DataFrame([], columns=["Warning", "Message", "Metric", "Value"])
+    if num_unique == len(s):
+        df.loc[0] = [
+            "high-cardinality",
+            f"every value is distinct",
+            "count",
+            num_unique,
+        ]
+    elif num_unique >= 15:
+        df.loc[0] = [
+            "high-cardinality",
+            f"{num_unique} unique values",
+            "count",
+            num_unique,
+        ]
+    return df
+
+
+def zeros_handler(s: pd.Series) -> pd.DataFrame:
+    """
+    Warning for greater than 10 percent zeros in series.
+
+    Parameters
+    ----------
+    s : pd.Series
+        Pandas series - column of some feature type.
+
+    Returns
+    -------
+    pd.Dataframe
+        Dataframe with 4 columns 'Warning', 'Message', 'Metric', 'Value'
+        and 2 rows, where first row is count of zero values and second is
+        percentage of zero values.
+    """
+    num_zeros = (s == 0).sum()
+    pct_missing = 100 * num_zeros / len(s)
+    df = pd.DataFrame([], columns=["Warning", "Message", "Metric", "Value"])
+    if pct_missing >= 5:
+        df.loc[0] = ["zeros", f"{num_zeros} zeros", "count", num_zeros]
+        df.loc[1] = [
+            "zeros",
+            f"{pct_missing:.1f}% zeros",
+            "percentage",
+            round(pct_missing, 2),
+        ]
+    return df

ads/feature_engineering/feature_type/integer.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2021, 2022 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+"""
+The module that represents an Integer feature type.
+
+Classes:
+    Integer
+        The Integer feature type.
+"""
+import matplotlib.pyplot as plt
+import pandas as pd
+from ads.feature_engineering.feature_type.base import FeatureType
+from ads.feature_engineering.utils import (
+    _add_missing,
+    _set_seaborn_theme,
+    SchemeTeal,
+    _format_stat,
+)
+from ads.feature_engineering import schema
+from ads.common.decorator.runtime_dependency import (
+    runtime_dependency,
+    OptionalDependency,
+)
+
+
+class Integer(FeatureType):
+    """
+    Type representing integer values.
+
+    Attributes
+    ----------
+    description: str
+        The feature type description.
+    name: str
+        The feature type name.
+    warning: FeatureWarning
+        Provides functionality to register warnings and invoke them.
+    validator
+        Provides functionality to register validators and invoke them.
+
+    Methods
+    --------
+    feature_stat(x: pd.Series) -> pd.DataFrame
+        Generates feature statistics.
+    feature_plot(x: pd.Series) -> plt.Axes
+        Shows distributions of datasets using box plot.
+    """
+
+    description = "Type representing integer values."
+
+    @staticmethod
+    def feature_stat(x: pd.Series) -> pd.DataFrame:
+        """Generates feature statistics.
+
+        Feature statistics include (total)count, mean, standard deviation, sample minimum,
+        lower quartile, median, 75%, upper quartile, max and missing(count) if there is any.
+
+        Examples
+        --------
+        >>> x = pd.Series([1, 0, 1, 2, 3, 4, np.nan], name='integer')
+        >>> x.ads.feature_type = ['integer']
+        >>> x.ads.feature_stat()
+            Metric                  Value
+        0	count	                7
+        1	mean	                1
+        2	standard deviation	    1
+        3	sample minimum	        0
+        4	lower quartile	        1
+        5	median	                1
+        6	upper quartile	        2
+        7	sample maximum	        4
+        8	missing	                1
+
+        Returns
+        -------
+        :class:`pandas.DataFrame`
+            Summary statistics of the Series or Dataframe provided.
+        """
+        df_stat = x.describe()
+        _format_stat(df_stat)
+        df_stat["count"] = len(x)
+        df_stat = _add_missing(x, df_stat).to_frame()
+        df_stat.iloc[:, 0] = df_stat.iloc[:, 0]
+        return df_stat
+
+    @staticmethod
+    @runtime_dependency(module="seaborn", install_from=OptionalDependency.VIZ)
+    def feature_plot(x: pd.Series) -> plt.Axes:
+        """
+        Shows distributions of datasets using box plot.
+
+        Examples
+        --------
+        >>> x = pd.Series([1, 0, 1, 2, 3, 4, np.nan], name='integer')
+        >>> x.ads.feature_type = ['integer']
+        >>> x.ads.feature_plot()
+
+        Returns
+        -------
+        matplotlib.axes._subplots.AxesSubplot
+            Plot object for the series based on the Integer feature type.
+        """
+        col_name = x.name if x.name else "integer"
+        df = x.to_frame(name=col_name)
+        df = df[pd.to_numeric(df[col_name], errors="coerce").notnull()]
+        if len(df.index):
+            _set_seaborn_theme()
+            return seaborn.boxplot(
+                x=df[col_name], width=0.2, color=SchemeTeal.AREA_DARK
+            )
+
+    @classmethod
+    def feature_domain(cls, x: pd.Series) -> schema.Domain:
+        """
+        Generate the domain of the data of this feature type.
+
+        Examples
+        --------
+        >>> s = pd.Series([True, False, True, False, np.NaN, None], name='integer')
+        >>> s.ads.feature_type = ['integer']
+        >>> s.ads.feature_domain()
+        constraints: []
+        stats:
+            count: 6
+            freq: 2
+            missing: 2
+            top: true
+            unique: 2
+        values: Integer
+
+
+        Returns
+        -------
+        ads.feature_engineering.schema.Domain
+            Domain based on the Integer feature type.
+        """
+
+        return schema.Domain(cls.__name__, cls.feature_stat(x).to_dict()[x.name], [])