pulling in docs changes

Author: ahosler

docs/source/index.rst

@@ -20,15 +20,15 @@ Oracle Accelerated Data Science (ADS)
 .. toctree::
    :hidden:
    :maxdepth: 5
-   :caption: Getting Started:
+   :caption: Getting Started
 
    release_notes
    user_guide/quick_start/quick_start
 
 .. toctree::
    :hidden:
    :maxdepth: 5
-   :caption: Installation and Configuration:
+   :caption: Installation and Configuration
 
    user_guide/cli/quickstart
    user_guide/cli/authentication
@@ -38,19 +38,19 @@ Oracle Accelerated Data Science (ADS)
 .. toctree::
    :hidden:
    :maxdepth: 5
-   :caption: Low-Code AI Operators:
+   :caption: Low-Code AI Operators
 
    user_guide/operators/index
-   user_guide/operators/common/index
-   user_guide/operators/forecasting_operator/index
+   user_guide/operators/forecast_operator/index
    user_guide/operators/anomaly_detection_operator/index
    user_guide/operators/pii_operator/index
    user_guide/operators/recommender_operator/index
+   user_guide/operators/common/index
 
 .. toctree::
    :hidden:
    :maxdepth: 5
-   :caption: Tasks:
+   :caption: Tasks
 
    user_guide/loading_data/connect
    user_guide/data_labeling/index
@@ -62,7 +62,7 @@ Oracle Accelerated Data Science (ADS)
 .. toctree::
    :hidden:
    :maxdepth: 5
-   :caption: Integrations:
+   :caption: Integrations
 
    user_guide/apachespark/spark
    user_guide/big_data_service/index
@@ -76,7 +76,7 @@ Oracle Accelerated Data Science (ADS)
 .. toctree::
    :hidden:
    :maxdepth: 5
-   :caption: Classes:
+   :caption: Classes
 
    modules
 

docs/source/release_notes.rst

@@ -146,7 +146,7 @@ Release date: March 20, 2024
 Release date: February 7, 2024
 
 * Releasing v1 of the Anomaly Detection Operator! The Anomaly Detection Operator is a no-code Anomaly or Outlier Detection solution through the OCI Data Science Platform. It uses dozens of models from Oracle’s own proprietary research and the best of open source. See the ``Anomaly Detection`` Section of the ``AI Operators`` tab for full details (:doc:`link <./user_guide/operators/anomaly_detection_operator/index>`).
-* Releasing a new version of the Forecast Operator. This release has faster explainability, improved support for reading from databases, upgrades to the automatic reporting, improved parallelization across all models, and an ability to save models for deferred inference. See the ``Forecast`` Section of the ``AI Operators`` tab for full details (:doc:`link <./user_guide/operators/forecasting_operator/index>`).
+* Releasing a new version of the Forecast Operator. This release has faster explainability, improved support for reading from databases, upgrades to the automatic reporting, improved parallelization across all models, and an ability to save models for deferred inference. See the ``Forecast`` Section of the ``AI Operators`` tab for full details (:doc:`link <./user_guide/operators/forecast_operator/index>`).
 * Change to the default signer such that it now defaults to ``resource_prinicpal`` on any OCI Data Science resource (for example, jobs, notebooks, model deployments, dataflow).
 
 2.10.0

docs/source/user_guide/operators/common/index.rst

@@ -1,6 +1,6 @@
-===============
-Getting Started
-===============
+====================
+More About Operators
+====================
 
 Welcome to the world of operators! Getting started with operators is a breeze, and this section will guide you through the process step by step. Whether you're a seasoned data scientist or a newcomer, you'll find that harnessing the power of operators is both accessible and rewarding.
 

docs/source/user_guide/operators/forecast_operator/data_sources.rst

@@ -0,0 +1,98 @@
+=================
+Data Integration
+=================
+
+Supported Data Sources
+----------------------
+
+The Operator can read data from the following sources:
+
+- Oracle RDBMS
+- OCI Object Storage
+- OCI Data Lake
+- HTTPS
+- S3
+- Azure Blob Storage
+- Google Cloud Storage
+- Local file systems
+
+Additionally, the operator supports any data source supported by `fsspec <https://filesystem-spec.readthedocs.io/en/latest/_modules/fsspec/registry.html>`_.
+
+Examples
+--------
+
+Reading from OCI Object Storage
+===============================
+
+Below is an example of reading data from OCI Object Storage using the operator:
+
+.. code-block:: yaml
+
+    kind: operator
+    type: forecast
+    version: v1
+    spec:
+        datetime_column:
+            name: ds
+        historical_data:
+            url: oci://<bucket_name>@<namespace_name>/example_yosemite_temps.csv
+        horizon: 3
+        target_column: y
+
+Reading from Oracle Database
+============================
+
+Below is an example of reading data from an Oracle Database:
+
+.. code-block:: yaml
+
+    kind: operator
+    type: forecast
+    version: v1
+    spec:
+        historical_data:
+            connect_args:
+                user: XXX
+                password: YYY
+                dsn: "localhost/orclpdb"
+            sql: 'SELECT Store_ID, Sales, Date FROM live_data'
+        datetime_column:
+            name: ds
+        horizon: 1
+        target_column: y
+
+
+Data Preprocessing
+------------------
+
+The forecasting operator simplifies powerful data preprocessing. By default, it includes several preprocessing steps to ensure dataset compliance with each framework. However, users can disable one or more of these steps if needed, though doing so may cause the model to fail. Proceed with caution.
+
+Default preprocessing steps:
+- Missing value imputation
+- Outlier treatment
+
+To disable ``outlier_treatment``, modify the YAML file as shown below:
+
+.. code-block:: yaml
+
+    kind: operator
+    type: forecast
+    version: v1
+    spec:
+        datetime_column:
+            name: ds
+        historical_data:
+            url: https://raw.githubusercontent.com/facebook/prophet/main/examples/example_yosemite_temps.csv
+        horizon: 3
+        target_column: y
+        preprocessing: 
+            enabled: true
+            steps:
+                missing_value_imputation: True
+                outlier_treatment: False
+
+
+Real-Time Trigger
+-----------------
+
+The Operator can be run locally or on an OCI Data Science Job. The resultant model can be saved and deployed for future use if needed. For questions regarding this integration, please reach out to the OCI Data Science team.

docs/source/user_guide/operators/forecast_operator/development.rst

@@ -0,0 +1,176 @@
+============
+Development
+============
+
+Data Formatting
+---------------
+
+Datetime Column
+===============
+
+Operators read data in "long" format, which requires a datetime column with a constant frequency (e.g., daily, quarterly, hourly). The operator will attempt to infer the datetime format, but if it's ambiguous, users can specify the format explicitly in the ``format`` field of ``datetime_column`` as shown below:
+
+.. code-block:: yaml
+
+    kind: operator
+    type: forecast
+    version: v1
+    spec:
+        datetime_column:
+            name: ds
+            format: "%Y-%m-%d"
+        historical_data:
+            url: oci://<bucket_name>@<namespace_name>/example_yosemite_temps.csv
+        horizon: 3
+        target_column: y
+
+Target Category Columns
+=======================
+
+A target category column, or series column, is optional. Use this field when you have multiple related forecasts over the same time period, such as predicting sales across different stores, forecasting system failures across multiple sensors, or forecasting different line items of a financial statement. The ``target_category_columns`` is a list of column names, though typically it contains just one. If a ``target_category_columns`` is specified in the ``historical_data``, it must also be present across all time periods in the ``additional_data``. Below is an example dataset and corresponding YAML:
+
+Example Dataset:
+
+=======  ========  ========
+Product   Qtr      Sales
+=======  ========  ========
+A        01-2024   $7,500
+B        01-2024   $4,500
+C        01-2024   $8,500
+A        04-2024   $9,500
+B        04-2024   $6,500
+C        04-2024   $9,500
+=======  ========  ========
+
+YAML Configuration:
+
+.. code-block:: yaml
+
+    kind: operator
+    type: forecast
+    version: v1
+    spec:
+        datetime_column:
+            name: Qtr
+            format: "%m-%Y"
+        historical_data:
+            url: historical_data.csv
+        target_category_columns:
+            - Product
+        horizon: 1
+        target_column: Sales
+
+Additional Data
+===============
+
+Additional data enables multivariate forecasts and must adhere to similar formatting rules as historical data:
+
+- It must include a datetime column with identical formatting to the historical data.
+- If a target category column is present in the historical data, it must also be present in the additional data.
+- The additional data must cover the entire forecast horizon.
+
+Continuing with the previous example, for a horizon of 1, the additional data would look like this:
+
+=======  ========  ========  ===================
+Product   Qtr      Promotion  Competitor Release
+=======  ========  ========  ===================
+A        01-2024   0          0
+B        01-2024   0          1
+C        01-2024   1          1
+A        04-2024   1          1
+B        04-2024   0          0
+C        04-2024   0          0
+A        07-2024   0          0
+B        07-2024   0          0
+C        07-2024   0          0
+=======  ========  ========  ===================
+
+Corresponding YAML Configuration:
+
+.. code-block:: yaml
+
+    kind: operator
+    type: forecast
+    version: v1
+    spec:
+        datetime_column:
+            name: Qtr
+            format: "%m-%Y"
+        historical_data:
+            url: data.csv
+        additional_data:
+            url: additional_data.csv
+        target_category_columns:
+            - Product
+        horizon: 1
+        target_column: Sales
+
+Output Directory
+================
+
+Before running operators on a job, users must configure their output directory. By default, results are output locally to a new folder named "results". This can be customized as shown below:
+
+.. code-block:: yaml
+
+    kind: operator
+    type: forecast
+    version: v1
+    spec:
+        datetime_column:
+            name: ds
+        historical_data:
+            url: oci://<bucket_name>@<namespace_name>/example_yosemite_temps.csv
+        output_directory:
+            url: oci://<bucket_name>@<namespace_name>/my_results/
+        horizon: 3
+        target_column: y
+
+Ingesting and Interpreting Outputs
+==================================
+
+The forecasting operator generates several output files: ``forecast.csv``, ``metrics.csv``, ``local_explanations.csv``, ``global_explanations.csv``, and ``report.html``.
+
+We will review each of these output files in turn.
+
+**forecast.csv**
+
+This file contains the entire historical dataset with the following columns:
+
+- **Series**: Categorical or numerical index
+- **Date**: Time series data
+- **Real values**: Target values from historical data
+- **Fitted values**: Model predictions on historical data
+- **Forecasted values**: Predictions for the forecast horizon
+- **Upper and lower bounds**: Confidence intervals for predictions (based on the specified confidence interval width in the YAML file)
+
+**report.html**
+
+The ``report.html`` file is customized for each model type. Generally, it contains a summary of the historical and additional data, plots of target values overlaid with fitted and forecasted values, analysis of the models used, and details about the model components. It also includes a "receipt" YAML file, providing a detailed version of the original ``forecast.yaml``.
+
+**metrics.csv**
+
+This file includes relevant metrics calculated on the training set.
+
+**Global and Local Explanations in Forecasting Models**
+
+Understanding the predictions and the driving factors behind them is crucial in forecasting models. Global and local explanations offer insights at different levels of granularity.
+
+**Global Explanations:**
+
+Global explanations provide a high-level overview of how a forecasting model operates across the entire dataset. Key aspects include:
+
+1. **Feature Importance**: Identifies and ranks variables based on their contribution to the model's predictions.
+2. **Model Structure**: Reveals the architecture, algorithms, parameters, and hyperparameters used in the model.
+3. **Trends and Patterns**: Highlights broad trends and patterns captured by the model, such as seasonality and long-term trends.
+4. **Assumptions and Constraints**: Uncovers underlying assumptions or constraints of the model.
+
+**Local Explanations:**
+
+Local explanations focus on specific data points or subsets, offering detailed insights into why the model made particular predictions. Key aspects include:
+
+1. **Instance-specific Insights**: Provides details on how individual features contributed to a specific prediction.
+2. **Contextual Understanding**: Considers the unique characteristics of the data point in question.
+3. **Model Variability**: Shows the model's sensitivity to changes in input variables.
+4. **Decision Boundaries**: In classification problems, explains the factors influencing specific classification outcomes.
+
+Global explanations offer a broad understanding of the model, while local explanations provide detailed insights at the individual data point level.

docs/source/user_guide/operators/forecast_operator/faq.rst

@@ -0,0 +1,23 @@
+====
+FAQs
+====
+
+**How can I learn more about AutoMLX?**
+
+For more details, refer to the official documentation: `AutoMLX Documentation <https://docs.oracle.com/en-us/iaas/tools/automlx/latest/html/multiversion/latest/automl.html>`_
+
+**How can I learn more about AutoTS?**
+
+For more details, refer to the official documentation: `AutoTS Documentation <https://winedarksea.github.io/AutoTS/build/html/source/tutorial.html>`_
+
+**How do you handle missing values?**
+
+By default, missing values are imputed using linear interpolation.
+
+**Is there a way to specify the percentage increase that should be marked as an anomaly?**
+
+Yes, the ``contamination`` parameter can be used to control the percentage of anomalies. The default value is 0.1 (10%).
+
+**How is seasonality handled?**
+
+Seasonality is analyzed differently by each modeling framework. Refer to the specific model's documentation for more detailed information.