Kats Documentation

You can install the full version of Kats using pip. It is recommended to upgrade pip first.

To install a minimal version that omits many dependencies (specifically those in test_requirements.txt), set the MINIMAL_KATS=1 environment variable during installation. Note that a minimal installation will disable many functionalities and trigger warnings when importing kats.

pip install --upgrade pip
pip install kats

# For a minimal installation:
MINIMAL_KATS=1 pip install kats

Kats allows efficient hyperparameter tuning using a search method factory. This requires ax-platform (e.g., pip install ax-platform).

Workflow:

1. Define a parameters_grid_search as a list of dictionaries specifying name, type (e.g., 'choice'), values, and value_type.
2. Create a search method using tpt.SearchMethodFactory.create_search_method with SearchMethodEnum.GRID_SEARCH.
3. Define an evaluation_function(params) that fits a model on training data and returns an error metric (like MAE) on test data.
4. Call generate_evaluate_new_parameter_values(evaluation_function).
5. Retrieve results via list_parameter_value_scores().

Kats provides pretrained daily GMEnsemble objects trained on the M4 dataset. You can download these files and load them directly for forecasting.

Available models:

• RNN-GME: Recurrent Neural Network ensemble.
• S2S-GME: Sequence to Sequence ensemble.

To use a pretrained model, download the .p file and use load_gmensemble_from_file.

To use Kats models, you must first convert your data into a TimeSeriesData object. If your DataFrame has a column named time, it will be used automatically. If not, you must rename your time column to time or specify it during processing.

import pandas as pd
from kats.consts import TimeSeriesData

# Ensure the time column is named 'time'
df = pd.read_csv("your_data.csv")
df.columns = ["time", "value"]

# Convert to Kats TimeSeriesData
ts = TimeSeriesData(df)

from kats.consts import TimeSeriesData

# Note: If the column holding the time values is not called time, you will want to specify the name of this column.
air_passengers_df.columns = ["time", "value"]
air_passengers_ts = TimeSeriesData(air_passengers_df)

To use Kats in a Python environment (such as Google Colab), install it via pip.

!pip install kats

Use the CUSUMDetector to identify change points in a time series. The detector requires a TimeSeriesData object and is invoked via the .detector() method.

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

# Simulate time series with an 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()

The TsFeatures class allows you to extract meaningful statistical features from a time series. Use the .transform() method on a TimeSeriesData object to calculate these features.

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

# Load data
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)

The ThetaModel is a univariate forecasting method. It follows the same fit/predict pattern as other Kats models.

1. Create ThetaParams (e.g., specifying seasonality m).
2. Initialize ThetaModel with data and params.
3. Call .fit().
4. Call .predict(steps=N, alpha=0.2) to generate the forecast.

Kats follows the sklearn model API pattern (fit and predict). To use the Prophet model, ensure fbprophet is installed (e.g., pip install kats[prophet]).

1. Create a ProphetParams instance to configure seasonality.
2. Initialize ProphetModel with your TimeSeriesData and parameters.
3. Call .fit() to train the model.
4. Call .predict(steps=N, freq="FREQ") to generate a forecast.