Chrono-kit Docs

!This page is still under progress

chrono-kit is an open source python library for time series analysis and forecasting.

This project was started in 2023 by ODTU YZT.

Take a look at our examples

Installation:


chronokit requires:

  • python >= 3.8.17
  • torch >= 1.13.1
  • numpy >= 1.24.0
  • pandas >= 1.4.0
  • scipy >= 1.10.1
  • matplotlib >= 3.2.1

    • pip install chrono-kit
    import chronokit

    exponential_smoothing module contains state space models based on Holt-Winters' Exponential Smoothing and ETS(Error-Trend-Seasonality) models


    exponential_smoothing.ExponentialSmoothing

    Exponential Smoothing Models for time series analysis and forecasting

    Exponential Smoothing Models was developed with Hyndman, R. et al. [1] as a reference;

    [1] 'Hyndman, R. J., Koehler, A. B., Ord, J. K., & Snyder, R. D. (2008). Forecasting with exponential smoothing: The state space approach''


        
    class ExponentialSmoothing:
                def __init__(self, 
                            data, 
                            trend=None, 
                            seasonal=None, 
                            seasonal_periods=None, 
                            damped=False, 
                            initialization_method='heuristic', 
                            **kwargs
                ):
    ExponentialSmoothing Models for 
    univariate time series modeling and forecasting
     
    Arguments:
     
    *data (array_like): Univariate time series data
    *trend (Optional[str]): Trend component; One of [None, "add", "mul]
    *seasonal (Optional[str]): Seasonal component; One of [None, "add", "mul]
        None if seasonal_periods is None
    *seasonal_periods (Optional[int]): Cyclic period of the
        seasonal component; None if seasonal is None
    *damped (bool): Damp factor of the trend component; One of [True, False]
        False if trend is None
    *initialization_method (Optional[str]): Initialization method to use
        for the model parameters; One of ["heuristic", "simple", "mle"]. 
        Default = 'heuristic'.
     
    Keyword Arguments:
     
    ** initial_level (float): Initial value for the level component;
    ** initial_trend_factor (float): Initial value for the trend component;
    ** initial_seasonal_factors (array_like): Initial values for seasonal components; 
        Must have length = seasonal_periods
     
    ** alpha (float): Smoothing parameter for level component;
        takes values in (0,1)
    ** beta (float): Smoothing parameter for trend component;
        takes values in (0,1)
    ** phi (float): Damp factor for trend component; takes values in (0,1]
    ** gamma (float): Smoothing parameter for seasonal component;
        takes values in (0,1)
     

    Methods:

  • fit(self)
    • Fit the model to the given data

  • predict(self, h, confidence=None)
    • Predict the next h values with the model
     
    .fit() should be called before making predictions
     
    Arguments:
     
    *h (int): Forecast horizon, minimum = 1
    *confidence (Optional[float]): Confidence bounds
        for predictions. Must take values in (0,1).
     
    Returns:
     
    *forecasts (array_like): Forecasted h values
    *bounds Optional(tuple): Upper and Lower
        forecast bounds, returns only if confidence != None

  • evaluate(self, val_data, metrics=['mae', 'rmse', 'mase'], criterions=['aic', 'bic', 'hqic'])
    • Evaluate the performance of the fitted model
    with the given validation data
     
    2 evaluation steps are performed;
     
    1) Evaluate model fit by selected information criterions
    2) Evaluate model predictions by selected metrics
     
    Plots model fit/predictions and returns metrics
     
    Arguments:
     
    *val_data (array_like): Data to perform evaluation on
    *metrics Optional(list): Regression metrics for evaluation
    *criterions Optional(list): Information criterions to
        evaluate model fit
     
    Returns:
     
    *res (pandas.DataFrame): Numerical results of the evaluation

    exponential_smoothing.ETS

    ETS (Error-Trend-Seasonality) Models for time series analysis and forecasting

    ETS Models was developed with Hyndman, R. et al. [1] as a reference;

    [1] 'Hyndman, R. J., Koehler, A. B., Ord, J. K., & Snyder, R. D. (2008). Forecasting with exponential smoothing: The state space approach'


        
    class ETS:
                def __init__(self, 
                            data, 
                            error_type='add', 
                            trend=None, 
                            seasonal=None, 
                            seasonal_periods=None, 
                            damped=False, 
                            initialization_method='heuristic', 
                            **kwargs
                ):
    ETS (Error-Trend-Seasonality) Models for 
    univariate time series modeling and forecasting
     
    Arguments:
     
    *error_type (Optional[str]): Error component; "add" or "mul"
    *data (array_like): Univariate time series data
    *trend (Optional[str]): Trend component; One of [None, "add", "mul]
    *seasonal (Optional[str]): Seasonal component; One of [None, "add", "mul]
        None if seasonal_periods is None
    *seasonal_periods (Optional[int]): Cyclic period of the
        seasonal component; None if seasonal is None
    *damped (bool): Damp factor of the trend component; One of [True, False]
        False if trend is None
    *initialization_method (Optional[str]): Initialization method to use
        for the model parameters; One of ["heuristic", "simple", "mle"]. 
        Default = 'heuristic'.
     
    Keyword Arguments:
     
    ** initial_level (float): Initial value for the level component;
    ** initial_trend_factor (float): Initial value for the trend component;
    ** initial_seasonal_factors (array_like): Initial values for seasonal components; 
        Must have length = seasonal_periods
     
    ** alpha (float): Smoothing parameter for level component;
        takes values in (0,1)
    ** beta (float): Smoothing parameter for trend component;
        takes values in (0,1)
    ** phi (float): Damp factor for trend component; takes values in (0,1]
    ** gamma (float): Smoothing parameter for seasonal component;
        takes values in (0,1)
     

    Methods:

  • fit(self)
    • Fit the model to the given data

  • predict(self, h, confidence=None)
    • Predict the next h values with the model
     
    .fit() should be called before making predictions
     
    Arguments:
     
    *h (int): Forecast horizon, minimum = 1
    *confidence (Optional[float]): Confidence bounds
        for predictions. Must take values in (0,1).
     
    Returns:
     
    *forecasts (array_like): Forecasted h values
    *bounds Optional(tuple): Upper and Lower
        forecast bounds, returns only if confidence != None

  • evaluate(self, val_data, metrics=['mae', 'rmse', 'mase'], criterions=['aic', 'bic', 'hqic'])
    • Evaluate the performance of the fitted model
    with the given validation data
     
    2 evaluation steps are performed;
     
    1) Evaluate model fit by selected information criterions
    2) Evaluate model predictions by selected metrics
     
    Plots model fit/predictions and returns metrics
     
    Arguments:
     
    *val_data (array_like): Data to perform evaluation on
    *metrics Optional(list): Regression metrics for evaluation
    *criterions Optional(list): Information criterions to
        evaluate model fit
     
    Returns:
     
    *res (pandas.DataFrame): Numerical results of the evaluation

    chronokit.arima

    arima module contains time series models based on ARIMA Processes


    arima.SARIMA

    SARIMA Models for time series analysis and forecasting

    SARIMA Models was developed by the below book as a reference;

    Box, G. E. P., Jenkins, G. M., Reinsel, G. C., & Ljung, G. M. (2015). Time series analysis: Forecasting and control (5th ed).'

        
    class SARIMA:
                def __init__(self, 
                            data, 
                            order = (0,0,0), 
                            seasonal_order=(0,0,0),
                            seasonal_periods=None,
                            **kwargs
                ):
    Seasonal AutoRegressive-Moving Average Integrated Model (SARIMA)
    for univarite time series modeling and forecasting.
     
    Arguments:
     
    *data (array_like): Univariate time series data
    *order (Optional[tuple]): Order of the ARIMA process (p,d,q)
    *seasonal_order (Optional[tuple]): Order of the seasonal process (P,D,Q)
        (0,0,0) if seasonal_periods is None
    *seasonal_periods (Optional[int]): Cyclic period of the
        seasonal component; None if seasonal_order = (0,0,0)
     
    Keyword Arguments:
     
    ** phi (array_like): Parameters for AR component;
        must be of length p
    ** theta (array_like): Parameters for MA component;
        must be of length q
    ** seasonal_phi (array_like): Parameters for Seasonal AR component;
        must be of length P
    ** seasonal_theta (array_like): Parameters for Seasonal MA component;
        must be of length Q
     

    Methods:

  • fit(self)
    • Fit the model to the given data

  • predict(self, h, confidence=None)
    • Predict the next h values with the model
     
    .fit() should be called before making predictions
     
    Arguments:
     
    *h (int): Forecast horizon, minimum = 1
    *confidence (Optional[float]): Confidence bounds
        for predictions. Must take values in (0,1).
     
    Returns:
     
    *forecasts (array_like): Forecasted h values
    *bounds Optional(tuple): Upper and Lower
        forecast bounds, returns only if confidence != None

  • evaluate(self, val_data, metrics=['mae', 'rmse', 'mase'], criterions=['aic', 'bic', 'hqic'])
    • Evaluate the performance of the fitted model
    with the given validation data
     
    2 evaluation steps are performed;
     
    1) Evaluate model fit by selected information criterions
    2) Evaluate model predictions by selected metrics
     
    Plots model fit/predictions and returns metrics
     
    Arguments:
     
    *val_data (array_like): Data to perform evaluation on
    *metrics Optional(list): Regression metrics for evaluation
    *criterions Optional(list): Information criterions to
        evaluate model fit
     
    Returns:
     
    *res (pandas.DataFrame): Numerical results of the evaluation