{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# Dynamic factors and coincident indices\n",
    "\n",
    "Factor models generally try to find a small number of unobserved \"factors\" that influence a subtantial portion of the variation in a larger number of observed variables, and they are related to dimension-reduction techniques such as principal components analysis. Dynamic factor models explicitly model the transition dynamics of the unobserved factors, and so are often applied to time-series data.\n",
    "\n",
    "Macroeconomic coincident indices are designed to capture the common component of the \"business cycle\"; such a component is assumed to simultaneously affect many macroeconomic variables. Although the estimation and use of coincident indices (for example the [Index of Coincident Economic Indicators](http://www.newyorkfed.org/research/regional_economy/coincident_summary.html)) pre-dates dynamic factor models, in several influential papers Stock and Watson (1989, 1991) used a dynamic factor model to provide a theoretical foundation for them.\n",
    "\n",
    "Below, we follow the treatment found in Kim and Nelson (1999), of the Stock and Watson (1991) model, to formulate a dynamic factor model, estimate its parameters via maximum likelihood, and create a coincident index."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Macroeconomic data\n",
    "\n",
    "The coincident index is created by considering the comovements in four macroeconomic variables (versions of thse variables are available on [FRED](https://research.stlouisfed.org/fred2/); the ID of the series used below is given in parentheses):\n",
    "\n",
    "- Industrial production (IPMAN)\n",
    "- Real aggregate income (excluding transfer payments) (W875RX1)\n",
    "- Manufacturing and trade sales (CMRMTSPL)\n",
    "- Employees on non-farm payrolls (PAYEMS)\n",
    "\n",
    "In all cases, the data is at the monthly frequency and has been seasonally adjusted; the time-frame considered is 1972 - 2005."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "import statsmodels.api as sm\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "np.set_printoptions(precision=4, suppress=True, linewidth=120)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from pandas.io.data import DataReader\n",
    "\n",
    "# Get the datasets from FRED\n",
    "start = '1979-01-01'\n",
    "end = '2014-12-01'\n",
    "indprod = DataReader('IPMAN', 'fred', start=start, end=end)\n",
    "income = DataReader('W875RX1', 'fred', start=start, end=end)\n",
    "sales = DataReader('CMRMTSPL', 'fred', start=start, end=end)\n",
    "emp = DataReader('PAYEMS', 'fred', start=start, end=end)\n",
    "# dta = pd.concat((indprod, income, sales, emp), axis=1)\n",
    "# dta.columns = ['indprod', 'income', 'sales', 'emp']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: in a recent update on FRED (8/12/15) the time series CMRMTSPL was truncated to begin in 1997; this is probably a mistake due to the fact that CMRMTSPL is a spliced series, so the earlier period is from the series HMRMT and the latter period is defined by CMRMT.\n",
    "\n",
    "This has since (02/11/16) been corrected, however the series could also be constructed by hand from HMRMT and CMRMT, as shown below (process taken from the notes in the Alfred xls file)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# HMRMT = DataReader('HMRMT', 'fred', start='1967-01-01', end=end)\n",
    "# CMRMT = DataReader('CMRMT', 'fred', start='1997-01-01', end=end)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# HMRMT_growth = HMRMT.diff() / HMRMT.shift()\n",
    "# sales = pd.Series(np.zeros(emp.shape[0]), index=emp.index)\n",
    "\n",
    "# # Fill in the recent entries (1997 onwards)\n",
    "# sales[CMRMT.index] = CMRMT\n",
    "\n",
    "# # Backfill the previous entries (pre 1997)\n",
    "# idx = sales.ix[:'1997-01-01'].index\n",
    "# for t in range(len(idx)-1, 0, -1):\n",
    "#     month = idx[t]\n",
    "#     prev_month = idx[t-1]\n",
    "#     sales.ix[prev_month] = sales.ix[month] / (1 + HMRMT_growth.ix[prev_month].values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "dta = pd.concat((indprod, income, sales, emp), axis=1)\n",
    "dta.columns = ['indprod', 'income', 'sales', 'emp']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "dta.ix[:, 'indprod':'emp'].plot(subplots=True, layout=(2, 2), figsize=(15, 6));"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Stock and Watson (1991) report that for their datasets, they could not reject the null hypothesis of a unit root in each series (so the series are integrated), but they did not find strong evidence that the series were co-integrated.\n",
    "\n",
    "As a result, they suggest estimating the model using the first differences (of the logs) of the variables, demeaned and standardized."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Create log-differenced series\n",
    "dta['dln_indprod'] = (np.log(dta.indprod)).diff() * 100\n",
    "dta['dln_income'] = (np.log(dta.income)).diff() * 100\n",
    "dta['dln_sales'] = (np.log(dta.sales)).diff() * 100\n",
    "dta['dln_emp'] = (np.log(dta.emp)).diff() * 100\n",
    "\n",
    "# De-mean and standardize\n",
    "dta['std_indprod'] = (dta['dln_indprod'] - dta['dln_indprod'].mean()) / dta['dln_indprod'].std()\n",
    "dta['std_income'] = (dta['dln_income'] - dta['dln_income'].mean()) / dta['dln_income'].std()\n",
    "dta['std_sales'] = (dta['dln_sales'] - dta['dln_sales'].mean()) / dta['dln_sales'].std()\n",
    "dta['std_emp'] = (dta['dln_emp'] - dta['dln_emp'].mean()) / dta['dln_emp'].std()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dynamic factors\n",
    "\n",
    "A general dynamic factor model is written as:\n",
    "\n",
    "$$\n",
    "\\begin{align}\n",
    "y_t & = \\Lambda f_t + B x_t + u_t \\\\\n",
    "f_t & = A_1 f_{t-1} + \\dots + A_p f_{t-p} + \\eta_t \\qquad \\eta_t \\sim N(0, I)\\\\\n",
    "u_t & = C_1 u_{t-1} + \\dots + C_1 f_{t-q} + \\varepsilon_t \\qquad \\varepsilon_t \\sim N(0, \\Sigma)\n",
    "\\end{align}\n",
    "$$\n",
    "\n",
    "where $y_t$ are observed data, $f_t$ are the unobserved factors (evolving as a vector autoregression), $x_t$ are (optional) exogenous variables, and $u_t$ is the error, or \"idiosyncratic\", process ($u_t$ is also optionally allowed to be autocorrelated). The $\\Lambda$ matrix is often referred to as the matrix of \"factor loadings\". The variance of the factor error term is set to the identity matrix to ensure identification of the unobserved factors.\n",
    "\n",
    "This model can be cast into state space form, and the unobserved factor estimated via the Kalman filter. The likelihood can be evaluated as a byproduct of the filtering recursions, and maximum likelihood estimation used to estimate the parameters."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Model specification\n",
    "\n",
    "The specific dynamic factor model in this application has 1 unobserved factor which is assumed to follow an AR(2) proces. The innovations $\\varepsilon_t$ are assumed to be independent (so that $\\Sigma$ is a diagonal matrix) and the error term associated with each equation, $u_{i,t}$ is assumed to follow an independent AR(2) process.\n",
    "\n",
    "Thus the specification considered here is:\n",
    "\n",
    "$$\n",
    "\\begin{align}\n",
    "y_{i,t} & = \\lambda_i f_t + u_{i,t} \\\\\n",
    "u_{i,t} & = c_{i,1} u_{1,t-1} + c_{i,2} u_{i,t-2} + \\varepsilon_{i,t} \\qquad & \\varepsilon_{i,t} \\sim N(0, \\sigma_i^2) \\\\\n",
    "f_t & = a_1 f_{t-1} + a_2 f_{t-2} + \\eta_t \\qquad & \\eta_t \\sim N(0, I)\\\\\n",
    "\\end{align}\n",
    "$$\n",
    "\n",
    "where $i$ is one of: `[indprod, income, sales, emp ]`.\n",
    "\n",
    "This model can be formulated using the `DynamicFactor` model built-in to Statsmodels. In particular, we have the following specification:\n",
    "\n",
    "- `k_factors = 1` - (there is 1 unobserved factor)\n",
    "- `factor_order = 2` - (it follows an AR(2) process)\n",
    "- `error_var = False` - (the errors evolve as independent AR processes rather than jointly as a VAR - note that this is the default option, so it is not specified below)\n",
    "- `error_order = 2` - (the errors are autocorrelated of order 2: i.e. AR(2) processes)\n",
    "- `error_cov_type = 'diagonal'` - (the innovations are uncorrelated; this is again the default)\n",
    "\n",
    "Once the model is created, the parameters can be estimated via maximum likelihood; this is done using the `fit()` method.\n",
    "\n",
    "**Note**: recall that we have de-meaned and standardized the data; this will be important in interpreting the results that follow.\n",
    "\n",
    "**Aside**: in their empirical example, Kim and Nelson (1999) actually consider a slightly different model in which the employment variable is allowed to also depend on lagged values of the factor - this model does not fit into the built-in `DynamicFactor` class, but can be accomodated by using a subclass to implement the required new parameters and restrictions - see Appendix A, below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parameter estimation\n",
    "\n",
    "Multivariate models can have a relatively large number of parameters, and it may be difficult to escape from local minima to find the maximized likelihood. In an attempt to mitigate this problem, I perform an initial maximization step (from the model-defined starting paramters) using the modified Powell method available in Scipy (see the minimize documentation for more information). The resulting parameters are then used as starting parameters in the standard LBFGS optimization method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# Get the endogenous data\n",
    "endog = dta.ix['1979-02-01':, 'std_indprod':'std_emp']\n",
    "\n",
    "# Create the model\n",
    "mod = sm.tsa.DynamicFactor(endog, k_factors=1, factor_order=2, error_order=2)\n",
    "initial_res = mod.fit(method='powell', disp=False)\n",
    "res = mod.fit(initial_res.params)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Estimates\n",
    "\n",
    "Once the model has been estimated, there are two components that we can use for analysis or inference:\n",
    "\n",
    "- The estimated parameters\n",
    "- The estimated factor"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Parameters\n",
    "\n",
    "The estimated parameters can be helpful in understanding the implications of the model, although in models with a larger number of observed variables and / or unobserved factors they can be difficult to interpret.\n",
    "\n",
    "One reason for this difficulty is due to identification issues between the factor loadings and the unobserved factors. One easy-to-see identification issue is the sign of the loadings and the factors: an equivalent model to the one displayed below would result from reversing the signs of all factor loadings and the unobserved factor.\n",
    "\n",
    "Here, one of the easy-to-interpret implications in this model is the persistence of the unobserved factor: we find that exhibits substantial persistence."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "print(res.summary(separate_params=False))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Estimated factors\n",
    "\n",
    "While it can be useful to plot the unobserved factors, it is less useful here than one might think for two reasons:\n",
    "\n",
    "1. The sign-related identification issue described above.\n",
    "2. Since the data was differenced, the estimated factor explains the variation in the differenced data, not the original data.\n",
    "\n",
    "It is for these reasons that the coincident index is created (see below).\n",
    "\n",
    "With these reservations, the unobserved factor is plotted below, along with the NBER indicators for US recessions. It appears that the factor is successful at picking up some degree of business cycle activity."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(13,3))\n",
    "\n",
    "# Plot the factor\n",
    "dates = endog.index._mpl_repr()\n",
    "ax.plot(dates, res.factors.filtered[0], label='Factor')\n",
    "ax.legend()\n",
    "\n",
    "# Retrieve and also plot the NBER recession indicators\n",
    "rec = DataReader('USREC', 'fred', start=start, end=end)\n",
    "ylim = ax.get_ylim()\n",
    "ax.fill_between(dates[:-3], ylim[0], ylim[1], rec.values[:,0], facecolor='k', alpha=0.1);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Post-estimation\n",
    "\n",
    "Although here we will be able to interpret the results of the model by constructing the coincident index, there is a useful and generic approach for getting a sense for what is being captured by the estimated factor. By taking the estimated factors as given, regressing them (and a constant) each (one at a time) on each of the observed variables, and recording the coefficients of determination ($R^2$ values), we can get a sense of the variables for which each factor explains a substantial portion of the variance and the variables for which it does not.\n",
    "\n",
    "In models with more variables and more factors, this can sometimes lend interpretation to the factors (for example sometimes one factor will load primarily on real variables and another on nominal variables).\n",
    "\n",
    "In this model, with only four endogenous variables and one factor, it is easy to digest a simple table of the $R^2$ values, but in larger models it is not. For this reason, a bar plot is often employed; from the plot we can easily see that the factor explains most of the variation in industrial production index and a large portion of the variation in sales and employment, it is less helpful in explaining income."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "res.plot_coefficients_of_determination(figsize=(8,2));"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Coincident Index\n",
    "\n",
    "As described above, the goal of this model was to create an interpretable series which could be used to understand the current status of the macroeconomy. This is what the coincident index is designed to do. It is constructed below. For readers interested in an explanation of the construction, see Kim and Nelson (1999) or Stock and Watson (1991).\n",
    "\n",
    "In essense, what is done is to reconstruct the mean of the (differenced) factor. We will compare it to the coincident index on published by the Federal Reserve Bank of Philadelphia (USPHCI on FRED)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "usphci = DataReader('USPHCI', 'fred', start='1979-01-01', end='2014-12-01')['USPHCI']\n",
    "usphci.plot(figsize=(13,3));"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "dusphci = usphci.diff()[1:].values\n",
    "def compute_coincident_index(mod, res):\n",
    "    # Estimate W(1)\n",
    "    spec = res.specification\n",
    "    design = mod.ssm['design']\n",
    "    transition = mod.ssm['transition']\n",
    "    ss_kalman_gain = res.filter_results.kalman_gain[:,:,-1]\n",
    "    k_states = ss_kalman_gain.shape[0]\n",
    "\n",
    "    W1 = np.linalg.inv(np.eye(k_states) - np.dot(\n",
    "        np.eye(k_states) - np.dot(ss_kalman_gain, design),\n",
    "        transition\n",
    "    )).dot(ss_kalman_gain)[0]\n",
    "\n",
    "    # Compute the factor mean vector\n",
    "    factor_mean = np.dot(W1, dta.ix['1972-02-01':, 'dln_indprod':'dln_emp'].mean())\n",
    "    \n",
    "    # Normalize the factors\n",
    "    factor = res.factors.filtered[0]\n",
    "    factor *= np.std(usphci.diff()[1:]) / np.std(factor)\n",
    "\n",
    "    # Compute the coincident index\n",
    "    coincident_index = np.zeros(mod.nobs+1)\n",
    "    # The initial value is arbitrary; here it is set to\n",
    "    # facilitate comparison\n",
    "    coincident_index[0] = usphci.iloc[0] * factor_mean / dusphci.mean()\n",
    "    for t in range(0, mod.nobs):\n",
    "        coincident_index[t+1] = coincident_index[t] + factor[t] + factor_mean\n",
    "    \n",
    "    # Attach dates\n",
    "    coincident_index = pd.Series(coincident_index, index=dta.index).iloc[1:]\n",
    "    \n",
    "    # Normalize to use the same base year as USPHCI\n",
    "    coincident_index *= (usphci.ix['1992-07-01'] / coincident_index.ix['1992-07-01'])\n",
    "    \n",
    "    return coincident_index"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below we plot the calculated coincident index along with the US recessions and the comparison coincident index USPHCI."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(13,3))\n",
    "\n",
    "# Compute the index\n",
    "coincident_index = compute_coincident_index(mod, res)\n",
    "\n",
    "# Plot the factor\n",
    "dates = endog.index._mpl_repr()\n",
    "ax.plot(dates, coincident_index, label='Coincident index')\n",
    "ax.plot(usphci.index._mpl_repr(), usphci, label='USPHCI')\n",
    "ax.legend(loc='lower right')\n",
    "\n",
    "# Retrieve and also plot the NBER recession indicators\n",
    "ylim = ax.get_ylim()\n",
    "ax.fill_between(dates[:-3], ylim[0], ylim[1], rec.values[:,0], facecolor='k', alpha=0.1);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Appendix 1: Extending the dynamic factor model\n",
    "\n",
    "Recall that the previous specification was described by:\n",
    "\n",
    "$$\n",
    "\\begin{align}\n",
    "y_{i,t} & = \\lambda_i f_t + u_{i,t} \\\\\n",
    "u_{i,t} & = c_{i,1} u_{1,t-1} + c_{i,2} u_{i,t-2} + \\varepsilon_{i,t} \\qquad & \\varepsilon_{i,t} \\sim N(0, \\sigma_i^2) \\\\\n",
    "f_t & = a_1 f_{t-1} + a_2 f_{t-2} + \\eta_t \\qquad & \\eta_t \\sim N(0, I)\\\\\n",
    "\\end{align}\n",
    "$$\n",
    "\n",
    "Written in state space form, the previous specification of the model had the following observation equation:\n",
    "\n",
    "$$\n",
    "\\begin{bmatrix}\n",
    "y_{\\text{indprod}, t} \\\\\n",
    "y_{\\text{income}, t} \\\\\n",
    "y_{\\text{sales}, t} \\\\\n",
    "y_{\\text{emp}, t} \\\\\n",
    "\\end{bmatrix} = \\begin{bmatrix}\n",
    "\\lambda_\\text{indprod} & 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "\\lambda_\\text{income}  & 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "\\lambda_\\text{sales}   & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "\\lambda_\\text{emp}     & 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\\\\n",
    "\\end{bmatrix}\n",
    "\\begin{bmatrix}\n",
    "f_t \\\\\n",
    "f_{t-1} \\\\\n",
    "u_{\\text{indprod}, t} \\\\\n",
    "u_{\\text{income}, t} \\\\\n",
    "u_{\\text{sales}, t} \\\\\n",
    "u_{\\text{emp}, t} \\\\\n",
    "u_{\\text{indprod}, t-1} \\\\\n",
    "u_{\\text{income}, t-1} \\\\\n",
    "u_{\\text{sales}, t-1} \\\\\n",
    "u_{\\text{emp}, t-1} \\\\\n",
    "\\end{bmatrix}\n",
    "$$\n",
    "\n",
    "and transition equation:\n",
    "\n",
    "$$\n",
    "\\begin{bmatrix}\n",
    "f_t \\\\\n",
    "f_{t-1} \\\\\n",
    "u_{\\text{indprod}, t} \\\\\n",
    "u_{\\text{income}, t} \\\\\n",
    "u_{\\text{sales}, t} \\\\\n",
    "u_{\\text{emp}, t} \\\\\n",
    "u_{\\text{indprod}, t-1} \\\\\n",
    "u_{\\text{income}, t-1} \\\\\n",
    "u_{\\text{sales}, t-1} \\\\\n",
    "u_{\\text{emp}, t-1} \\\\\n",
    "\\end{bmatrix} = \\begin{bmatrix}\n",
    "a_1 & a_2 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "1   & 0   & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "0   & 0   & c_{\\text{indprod}, 1} & 0 & 0 & 0 & c_{\\text{indprod}, 2} & 0 & 0 & 0 \\\\\n",
    "0   & 0   & 0 & c_{\\text{income}, 1} & 0 & 0 & 0 & c_{\\text{income}, 2} & 0 & 0 \\\\\n",
    "0   & 0   & 0 & 0 & c_{\\text{sales}, 1} & 0 & 0 & 0 & c_{\\text{sales}, 2} & 0 \\\\\n",
    "0   & 0   & 0 & 0 & 0 & c_{\\text{emp}, 1} & 0 & 0 & 0 & c_{\\text{emp}, 2} \\\\\n",
    "0   & 0   & 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "0   & 0   & 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "0   & 0   & 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "0   & 0   & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\\\\n",
    "\\end{bmatrix} \n",
    "\\begin{bmatrix}\n",
    "f_{t-1} \\\\\n",
    "f_{t-2} \\\\\n",
    "u_{\\text{indprod}, t-1} \\\\\n",
    "u_{\\text{income}, t-1} \\\\\n",
    "u_{\\text{sales}, t-1} \\\\\n",
    "u_{\\text{emp}, t-1} \\\\\n",
    "u_{\\text{indprod}, t-2} \\\\\n",
    "u_{\\text{income}, t-2} \\\\\n",
    "u_{\\text{sales}, t-2} \\\\\n",
    "u_{\\text{emp}, t-2} \\\\\n",
    "\\end{bmatrix}\n",
    "+ R \\begin{bmatrix}\n",
    "\\eta_t \\\\\n",
    "\\varepsilon_{t}\n",
    "\\end{bmatrix}\n",
    "$$\n",
    "\n",
    "the `DynamicFactor` model handles setting up the state space representation and, in the `DynamicFactor.update` method, it fills in the fitted parameter values into the appropriate locations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The extended specification is the same as in the previous example, except that we also want to allow employment to depend on lagged values of the factor. This creates a change to the $y_{\\text{emp},t}$ equation. Now we have:\n",
    "\n",
    "$$\n",
    "\\begin{align}\n",
    "y_{i,t} & = \\lambda_i f_t + u_{i,t} \\qquad & i \\in \\{\\text{indprod}, \\text{income}, \\text{sales} \\}\\\\\n",
    "y_{i,t} & = \\lambda_{i,0} f_t + \\lambda_{i,1} f_{t-1} + \\lambda_{i,2} f_{t-2} + \\lambda_{i,2} f_{t-3} + u_{i,t} \\qquad & i = \\text{emp} \\\\\n",
    "u_{i,t} & = c_{i,1} u_{i,t-1} + c_{i,2} u_{i,t-2} + \\varepsilon_{i,t} \\qquad & \\varepsilon_{i,t} \\sim N(0, \\sigma_i^2) \\\\\n",
    "f_t & = a_1 f_{t-1} + a_2 f_{t-2} + \\eta_t \\qquad & \\eta_t \\sim N(0, I)\\\\\n",
    "\\end{align}\n",
    "$$\n",
    "\n",
    "Now, the corresponding observation equation should look like the following:\n",
    "\n",
    "$$\n",
    "\\begin{bmatrix}\n",
    "y_{\\text{indprod}, t} \\\\\n",
    "y_{\\text{income}, t} \\\\\n",
    "y_{\\text{sales}, t} \\\\\n",
    "y_{\\text{emp}, t} \\\\\n",
    "\\end{bmatrix} = \\begin{bmatrix}\n",
    "\\lambda_\\text{indprod} & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "\\lambda_\\text{income}  & 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "\\lambda_\\text{sales}   & 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "\\lambda_\\text{emp,1}   & \\lambda_\\text{emp,2} & \\lambda_\\text{emp,3} & \\lambda_\\text{emp,4} & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\\\\n",
    "\\end{bmatrix}\n",
    "\\begin{bmatrix}\n",
    "f_t \\\\\n",
    "f_{t-1} \\\\\n",
    "f_{t-2} \\\\\n",
    "f_{t-3} \\\\\n",
    "u_{\\text{indprod}, t} \\\\\n",
    "u_{\\text{income}, t} \\\\\n",
    "u_{\\text{sales}, t} \\\\\n",
    "u_{\\text{emp}, t} \\\\\n",
    "u_{\\text{indprod}, t-1} \\\\\n",
    "u_{\\text{income}, t-1} \\\\\n",
    "u_{\\text{sales}, t-1} \\\\\n",
    "u_{\\text{emp}, t-1} \\\\\n",
    "\\end{bmatrix}\n",
    "$$\n",
    "\n",
    "Notice that we have introduced two new state variables, $f_{t-2}$ and $f_{t-3}$, which means we need to update the  transition equation:\n",
    "\n",
    "$$\n",
    "\\begin{bmatrix}\n",
    "f_t \\\\\n",
    "f_{t-1} \\\\\n",
    "f_{t-2} \\\\\n",
    "f_{t-3} \\\\\n",
    "u_{\\text{indprod}, t} \\\\\n",
    "u_{\\text{income}, t} \\\\\n",
    "u_{\\text{sales}, t} \\\\\n",
    "u_{\\text{emp}, t} \\\\\n",
    "u_{\\text{indprod}, t-1} \\\\\n",
    "u_{\\text{income}, t-1} \\\\\n",
    "u_{\\text{sales}, t-1} \\\\\n",
    "u_{\\text{emp}, t-1} \\\\\n",
    "\\end{bmatrix} = \\begin{bmatrix}\n",
    "a_1 & a_2 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "1   & 0   & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "0   & 1   & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "0   & 0   & 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "0   & 0   & 0 & 0 & c_{\\text{indprod}, 1} & 0 & 0 & 0 & c_{\\text{indprod}, 2} & 0 & 0 & 0 \\\\\n",
    "0   & 0   & 0 & 0 & 0 & c_{\\text{income}, 1} & 0 & 0 & 0 & c_{\\text{income}, 2} & 0 & 0 \\\\\n",
    "0   & 0   & 0 & 0 & 0 & 0 & c_{\\text{sales}, 1} & 0 & 0 & 0 & c_{\\text{sales}, 2} & 0 \\\\\n",
    "0   & 0   & 0 & 0 & 0 & 0 & 0 & c_{\\text{emp}, 1} & 0 & 0 & 0 & c_{\\text{emp}, 2} \\\\\n",
    "0   & 0   & 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "0   & 0   & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "0   & 0   & 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "0   & 0   & 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\\\\n",
    "\\end{bmatrix} \n",
    "\\begin{bmatrix}\n",
    "f_{t-1} \\\\\n",
    "f_{t-2} \\\\\n",
    "f_{t-3} \\\\\n",
    "f_{t-4} \\\\\n",
    "u_{\\text{indprod}, t-1} \\\\\n",
    "u_{\\text{income}, t-1} \\\\\n",
    "u_{\\text{sales}, t-1} \\\\\n",
    "u_{\\text{emp}, t-1} \\\\\n",
    "u_{\\text{indprod}, t-2} \\\\\n",
    "u_{\\text{income}, t-2} \\\\\n",
    "u_{\\text{sales}, t-2} \\\\\n",
    "u_{\\text{emp}, t-2} \\\\\n",
    "\\end{bmatrix}\n",
    "+ R \\begin{bmatrix}\n",
    "\\eta_t \\\\\n",
    "\\varepsilon_{t}\n",
    "\\end{bmatrix}\n",
    "$$\n",
    "\n",
    "This model cannot be handled out-of-the-box by the `DynamicFactor` class, but it can be handled by creating a subclass when alters the state space representation in the appropriate way."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, notice that if we had set `factor_order = 4`, we would almost have what we wanted. In that case, the last line of the observation equation would be:\n",
    "\n",
    "$$\n",
    "\\begin{bmatrix}\n",
    "\\vdots \\\\\n",
    "y_{\\text{emp}, t} \\\\\n",
    "\\end{bmatrix} = \\begin{bmatrix}\n",
    "\\vdots &  &  &  &  &  &  &  &  &  &  & \\vdots \\\\\n",
    "\\lambda_\\text{emp,1}   & 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\\\\n",
    "\\end{bmatrix}\n",
    "\\begin{bmatrix}\n",
    "f_t \\\\\n",
    "f_{t-1} \\\\\n",
    "f_{t-2} \\\\\n",
    "f_{t-3} \\\\\n",
    "\\vdots\n",
    "\\end{bmatrix}\n",
    "$$\n",
    "\n",
    "\n",
    "and the first line of the transition equation would be:\n",
    "\n",
    "$$\n",
    "\\begin{bmatrix}\n",
    "f_t \\\\\n",
    "\\vdots\n",
    "\\end{bmatrix} = \\begin{bmatrix}\n",
    "a_1 & a_2 & a_3 & a_4 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\\\\n",
    "\\vdots &  &  &  &  &  &  &  &  &  &  & \\vdots \\\\\n",
    "\\end{bmatrix} \n",
    "\\begin{bmatrix}\n",
    "f_{t-1} \\\\\n",
    "f_{t-2} \\\\\n",
    "f_{t-3} \\\\\n",
    "f_{t-4} \\\\\n",
    "\\vdots\n",
    "\\end{bmatrix}\n",
    "+ R \\begin{bmatrix}\n",
    "\\eta_t \\\\\n",
    "\\varepsilon_{t}\n",
    "\\end{bmatrix}\n",
    "$$\n",
    "\n",
    "Relative to what we want, we have the following differences:\n",
    "\n",
    "1. In the above situation, the $\\lambda_{\\text{emp}, j}$ are forced to be zero for $j > 0$, and we want them to be estimated as parameters.\n",
    "2. We only want the factor to transition according to an AR(2), but under the above situation it is an AR(4).\n",
    "\n",
    "Our strategy will be to subclass `DynamicFactor`, and let it do most of the work (setting up the state space representation, etc.) where it assumes that `factor_order = 4`. The only things we will actually do in the subclass will be to fix those two issues.\n",
    "\n",
    "First, here is the full code of the subclass; it is discussed below. It is important to note at the outset that none of the methods defined below could have been omitted. In fact, the methods `__init__`, `start_params`, `param_names`, `transform_params`, `untransform_params`, and `update` form the core of all state space models in Statsmodels, not just the `DynamicFactor` class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from statsmodels.tsa.statespace import tools\n",
    "class ExtendedDFM(sm.tsa.DynamicFactor):\n",
    "    def __init__(self, endog, **kwargs):\n",
    "            # Setup the model as if we had a factor order of 4\n",
    "            super(ExtendedDFM, self).__init__(\n",
    "                endog, k_factors=1, factor_order=4, error_order=2,\n",
    "                **kwargs)\n",
    "\n",
    "            # Note: `self.parameters` is an ordered dict with the\n",
    "            # keys corresponding to parameter types, and the values\n",
    "            # the number of parameters of that type.\n",
    "            # Add the new parameters\n",
    "            self.parameters['new_loadings'] = 3\n",
    "\n",
    "            # Cache a slice for the location of the 4 factor AR\n",
    "            # parameters (a_1, ..., a_4) in the full parameter vector\n",
    "            offset = (self.parameters['factor_loadings'] +\n",
    "                      self.parameters['exog'] +\n",
    "                      self.parameters['error_cov'])\n",
    "            self._params_factor_ar = np.s_[offset:offset+2]\n",
    "            self._params_factor_zero = np.s_[offset+2:offset+4]\n",
    "\n",
    "    @property\n",
    "    def start_params(self):\n",
    "        # Add three new loading parameters to the end of the parameter\n",
    "        # vector, initialized to zeros (for simplicity; they could\n",
    "        # be initialized any way you like)\n",
    "        return np.r_[super(ExtendedDFM, self).start_params, 0, 0, 0]\n",
    "    \n",
    "    @property\n",
    "    def param_names(self):\n",
    "        # Add the corresponding names for the new loading parameters\n",
    "        #  (the name can be anything you like)\n",
    "        return super(ExtendedDFM, self).param_names + [\n",
    "            'loading.L%d.f1.%s' % (i, self.endog_names[3]) for i in range(1,4)]\n",
    "\n",
    "    def transform_params(self, unconstrained):\n",
    "            # Perform the typical DFM transformation (w/o the new parameters)\n",
    "            constrained = super(ExtendedDFM, self).transform_params(\n",
    "            unconstrained[:-3])\n",
    "\n",
    "            # Redo the factor AR constraint, since we only want an AR(2),\n",
    "            # and the previous constraint was for an AR(4)\n",
    "            ar_params = unconstrained[self._params_factor_ar]\n",
    "            constrained[self._params_factor_ar] = (\n",
    "                tools.constrain_stationary_univariate(ar_params))\n",
    "\n",
    "            # Return all the parameters\n",
    "            return np.r_[constrained, unconstrained[-3:]]\n",
    "\n",
    "    def untransform_params(self, constrained):\n",
    "            # Perform the typical DFM untransformation (w/o the new parameters)\n",
    "            unconstrained = super(ExtendedDFM, self).untransform_params(\n",
    "                constrained[:-3])\n",
    "\n",
    "            # Redo the factor AR unconstraint, since we only want an AR(2),\n",
    "            # and the previous unconstraint was for an AR(4)\n",
    "            ar_params = constrained[self._params_factor_ar]\n",
    "            unconstrained[self._params_factor_ar] = (\n",
    "                tools.unconstrain_stationary_univariate(ar_params))\n",
    "\n",
    "            # Return all the parameters\n",
    "            return np.r_[unconstrained, constrained[-3:]]\n",
    "\n",
    "    def update(self, params, transformed=True, complex_step=False):\n",
    "        # Peform the transformation, if required\n",
    "        if not transformed:\n",
    "            params = self.transform_params(params)\n",
    "        params[self._params_factor_zero] = 0\n",
    "        \n",
    "        # Now perform the usual DFM update, but exclude our new parameters\n",
    "        super(ExtendedDFM, self).update(params[:-3], transformed=True, complex_step=complex_step)\n",
    "\n",
    "        # Finally, set our new parameters in the design matrix\n",
    "        self.ssm['design', 3, 1:4] = params[-3:]\n",
    "        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So what did we just do?\n",
    "\n",
    "#### `__init__`\n",
    "\n",
    "The important step here was specifying the base dynamic factor model which we were operating with. In particular, as described above, we initialize with `factor_order=4`, even though we will only end up with an AR(2) model for the factor. We also performed some general setup-related tasks.\n",
    "\n",
    "#### `start_params`\n",
    "\n",
    "`start_params` are used as initial values in the optimizer. Since we are adding three new parameters, we need to pass those in. If we hadn't done this, the optimizer would use the default starting values, which would be three elements short.\n",
    "\n",
    "#### `param_names`\n",
    "\n",
    "`param_names` are used in a variety of places, but especially in the results class. Below we get a full result summary, which is only possible when all the parameters have associated names.\n",
    "\n",
    "#### `transform_params` and `untransform_params`\n",
    "\n",
    "The optimizer selects possibly parameter values in an unconstrained way. That's not usually desired (since variances can't be negative, for example), and `transform_params` is used to transform the unconstrained values used by the optimizer to constrained values appropriate to the model. Variances terms are typically squared (to force them to be positive), and AR lag coefficients are often constrained to lead to a stationary model. `untransform_params` is used for the reverse operation (and is important because starting parameters are usually specified in terms of values appropriate to the model, and we need to convert them to parameters appropriate to the optimizer before we can begin the optimization routine).\n",
    "\n",
    "Even though we don't need to transform or untransform our new parameters (the loadings can in theory take on any values), we still need to modify this function for two reasons:\n",
    "\n",
    "1. The version in the `DynamicFactor` class is expecting 3 fewer parameters than we have now. At a minimum, we need to handle the three new parameters.\n",
    "2. The version in the `DynamicFactor` class constrains the factor lag coefficients to be stationary as though it was an AR(4) model. Since we actually have an AR(2) model, we need to re-do the constraint. We also set the last two autoregressive coefficients to be zero here.\n",
    "\n",
    "#### `update`\n",
    "\n",
    "The most important reason we need to specify a new `update` method is because we have three new parameters that we need to place into the state space formulation. In particular we let the parent `DynamicFactor.update` class handle placing all the parameters except the three new ones in to the state space representation, and then we put the last three in manually."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# Create the model\n",
    "extended_mod = ExtendedDFM(endog)\n",
    "initial_extended_res = extended_mod.fit(maxiter=1000, disp=False)\n",
    "extended_res = extended_mod.fit(initial_extended_res.params, method='nm', maxiter=1000)\n",
    "print(extended_res.summary(separate_params=False))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Although this model increases the likelihood, it is not preferred by the AIC and BIC mesaures which penalize the additional three parameters.\n",
    "\n",
    "Furthermore, the qualitative results are unchanged, as we can see from the updated $R^2$ chart and the new coincident index, both of which are practically identical to the previous results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "extended_res.plot_coefficients_of_determination(figsize=(8,2));"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(13,3))\n",
    "\n",
    "# Compute the index\n",
    "extended_coincident_index = compute_coincident_index(extended_mod, extended_res)\n",
    "\n",
    "# Plot the factor\n",
    "dates = endog.index._mpl_repr()\n",
    "ax.plot(dates, coincident_index, '-', linewidth=1, label='Basic model')\n",
    "ax.plot(dates, extended_coincident_index, '--', linewidth=3, label='Extended model')\n",
    "ax.plot(usphci.index._mpl_repr(), usphci, label='USPHCI')\n",
    "ax.legend(loc='lower right')\n",
    "ax.set(title='Coincident indices, comparison')\n",
    "\n",
    "# Retrieve and also plot the NBER recession indicators\n",
    "ylim = ax.get_ylim()\n",
    "ax.fill_between(dates[:-3], ylim[0], ylim[1], rec.values[:,0], facecolor='k', alpha=0.1);"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.4.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
