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

ads/feature_engineering/feature_type/creditcard.py

@@ -0,0 +1,314 @@
+#!/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 represents a CreditCard feature type.
+
+Classes:
+    CreditCard
+        The CreditCard feature type.
+
+Functions:
+    default_handler(data: pd.Series) -> pd.Series
+        Processes given data and indicates if the data matches requirements.
+    _luhn_checksum(card_number: str) -> float
+        Implements Luhn algorithm to validate a credit card number.
+"""
+import matplotlib.pyplot as plt
+import pandas as pd
+import re
+from ads.feature_engineering.feature_type.string import String
+from ads.feature_engineering.utils import (
+    assign_issuer,
+    _count_unique_missing,
+    _set_seaborn_theme,
+    SchemeTeal,
+)
+from ads.feature_engineering import schema
+from ads.common.decorator.runtime_dependency import (
+    runtime_dependency,
+    OptionalDependency,
+)
+
+
+_max_sample_size_to_luhn_check = 1000
+_pattern_string = r"""
+        ^(?:4[0-9]{12}(?:[0-9]{3})?         # Visa
+        |  (?:5[1-5][0-9]{2}                # MasterCard
+        | 222[1-9]|22[3-9][0-9]|2[3-6][0-9]{2}|27[01][0-9]|2720)[0-9]{12}
+        |  3[47][0-9]{13}                   # American Express
+        |  3(?:0[0-5]|[68][0-9])[0-9]{11}   # Diners Club
+        |  6(?:011|5[0-9]{2})[0-9]{12}      # Discover
+        |  (?:2131|1800|35\d{3})\d{11}      # JCB
+        |  (5018|5020|5038|5612|5893|6304|6759|6761|6762|6763|0604|6390)\d+$   # Maestro
+        |  ^(5[06789]|6)[0-9]{0,}$          # Maestro
+        |  ^4[0-9]{12}(?:[0-9]{6})?$        #Visa 19 digit
+        )$
+    """
+PATTERN = re.compile(_pattern_string, 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_credit_card(x: pd.Series):
+        return (
+            not pd.isnull(x)
+            and PATTERN.match(str(x)) is not None
+            and _luhn_checksum(str(x)) == 0
+        )
+
+    return data.apply(lambda x: True if _is_credit_card(x) else False)
+
+
+def _luhn_checksum(card_number: str) -> float:
+    """
+    Implements Luhn algorithm to validate a credit card number.
+
+    Parameters
+    ----------
+    card_number : str
+        The credit card number.
+
+    Returns
+    -------
+    float
+        The checksum of the card number
+    """
+
+    def digits_of(n):
+        return [int(d) for d in str(n)]
+
+    digits = digits_of(card_number)
+    odd_digits = digits[-1::-2]
+    even_digits = digits[-2::-2]
+    checksum = 0
+    checksum += sum(odd_digits)
+    for d in even_digits:
+        checksum += sum(digits_of(d * 2))
+    return checksum % 10
+
+
+class CreditCard(String):
+    """
+    Type representing credit card 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.
+    feature_plot(x: pd.Series) -> plt.Axes
+        Shows the counts of observations in each credit card type using bar chart.
+
+
+    Examples
+    --------
+    >>> from ads.feature_engineering.feature_type.creditcard import CreditCard
+    >>> import pandas as pd
+    >>> s = pd.Series(["4532640527811543", None, "4556929308150929", "4539944650919740", "4485348152450846", "4556593717607190"], name='credit_card')
+    >>> s.ads.feature_type = ['credit_card']
+    >>> CreditCard.validator.is_credit_card(s)
+    0     True
+    1    False
+    2     True
+    3     True
+    4     True
+    5     True
+    Name: credit_card, dtype: bool
+    """
+
+    description = "Type representing credit card numbers."
+
+    @staticmethod
+    def feature_stat(x: pd.Series):
+        """Generates feature statistics.
+
+        Feature statistics include (total)count, unique(count), missing(count) and
+            count of each credit card type.
+
+        Examples
+        --------
+        >>> visa = [
+            "4532640527811543",
+            None,
+            "4556929308150929",
+            "4539944650919740",
+            "4485348152450846",
+            "4556593717607190",
+            ]
+        >>> mastercard = [
+            "5334180299390324",
+            "5111466404826446",
+            "5273114895302717",
+            "5430972152222336",
+            "5536426859893306",
+            ]
+        >>> amex = [
+            "371025944923273",
+            "374745112042294",
+            "340984902710890",
+            "375767928645325",
+            "370720852891659",
+            ]
+        >>> creditcard_list = visa + mastercard + amex
+        >>> creditcard_series = pd.Series(creditcard_list,name='card')
+        >>> creditcard_series.ads.feature_type = ['credit_card']
+        >>> creditcard_series.ads.feature_stat()
+            Metric              Value
+        0	count	            16
+        1	unique	            15
+        2	missing	            1
+        3	count_Amex	        5
+        4	count_Visa	        5
+        5	count_MasterCard	3
+        6	count_Diners Club	2
+        7	count_missing	    1
+
+        Returns
+        -------
+        :class:`pandas.DataFrame`
+            Summary statistics of the Series or Dataframe provided.
+        """
+        df_stat = _count_unique_missing(x)
+        card_types = x.apply(assign_issuer)
+        value_counts = card_types.value_counts()
+        value_counts.rename("creditcard", inplace=True)
+        value_counts.index = [
+            "count_" + cardtype for cardtype in list(value_counts.index)
+        ]
+        return pd.concat([df_stat, value_counts.to_frame()])
+
+    @staticmethod
+    @runtime_dependency(module="seaborn", install_from=OptionalDependency.VIZ)
+    def feature_plot(x: pd.Series) -> plt.Axes:
+        """
+        Shows the counts of observations in each credit card type using bar chart.
+
+        Examples
+        --------
+        >>> visa = [
+            "4532640527811543",
+            None,
+            "4556929308150929",
+            "4539944650919740",
+            "4485348152450846",
+            "4556593717607190",
+            ]
+        >>> mastercard = [
+            "5334180299390324",
+            "5111466404826446",
+            "5273114895302717",
+            "5430972152222336",
+            "5536426859893306",
+            ]
+        >>> amex = [
+            "371025944923273",
+            "374745112042294",
+            "340984902710890",
+            "375767928645325",
+            "370720852891659",
+            ]
+        >>> creditcard_list = visa + mastercard + amex
+        >>> creditcard_series = pd.Series(creditcard_list,name='card')
+        >>> creditcard_series.ads.feature_type = ['credit_card']
+        >>> creditcard_series.ads.feature_plot()
+
+        Returns
+        -------
+        matplotlib.axes._subplots.AxesSubplot
+            Plot object for the series based on the CreditCard feature type.
+        """
+        card_types = x.apply(assign_issuer)
+        df = card_types.value_counts().to_frame()
+        if len(df.index):
+            _set_seaborn_theme()
+            ax = seaborn.barplot(
+                y=df.index, x=list(df.iloc[:, 0]), 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
+        --------
+        >>> visa = [
+            "4532640527811543",
+            None,
+            "4556929308150929",
+            "4539944650919740",
+            "4485348152450846",
+            "4556593717607190",
+            ]
+        >>> mastercard = [
+            "5334180299390324",
+            "5111466404826446",
+            "5273114895302717",
+            "5430972152222336",
+            "5536426859893306",
+            ]
+        >>> amex = [
+            "371025944923273",
+            "374745112042294",
+            "340984902710890",
+            "375767928645325",
+            "370720852891659",
+            ]
+        >>> creditcard_list = visa + mastercard + amex
+        >>> creditcard_series = pd.Series(creditcard_list,name='card')
+        >>> creditcard_series.ads.feature_type = ['credit_card']
+        >>> creditcard_series.ads.feature_domain()
+        constraints: []
+        stats:
+            count: 16
+            count_Amex: 5
+            count_Diners Club: 2
+            count_MasterCard: 3
+            count_Visa: 5
+            count_missing: 1
+            missing: 1
+            unique: 15
+        values: CreditCard
+
+        Returns
+        -------
+        ads.feature_engineering.schema.Domain
+            Domain based on the CreditCard feature type.
+        """
+        return schema.Domain(
+            cls.__name__,
+            cls.feature_stat(x).to_dict()[x.name],
+            [],
+        )
+
+
+CreditCard.validator.register("is_credit_card", default_handler)

ads/feature_engineering/feature_type/datetime.py

@@ -0,0 +1,190 @@
+#!/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 DateTime feature type.
+
+Classes:
+    DateTime
+        The DateTime feature type.
+"""
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import pandas.api.types as pdtypes
+from ads.feature_engineering.feature_type.base import FeatureType
+from ads.feature_engineering.utils import (
+    _add_missing,
+    _set_seaborn_theme,
+    SchemeTeal,
+)
+from ads.feature_engineering import schema
+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: :class:`pandas.Series`
+        The data to process.
+
+    Returns
+    -------
+    :class:`pandas.Series`
+        The logical list indicating if the data matches requirements.
+    """
+
+    def _is_datetime(x: any):
+        if pd.isnull(x):
+            return False
+        if pdtypes.is_datetime64_any_dtype(type(x)):
+            return True
+        if pdtypes.is_string_dtype(type(x)) or pdtypes.is_object_dtype(type(x)):
+            try:
+                pd.to_datetime(x)
+            except:
+                return False
+            return True
+        return False
+
+    return data.apply(lambda x: True if _is_datetime(x) else False)
+
+
+class DateTime(FeatureType):
+    """
+    Type representing date and/or time.
+
+    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 datetime datasets using histograms.
+
+    Example
+    -------
+    >>> from ads.feature_engineering.feature_type.datetime import DateTime
+    >>> import pandas as pd
+    >>> s = pd.Series(["12/12/12", "12/12/13", None, "12/12/14"], name='datetime')
+    >>> s.ads.feature_type = ['date_time']
+    >>> DateTime.validator.is_datetime(s)
+    0     True
+    1     True
+    2    False
+    3     True
+    Name: datetime, dtype: bool
+    """
+
+    description = "Type representing date and/or time."
+
+    @staticmethod
+    def feature_stat(x: pd.Series) -> pd.DataFrame:
+        """Generates feature statistics.
+
+        Feature statistics include (total)count, sample maximum, sample minimum, and
+        missing(count) if there is any.
+
+        Examples
+        --------
+        >>> x = pd.Series(['3/11/2000', '3/12/2000', '3/13/2000', '', None, np.nan, 'April/13/2011', 'April/15/11'], name='datetime')
+        >>> x.ads.feature_type = ['date_time']
+        >>> x.ads.feature_stat()
+            Metric              Value
+        0	count	            8
+        1	sample maximum	    April/15/11
+        2	sample minimum	    3/11/2000
+        3	missing	            3
+
+        Returns
+        -------
+        :class:`pandas.DataFrame`
+            Summary statistics of the Series or Dataframe provided.
+        """
+        df_stat = pd.Series(
+            {
+                "count": len(x),
+                "sample maximum": x.replace(r"", np.NaN).dropna().max(),
+                "sample minimum": x.replace(r"", np.NaN).dropna().min(),
+            },
+            name=x.name,
+        ).to_frame()
+        return _add_missing(x.replace(r"", np.NaN), df_stat)
+
+    @staticmethod
+    @runtime_dependency(module="seaborn", install_from=OptionalDependency.VIZ)
+    def feature_plot(x: pd.Series) -> plt.Axes:
+        """
+        Shows distributions of datetime datasets using histograms.
+
+        Examples
+        --------
+        >>> x = pd.Series(['3/11/2000', '3/12/2000', '3/13/2000', '', None, np.nan, 'April/13/2011', 'April/15/11'], name='datetime')
+        >>> x.ads.feature_type = ['date_time']
+        >>> x.ads.feature_plot()
+
+        Returns
+        -------
+        matplotlib.axes._subplots.AxesSubplot
+            Plot object for the series based on the DateTime feature type.
+        """
+        col_name = x.name if x.name else "datetime"
+        df = x.to_frame(col_name)
+        df["validation"] = default_handler(x)
+        df = df[df["validation"] == True]
+        if len(df.index):
+            df[col_name] = df[col_name].apply(lambda x: pd.to_datetime(x))
+            _set_seaborn_theme()
+            return seaborn.histplot(data=df, y=col_name, 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(['3/11/2000', '3/12/2000', '3/13/2000', '', None, np.nan, 'April/13/2011', 'April/15/11'], name='datetime')
+        >>> s.ads.feature_type = ['date_time']
+        >>> s.ads.feature_domain()
+        constraints: []
+        stats:
+            count: 8
+            missing: 3
+            sample maximum: April/15/11
+            sample minimum: 3/11/2000
+        values: DateTime
+
+        Returns
+        -------
+        ads.feature_engineering.schema.Domain
+            Domain based on the DateTime feature type.
+        """
+
+        return schema.Domain(
+            cls.__name__,
+            cls.feature_stat(x).to_dict()[x.name],
+            [],
+        )
+
+
+DateTime.validator.register("is_datetime", default_handler)

ads/feature_engineering/feature_type/discrete.py

@@ -0,0 +1,134 @@
+#!/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 Discrete feature type.
+
+Classes:
+    Discrete
+        The Discrete 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 Discrete(FeatureType):
+    """
+    Type representing discrete 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 discrete values."
+
+    @staticmethod
+    def feature_stat(x: pd.Series) -> pd.DataFrame:
+        """Generates feature statistics.
+
+        Feature statistics include (total)count, unique(count) and missing(count).
+
+        Examples
+        --------
+        >>> discrete_numbers = pd.Series([35, 25, 13, 42],
+                   name='discrete')
+        >>> discrete_numbers.ads.feature_type = ['discrete']
+        >>> discrete_numbers.ads.feature_stat()
+                    discrete
+        count	4
+        unique	4
+
+        Returns
+        -------
+        :class:`pandas.DataFrame`
+            Summary statistics of the Series provided.
+        """
+        return _count_unique_missing(x)
+
+    @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
+        --------
+        >>> discrete_numbers = pd.Series([35, 25, 13, 42],
+                   name='discrete')
+        >>> discrete_numbers.ads.feature_type = ['discrete']
+        >>> discrete_numbers.ads.feature_stat()
+            Metric  Value
+        0	count	4
+        1	unique	4
+
+        Returns
+        -------
+        matplotlib.axes._subplots.AxesSubplot
+            Plot object for the series based on the Discrete feature type.
+        """
+        col_name = x.name if x.name else "discrete"
+        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
+        --------
+        >>> discrete_numbers = pd.Series([35, 25, 13, 42],
+                   name='discrete')
+        >>> discrete_numbers.ads.feature_type = ['discrete']
+        >>> discrete_numbers.ads.feature_domain()
+        constraints: []
+        stats:
+            count: 4
+            unique: 4
+        values: Discrete
+
+        Returns
+        -------
+        ads.feature_engineering.schema.Domain
+            Domain based on the Discrete feature type.
+        """
+
+        return schema.Domain(
+            cls.__name__,
+            cls.feature_stat(x).to_dict()[x.name],
+            [],
+        )

ads/feature_engineering/feature_type/document.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 a Document feature type.
+
+Classes:
+    Document
+        The Document feature type.
+"""
+from ads.feature_engineering.feature_type.base import FeatureType
+
+
+class Document(FeatureType):
+    """
+    Type representing document 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.
+    """
+
+    description = "Type representing document values."
+
+    @classmethod
+    def feature_domain(cls):
+        """
+        Returns
+        -------
+        None
+            Nothing.
+        """
+        return None