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

ads/feature_engineering/feature_type/object.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2021 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 Object feature type.
+
+Classes:
+    Object
+        The Object feature type.
+"""
+from ads.feature_engineering.feature_type.base import FeatureType
+
+
+class Object(FeatureType):
+    """
+    Type representing object.
+
+    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.
+    """
+
+    description = "Type representing object."
+
+    @classmethod
+    def feature_domain(cls):
+        """
+        Returns
+        -------
+        None
+            Nothing.
+        """
+        return None

ads/feature_engineering/feature_type/ordinal.py

@@ -0,0 +1,132 @@
+#!/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 Ordinal feature type.
+
+Classes:
+    Ordinal
+        The Ordinal 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 (
+    _count_unique_missing,
+    _set_seaborn_theme,
+    SchemeTeal,
+)
+from ads.feature_engineering import schema
+from ads.common.decorator.runtime_dependency import (
+    runtime_dependency,
+    OptionalDependency,
+)
+
+
+class Ordinal(FeatureType):
+    """Type representing ordered 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 the counts of observations in each categorical bin using bar chart.
+    """
+
+    description = "Type representing ordered values."
+
+    @staticmethod
+    def feature_stat(x: pd.Series) -> pd.DataFrame:
+        """Generates feature statistics.
+
+        Feature statistics include (total)count, unique(count),
+        and missing(count) if there is any.
+
+        Examples
+        --------
+        >>> x = pd.Series([1, 2, 3, 4, 5, 6, 7, 8, 9, np.nan], name='ordinal')
+        >>> x.ads.feature_type = ['ordinal']
+        >>> x.ads.feature_stat()
+            Metric  Value
+        0	count	10
+        1	unique	9
+        2	missing	1
+
+        Returns
+        -------
+        :class:`pandas.DataFrame`
+            Summary statistics of the Series or Dataframe provided.
+        """
+        return _count_unique_missing(x)
+
+    @staticmethod
+    @runtime_dependency(module="seaborn", install_from=OptionalDependency.VIZ)
+    def feature_plot(x: pd.Series) -> plt.Axes:
+        """
+        Shows the counts of observations in each categorical bin using bar chart.
+
+        Examples
+        --------
+        >>> x = pd.Series([1, 2, 3, 4, 5, 6, 7, 8, 9, np.nan], name='ordinal')
+        >>> x.ads.feature_type = ['ordinal']
+        >>> x.ads.feature_plot()
+
+        Returns
+        -------
+        matplotlib.axes._subplots.AxesSubplot
+            The bart chart plot object for the series based on the Continuous feature type.
+        """
+        col_name = x.name if x.name else "ordinal"
+        df = x.to_frame(name=col_name)
+        df = df.dropna()
+        if len(df.index):
+            _set_seaborn_theme()
+            ax = seaborn.countplot(y=col_name, data=df, color=SchemeTeal.AREA_DARK)
+            ax.set(xlabel="Count")
+            return ax
+
+    @classmethod
+    def feature_domain(cls, x: pd.Series) -> schema.Domain:
+        """
+        Generate the domain of the data of this feature type.
+
+        Examples
+        --------
+        >>> x = pd.Series([1, 2, 3, 4, 5, 6, 7, 8, 9, np.nan], name='ordinal')
+        >>> x.ads.feature_type = ['ordinal']
+        >>> x.ads.feature_domain()
+        constraints:
+        - expression: $x in [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0]
+            language: python
+        stats:
+            count: 10
+            missing: 1
+            unique: 9
+        values: Ordinal
+
+        Returns
+        -------
+        ads.feature_engineering.schema.Domain
+            Domain based on the Ordinal feature type.
+        """
+
+        return schema.Domain(
+            cls.__name__,
+            cls.feature_stat(x).to_dict()[x.name],
+            [schema.Expression(f"$x in {x.dropna().unique().tolist()}")],
+        )

ads/feature_engineering/feature_type/phone_number.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2021 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 a Phone Number feature type.
+
+Classes:
+    PhoneNumber
+        The Phone Number feature type.
+
+Functions:
+    default_handler(data: pd.Series) -> pd.Series
+        Processes given data and indicates if the data matches requirements.
+"""
+import pandas as pd
+import re
+from ads.feature_engineering.feature_type.string import String
+from ads.feature_engineering.utils import _count_unique_missing
+from ads.feature_engineering import schema
+
+
+PATTERN = re.compile(
+    r"^(\+?\d{1,2}[\s-])?\(?(\d{3})\)?[\s.-]?\d{3}[\s.-]?\d{4}$", re.VERBOSE
+)
+
+
+def default_handler(data: pd.Series, *args, **kwargs) -> pd.Series:
+    """Processes given data and indicates if the data matches requirements.
+
+    Parameters
+    ----------
+    data: :class:`pandas.Series`
+        The data to process.
+
+    Returns
+    -------
+    :class:`pandas.Series`
+        The logical list indicating if the data matches requirements.
+    """
+
+    def _is_phone_number(x: any):
+        return (
+            not pd.isnull(x) and isinstance(x, str) and re.match(PATTERN, x) is not None
+        )
+
+    return data.apply(lambda x: True if _is_phone_number(x) else False)
+
+
+class PhoneNumber(String):
+    """Type representing phone numbers.
+
+    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.
+
+    Examples
+    --------
+    >>> from ads.feature_engineering.feature_type.phone_number import PhoneNumber
+    >>> import pandas as pd
+    >>> s = pd.Series([None, "1-640-124-5367", "1-573-916-4412"])
+    >>> PhoneNumber.validator.is_phone_number(s)
+    0    False
+    1     True
+    2     True
+    dtype: bool
+    """
+
+    description = "Type representing phone numbers."
+
+    @staticmethod
+    def feature_stat(x: pd.Series) -> pd.DataFrame:
+        """Generates feature statistics.
+
+        Feature statistics include (total)count, unique(count) and
+        missing(count) if there is any.
+
+        Examples
+        --------
+        >>> s = pd.Series(['2068866666', '6508866666', '2068866666', '', np.NaN, np.nan, None], name='phone')
+        >>> s.ads.feature_type = ['phone_number']
+        >>> s.ads.feature_stat()
+            Metric  Value
+        1	count	7
+        2	unique	2
+        3	missing	4
+
+        Returns
+        -------
+        :class:`pandas.DataFrame`
+            Summary statistics of the Series or Dataframe provided.
+        """
+        return _count_unique_missing(x)
+
+    @classmethod
+    def feature_domain(cls, x: pd.Series) -> schema.Domain:
+        """
+        Generate the domain of the data of this feature type.
+
+        Examples
+        --------
+        >>> s = pd.Series(['2068866666', '6508866666', '2068866666', '', np.NaN, np.nan, None], name='phone')
+        >>> s.ads.feature_type = ['phone_number']
+        >>> s.ads.feature_domain()
+        constraints: []
+        stats:
+            count: 7
+            missing: 4
+            unique: 2
+        values: PhoneNumber
+
+        Returns
+        -------
+        ads.feature_engineering.schema.Domain
+            Domain based on the PhoneNumber feature type.
+        """
+
+        return schema.Domain(cls.__name__, cls.feature_stat(x).to_dict()[x.name], [])
+
+
+PhoneNumber.validator.register("is_phone_number", default_handler)

ads/feature_engineering/feature_type/string.py

@@ -0,0 +1,171 @@
+#!/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 a String feature type.
+
+Classes:
+    String
+        The feature type that represents string values.
+"""
+import matplotlib.pyplot as plt
+import pandas as pd
+from ads.feature_engineering.feature_type.base import FeatureType
+from ads.feature_engineering.utils import (
+    _count_unique_missing,
+    random_color_func,
+    SchemeNeutral,
+)
+from ads.feature_engineering import schema
+from ads.common import utils, logger
+from ads.common.decorator.runtime_dependency import (
+    runtime_dependency,
+    OptionalDependency,
+)
+
+
+def default_handler(data: pd.Series, *args, **kwargs) -> pd.Series:
+    """Processes given data and indicates if the data matches requirements.
+
+    Parameters
+    ----------
+    data: pd.Series
+        The data to process.
+
+    Returns
+    -------
+    pd.Series: The logical list indicating if the data matches requirements.
+    """
+    return data.apply(lambda x: isinstance(x, str))
+
+
+class String(FeatureType):
+    """
+    Type representing string 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 wordcloud.
+
+
+    Example
+    -------
+    >>> from ads.feature_engineering.feature_type.string import String
+    >>> import pandas as pd
+    >>> s = pd.Series(["Hello", "world", None], name='string')
+    >>> String.validator.is_string(s)
+    0     True
+    1     True
+    2    False
+    Name: string, dtype: bool
+    """
+
+    description = "Type representing string values."
+
+    @staticmethod
+    def feature_stat(x: pd.Series) -> pd.DataFrame:
+        """Generates feature statistics.
+
+        Feature statistics include (total)count, unique(count)
+        and missing(count) if there is any.
+
+        Examples
+        --------
+        >>> string = pd.Series(['S', 'C', 'S', 'S', 'S', 'Q', 'S', 'S', 'S', 'C', 'S', 'S', 'S',
+                'S', 'S', 'S', 'Q', 'S', 'S', '', np.NaN, None], name='string')
+        >>> string.ads.feature_type = ['string']
+        >>> string.ads.feature_stat()
+            Metric  Value
+        0	count	22
+        1	unique	3
+        2	missing	3
+
+        Returns
+        -------
+        Pandas Dataframe
+            Summary statistics of the Series or Dataframe provided.
+        """
+        return _count_unique_missing(x)
+
+    @staticmethod
+    @runtime_dependency(module="wordcloud", install_from=OptionalDependency.TEXT)
+    def feature_plot(x: pd.Series) -> plt.Axes:
+        """
+        Shows distributions of datasets using wordcloud.
+
+        Examples
+        --------
+        >>> string = pd.Series(['S', 'C', 'S', 'S', 'S', 'Q', 'S', 'S', 'S', 'C', 'S', 'S', 'S',
+                'S', 'S', 'S', 'Q', 'S', 'S', '', np.NaN, None], name='string')
+        >>> string.ads.feature_type = ['string']
+        >>> string.ads.feature_plot()
+
+        Returns
+        -------
+        matplotlib.axes._subplots.AxesSubplot
+            Plot object for the series based on the String feature type.
+        """
+        col_name = x.name if x.name else "text"
+        df = x.to_frame(col_name)
+        df["validation"] = default_handler(x)
+        df = df[df["validation"] == True]
+        words = " ".join(df[col_name].dropna().to_list())
+        if not words:
+            return
+
+        from wordcloud import WordCloud
+
+        wc = WordCloud(
+            background_color=SchemeNeutral.BACKGROUND_LIGHT,
+            color_func=random_color_func,
+        ).generate(words)
+        _, ax = plt.subplots(facecolor=SchemeNeutral.BACKGROUND_LIGHT)
+        ax.imshow(wc)
+        plt.axis("off")
+        return ax
+
+    @classmethod
+    def feature_domain(cls, x: pd.Series) -> schema.Domain:
+        """
+        Generate the domain of the data of this feature type.
+
+        Examples
+        --------
+        >>> string = pd.Series(['S', 'C', 'S', 'S', 'S', 'Q', 'S', 'S', 'S', 'C', 'S', 'S', 'S',
+                'S', 'S', 'S', 'Q', 'S', 'S', '', np.NaN, None], name='string')
+        >>> string.ads.feature_type = ['string']
+        >>> string.ads.feature_domain()
+        constraints: []
+        stats:
+            count: 22
+            missing: 3
+            unique: 3
+        values: String
+
+        Returns
+        -------
+        ads.feature_engineering.schema.Domain
+            Domain based on the String feature type.
+        """
+
+        return schema.Domain(cls.__name__, cls.feature_stat(x).to_dict()[x.name], [])
+
+
+String.validator.register("is_string", default_handler)

ads/feature_engineering/feature_type/text.py

@@ -0,0 +1,93 @@
+#!/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 a Text feature type.
+
+Classes:
+    Text
+        The Text feature type.
+"""
+import matplotlib.pyplot as plt
+import pandas as pd
+from ads.feature_engineering.feature_type.string import String
+from ads.feature_engineering.utils import random_color_func, SchemeNeutral
+
+from ads.common import utils, logger
+from ads.common.decorator.runtime_dependency import (
+    runtime_dependency,
+    OptionalDependency,
+)
+
+
+class Text(String):
+    """
+    Type representing text 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_plot(x: pd.Series) -> plt.Axes
+        Shows distributions of datasets using wordcloud.
+    """
+
+    @staticmethod
+    @runtime_dependency(module="wordcloud", install_from=OptionalDependency.TEXT)
+    def feature_plot(x: pd.Series) -> plt.Axes:
+        """
+        Shows distributions of datasets using wordcloud.
+
+        Examples
+        --------
+        >>> text = pd.Series(['S', 'C', 'S', 'S', 'S', 'Q', 'S', 'S', 'S', 'C', 'S', 'S', 'S',
+                'S', 'S', 'S', 'Q', 'S', 'S', '', np.NaN, None], name='text')
+        >>> text.ads.feature_type = ['text']
+        >>> text.ads.feature_plot()
+
+        Returns
+        -------
+        matplotlib.axes._subplots.AxesSubplot
+            Plot object for the series based on the Text feature type.
+        """
+        col_name = x.name if x.name else "text"
+        df = x.to_frame(col_name)
+        words = df[col_name].dropna().to_list()
+        words = " ".join([s for s in words if isinstance(s, str)])
+        if not words:
+            return
+
+        from wordcloud import WordCloud
+
+        wc = WordCloud(
+            background_color=SchemeNeutral.BACKGROUND_LIGHT,
+            color_func=random_color_func,
+        ).generate(words)
+        _, ax = plt.subplots(facecolor=SchemeNeutral.BACKGROUND_LIGHT)
+        ax.imshow(wc)
+        plt.axis("off")
+        return ax
+
+    description = "Type representing text values."
+
+    @classmethod
+    def feature_domain(cls):
+        """
+        Returns
+        -------
+        None
+            Nothing.
+        """
+        return None

ads/feature_engineering/feature_type/unknown.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2021 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 Unknown feature type.
+
+Classes:
+    Text
+        The Unknown feature type.
+"""
+from ads.feature_engineering.feature_type.base import FeatureType
+
+
+class Unknown(FeatureType):
+    """
+    Type representing third-party dtypes.
+
+    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.
+    """
+
+    description = "Type representing unknown type."
+
+    @classmethod
+    def feature_domain(cls):
+        """
+        Returns
+        -------
+        None
+            Nothing.
+        """
+        return None