oracle-ads 2.10.0__py3-none-any.whl → 2.11.0__py3-none-any.whl

ads/opctl/operator/lowcode/anomaly/model/base_model.py

@@ -0,0 +1,354 @@
+#!/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 os
+import tempfile
+import time
+from abc import ABC, abstractmethod
+from typing import Tuple
+
+import fsspec
+import pandas as pd
+import numpy as np
+from sklearn import linear_model
+
+from ads.opctl import logger
+
+from ..operator_config import AnomalyOperatorConfig, AnomalyOperatorSpec
+from .anomaly_dataset import AnomalyDatasets, AnomalyOutput, TestData
+from ads.opctl.operator.lowcode.anomaly.const import OutputColumns, SupportedMetrics
+from ..const import SupportedModels
+from ads.opctl.operator.lowcode.common.utils import (
+    human_time_friendly,
+    enable_print,
+    disable_print,
+    write_data,
+    merge_category_columns,
+    find_output_dirname,
+)
+from ads.opctl.operator.lowcode.anomaly.utils import _build_metrics_df, default_signer
+from ads.common.object_storage_details import ObjectStorageDetails
+
+
+class AnomalyOperatorBaseModel(ABC):
+    """The base class for the anomaly detection operator models."""
+
+    def __init__(self, config: AnomalyOperatorConfig, datasets: AnomalyDatasets):
+        """Instantiates the AnomalyOperatorBaseModel instance.
+
+        Properties
+        ----------
+        config: AnomalyOperatorConfig
+            The anomaly detection operator configuration.
+        """
+
+        self.config: AnomalyOperatorConfig = config
+        self.spec: AnomalyOperatorSpec = config.spec
+        self.datasets = datasets
+        if self.spec.validation_data is not None:
+            self.X_valid_dict = self.datasets.valid_data.X_valid_dict
+            self.y_valid_dict = self.datasets.valid_data.y_valid_dict
+        else:
+            self.X_valid_dict = None
+            self.y_valid_dict = None
+
+    def generate_report(self):
+        """Generates the report."""
+        import datapane as dp
+        import matplotlib.pyplot as plt
+
+        start_time = time.time()
+        # fallback using sklearn oneclasssvm when the sub model _build_model fails
+        try:
+            anomaly_output = self._build_model()
+        except Exception as e:
+            anomaly_output = self._fallback_build_model()
+
+        elapsed_time = time.time() - start_time
+
+        summary_metrics = None
+        total_metrics = None
+        test_data = None
+
+        if self.spec.test_data:
+            test_data = TestData(self.spec)
+            total_metrics, summary_metrics = self._test_data_evaluate_metrics(
+                anomaly_output, test_data, elapsed_time
+            )
+        table_blocks = [
+            dp.DataTable(df, label=col)
+            for col, df in self.datasets.full_data_dict.items()
+        ]
+        data_table = (
+            dp.Select(blocks=table_blocks) if len(table_blocks) > 1 else table_blocks[0]
+        )
+        date_column = self.spec.datetime_column.name
+
+        blocks = []
+        for target, df in self.datasets.full_data_dict.items():
+            figure_blocks = []
+            time_col = df[date_column].reset_index(drop=True)
+            anomaly_col = anomaly_output.get_anomalies_by_cat(category=target)[
+                OutputColumns.ANOMALY_COL
+            ]
+            columns = set(df.columns).difference({date_column})
+            for col in columns:
+                y = df[col].reset_index(drop=True)
+                fig, ax = plt.subplots(figsize=(8, 3), layout="constrained")
+                ax.grid()
+                ax.plot(time_col, y, color="black")
+                for i, index in enumerate(anomaly_col):
+                    if anomaly_col[i] == 1:
+                        ax.scatter(time_col[i], y[i], color="red", marker="o")
+                plt.xlabel(date_column)
+                plt.ylabel(col)
+                plt.title(f"`{col}` with reference to anomalies")
+                figure_blocks.append(ax)
+            blocks.append(dp.Group(blocks=figure_blocks, label=target))
+        plots = dp.Select(blocks=blocks) if len(blocks) > 1 else blocks[0]
+
+        report_sections = []
+        title_text = dp.Text("# Anomaly Detection Report")
+
+        yaml_appendix_title = dp.Text(f"## Reference: YAML File")
+        yaml_appendix = dp.Code(code=self.config.to_yaml(), language="yaml")
+        summary = dp.Blocks(
+            blocks=[
+                dp.Group(
+                    dp.Text(f"You selected the **`{self.spec.model}`** model."),
+                    dp.Text(
+                        "Based on your dataset, you could have also selected "
+                        f"any of the models: `{'`, `'.join(SupportedModels.keys())}`."
+                    ),
+                    dp.BigNumber(
+                        heading="Analysis was completed in ",
+                        value=human_time_friendly(elapsed_time),
+                    ),
+                    label="Summary",
+                )
+            ]
+        )
+        sec_text = dp.Text(f"## Train Evaluation Metrics")
+        sec = dp.DataTable(self._evaluation_metrics(anomaly_output))
+        evaluation_metrics_sec = [sec_text, sec]
+
+        test_metrics_sections = []
+        if total_metrics is not None and not total_metrics.empty:
+            sec_text = dp.Text(f"## Test Data Evaluation Metrics")
+            sec = dp.DataTable(total_metrics)
+            test_metrics_sections = test_metrics_sections + [sec_text, sec]
+
+        if summary_metrics is not None and not summary_metrics.empty:
+            sec_text = dp.Text(f"## Test Data Summary Metrics")
+            sec = dp.DataTable(summary_metrics)
+            test_metrics_sections = test_metrics_sections + [sec_text, sec]
+
+        report_sections = (
+            [title_text, summary]
+            + [plots]
+            + [data_table]
+            + evaluation_metrics_sec
+            + test_metrics_sections
+            + [yaml_appendix_title, yaml_appendix]
+        )
+
+        # save the report and result CSV
+        self._save_report(
+            report_sections=report_sections,
+            anomaly_output=anomaly_output,
+            test_metrics=total_metrics,
+        )
+
+    def _evaluation_metrics(self, anomaly_output):
+        total_metrics = pd.DataFrame()
+        for cat in anomaly_output.list_categories():
+            num_anomalies = anomaly_output.get_num_anomalies_by_cat(cat)
+            metrics_df = pd.DataFrame.from_dict(
+                {"Num of Anomalies": num_anomalies}, orient="index", columns=[cat]
+            )
+            total_metrics = pd.concat([total_metrics, metrics_df], axis=1)
+        return total_metrics
+
+    def _test_data_evaluate_metrics(self, anomaly_output, test_data, elapsed_time):
+        total_metrics = pd.DataFrame()
+        summary_metrics = pd.DataFrame()
+
+        for cat in anomaly_output.list_categories():
+            output = anomaly_output.category_map[cat][0]
+            date_col = self.spec.datetime_column.name
+
+            test_data_i = test_data.get_data_for_series(cat)
+
+            dates = output[output[date_col].isin(test_data_i[date_col])][date_col]
+
+            metrics_df = _build_metrics_df(
+                test_data_i[test_data_i[date_col].isin(dates)][
+                    OutputColumns.ANOMALY_COL
+                ].values,
+                output[output[date_col].isin(dates)][OutputColumns.ANOMALY_COL].values,
+                cat,
+            )
+            total_metrics = pd.concat([total_metrics, metrics_df], axis=1)
+
+        if total_metrics.empty:
+            return total_metrics, summary_metrics
+
+        summary_metrics = pd.DataFrame(
+            {
+                SupportedMetrics.MEAN_RECALL: np.mean(
+                    total_metrics.loc[SupportedMetrics.RECALL]
+                ),
+                SupportedMetrics.MEDIAN_RECALL: np.median(
+                    total_metrics.loc[SupportedMetrics.RECALL]
+                ),
+                SupportedMetrics.MEAN_PRECISION: np.mean(
+                    total_metrics.loc[SupportedMetrics.PRECISION]
+                ),
+                SupportedMetrics.MEDIAN_PRECISION: np.median(
+                    total_metrics.loc[SupportedMetrics.PRECISION]
+                ),
+                SupportedMetrics.MEAN_ACCURACY: np.mean(
+                    total_metrics.loc[SupportedMetrics.ACCURACY]
+                ),
+                SupportedMetrics.MEDIAN_ACCURACY: np.median(
+                    total_metrics.loc[SupportedMetrics.ACCURACY]
+                ),
+                SupportedMetrics.MEAN_F1_SCORE: np.mean(
+                    total_metrics.loc[SupportedMetrics.F1_SCORE]
+                ),
+                SupportedMetrics.MEDIAN_F1_SCORE: np.median(
+                    total_metrics.loc[SupportedMetrics.F1_SCORE]
+                ),
+                SupportedMetrics.MEAN_ROC_AUC: np.mean(
+                    total_metrics.loc[SupportedMetrics.ROC_AUC]
+                ),
+                SupportedMetrics.MEDIAN_ROC_AUC: np.median(
+                    total_metrics.loc[SupportedMetrics.ROC_AUC]
+                ),
+                SupportedMetrics.MEAN_PRC_AUC: np.mean(
+                    total_metrics.loc[SupportedMetrics.PRC_AUC]
+                ),
+                SupportedMetrics.MEDIAN_PRC_AUC: np.median(
+                    total_metrics.loc[SupportedMetrics.PRC_AUC]
+                ),
+                SupportedMetrics.ELAPSED_TIME: elapsed_time,
+            },
+            index=["All Targets"],
+        )
+
+        return total_metrics, summary_metrics
+
+    def _save_report(
+        self,
+        report_sections: Tuple,
+        anomaly_output: AnomalyOutput,
+        test_metrics: pd.DataFrame,
+    ):
+        """Saves resulting reports to the given folder."""
+        import datapane as dp
+
+        unique_output_dir = find_output_dirname(self.spec.output_directory)
+
+        if ObjectStorageDetails.is_oci_path(unique_output_dir):
+            storage_options = default_signer()
+        else:
+            storage_options = dict()
+
+        # datapane html report
+        with tempfile.TemporaryDirectory() as temp_dir:
+            report_local_path = os.path.join(temp_dir, "___report.html")
+            disable_print()
+            dp.save_report(report_sections, report_local_path)
+            enable_print()
+            with open(report_local_path) as f1:
+                with fsspec.open(
+                    os.path.join(unique_output_dir, self.spec.report_file_name),
+                    "w",
+                    **storage_options,
+                ) as f2:
+                    f2.write(f1.read())
+
+        if self.spec.generate_inliers:
+            inliers = anomaly_output.get_inliers(self.datasets.data)
+            write_data(
+                data=inliers,
+                filename=os.path.join(unique_output_dir, self.spec.inliers_filename),
+                format="csv",
+                storage_options=storage_options,
+            )
+
+        outliers = anomaly_output.get_outliers(self.datasets.data)
+        write_data(
+            data=outliers,
+            filename=os.path.join(unique_output_dir, self.spec.outliers_filename),
+            format="csv",
+            storage_options=storage_options,
+        )
+
+        if test_metrics is not None and not test_metrics.empty:
+            write_data(
+                data=test_metrics.rename_axis("metrics").reset_index(),
+                filename=os.path.join(
+                    unique_output_dir, self.spec.test_metrics_filename
+                ),
+                format="csv",
+                storage_options=storage_options,
+            )
+
+        logger.warn(
+            f"The report has been successfully "
+            f"generated and placed to the: {unique_output_dir}."
+        )
+
+    def _fallback_build_model(self):
+        """
+        Fallback method for the sub model _build_model method.
+        """
+        logger.warn(
+            "The build_model method has failed for the model: {}. "
+            "A fallback model will be built.".format(self.spec.model)
+        )
+
+        date_column = self.spec.datetime_column.name
+        dataset = self.datasets
+
+        anomaly_output = AnomalyOutput(date_column=date_column)
+
+        # map the output as per anomaly dataset class, 1: outlier, 0: inlier
+        self.outlier_map = {1: 0, -1: 1}
+
+        # Iterate over the full_data_dict items
+        for target, df in self.datasets.full_data_dict.items():
+            est = linear_model.SGDOneClassSVM(random_state=42)
+            est.fit(df[target].values.reshape(-1, 1))
+            y_pred = np.vectorize(self.outlier_map.get)(
+                est.predict(df[target].values.reshape(-1, 1))
+            )
+            scores = est.score_samples(df[target].values.reshape(-1, 1))
+
+            anomaly = pd.DataFrame(
+                {date_column: df[date_column], OutputColumns.ANOMALY_COL: y_pred}
+            ).reset_index(drop=True)
+            score = pd.DataFrame(
+                {date_column: df[date_column], OutputColumns.SCORE_COL: scores}
+            ).reset_index(drop=True)
+            anomaly_output.add_output(target, anomaly, score)
+
+        return anomaly_output
+
+    @abstractmethod
+    def _generate_report(self):
+        """
+        Generates the report for the particular model.
+        The method that needs to be implemented on the particular model level.
+        """
+
+    @abstractmethod
+    def _build_model(self) -> pd.DataFrame:
+        """
+        Build the model.
+        The method that needs to be implemented on the particular model level.
+        """

ads/opctl/operator/lowcode/anomaly/model/factory.py

@@ -0,0 +1,67 @@
+#!/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 ..const import SupportedModels
+from ..operator_config import AnomalyOperatorConfig
+from .automlx import AutoMLXOperatorModel
+from .autots import AutoTSOperatorModel
+from ads.opctl.operator.lowcode.anomaly.utils import select_auto_model
+
+# from .tods import TODSOperatorModel
+from .base_model import AnomalyOperatorBaseModel
+from .anomaly_dataset import AnomalyDatasets
+
+
+class UnSupportedModelError(Exception):
+    def __init__(self, model_type: str):
+        super().__init__(
+            f"Model: `{model_type}` "
+            f"is not supported. Supported models: {SupportedModels.values}"
+        )
+
+
+class AnomalyOperatorModelFactory:
+    """
+    The factory class helps to instantiate proper model operator based on the model type.
+    """
+
+    _MAP = {
+        SupportedModels.AutoMLX: AutoMLXOperatorModel,
+        # SupportedModels.TODS: TODSOperatorModel,
+        SupportedModels.AutoTS: AutoTSOperatorModel,
+    }
+
+    @classmethod
+    def get_model(
+        cls, operator_config: AnomalyOperatorConfig, datasets: AnomalyDatasets
+    ) -> AnomalyOperatorBaseModel:
+        """
+        Gets the operator model based on the model type.
+
+        Parameters
+        ----------
+        operator_config: AnomalyOperatorConfig
+            The anomaly detection operator config.
+
+        datasets: AnomalyDatasets
+            Datasets for finding anomaly
+
+        Returns
+        -------
+        AnomalyOperatorBaseModel
+            The anomaly detection operator model.
+
+        Raises
+        ------
+        UnSupportedModelError
+            In case of not supported model.
+        """
+        model_type = operator_config.spec.model
+        if model_type == "auto":
+            model_type = select_auto_model(datasets, operator_config)
+        if model_type not in cls._MAP:
+            raise UnSupportedModelError(model_type)
+        return cls._MAP[model_type](config=operator_config, datasets=datasets)

ads/opctl/operator/lowcode/anomaly/model/tods.py

@@ -0,0 +1,119 @@
+# #!/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 importlib
+
+# import numpy as np
+# import pandas as pd
+
+# from ads.common.decorator.runtime_dependency import runtime_dependency
+# from .anomaly_dataset import AnomalyOutput
+
+# from ..const import (
+#     TODS_IMPORT_MODEL_MAP,
+#     TODS_MODEL_MAP,
+#     OutputColumns,
+#     TODS_DEFAULT_MODEL,
+# )
+# from .base_model import AnomalyOperatorBaseModel
+
+
+# class TODSOperatorModel(AnomalyOperatorBaseModel):
+#     """Class representing TODS Anomaly Detection operator model."""
+
+#     @runtime_dependency(
+#         module="tods",
+#         err_msg=(
+#             "Please run `pip3 install tods` to "
+#             "install the required dependencies for TODS."
+#         ),
+#     )
+#     def _build_model(self) -> pd.DataFrame:
+#         """
+#         Build the TODS model.
+
+#         Returns
+#         -------
+#             Tuple: model, predictions_train, and prediction_score_test
+#         """
+#         # Import the TODS module
+#         tods_module = importlib.import_module(
+#             name=TODS_IMPORT_MODEL_MAP.get(
+#                 self.spec.model_kwargs.get("sub_model", TODS_DEFAULT_MODEL)
+#             ),
+#             package="tods.sk_interface.detection_algorithm",
+#         )
+
+#         # Get the model kwargs
+#         model_kwargs = self.spec.model_kwargs
+#         sub_model = self.spec.model_kwargs.get("sub_model", TODS_DEFAULT_MODEL)
+#         model_kwargs.pop("sub_model", None)
+
+#         # Initialize variables
+#         models = {}
+#         predictions_train = {}
+#         prediction_score_train = {}
+#         predictions_test = {}
+#         prediction_score_test = {}
+#         date_column = self.spec.datetime_column.name
+#         anomaly_output = AnomalyOutput(date_column=date_column)
+
+#         # Iterate over the full_data_dict items
+#         for target, df in self.datasets.full_data_dict.items():
+#             # Instantiate the model
+#             model = getattr(tods_module, TODS_MODEL_MAP.get(sub_model))(**model_kwargs)
+
+#             # Fit the model
+#             model.fit(np.array(df[self.spec.target_column]).reshape(-1, 1))
+
+#             # Make predictions
+#             predictions_train[target] = model.predict(
+#                 np.array(df[self.spec.target_column]).reshape(-1, 1)
+#             )
+#             prediction_score_train[target] = model.predict_score(
+#                 np.array(df[self.spec.target_column]).reshape(-1, 1)
+#             )
+
+#             # Store the model and predictions in dictionaries
+#             models[target] = model
+
+#             anomaly = pd.DataFrame(
+#                 {
+#                     date_column: df[date_column],
+#                     OutputColumns.ANOMALY_COL: predictions_train[target],
+#                 }
+#             )
+#             score = pd.DataFrame(
+#                 {
+#                     date_column: df[date_column],
+#                     OutputColumns.SCORE_COL: prediction_score_train[target],
+#                 }
+#             )
+#             anomaly_output.add_output(target, anomaly, score)
+
+#         return anomaly_output
+
+#     def _generate_report(self):
+#         import datapane as dp
+
+#         """The method that needs to be implemented on the particular model level."""
+#         selected_models_text = dp.Text(
+#             f"## Selected Models Overview \n "
+#             "The following tables provide information regarding the chosen model."
+#         )
+#         all_sections = [selected_models_text]
+
+#         model_description = dp.Text(
+#             "The tods model is a full-stack automated machine learning system for outlier detection "
+#             "on univariate / multivariate time-series data. It provides exhaustive modules for building "
+#             "machine learning-based outlier detection systems and wide range of algorithms."
+#         )
+#         other_sections = all_sections
+
+#         return (
+#             model_description,
+#             other_sections,
+#         )

ads/opctl/operator/lowcode/anomaly/operator_config.py

@@ -0,0 +1,105 @@
+#!/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 os
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+from ads.common.serializer import DataClassSerializable
+from ads.opctl.operator.common.utils import _load_yaml_from_uri
+from ads.opctl.operator.common.operator_config import (
+    OperatorConfig,
+    OutputDirectory,
+    InputData,
+)
+from .const import SupportedModels
+
+
+@dataclass(repr=True)
+class ValidationData(InputData):
+    """Class representing operator specification input data details."""
+
+
+@dataclass(repr=True)
+class DateTimeColumn(DataClassSerializable):
+    """Class representing operator specification date time column details."""
+
+    name: str = None
+    format: str = None
+
+
+@dataclass(repr=True)
+class TestData(InputData):
+    """Class representing operator specification test data details."""
+
+
+@dataclass(repr=True)
+class AnomalyOperatorSpec(DataClassSerializable):
+    """Class representing operator specification."""
+
+    input_data: InputData = field(default_factory=InputData)
+    datetime_column: DateTimeColumn = field(default_factory=DateTimeColumn)
+    test_data: TestData = field(default_factory=TestData)
+    validation_data: ValidationData = field(default_factory=ValidationData)
+    output_directory: OutputDirectory = field(default_factory=OutputDirectory)
+    report_file_name: str = None
+    report_title: str = None
+    report_theme: str = None
+    metrics_filename: str = None
+    test_metrics_filename: str = None
+    inliers_filename: str = None
+    outliers_filename: str = None
+    target_column: str = None
+    target_category_columns: List[str] = field(default_factory=list)
+    preprocessing: bool = None
+    generate_report: bool = None
+    generate_metrics: bool = None
+    generate_inliers: bool = None
+    model: str = None
+    model_kwargs: Dict = field(default_factory=dict)
+    contamination: float = None
+
+    def __post_init__(self):
+        """Adjusts the specification details."""
+        self.report_file_name = self.report_file_name or "report.html"
+        self.report_theme = self.report_theme or "light"
+        self.inliers_filename = self.inliers_filename or "inliers.csv"
+        self.outliers_filename = self.outliers_filename or "outliers.csv"
+        self.test_metrics_filename = self.test_metrics_filename or "metrics.csv"
+        self.model = self.model or SupportedModels.Auto
+        self.generate_inliers = (
+            self.generate_inliers if self.generate_inliers is not None else False
+        )
+        self.model_kwargs = self.model_kwargs or dict()
+
+
+@dataclass(repr=True)
+class AnomalyOperatorConfig(OperatorConfig):
+    """Class representing operator config.
+
+    Attributes
+    ----------
+    kind: str
+        The kind of the resource. For operators it is always - `operator`.
+    type: str
+        The type of the operator.
+    version: str
+        The version of the operator.
+    spec: AnomalyOperatorSpec
+        The operator specification.
+    """
+
+    kind: str = "operator"
+    type: str = "anomaly"
+    version: str = "v1"
+    spec: AnomalyOperatorSpec = field(default_factory=AnomalyOperatorSpec)
+
+    @classmethod
+    def _load_schema(cls) -> str:
+        """Loads operator schema."""
+        return _load_yaml_from_uri(
+            os.path.join(os.path.dirname(os.path.abspath(__file__)), "schema.yaml")
+        )