oracle-ads 2.12.8__py3-none-any.whl → 2.12.10__py3-none-any.whl

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

@@ -28,6 +28,7 @@ from ads.opctl.operator.lowcode.common.utils import (
     seconds_to_datetime,
     write_data,
 )
+from ads.opctl.operator.lowcode.common.const import DataColumns
 from ads.opctl.operator.lowcode.forecast.model.forecast_datasets import TestData
 from ads.opctl.operator.lowcode.forecast.utils import (
     _build_metrics_df,
@@ -43,10 +44,12 @@ from ads.opctl.operator.lowcode.forecast.utils import (
 
 from ..const import (
     AUTO_SELECT,
+    BACKTEST_REPORT_NAME,
     SUMMARY_METRICS_HORIZON_LIMIT,
     SpeedAccuracyMode,
     SupportedMetrics,
     SupportedModels,
+    BACKTEST_REPORT_NAME,
 )
 from ..operator_config import ForecastOperatorConfig, ForecastOperatorSpec
 from .forecast_datasets import ForecastDatasets
@@ -68,7 +71,7 @@ class ForecastOperatorBaseModel(ABC):
         self.config: ForecastOperatorConfig = config
         self.spec: ForecastOperatorSpec = config.spec
         self.datasets: ForecastDatasets = datasets
-
+        self.target_cat_col = self.spec.target_category_columns
         self.full_data_dict = datasets.get_data_by_series()
 
         self.test_eval_metrics = None
@@ -123,6 +126,9 @@ class ForecastOperatorBaseModel(ABC):
 
             if self.spec.generate_report or self.spec.generate_metrics:
                 self.eval_metrics = self.generate_train_metrics()
+                if not self.target_cat_col:
+                    self.eval_metrics.rename({"Series 1": self.original_target_column},
+                                             axis=1, inplace=True)
 
                 if self.spec.test_data:
                     try:
@@ -133,6 +139,9 @@ class ForecastOperatorBaseModel(ABC):
                         ) = self._test_evaluate_metrics(
                             elapsed_time=elapsed_time,
                         )
+                        if not self.target_cat_col:
+                            self.test_eval_metrics.rename({"Series 1": self.original_target_column},
+                                                     axis=1, inplace=True)
                     except Exception:
                         logger.warn("Unable to generate Test Metrics.")
                         logger.debug(f"Full Traceback: {traceback.format_exc()}")
@@ -178,7 +187,7 @@ class ForecastOperatorBaseModel(ABC):
                 first_5_rows_blocks = [
                     rc.DataTable(
                         df.head(5),
-                        label=s_id,
+                        label=s_id if self.target_cat_col else None,
                         index=True,
                     )
                     for s_id, df in self.full_data_dict.items()
@@ -187,7 +196,7 @@ class ForecastOperatorBaseModel(ABC):
                 last_5_rows_blocks = [
                     rc.DataTable(
                         df.tail(5),
-                        label=s_id,
+                        label=s_id if self.target_cat_col else None,
                         index=True,
                     )
                     for s_id, df in self.full_data_dict.items()
@@ -196,7 +205,7 @@ class ForecastOperatorBaseModel(ABC):
                 data_summary_blocks = [
                     rc.DataTable(
                         df.describe(),
-                        label=s_id,
+                        label=s_id if self.target_cat_col else None,
                         index=True,
                     )
                     for s_id, df in self.full_data_dict.items()
@@ -214,17 +223,17 @@ class ForecastOperatorBaseModel(ABC):
                     rc.Block(
                         first_10_title,
                         # series_subtext,
-                        rc.Select(blocks=first_5_rows_blocks),
+                        rc.Select(blocks=first_5_rows_blocks) if self.target_cat_col else first_5_rows_blocks[0],
                     ),
                     rc.Block(
                         last_10_title,
                         # series_subtext,
-                        rc.Select(blocks=last_5_rows_blocks),
+                        rc.Select(blocks=last_5_rows_blocks) if self.target_cat_col else last_5_rows_blocks[0],
                     ),
                     rc.Block(
                         summary_title,
                         # series_subtext,
-                        rc.Select(blocks=data_summary_blocks),
+                        rc.Select(blocks=data_summary_blocks) if self.target_cat_col else data_summary_blocks[0],
                     ),
                     rc.Separator(),
                 )
@@ -256,11 +265,12 @@ class ForecastOperatorBaseModel(ABC):
 
                 backtest_sections = []
                 output_dir = self.spec.output_directory.url
-                backtest_report_name = "backtest_stats.csv"
-                file_path = f"{output_dir}/{backtest_report_name}"
+                file_path = f"{output_dir}/{BACKTEST_REPORT_NAME}"
                 if self.spec.model == AUTO_SELECT:
                     backtest_sections.append(
-                        rc.Heading("Auto-select statistics", level=2)
+                        rc.Heading(
+                            "Auto-Select Backtesting and Performance Metrics", level=2
+                        )
                     )
                     if not os.path.exists(file_path):
                         failure_msg = rc.Text(
@@ -270,18 +280,22 @@ class ForecastOperatorBaseModel(ABC):
                         backtest_sections.append(failure_msg)
                     else:
                         backtest_stats = pd.read_csv(file_path)
-                        average_dict = backtest_stats.mean().to_dict()
-                        del average_dict["backtest"]
+                        model_metric_map = backtest_stats.drop(
+                            columns=["metric", "backtest"]
+                        )
+                        average_dict = {
+                            k: round(v, 4)
+                            for k, v in model_metric_map.mean().to_dict().items()
+                        }
                         best_model = min(average_dict, key=average_dict.get)
-                        backtest_text = rc.Heading("Back Testing Metrics", level=3)
                         summary_text = rc.Text(
-                            f"Overall, the average scores for the models are {average_dict}, with {best_model}"
-                            f" being identified as the top-performing model during backtesting."
+                            f"Overall, the average {self.spec.metric} scores for the models are {average_dict}, with"
+                            f" {best_model} being identified as the top-performing model during backtesting."
                         )
                         backtest_table = rc.DataTable(backtest_stats, index=True)
                         liner_plot = get_auto_select_plot(backtest_stats)
                         backtest_sections.extend(
-                            [backtest_text, backtest_table, summary_text, liner_plot]
+                            [backtest_table, summary_text, liner_plot]
                         )
 
                 forecast_plots = []
@@ -294,6 +308,7 @@ class ForecastOperatorBaseModel(ABC):
                         horizon=self.spec.horizon,
                         test_data=test_data,
                         ci_interval_width=self.spec.confidence_interval_width,
+                        target_category_column=self.target_cat_col
                     )
                     if (
                         series_name is not None
@@ -307,7 +322,14 @@ class ForecastOperatorBaseModel(ABC):
                         forecast_plots = [forecast_text, forecast_sec]
 
                 yaml_appendix_title = rc.Heading("Reference: YAML File", level=2)
-                yaml_appendix = rc.Yaml(self.config.to_dict())
+                config_dict = self.config.to_dict()
+                # pop the data incase it isn't json serializable
+                config_dict["spec"]["historical_data"].pop("data")
+                if config_dict["spec"].get("additional_data"):
+                    config_dict["spec"]["additional_data"].pop("data")
+                if config_dict["spec"].get("test_data"):
+                    config_dict["spec"]["test_data"].pop("data")
+                yaml_appendix = rc.Yaml(config_dict)
                 report_sections = (
                     [summary]
                     + backtest_sections
@@ -469,6 +491,7 @@ class ForecastOperatorBaseModel(ABC):
                         f2.write(f1.read())
 
         # forecast csv report
+        result_df = result_df if self.target_cat_col else result_df.drop(DataColumns.Series, axis=1)
         write_data(
             data=result_df,
             filename=os.path.join(unique_output_dir, self.spec.forecast_filename),
@@ -643,6 +666,13 @@ class ForecastOperatorBaseModel(ABC):
             storage_options=storage_options,
         )
 
+    def _validate_automlx_explanation_mode(self):
+        if self.spec.model != SupportedModels.AutoMLX and self.spec.explanations_accuracy_mode == SpeedAccuracyMode.AUTOMLX:
+            raise ValueError(
+                "AUTOMLX explanation accuracy mode is only supported for AutoMLX models. "
+                "Please select mode other than AUTOMLX from the available explanations_accuracy_mode options"
+            )
+
     @runtime_dependency(
         module="shap",
         err_msg=(
@@ -671,6 +701,9 @@ class ForecastOperatorBaseModel(ABC):
         )
         ratio = SpeedAccuracyMode.ratio[self.spec.explanations_accuracy_mode]
 
+        # validate the automlx mode is use for automlx model
+        self._validate_automlx_explanation_mode()
+
         for s_id, data_i in self.datasets.get_data_by_series(
             include_horizon=False
         ).items():
@@ -705,6 +738,14 @@ class ForecastOperatorBaseModel(ABC):
                     logger.warn(
                         "No explanations generated. Ensure that additional data has been provided."
                     )
+                elif (
+                    self.spec.model == SupportedModels.AutoMLX
+                    and self.spec.explanations_accuracy_mode
+                    == SpeedAccuracyMode.AUTOMLX
+                ):
+                    logger.warning(
+                        "Global explanations not available for AutoMLX models with inherent explainability"
+                    )
                 else:
                     self.global_explanation[s_id] = dict(
                         zip(

ads/opctl/operator/lowcode/forecast/model/forecast_datasets.py

@@ -167,7 +167,7 @@ class ForecastDatasets:
                 self.historical_data.data,
                 self.additional_data.data,
             ],
-            axis=1,
+            axis=1
         )
 
     def get_data_by_series(self, include_horizon=True):

ads/opctl/operator/lowcode/forecast/model/neuralprophet.py

@@ -360,7 +360,7 @@ class NeuralProphetOperatorModel(ForecastOperatorBaseModel):
                     pd.Series(
                         m.state_dict(),
                         index=m.state_dict().keys(),
-                        name=s_id,
+                        name=s_id if self.target_cat_col else self.original_target_column,
                     )
                 )
             all_model_states = pd.concat(model_states, axis=1)
@@ -373,6 +373,13 @@ class NeuralProphetOperatorModel(ForecastOperatorBaseModel):
                 # If the key is present, call the "explain_model" method
                 self.explain_model()
 
+                if not self.target_cat_col:
+                    self.formatted_global_explanation = self.formatted_global_explanation.rename(
+                        {"Series 1": self.original_target_column},
+                        axis=1,
+                    )
+                    self.formatted_local_explanation.drop("Series", axis=1, inplace=True)
+
                 # Create a markdown section for the global explainability
                 global_explanation_section = rc.Block(
                     rc.Heading("Global Explainability", level=2),
@@ -385,14 +392,14 @@ class NeuralProphetOperatorModel(ForecastOperatorBaseModel):
                 blocks = [
                     rc.DataTable(
                         local_ex_df.drop("Series", axis=1),
-                        label=s_id,
+                        label=s_id if self.target_cat_col else None,
                         index=True,
                     )
                     for s_id, local_ex_df in self.local_explanation.items()
                 ]
                 local_explanation_section = rc.Block(
                     rc.Heading("Local Explanation of Models", level=2),
-                    rc.Select(blocks=blocks),
+                    rc.Select(blocks=blocks) if len(blocks) > 1 else blocks[0],
                 )
 
                 # Append the global explanation text and section to the "all_sections" list

ads/opctl/operator/lowcode/forecast/model/prophet.py

@@ -256,6 +256,7 @@ class ProphetOperatorModel(ForecastOperatorBaseModel):
                     self.outputs[s_id], include_legend=True
                 ),
                 series_ids=series_ids,
+                target_category_column=self.target_cat_col
             )
             section_1 = rc.Block(
                 rc.Heading("Forecast Overview", level=2),
@@ -268,6 +269,7 @@ class ProphetOperatorModel(ForecastOperatorBaseModel):
             sec2 = _select_plot_list(
                 lambda s_id: self.models[s_id].plot_components(self.outputs[s_id]),
                 series_ids=series_ids,
+                target_category_column=self.target_cat_col
             )
             section_2 = rc.Block(
                 rc.Heading("Forecast Broken Down by Trend Component", level=2), sec2
@@ -281,7 +283,9 @@ class ProphetOperatorModel(ForecastOperatorBaseModel):
                     sec3_figs[s_id].gca(), self.models[s_id], self.outputs[s_id]
                 )
             sec3 = _select_plot_list(
-                lambda s_id: sec3_figs[s_id], series_ids=series_ids
+                lambda s_id: sec3_figs[s_id],
+                series_ids=series_ids,
+                target_category_column=self.target_cat_col
             )
             section_3 = rc.Block(rc.Heading("Forecast Changepoints", level=2), sec3)
 
@@ -295,7 +299,7 @@ class ProphetOperatorModel(ForecastOperatorBaseModel):
                     pd.Series(
                         m.seasonalities,
                         index=pd.Index(m.seasonalities.keys(), dtype="object"),
-                        name=s_id,
+                        name=s_id if self.target_cat_col else self.original_target_column,
                         dtype="object",
                     )
                 )
@@ -316,15 +320,6 @@ class ProphetOperatorModel(ForecastOperatorBaseModel):
                     global_explanation_df / global_explanation_df.sum(axis=0) * 100
                 )
 
-                # Create a markdown section for the global explainability
-                global_explanation_section = rc.Block(
-                    rc.Heading("Global Explanation of Models", level=2),
-                    rc.Text(
-                        "The following tables provide the feature attribution for the global explainability."
-                    ),
-                    rc.DataTable(self.formatted_global_explanation, index=True),
-                )
-
                 aggregate_local_explanations = pd.DataFrame()
                 for s_id, local_ex_df in self.local_explanation.items():
                     local_ex_df_copy = local_ex_df.copy()
@@ -334,17 +329,33 @@ class ProphetOperatorModel(ForecastOperatorBaseModel):
                     )
                 self.formatted_local_explanation = aggregate_local_explanations
 
+                if not self.target_cat_col:
+                    self.formatted_global_explanation = self.formatted_global_explanation.rename(
+                        {"Series 1": self.original_target_column},
+                        axis=1,
+                    )
+                    self.formatted_local_explanation.drop("Series", axis=1, inplace=True)
+
+                # Create a markdown section for the global explainability
+                global_explanation_section = rc.Block(
+                    rc.Heading("Global Explanation of Models", level=2),
+                    rc.Text(
+                        "The following tables provide the feature attribution for the global explainability."
+                    ),
+                    rc.DataTable(self.formatted_global_explanation, index=True),
+                )
+
                 blocks = [
                     rc.DataTable(
                         local_ex_df.div(local_ex_df.abs().sum(axis=1), axis=0) * 100,
-                        label=s_id,
+                        label=s_id if self.target_cat_col else None,
                         index=True,
                     )
                     for s_id, local_ex_df in self.local_explanation.items()
                 ]
                 local_explanation_section = rc.Block(
                     rc.Heading("Local Explanation of Models", level=2),
-                    rc.Select(blocks=blocks),
+                    rc.Select(blocks=blocks) if len(blocks) > 1 else blocks[0],
                 )
 
                 # Append the global explanation text and section to the "all_sections" list
@@ -358,11 +369,7 @@ class ProphetOperatorModel(ForecastOperatorBaseModel):
                 logger.debug(f"Full Traceback: {traceback.format_exc()}")
 
         model_description = rc.Text(
-            "Prophet is a procedure for forecasting time series data based on an additive "
-            "model where non-linear trends are fit with yearly, weekly, and daily seasonality, "
-            "plus holiday effects. It works best with time series that have strong seasonal "
-            "effects and several seasons of historical data. Prophet is robust to missing "
-            "data and shifts in the trend, and typically handles outliers well."
+            """Prophet is a procedure for forecasting time series data based on an additive model where non-linear trends are fit with yearly, weekly, and daily seasonality, plus holiday effects. It works best with time series that have strong seasonal effects and several seasons of historical data. Prophet is robust to missing data and shifts in the trend, and typically handles outliers well."""
         )
         other_sections = all_sections
 

ads/opctl/operator/lowcode/forecast/model_evaluator.py

@@ -10,6 +10,7 @@ from pathlib import Path
 
 from ads.opctl import logger
 from ads.opctl.operator.lowcode.common.const import DataColumns
+from ads.opctl.operator.lowcode.forecast.const import BACKTEST_REPORT_NAME
 from .model.forecast_datasets import ForecastDatasets
 from .operator_config import ForecastOperatorConfig
 from ads.opctl.operator.lowcode.forecast.model.factory import SupportedModels
@@ -156,8 +157,8 @@ class ModelEvaluator:
         best_model = min(avg_backtests_metric, key=avg_backtests_metric.get)
         logger.info(f"Among models {self.models}, {best_model} model shows better performance during backtesting.")
         backtest_stats = pd.DataFrame(nonempty_metrics).rename_axis('backtest')
+        backtest_stats["metric"] = operator_config.spec.metric
         backtest_stats.reset_index(inplace=True)
         output_dir = operator_config.spec.output_directory.url
-        backtest_report_name = "backtest_stats.csv"
-        backtest_stats.to_csv(f"{output_dir}/{backtest_report_name}", index=False)
+        backtest_stats.to_csv(f"{output_dir}/{BACKTEST_REPORT_NAME}", index=False)
         return best_model

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

@@ -18,6 +18,35 @@ from ads.opctl.operator.lowcode.common.utils import find_output_dirname
 
 from .const import SpeedAccuracyMode, SupportedMetrics, SupportedModels
 
+@dataclass
+class AutoScaling(DataClassSerializable):
+    """Class representing simple autoscaling policy"""
+    minimum_instance: int = 1
+    maximum_instance: int = None
+    cool_down_in_seconds: int = 600
+    scale_in_threshold: int = 10
+    scale_out_threshold: int = 80
+    scaling_metric: str = "CPU_UTILIZATION"
+
+@dataclass(repr=True)
+class ModelDeploymentServer(DataClassSerializable):
+    """Class representing model deployment server specification for whatif-analysis."""
+    display_name: str = None
+    initial_shape: str = None
+    description: str = None
+    log_group: str = None
+    log_id: str = None
+    auto_scaling: AutoScaling = field(default_factory=AutoScaling)
+
+
+@dataclass(repr=True)
+class WhatIfAnalysis(DataClassSerializable):
+    """Class representing operator specification for whatif-analysis."""
+    model_display_name: str = None
+    compartment_id: str = None
+    project_id: str = None
+    model_deployment: ModelDeploymentServer = field(default_factory=ModelDeploymentServer)
+
 
 @dataclass(repr=True)
 class TestData(InputData):
@@ -90,12 +119,14 @@ class ForecastOperatorSpec(DataClassSerializable):
     confidence_interval_width: float = None
     metric: str = None
     tuning: Tuning = field(default_factory=Tuning)
+    what_if_analysis: WhatIfAnalysis = field(default_factory=WhatIfAnalysis)
 
     def __post_init__(self):
         """Adjusts the specification details."""
         self.output_directory = self.output_directory or OutputDirectory(
             url=find_output_dirname(self.output_directory)
         )
+        self.generate_model_pickle = True if self.generate_model_pickle or self.what_if_analysis else False
         self.metric = (self.metric or "").lower() or SupportedMetrics.SMAPE.lower()
         self.model = self.model or SupportedModels.Prophet
         self.confidence_interval_width = self.confidence_interval_width or 0.80

ads/opctl/operator/lowcode/forecast/schema.yaml

@@ -37,6 +37,9 @@ spec:
           nullable: true
           required: false
           type: dict
+        data:
+          nullable: true
+          required: false
         format:
           allowed:
             - csv
@@ -48,6 +51,7 @@ spec:
             - sql_query
             - hdf
             - tsv
+            - pandas
           required: false
           type: string
         columns:
@@ -92,6 +96,9 @@ spec:
           nullable: true
           required: false
           type: dict
+        data:
+          nullable: true
+          required: false
         format:
           allowed:
             - csv
@@ -103,6 +110,7 @@ spec:
             - sql_query
             - hdf
             - tsv
+            - pandas
           required: false
           type: string
         columns:
@@ -146,6 +154,9 @@ spec:
           nullable: true
           required: false
           type: dict
+        data:
+          nullable: true
+          required: false
         format:
           allowed:
             - csv
@@ -157,6 +168,7 @@ spec:
             - sql_query
             - hdf
             - tsv
+            - pandas
           required: false
           type: string
         columns:
@@ -332,6 +344,7 @@ spec:
         - HIGH_ACCURACY
         - BALANCED
         - FAST_APPROXIMATE
+        - AUTOMLX
 
     generate_report:
       type: boolean
@@ -340,6 +353,69 @@ spec:
       meta:
         description: "Report file generation can be enabled using this flag. Defaults to true."
 
+    what_if_analysis:
+      type: dict
+      required: false
+      schema:
+        model_deployment:
+          type: dict
+          required: false
+          meta: "If model_deployment id is not specified, a new model deployment is created; otherwise, the model is linked to the specified model deployment."
+          schema:
+            id:
+              type: string
+              required: false
+            display_name:
+              type: string
+              required: false
+            initial_shape:
+              type: string
+              required: false
+            description:
+              type: string
+              required: false
+            log_group:
+              type: string
+              required: true
+            log_id:
+              type: string
+              required: true
+            auto_scaling:
+              type: dict
+              required: false
+              schema:
+                minimum_instance:
+                  type: integer
+                  required: true
+                maximum_instance:
+                  type: integer
+                  required: true
+                scale_in_threshold:
+                  type: integer
+                  required: true
+                scale_out_threshold:
+                  type: integer
+                  required: true
+                scaling_metric:
+                  type: string
+                  required: true
+                cool_down_in_seconds:
+                  type: integer
+                  required: true
+        model_display_name:
+          type: string
+          required: true
+        project_id:
+          type: string
+          required: false
+          meta: "If not provided, The project OCID from config.PROJECT_OCID is used"
+        compartment_id:
+          type: string
+          required: false
+          meta: "If not provided, The compartment OCID from config.NB_SESSION_COMPARTMENT_OCID is used."
+      meta:
+        description: "When enabled, the models are saved to the model catalog. Defaults to false."
+
     generate_metrics:
       type: boolean
       required: false

ads/opctl/operator/lowcode/forecast/utils.py

@@ -250,8 +250,8 @@ def evaluate_train_metrics(output):
     return total_metrics
 
 
-def _select_plot_list(fn, series_ids):
-    blocks = [rc.Widget(fn(s_id=s_id), label=s_id) for s_id in series_ids]
+def _select_plot_list(fn, series_ids, target_category_column):
+    blocks = [rc.Widget(fn(s_id=s_id), label=s_id if target_category_column else None) for s_id in series_ids]
     return rc.Select(blocks=blocks) if len(blocks) > 1 else blocks[0]
 
 
@@ -261,10 +261,11 @@ def _add_unit(num, unit):
 
 def get_auto_select_plot(backtest_results):
     fig = go.Figure()
-    columns = backtest_results.columns.tolist()
+    back_test_csv_columns = backtest_results.columns.tolist()
     back_test_column = "backtest"
-    columns.remove(back_test_column)
-    for column in columns:
+    metric_column = "metric"
+    models = [x for x in back_test_csv_columns if x not in [back_test_column, metric_column]]
+    for i, column in enumerate(models):
         fig.add_trace(
             go.Scatter(
                 x=backtest_results[back_test_column],
@@ -282,6 +283,7 @@ def get_forecast_plots(
     horizon,
     test_data=None,
     ci_interval_width=0.95,
+    target_category_column=None
 ):
     def plot_forecast_plotly(s_id):
         fig = go.Figure()
@@ -378,7 +380,7 @@ def get_forecast_plots(
         )
         return fig
 
-    return _select_plot_list(plot_forecast_plotly, forecast_output.list_series_ids())
+    return _select_plot_list(plot_forecast_plotly, forecast_output.list_series_ids(), target_category_column)
 
 
 def convert_target(target: str, target_col: str):

ads/opctl/operator/lowcode/forecast/whatifserve/__init__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python
+
+# Copyright (c) 2023, 2024 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+
+from .deployment_manager import ModelDeploymentManager