%% Work with State Transitions
% This example shows how to work with transition data from an empirical array of state counts, and create a discrete-time Markov chain (dtmc) model characterizing state transitions. For each quarter in 1857–2019, the example categorizes the state of the US economy as experiencing a recession or expansion by using historical recession periods defined by the National Bureau of Economic Research (NBER). Then, the example forms the empirical transition matrix by counting the quarter-to-quarter transitions of the economic state.
%% Load and Process Data
% Load the historical, NBER-defined recession start and end dates.

load Data_Recessions

% The Recessions variable in the workspace is a 33-by-2 matrix of serial date numbers.  Rows of Recessions correspond to successive periods of recession, and columns 1 and 2 contain the start and end dates, respectively.  For more details, enter Description at the command line.
% Because MATLAB® datetime arrays enable you to work with date data efficiently, convert Recessions to a datetime array.  Specify the date format yyyy-MM-dd. Visually compare the data types of the first few periods and the last few periods.

NBERRec = datetime(Recessions,'ConvertFrom',"datenum",...
    "Format","yyyy-MM-dd");
disptbl = table(Recessions,NBERRec);
head(disptbl,3)
tail(disptbl,3)

%
%% Create Array of Visited States
% Assume that the sampling period begins on NBERRec(1,1) = 1857-06-15 and ends on 2019-05-03. Create a datetime array of all consecutive quarters in the interval 1857-06-15 though 2019-05-03.

timeline = NBERRec(1,1):calquarters(1):datetime("2019-05-03");
T = numel(timeline); % Sample size

% Identify which quarters occur during a recession.

isrecession = @(x)any(isbetween(x,NBERRec(:,1),NBERRec(:,2)));
idxrecession = arrayfun(isrecession,timeline);

% Create a MATLAB® timetable containing a variable that identifies the economic state of each quarter in the sampling period. Display the first few observations and the last few observations in the timetable.

EconState = repmat("Expansion",T,1); % Preallocation
EconState(idxrecession) = "Recession";

Tbl = timetable(EconState,'RowTimes',timeline);
head(Tbl,3)
tail(Tbl,3)

% Tbl is a data set of the observed, quarterly economic states, from which transitions can be counted.
%
%% Count State Transitions
% Consider creating a 2-by-2 matrix containing the number of:
% Transitions from a recession to an expansion
% Transitions from an expansion to a recession
% Self-transitions of recessions
% Self-transitions of expansions
% Row j and column j of the matrix correspond to the same economic state, and element \left(j,k\right) contains the number of transitions from state j to state k.
% First, assign indices to members of the state space.

[idxstate,states] = grp2idx(Tbl.EconState);
states
numstates = numel(states);
P = zeros(numstates); % Preallocate transition matrix

% The state indices idxstate correspond to states (rows and columns) of the transition matrix, and states defines the indices. P(1,1) is the number of self-transitions of recessions, P(1,2) is the number of transitions from a recession to an expansion, and so on. Therefore, to count the transition types in the data efficiently, for every transition t to t+1, tally the observed transition by indexing into the transition matrix using state indices at times t (row) and t+1 (column).

for t = 1:(T - 1)
    P(idxstate(t),idxstate(t+1)) = P(idxstate(t),idxstate(t+1)) + 1;
end

array2table(P,'VariableNames',states,'RowNames',states)

% P is the matrix of observed transitions. P(1,2) = 33 means that the US economy transitioned from a recession to an expansion 33 times between 15-Jun-1857 and 03-May-2019.
%
%% Create Discrete-Time Markov Chain
% Create a discrete-time Markov chain model characterized by the transition matrix P.

mc = dtmc(P,'StateNames',states);
array2table(mc.P,'VariableNames',states,'RowNames',states)

% mc is a dtmc object. dtmc normalizes P to create the right-stochastic transition matrix mc.P (each row sums to 1).  The element mc.P(1,2) = 0.1618 means that the empirical probability of transitioning to an expansion at time t + 1, given that the US economy is in a recession at time t, is 0.1618.
% Plot a directed graph of the Markov chain.

graphplot(mc,'LabelEdges',true)

% The Markov chain suggests that the current economic state tends to persist, from quarter to quarter.
% Copyright 2019 The MathWorks, Inc.