Add usertype argument to X13-ARIMA API

Start in statsmodels/tsa/x13.py by reading x13_arima_analysis and _make_regression_options, then compare the generated regression specification with the X13 usertype documentation. Done means the API accepts usertype values for exogenous variables and emits the corresponding usertype specification; use the provided reproduction to check the seasonal-adjustment result.

Is your feature request related to a problem? Please describe

Hi, the issue is with statsmodels.tsa.x13.x13_arima_analysis which doesn't allow to edit usertype of exogenous variables in the specs. This is crucial if you want to add to the model your own list of holidays or trend or seasonal factors.

The 'X13-ARIMA' model is designed to extract trend and seasonality from the data and it's Fortran version allows you to pass external factors that models either trend, holidays or seasonality. Basically it is done using specs by passing usertype=holiday or user_type=td and etc. Howeverstatsmodels.tsa.x13.x13_arima_analysis doesn't allow to change user_type spec.

Let me show on the example. For example if I create a dummy time series which has custom holidays then when passing my_holidays feature to the x13_arima_analysis I get the following:

Current behavoiur: Seasonal adjusted component (by default usertype=user):

Required behaviour: Seasonal adjusted component (changing to usertype=holiday):

Describe the solution you'd like

Basically function statsmodels.tsa.x13.x13_arima_analysis should accept as an input argument userttype: list[Union[str]] to allow to change type of each exogenous variable.

Here is description of usertype from X13 documentation:

in statsmodels/tsa/x13.py following changes are required

def _make_regression_options(trading, exog, user_type='user'):
    if not trading and exog is None:  # start regression spec
        return ""

    reg_spec = "regression{\n"
    if trading:
        reg_spec += "    variables = (td)\n"
    if exog is not None:
        var_names = _make_var_names(exog)
        reg_spec += f"    user = ({var_names})\n"
        reg_spec += f"    usertype = ({user_type})\n"   #  <----
        reg_spec += "    data = ({})\n".format(
            "\n".join(
                map(str, exog.values.ravel().tolist())
            )
        )

    reg_spec += "}\n"  # close out regression spec
    return reg_spec

Code that reproduces an example:

import os

from statsmodels.tsa.x13 import x13_arima_analysis
import numpy as np
import pandas as pd
from datetime import datetime, timedelta
from  matplotlib.pyplot import waitforbuttonpress

os.environ['X13PATH'] = "...."


n_obs = 12*10

# create list of dates
base = datetime.strptime("2002-01-01", "%Y-%m-%d")
all_dates = []
for _ in range(n_obs):
    all_dates.append(base)
    base = (base + timedelta(days=31)).replace(day=1)

# generating random dataset
df = pd.DataFrame(index=all_dates)
df['idx'] = np.arange(n_obs)
df['seas'] = np.sin(df['idx'] / 12 * 2*np.pi)
df['trend'] = np.log(1+df['idx'])
df['holidays'] = np.random.binomial(1,0.1,size=n_obs)
df['const'] = 1
df['ts'] = df['trend'] + \
           df['seas'] + 3.3 + \
           df['holidays'] + \
           0.1*np.random.normal(size=n_obs)
df['ts'].plot()


res = x13_arima_analysis(df['ts'],
                         maxorder=(4,0),                         
                         maxdiff=(2,0),
                         exog = df[['holidays']],   #  passing my custom holidays
                         forecast_periods = 0,
                         outlier = False,  # better to use False this allows otherwise part of the custom holidays will be modeled as outliers
                         tempdir ="/Users/ivanpetrov/codebase/stack_overflow/data"
                        )

res.plot()   # check plot with SeasAdj data
waitforbuttonpress()