### Install Kats and Download Data

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_201_forecasting.ipynb

Installs the Kats library and downloads necessary datasets for the tutorial. This is a prerequisite for running the forecasting examples.

```python
%%capture
# For Google Colab:
!pip install kats
!wget https://raw.githubusercontent.com/facebookresearch/Kats/main/kats/data/air_passengers.csv
!wget https://raw.githubusercontent.com/facebookresearch/Kats/main/kats/data/multi_ts.csv
```

--------------------------------

### Install Kats and Download Data

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_202_detection.ipynb

Installs the Kats library and downloads necessary datasets for the tutorial. This is typically run in a Google Colab environment.

```python
%%capture
# For Google Colab:
!pip install kats
!wget https://raw.githubusercontent.com/facebookresearch/Kats/main/kats/data/air_passengers.csv
!wget https://raw.githubusercontent.com/facebookresearch/Kats/main/kats/data/multivariate_anomaly_simulated_data.csv
```

--------------------------------

### Install Kats Library

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_203_tsfeatures.ipynb

Installs the Kats library. This is typically the first step for using Kats functionalities.

```python
%%capture
# For Google Colab:
!pip install kats
```

--------------------------------

### Install Kats and Download Data

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_204_metalearning.ipynb

Installs the Kats library and downloads necessary datasets for demonstration purposes. This is typically run in a Google Colab environment.

```python
%%capture
# For Google Colab:
!pip install kats
!wget https://raw.githubusercontent.com/facebookresearch/Kats/main/kats/data/air_passengers.csv
!wget https://raw.githubusercontent.com/facebookresearch/Kats/main/kats/data/m3_meta_data.csv
```

--------------------------------

### Detector Output Structure Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/README.md

Demonstrates accessing changepoint information, including start time, end time, and confidence.

```python
changepoints  # Sequence[TimeSeriesChangePoint]
cp.start_time    # pd.Timestamp
cp.end_time      # pd.Timestamp
cp.confidence    # float (0.0 to 1.0)
```

--------------------------------

### Install Kats with Pip

Source: https://github.com/facebookresearch/kats/blob/main/README.md

Install the latest version of Kats using pip. This is the standard installation method.

```bash
pip install --upgrade pip
pip install kats
```

--------------------------------

### LSTM Model Training and Prediction Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/models.md

Demonstrates how to initialize, train, and predict using the LSTM model. Ensure you have a 'data.csv' file and have installed pandas and kats.

```python
from kats.models.lstm import LSTMModel, LSTMParams
from kats.consts import TimeSeriesData
import pandas as pd

df = pd.read_csv('data.csv')
ts = TimeSeriesData(df=df)

params = LSTMParams(
    time_window=10,
    num_epochs=50,
    hidden_size=64,
    batch_size=16
)
model = LSTMModel(ts, params)
model.fit()
model.predict(steps=30, freq='D')
```

--------------------------------

### Install and Format Code with Black and isort

Source: https://github.com/facebookresearch/kats/blob/main/CONTRIBUTING.md

Install the required code formatting tools and apply them to the kats project directory. Ensure code adheres to project style guidelines before submission.

```bash
(kats_venv) $ pip install isort black
```

```bash
(kats_venv) $ black kats
```

```bash
(kats_venv) $ isort kats --recursive --multi-line 3 --trailing-comma --force-grid-wrap 0 --line-width 88 --lines-after-imports 2 --combine-as --section-default THIRDPARTY
```

--------------------------------

### Install Kats and Download Data

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_205_globalmodel.ipynb

Installs the Kats library and downloads necessary data files for demonstration purposes. This is typically run in a Colab environment.

```bash
%%capture
# For Google Colab:
!pip install kats
!wget https://raw.githubusercontent.com/facebookresearch/Kats/main/kats/data/air_passengers.csv
!wget https://globalmodel.s3.amazonaws.com/pretrained_daily_rnn.p
```

--------------------------------

### CUSUMDetector Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/detectors.md

Demonstrates how to initialize and use the CUSUMDetector to find change points in a time series. Requires kats, pandas, and numpy. The example creates sample data with a simulated change point.

```python
from kats.detectors.cusum_detection import CUSUMDetector
from kats.consts import TimeSeriesData
import pandas as pd
import numpy as np

# Create sample data with change point
dates = pd.date_range('2020-01-01', periods=100)
values = np.concatenate([np.random.normal(1, 0.1, 50), np.random.normal(2, 0.1, 50)])
df = pd.DataFrame({'time': dates, 'value': values})

ts = TimeSeriesData(df=df)
detector = CUSUMDetector(ts)
change_points = detector.detector()

for cp in change_points:
    print(f"Change point at {cp.start_time}")
```

--------------------------------

### Complete Detection Example with CUSUM and Outlier Detectors

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/detectors.md

An end-to-end example demonstrating change point detection using CUSUMDetector and outlier detection/removal using OutlierDetector.

```python
from kats.consts import TimeSeriesData
from kats.detectors.cusum_detection import CUSUMDetector
from kats.detectors.outlier import OutlierDetector
import pandas as pd
import numpy as np

# Generate sample data with anomalies
np.random.seed(42)
dates = pd.date_range('2020-01-01', periods=200)
values = np.concatenate([
    np.random.normal(100, 5, 60),  # Normal
    np.random.normal(110, 5, 60),  # Change point
    np.random.normal(100, 5, 80),  # Back to normal
])
# Add outliers
values[[50, 120, 180]] = [200, 50, 200]
df = pd.DataFrame({'time': dates, 'value': values})

# Create TimeSeriesData
ts = TimeSeriesData(df=df)

# Detect change points
cusum = CUSUMDetector(ts)
change_points = cusum.detector()
print(f"Change points detected: {len(change_points)}")

# Detect outliers
outlier_detector = OutlierDetector(ts, threshold=2.0)
outliers = outlier_detector.detector()
print(f"Outliers detected: {len(outliers)}")

# Remove outliers
clean_ts = outlier_detector.remover(interpolate=True)

# Visualize
cusum.plot()
```

--------------------------------

### ProphetModel Usage Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/models.md

Demonstrates how to initialize, fit, and predict using the Prophet model. Ensure you have a 'data.csv' file and necessary imports.

```python
from kats.models.prophet import ProphetModel, ProphetParams
from kats.consts import TimeSeriesData
import pandas as pd

df = pd.read_csv('data.csv')
ts = TimeSeriesData(df=df)

params = ProphetParams(
    seasonality_mode='multiplicative',
    yearly_seasonality=True,
    weekly_seasonality=True
)
model = ProphetModel(ts, params)
model.fit()
model.predict(steps=30, freq='D')
model.plot()
```

--------------------------------

### Full Configuration Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/configuration.md

This snippet demonstrates a complete workflow using Kats, including data loading, feature extraction, anomaly detection, forecasting with Prophet, and evaluation.

```python
import pandas as pd
from kats.consts import TimeSeriesData
from kats.models.prophet import ProphetModel, ProphetParams
from kats.tsfeatures.tsfeatures import TsFeatures
from kats.detectors.cusum_detection import CUSUMDetector
from kats.metrics.metrics import mean_absolute_error

# 1. Load and configure data
df = pd.read_csv('data.csv')
ts = TimeSeriesData(
    df=df,
    time_col_name='date',
    date_format='%Y-%m-%d',
    sort_by_time=True
)
ts.validate_data(validate_frequency=True)

# 2. Extract features
feature_extractor = TsFeatures(
    selected_features=['mean', 'var', 'trend_strength', 'seasonality_strength'],
    stl_period=12
)
features = feature_extractor.transform(ts)

# 3. Detect anomalies
cusum_detector = CUSUMDetector(
    ts,
    threshold=0.01,
    change_directions=['increase', 'decrease']
)
changepoints = cusum_detector.detector()

# 4. Configure and fit forecast model
prophet_params = ProphetParams(
    seasonality_mode='multiplicative',
    yearly_seasonality=True,
    changepoint_prior_scale=0.05
)
model = ProphetModel(ts, prophet_params)
model.fit()

# 5. Generate forecast
model.predict(steps=30, freq='D')

# 6. Evaluate
mae = mean_absolute_error(
    ts.value[-10:].values,
    model.fcst_df['fcst'][-10:].values
)

print(f"Features: {len(features)}")
print(f"Changepoints: {len(changepoints)}")
print(f"MAE: {mae:.2f}")
```

--------------------------------

### Install Minimal Kats with Pip

Source: https://github.com/facebookresearch/kats/blob/main/README.md

Install a minimal version of Kats to reduce dependencies. This may disable some functionalities.

```bash
MINIMAL_KATS=1 pip install kats
```

--------------------------------

### Model Output Structure Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/README.md

Shows how to access forecast data and history inclusion status from a trained model.

```python
model.fcst_df  # pd.DataFrame with columns: time, fcst, fcst_lower, fcst_upper
model.include_history  # bool: includes training data in output
```

--------------------------------

### Initialize and Use KatsEnsemble for Forecasting

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_201_forecasting.ipynb

Demonstrates how to initialize KatsEnsemble with multiple forecasting models, configure parameters, fit the model, predict future values, aggregate results, and plot the forecast. Ensure `fbprophet` is installed for the Prophet model.

```python
from kats.models.ensemble.ensemble import EnsembleParams, BaseModelParams
from kats.models.ensemble.kats_ensemble import KatsEnsemble
from kats.models import (
    arima,
    holtwinters,
    linear_model,
    prophet,  # requires fbprophet be installed
    quadratic_model,
    sarima,
    theta,
)

# we need define params for each individual forecasting model in `EnsembleParams` class
# here we include 6 different models
model_params = EnsembleParams(
            [
                BaseModelParams("arima", arima.ARIMAParams(p=1, d=1, q=1)),
                BaseModelParams(
                    "sarima",
                    sarima.SARIMAParams(
                        p=2,
                        d=1,
                        q=1,
                        trend="ct",
                        seasonal_order=(1, 0, 1, 12),
                        enforce_invertibility=False,
                        enforce_stationarity=False,
                    ),
                ),
                BaseModelParams("prophet", prophet.ProphetParams()),  # requires fbprophet be installed
                BaseModelParams("linear", linear_model.LinearModelParams()),
                BaseModelParams("quadratic", quadratic_model.QuadraticModelParams()),
                BaseModelParams("theta", theta.ThetaParams(m=12)),
            ]
        )

# create `KatsEnsembleParam` with detailed configurations 
KatsEnsembleParam = {
    "models": model_params,
    "aggregation": "median",
    "seasonality_length": 12,
    "decomposition_method": "multiplicative",
}

# create `KatsEnsemble` model
m = KatsEnsemble(
    data=air_passengers_ts, 
    params=KatsEnsembleParam
    )

# fit and predict
m.fit()

# predict for the next 30 steps
fcst = m.predict(steps=30)

# aggregate individual model results
m.aggregate()

# plot to visualize
m.plot()
```

--------------------------------

### Initialize and Run Backtester

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/utilities.md

Initializes the BackTester with time series data and backtesting parameters, then runs a backtest using a provided forecasting function. The example uses an ARIMA model for forecasting.

```python
from kats.utils.backtest import BackTester
from kats.models.arima import ARIMAModel, ARIMAParams

backtester = BackTester(
    data=ts,
    start_date=pd.Timestamp('2019-01-01'),
    end_date=pd.Timestamp('2019-12-31'),
    train_interval=100,
    test_interval=20,
)

def forecast_func(data):
    params = ARIMAParams(p=1, d=1, q=1)
    model = ARIMAModel(data, params)
    model.fit()
    model.predict(steps=20)
    return model.fcst_df

results = backtester.run_backtest(forecast_func)
print(f"Average MAE: {results['mae'].mean():.2f}")
```

--------------------------------

### CUSUM Detector Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/detectors.md

Demonstrates how to initialize and run the CUSUMDetector to find change points in time series data. It iterates through the detected change points and prints their details.

```python
from kats.consts import TimeSeriesData
from kats.detectors.cusum_detection import CUSUMDetector

ts = TimeSeriesData(df=df)
detector = CUSUMDetector(ts)
change_points = detector.detector()

for cp in change_points:
    print(f"Change from {cp.start_time} to {cp.end_time}, confidence: {cp.confidence}")
```

--------------------------------

### Prophet Parameters Implementation

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/types.md

Example implementation of the Params class for Prophet model parameters, including growth, changepoints, n_changepoints, and seasonality_mode.

```python
# Prophet Parameters
class ProphetParams(Params):
    growth: str
    changepoints: Optional[List[float]]
    n_changepoints: int
    seasonality_mode: str
    # ... many more attributes
```

--------------------------------

### TimeSeriesData Structure Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/README.md

Illustrates accessing components of the TimeSeriesData object, including time, value, and min/max.

```python
ts = TimeSeriesData(df=df)

ts.time      # pd.Series of pd.Timestamp
ts.value     # pd.Series (univariate) or pd.DataFrame (multivariate)
ts.min, ts.max  # Min/max values
```

--------------------------------

### Metric Output Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/README.md

Represents a single scalar metric value.

```python
error_value  # float: single scalar metric
```

--------------------------------

### load_data

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/utilities.md

Loads predefined sample datasets for examples and testing. Available datasets include 'air_passengers', 'electricity', and 'weather'.

```APIDOC
## load_data

### Description
Loads predefined sample datasets for examples and testing.

### Parameters
None

### Available Sample Data
- air_passengers: Classic airline passenger dataset
- electricity: Electricity consumption
- weather: Weather time series

### Example
```python
from kats.data import air_passengers_df
from kats.consts import TimeSeriesData

df = air_passengers_df
ts = TimeSeriesData(df=df)
print(f"Loaded {len(ts)} observations")
```
```

--------------------------------

### Instantiate IntervalAnomaly

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/types.md

Example of creating an IntervalAnomaly object. Ensure timestamps are in Unix format and confidence is between 0.0 and 1.0.

```python
from kats.consts import IntervalAnomaly
import time

anomaly = IntervalAnomaly(
    start_timestamp=time.time() - 3600,
    end_timestamp=time.time(),
    metric_name="cpu_usage",
    anomaly_value=95.5,
    expected_value=30.0,
    confidence=0.92
)
```

--------------------------------

### ModelEnum Usage Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/types.md

Demonstrates how to use the ModelEnum to specify a model type and access its string value.

```python
from kats.consts import ModelEnum

model_type = ModelEnum.PROPHET
print(model_type.value)  # "prophet"
```

--------------------------------

### ARIMA Model Usage Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/models.md

Demonstrates how to instantiate, fit, and predict using the ARIMAModel. Ensure your data is loaded into a TimeSeriesData object and parameters are set correctly.

```python
from kats.consts import TimeSeriesData
from kats.models.arima import ARIMAModel, ARIMAParams
import pandas as pd

# Create data
df = pd.read_csv('data.csv', parse_dates=['time'])
ts = TimeSeriesData(df=df)

# Create model
params = ARIMAParams(p=1, d=1, q=1)
model = ARIMAModel(ts, params)

# Fit and predict
model.fit()
model.predict(steps=30, freq='D')

# Plot results
model.plot()
```

--------------------------------

### Forecasting with Prophet Model in Kats

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_101_basics.ipynb

Demonstrates how to use the Prophet model for time series forecasting. Requires fbprophet to be installed. The fit and predict methods follow the scikit-learn API pattern.

```python
# import the param and model classes for Prophet model
from kats.models.prophet import ProphetModel, ProphetParams

# create a model param instance
params = ProphetParams(seasonality_mode='multiplicative') # additive mode gives worse results

# create a prophet model instance
m = ProphetModel(air_passengers_ts, params)

# fit model simply by calling m.fit()
m.fit()

# make prediction for next 30 month
fcst = m.predict(steps=30, freq="MS")
```

--------------------------------

### Import necessary libraries for hyperparameter tuning

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_201_forecasting.ipynb

Imports required modules from kats, ax-platform, and standard libraries for time series analysis and hyperparameter tuning. Ensure ax-platform is installed.

```python
import kats.utils.time_series_parameter_tuning as tpt
from kats.consts import ModelEnum, SearchMethodEnum, TimeSeriesData
from kats.models.arima import ARIMAParams, ARIMAModel

from ax.core.parameter import ChoiceParameter, FixedParameter, ParameterType
from ax.generators.random.sobol import SobolGenerator
from ax.generators.random.uniform import UniformGenerator
import warnings
import numpy as np

# Assuming air_passengers_df and air_passengers_ts are already defined
# For example:
# from kats.datasets import load_air_passengers
# air_passengers_df = load_air_passengers()
# air_passengers_ts = TimeSeriesData(air_passengers_df)

warnings.simplefilter(action='ignore')
```

--------------------------------

### Kats Error Handling Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/README.md

Shows how to catch specific Kats exceptions like DataError and ParameterError, as well as the base KatsError.

```python
from kats.consts import (
    KatsError,
    DataError,
    DataIrregularGranularityError,
    ParameterError,
)

try:
    ts = TimeSeriesData(df=df)
except DataError:
    print("Data validation failed")
except ParameterError:
    print("Invalid parameters")
except KatsError:
    print("Kats error")
```

--------------------------------

### Prophet Model Forecasting

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_201_forecasting.ipynb

Initializes, fits, and predicts using the Prophet model. This model requires the 'fbprophet' library to be installed. It allows specifying seasonality modes.

```python
# import the param and model classes for Prophet model
from kats.models.prophet import ProphetModel, ProphetParams

# create a model param instance
params = ProphetParams(seasonality_mode='multiplicative') # additive mode gives worse results

# create a prophet model instance
m = ProphetModel(air_passengers_ts, params)

# fit model simply by calling m.fit()
m.fit()

# make prediction for next 30 month
fcst = m.predict(steps=30, freq="MS")

# plot to visualize
m.plot()
```

--------------------------------

### Create TimeSeriesChangePoint Instance

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/timeseries-core.md

Instantiate a TimeSeriesChangePoint object to represent a detected change point. Requires start time, end time, and confidence level.

```python
cp = TimeSeriesChangePoint(
    start_time=pd.Timestamp('2020-06-01'),
    end_time=pd.Timestamp('2020-06-05'),
    confidence=0.95
)
print(f"Change detected from {cp.start_time} to {cp.end_time} with {cp.confidence} confidence")
```

--------------------------------

### Initialize and Use TsFeatures

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/metrics-features.md

Demonstrates how to initialize the TsFeatures class and extract features from a TimeSeriesData object. Ensure you have a 'data.csv' file and the necessary pandas and kats libraries installed.

```python
from kats.tsfeatures.tsfeatures import TsFeatures
from kats.consts import TimeSeriesData
import pandas as pd

df = pd.read_csv('data.csv')
ts = TimeSeriesData(df=df)

feature_extractor = TsFeatures()
features = feature_extractor.transform(ts)

print(f"Extracted {len(features)} features")
for name, value in features.items():
    print(f"{name}: {value:.4f}")
```

--------------------------------

### ARIMA Parameters Implementation

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/types.md

Example implementation of the Params class for ARIMA model parameters, including p, d, q, exog, dates, and freq.

```python
# ARIMA Parameters
class ARIMAParams(Params):
    p: int
    d: int
    q: int
    exog: Optional[npt.NDArray]
    dates: Optional[pd.DatetimeIndex]
    freq: Optional[str]
```

--------------------------------

### Handling No Change Point Detection with Interest Window

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_202_detection.ipynb

This example shows how CUSUMDetector behaves when the specified interest window does not contain any detectable change points. It includes plotting the results.

```python
# limit the interest_window to last 20 the datapoint and no change point detected
tsd = TimeSeriesData(df_increase_decrease.loc[:,['time','increase']])
detector = CUSUMDetector(tsd)
change_points = detector.detector(interest_window=[40,60])

detector.plot(change_points)
plt.xticks(rotation=45)
plt.show()
```

--------------------------------

### Get Length of TimeSeriesData

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_101_basics.ipynb

Demonstrates how to get the number of data points in a TimeSeriesData object using the len() function.

```python
len(air_passengers_ts)
```

--------------------------------

### Initialize and Recommend with DefaultMetaLearner

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/utilities.md

Instantiate DefaultMetaLearner to automatically select appropriate models and parameters for a given time series.

```python
from kats.models.metalearner import DefaultMetaLearner

metalearner = DefaultMetaLearner()
recommended_params = metalearner.recommend(ts)
# Returns recommended model and parameters
```

--------------------------------

### Import GMEnsemble and load_gmensemble_from_file

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_205_globalmodel.ipynb

Import necessary classes for using the GMEnsemble functionality.

```python
from kats.models.globalmodel.ensemble import GMEnsemble, load_gmensemble_from_file
```

--------------------------------

### Plot Time Series Data

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/utilities.md

Visualizes a TimeSeriesData object using matplotlib. Ensure matplotlib is installed and imported.

```python
import matplotlib.pyplot as plt
from kats.graphics import plot_tsdata

# Plot time series
fig, ax = plt.subplots(figsize=(12, 6))
ts.plot(ax=ax)
plt.title("Time Series Data")
plt.show()
```

--------------------------------

### Example of Kats TSFeatures Output

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_203_tsfeatures.ipynb

This snippet shows the full output of calculated features from the Kats TSFeatures module.

```python
Result:
{'length': 90,
 'mean': -4.973228083549793,
 'var': 50.69499812650379,
 'entropy': 0.2742447620827895,
 'lumpiness': 10.258210327109449,
 'stability': 45.07760417461487,
 'flat_spots': 1,
 'hurst': 0.41884368965647256,
 'std1st_der': 0.8773588739369633,
 'crossing_points': 5,
 'binarize_mean': 0.43333333333333335,
 'unitroot_kpss': 0.4164114707833328,
 'heterogeneity': 73.29527168434541,
 'histogram_mode': -11.841676172131818,
 'linearity': 0.834635526909661,
 'seasonality_strength': 0.3521955818150291,
 'y_acf1': 0.9597578784708428,
 'y_acf5': 4.0361834721280365,
 'diff1y_acf1': 0.1830233735938267,
 'diff1y_acf5': 0.0794760417768679,
 'diff2y_acf1': -0.4816907863327952,
 'diff2y_acf5': 0.24476824866108501,
 'y_pacf5': 0.9862593061001357,
 'diff1y_pacf5': 0.07981792144706332,
 'diff2y_pacf5': 0.36145785941160113,
 'seas_acf1': 0.8149983814152568,
 'seas_pacf1': 0.030344962550473576,
 'nowcast_roc': 0.05212172487338159,
 'nowcast_mom': -0.9575428298227386,
 'nowcast_ma': -4.832882514728335,
 'nowcast_lag': -4.393327628568679,
 'nowcast_macd': -0.9380868822690636,
 'nowcast_macdsign': -1.0413322101367146,
 'nowcast_macddiff': -0.049750365563814056}
```

--------------------------------

### Initialize and run MultivariateAnomalyDetector

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_202_detection.ipynb

Initializes the MultivariateAnomalyDetector with simulated time series data and VAR parameters, then runs the detection. The first 60 days are used for training and excluded from the output plots.

```python
np.random.seed(10)
params = VARParams(maxlags=2)
d = MultivariateAnomalyDetector(multi_anomaly_ts, params, training_days=60)
anomaly_score_df = d.detector()
d.plot()
```

--------------------------------

### Configure and Run Prophet Backtester

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_201_forecasting.ipynb

Sets up and runs a BackTesterSimple for a Prophet model with specified parameters and a 75/25 training-test split. It calculates the same error metrics as the ARIMA model.

```python
params_prophet = ProphetParams(seasonality_mode='multiplicative') # additive mode gives worse results

backtester_prophet = BackTesterSimple(
    error_methods=ALL_ERRORS,
    data=air_passengers_ts,
    params=params_prophet,
    train_percentage=75,
    test_percentage=25, 
    model_class=ProphetModel)

backtester_prophet.run_backtest()

backtester_errors['prophet'] = {}
for error, value in backtester_prophet.errors.items():
    backtester_errors['prophet'][error] = value

```

--------------------------------

### Use Metric Class for MAE Calculation

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/metrics-features.md

Example of instantiating the Metric class with the mean_absolute_error function and calculating the metric value.

```python
from kats.metrics.metrics import Metric, mean_absolute_error

mae_metric = Metric("MAE", mean_absolute_error)
actual = np.array([1, 2, 3])
predicted = np.array([1.1, 2.1, 3.1])
print(mae_metric.value(actual, predicted))
```

--------------------------------

### Import necessary libraries

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_202_detection.ipynb

Import MultivariateAnomalyDetector, VARParams, and suppress future warnings.

```python
from kats.detectors.outlier import MultivariateAnomalyDetector, MultivariateAnomalyDetectorType
from kats.models.var import VARParams

import warnings
warnings.filterwarnings(action='ignore',category=FutureWarning)
```

--------------------------------

### TimeSeriesChangePoint Class

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/timeseries-core.md

Represents a detected change point in a time series, including its start and end times and confidence level.

```APIDOC
## Class: TimeSeriesChangePoint

### Description
Represents a detected change point in a time series, including its start and end times and confidence level.

### Parameters
#### Constructor Parameters
- **start_time** (pd.Timestamp) - Required - Start time of the change point
- **end_time** (pd.Timestamp) - Required - End time of the change point
- **confidence** (float) - Required - Confidence level of the change point (0.0 to 1.0)

### Properties
- **start_time** (pd.Timestamp): Start time of the detected change
- **end_time** (pd.Timestamp): End time of the detected change
- **confidence** (float): Confidence score of the change point

### Example
```python
cp = TimeSeriesChangePoint(
    start_time=pd.Timestamp('2020-06-01'),
    end_time=pd.Timestamp('2020-06-05'),
    confidence=0.95
)
print(f"Change detected from {cp.start_time} to {cp.end_time} with {cp.confidence} confidence")
```
```

--------------------------------

### Configure Prophet Model Parameters

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/configuration.md

Sets up parameters for the Prophet model, including seasonality, growth mode, and prior scales. Adjust 'seasonality_prior_scale' and 'changepoint_prior_scale' to control model flexibility.

```python
from kats.models.prophet import ProphetParams, ProphetModel

params = ProphetParams(
    growth='linear',
    seasonality_mode='additive',
    yearly_seasonality=True,
    weekly_seasonality=True,
    daily_seasonality=False,
    changepoint_prior_scale=0.05,
    seasonality_prior_scale=10.0,
    interval_width=0.80
)
model = ProphetModel(ts, params)
```

--------------------------------

### Get anomaly time points

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_202_detection.ipynb

Retrieves the specific time points identified as anomalous based on a given significance level (alpha).

```python
anomalies = d.get_anomaly_timepoints(alpha=0.05)
anomalies
```

--------------------------------

### Initialize GMParam for Daily Model

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_205_globalmodel.ipynb

Initializes a GMParam object to configure a daily Global Model with weekly seasonality. Demonstrates setting key parameters like input window, forecast window, seasonality, frequency, loss function, neural network structure, features, and training epochs/size.

```python
gmparam = GMParam(
    input_window = 35, 
    fcst_window = 31,
    seasonality = 7,
    freq = 'D',
    loss_function = 'adjustedpinball',
    nn_structure = [[1,3]],
    gmfeature = ['last_date'],
    epoch_num = 1, 
    epoch_size = 2, # use a small num just for demonstration
    gmname = "daily_default",
)
```

--------------------------------

### OperationsEnum Usage Example

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/types.md

Shows how to use OperationsEnum with TimeSeriesData objects for arithmetic operations like addition, subtraction, multiplication, and division.

```python
from kats.consts import OperationsEnum, TimeSeriesData

ts1 = TimeSeriesData(...)
ts2 = TimeSeriesData(...)

# Equivalent operations
ts_sum = ts1 + ts2
ts_diff = ts1 - ts2
ts_prod = ts1 * ts2
ts_div = ts1 / ts2
```

--------------------------------

### Initialize GMBackTester

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_205_globalmodel.ipynb

Initialize the GMBackTester object with training data, GM parameters, and backtesting configurations. Key parameters include `train_TSs`, `gmparam`, `backtest_timestamp`, and `test_size`.

```python
from kats.models.globalmodel.backtester import GMBackTester

gbm = GMBackTester(train_TSs, gmparam, backtest_timestamp = ['2020-08-10'], test_size=0.1)
```

--------------------------------

### Configure Basic ARIMA Model

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/configuration.md

Sets up basic ARIMA model parameters (p, d, q). Use this for standard time series forecasting without external factors.

```python
from kats.models.arima import ARIMAParams, ARIMAModel

# Basic ARIMA
params = ARIMAParams(p=1, d=1, q=1)
model = ARIMAModel(ts, params)
```

--------------------------------

### Initialize MetaLearnPredictability Model

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_204_metalearning.ipynb

Initializes the MetaLearnPredictability model using a list of metadata and a threshold for forecasting error. Use this to train a new predictability model.

```python
from kats.models.metalearner.metalearner_predictability import MetaLearnPredictability

# take the time series with MAPE>=0.2 as unpreditable time series and initial the object
mlp=MetaLearnPredictability(metadata_list, threshold=0.2)
```

--------------------------------

### Process Change Points Function

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/types.md

Example function demonstrating the use of Kats' TimeSeriesData and TimeSeriesChangePoint types for processing detected change points.

```python
from kats.consts import TimeSeriesChangePoint, TimeSeriesData
from kats.detectors.cusum_detection import CUSUMChangePointVal
from typing import Sequence

def process_changepoints(
    data: TimeSeriesData,
    changepoints: Sequence[TimeSeriesChangePoint],
) -> None:
    """Process detected change points."""
    for cp in changepoints:
        print(f"Change from {cp.start_time} to {cp.end_time}")
```

--------------------------------

### Configure and Run ARIMA Backtester

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_201_forecasting.ipynb

Sets up and runs a BackTesterSimple for an ARIMA model with specified parameters and a 75/25 training-test split. It calculates multiple error metrics.

```python
params = ARIMAParams(p=2, d=1, q=1)
ALL_ERRORS = ['mape', 'smape', 'mae', 'mase', 'mse', 'rmse']

backtester_arima = BackTesterSimple(
    error_methods=ALL_ERRORS,
    data=air_passengers_ts,
    params=params,
    train_percentage=75,
    test_percentage=25, 
    model_class=ARIMAModel)

backtester_arima.run_backtest()

```

--------------------------------

### Get Default ARIMA Parameter Search Space

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/models.md

Retrieves the default parameter search space for ARIMA models, useful for automated model tuning.

```python
from kats.utils.parameter_tuning_utils import get_default_arima_parameter_search_space

search_space = get_default_arima_parameter_search_space()
# Returns: dict of parameter ranges for ARIMA
```

--------------------------------

### Detector Model Registry Usage

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/detectors.md

Demonstrates how to access and use the DetectorModelRegistry to find and instantiate detector classes.

```python
from kats.detectors.detector import DetectorModelRegistry

registry = DetectorModelRegistry.get_registry()
print(list(registry.keys()))  # All available detectors

DetectorClass = DetectorModelRegistry.get_detector_model_by_name("CUSUMDetector")
detector = DetectorClass(data_serialized)
```

--------------------------------

### LSTM Model Initialization and Usage

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/models.md

Demonstrates how to initialize and use the LSTMModel for time series forecasting. This includes creating a TimeSeriesData object, defining LSTM parameters, initializing the model, fitting it to the data, and making predictions.

```APIDOC
## LSTMModel

### Description
Represents a Long Short-Term Memory (LSTM) neural network model for time series forecasting.

### Initialization
```python
LSTMModel(data: TimeSeriesData, params: LSTMParams)
```

### Methods
#### fit
Fits the LSTM model to the provided time series data.

#### predict
Generates future forecasts from the fitted LSTM model.

### Example Usage
```python
from kats.models.lstm import LSTMModel, LSTMParams
from kats.consts import TimeSeriesData
import pandas as pd

df = pd.read_csv('data.csv')
ts = TimeSeriesData(df=df)

params = LSTMParams(
    time_window=10,
    num_epochs=50,
    hidden_size=64,
    batch_size=16
)
model = LSTMModel(ts, params)
model.fit()
model.predict(steps=30, freq='D')
```
```

--------------------------------

### Time Series Feature Extraction

Source: https://github.com/facebookresearch/kats/blob/main/README.md

Extract meaningful features from time series data using the TsFeatures class. The 'air_passengers' dataset is used as an example.

```python
# Initiate feature extraction class
import pandas as pd
from kats.consts import TimeSeriesData
from kats.tsfeatures.tsfeatures import TsFeatures

# take `air_passengers` data as an example
air_passengers_df = pd.read_csv(
    "../kats/data/air_passengers.csv",
    header=0,
    names=["time", "passengers"],
)

# convert to TimeSeriesData object
air_passengers_ts = TimeSeriesData(air_passengers_df)

# calculate the TsFeatures
features = TsFeatures().transform(air_passengers_ts)
```

--------------------------------

### Basic RobustStatDetector Usage

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_202_detection.ipynb

Demonstrates the basic usage of RobustStatDetector for detecting change points in a time series. Requires importing the detector and plotting the results.

```python
# import package
from kats.detectors.robust_stat_detection import RobustStatDetector

tsd = TimeSeriesData(df_increase_decrease.loc[:,['time','increase']])
detector = RobustStatDetector(tsd)
change_points = detector.detector()

detector.plot(change_points)
plt.xticks(rotation=45)
plt.show()
```

--------------------------------

### Get Number of Trained GMs in Ensemble

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_205_globalmodel.ipynb

Check the number of individual Global Models (GMs) trained within the ensemble, based on the 'splits' and 'replicate' parameters.

```python
len(gme.gm_info)
```

--------------------------------

### Initialize MetaLearnHPT with Default Holt-Winters

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_204_metalearning.ipynb

Initializes the MetaLearnHPT class with metadata features and target hyperparameters, specifying 'holtwinters' as the default model.

```python
from kats.models.metalearner.metalearner_hpt import MetaLearnHPT

mlhpt_holtwinters = MetaLearnHPT(
    data_x=metadata_features_df,
    data_y=metadata_hpt_df,
    default_model='holtwinters'
)
```

--------------------------------

### Forecasting Model Lifecycle

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/START_HERE.md

Illustrates the standard workflow for using forecasting models in Kats: initialization, training, prediction, and accessing results.

```python
model = ModelClass(data, params)  # Initialize
model.fit()                        # Train
model.predict(steps=10)            # Forecast
fcst_df = model.fcst_df           # Get results
```

--------------------------------

### Prepare training and testing data

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_205_globalmodel.ipynb

Generate sample time series data for training and testing using get_ts.

```python
from kats.tests.models.test_globalmodel import get_ts

train_TSs = [get_ts(n*5, '2020-05-06', has_nans=False) for n in range(20, 40)]
test_TSs = [get_ts(n*2, '2020-05-06', has_nans=False) for n in range(40, 45)]
```

--------------------------------

### Initialize and Predict with Nowcaster

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/utilities.md

Create a Nowcaster instance to estimate current unobserved time series values. The default model used is exponential smoothing.

```python
from kats.models.nowcasting import Nowcaster

nowcaster = Nowcaster(ts)
current_estimate = nowcaster.predict()
print(f"Current estimated value: {current_estimate}")
```

--------------------------------

### CUSUM Change Point Detection

Source: https://github.com/facebookresearch/kats/blob/main/README.md

Detect change points in time series data using the CUSUM algorithm. This example simulates data with an increase and then applies the detector.

```python
# import packages
import numpy as np
import pandas as pd

from kats.consts import TimeSeriesData
from kats.detectors.cusum_detection import CUSUMDetector

# simulate time series with increase
np.random.seed(10)
df_increase = pd.DataFrame(
    {
        'time': pd.date_range('2019-01-01', '2019-03-01'),
        'increase':np.concatenate([np.random.normal(1,0.2,30), np.random.normal(2,0.2,30)]),
    }
)

# convert to TimeSeriesData object
timeseries = TimeSeriesData(df_increase)

# run detector and find change points
change_points = CUSUMDetector(timeseries).detector()
```

--------------------------------

### Slice TimeSeriesData by Time Range

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/timeseries-core.md

Extract a portion of the time series data within a specified start and end time (inclusive). Returns a new TimeSeriesData object.

```python
ts_slice = ts.slice(start_time=pd.Timestamp('2020-01-01'), end_time=pd.Timestamp('2020-06-30'))
```

--------------------------------

### Accessing Metadata Keys

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_204_metalearning.ipynb

Demonstrates how to view the available metadata keys for a time series dataset. This includes keys like 'hpt_res', 'features', 'best_model', 'search_method', and 'error_method'.

```python
air_passengers_metadata.keys()
```

--------------------------------

### Provide User-Friendly Error Messages

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/errors.md

Provide helpful error messages to users, especially when specific exceptions like DataIrregularGranularityError occur. This guides users on how to resolve the issue.

```python
try:
    detector = CUSUMDetector(ts)
    changepoints = detector.detector()
except DataIrregularGranularityError:
    print("Your data has irregular time spacing. Consider resampling.")
```

--------------------------------

### Initialize Metric Class

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/metrics-features.md

Base class for vector/multivariate metrics. Initialize with a name and a metric function.

```python
class Metric:
    def __init__(
        self,
        name: str,
        metric_func: Callable[[npt.NDArray, npt.NDArray], float],
    ) -> None
```

--------------------------------

### SARIMA Model Forecasting

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_201_forecasting.ipynb

Initializes, fits, and predicts using the SARIMA model. Requires specifying SARIMA-specific parameters like p, d, q, and seasonal_order.

```python
from kats.models.sarima import SARIMAModel, SARIMAParams
warnings.simplefilter(action='ignore')

# create SARIMA param class
params = SARIMAParams(
    p = 2, 
    d=1, 
    q=1, 
    trend = 'ct', 
    seasonal_order=(1,0,1,12)
    )

# initiate SARIMA model
m = SARIMAModel(data=air_passengers_ts, params=params)

# fit SARIMA model
m.fit()

# generate forecast values
fcst = m.predict(
    steps=30, 
    freq="MS",
    include_history=True
    )

# make plot to visualize
m.plot()
```

--------------------------------

### Get Time Series Timestamp Statistics

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/utilities.md

Use this function to retrieve statistics about the time index of a TimeSeriesData object. It helps identify frequency, missing dates, and duplicate timestamps.

```python
from kats.utils.time_series_utils import TimeSeriesUtils

stats = TimeSeriesUtils.get_timestamp_stats(ts)
# Returns: {'frequency': 'D', 'missing_dates': [], 'duplicates': []}
```

--------------------------------

### Initialize and Reconcile with HierarchicalForecaster

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/utilities.md

Instantiate HierarchicalForecaster to reconcile forecasts across different levels of a time series hierarchy. Requires a dictionary of forecasts and a reconciliation method.

```python
from kats.models.reconciliation import HierarchicalForecaster

hierarchical_forecaster = HierarchicalForecaster(
    forecasts=forecasts_dict,  # Dict of forecasts by level
    method='optimal_combination'
)

reconciled = hierarchical_forecaster.reconcile()
```

--------------------------------

### Get Default Prophet Parameter Search Space

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/utilities.md

Retrieves the default parameter ranges for Prophet hyperparameter tuning. This includes seasonality modes, prior scales, and changepoint configurations.

```python
from kats.utils.parameter_tuning_utils import get_default_prophet_parameter_search_space
from kats.models.prophet import ProphetModel, ProphetParams

search_space = get_default_prophet_parameter_search_space()

for seasonality_mode in search_space.get('seasonality_mode', ['additive']):
    for changepoint_prior_scale in search_space.get('changepoint_prior_scale', [0.05]):
        params = ProphetParams(
            seasonality_mode=seasonality_mode,
            changepoint_prior_scale=changepoint_prior_scale
        )
        model = ProphetModel(ts, params)
        model.fit()
        model.predict(steps=30)
```

--------------------------------

### Detector Interface in Kats

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/README.md

Illustrates the consistent API for all detectors in Kats, covering initialization, detection, visualization, and anomaly removal.

```python
detector = DetectorClass(data)         # Initialize
changepoints = detector.detector()     # Detect
detector.plot()                        # Visualize
clean_data = detector.remover()        # Remove anomalies
```

--------------------------------

### Interpret MKChangePoint Object

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_202_detection.ipynb

Accesses and displays the details of the first detected trend change point. This includes start and end times, confidence, detector type, and trend direction.

```python
cp = detected_time_points[0]
cp
```

--------------------------------

### Check Optional Dependencies

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/configuration.md

Checks for the availability of optional dependencies like Prophet and PyTorch using try-except blocks. Imports ProphetModel if available.

```python
# Check for optional dependencies
try:
    import prophet
    PROPHET_AVAILABLE = True
except ImportError:
    PROPHET_AVAILABLE = False

try:
    import torch
    TORCH_AVAILABLE = True
except ImportError:
    TORCH_AVAILABLE = False

if PROPHET_AVAILABLE:
    from kats.models.prophet import ProphetModel, ProphetParams
```

--------------------------------

### CUSUMDetector Initialization

Source: https://github.com/facebookresearch/kats/blob/main/_autodocs/api-reference/detectors.md

Initializes the CUSUMDetector with time series data and various parameters to control the change point detection sensitivity and behavior.

```APIDOC
## CUSUMDetector

### Description
Initializes the CUSUMDetector with time series data and various parameters to control the change point detection sensitivity and behavior.

### Parameters

- **data** (TimeSeriesData) - Required - Input time series.
- **threshold** (float) - Optional - Threshold for chi-squared test. Default: 0.01.
- **max_iter** (int) - Optional - Maximum iterations for change point estimation. Default: 10.
- **delta_std_ratio** (float) - Optional - Ratio of delta to standard deviation. Default: 1.0.
- **min_abs_change** (int) - Optional - Minimum absolute change to detect. Default: 0.
- **start_point** (int) - Optional - Start point for search (default: middle).
- **change_directions** (List[str]) - Optional - Detect only 'increase' or 'decrease'.
- **interest_window** (int) - Optional - Window size for local search.
- **magnitude_quantile** (float) - Optional - Quantile threshold for magnitude filtering.
- **magnitude_ratio** (float) - Optional - Ratio for magnitude comparison. Default: 1.3.
- **magnitude_comparable_day** (float) - Optional - Comparable period ratio. Default: 0.5.
- **return_all_changepoints** (bool) - Optional - Return all potential change points. Default: False.
- **remove_seasonality** (bool) - Optional - Remove seasonal component before detection. Default: False.
```

--------------------------------

### Get Minimum Training Length

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_205_globalmodel.ipynb

Retrieve the minimum required training data length for the Global Model (GM) backtester. This value is crucial for ensuring sufficient data is available for training before backtesting.

```python
gbm.min_train_length
```

--------------------------------

### Run BOCPDetector for Change Point Detection

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_202_detection.ipynb

Initializes and runs the BOCPDetector on simulated time series data to detect mean shifts. The default NORMAL_KNOWN_MODEL is used.

```python
from kats.detectors.bocpd import BOCPDetector, BOCPDModelType, TrendChangeParameters

# Initialize the detector
detector = BOCPDetector(ts_bocpd)


changepoints = detector.detector(
    model=BOCPDModelType.NORMAL_KNOWN_MODEL # this is the default choice
)

# Plot the data
detector.plot(changepoints)
plt.xticks(rotation=45)
plt.show()
```

--------------------------------

### Demonstration of Conflicting Feature Selections

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_203_tsfeatures.ipynb

This snippet illustrates that attempting to include a feature group or a specific feature in `selected_features` while simultaneously opting out the same feature or its group will result in an error. The provided examples show two such invalid configurations.

```python
# THIS DOES NOT WORK
# TsFeatures(selected_features = ['mean'], statitics = False).transform(ts)

# THIS ALSO DOES NOT WORK
# TsFeatures(selected_features = ['mean'], mean = False).transform(ts)
```

--------------------------------

### Disabling Multiple Feature Groups

Source: https://github.com/facebookresearch/kats/blob/main/tutorials/kats_203_tsfeatures.ipynb

This example shows how to disable multiple feature groups, 'length', 'mean', and 'stl_features', simultaneously by passing False to their respective parameters in the TsFeatures constructor. This allows for fine-grained control over feature computation.

```python
tsf = TsFeatures(length = False, mean = False, stl_features=False)
tsf.transform(ts)
```