function Data = Example_USEconData(EndDate)
%EXAMPLE_USECONDATA Load FRED economic data for U.S. Economy Example
%
% Syntax:
%
%   Data = Example_USEconData
%   Data = Example_USEconData(EndDate)
%
% Description:
%
%   Load data from St. Louis Federal Reserve Economic Database (FRED) used
%   in the example "Modeling the United States Economy" in Econometrics 
%   Toolbox. The first observation returned occurs at 1957:Q1 (31-Mar-1957).
%   By default, the most recent data available from FRED is returned. The
%   data is returned in a timetable.
%
%   An optional ending date (EndDate) of the last observation returned is 
%   specified as a datetime scalar. For example, the following command returns 
%   economic time series data from 1957:Q1 to 2012:Q4, inclusive, in timetable
%   Data:
%
%   Data =  Example_USEconData(datetime(2012,12,31));
%
%   in which (Year,Month,Day) triplet (2012,12,31) indicates '31-Dec-2012'.
%
%   The series loaded are:
%
%   FRED Series   Description
%   ------------  ----------------------------------------------------------------------------
%   GDP           Gross Domestic Product (USD billions, Quarterly)
%   GDPDEF        Gross Domestic Product Implicit Price Deflator 
%                 (Index 2009 = 100, Quarterly)
%   COE           Paid Compensation of Employees (USD billions, Quarterly)
%   HOANBS        Nonfarm Business Sector Hours of All Persons 
%                 (Index 2009 = 100, Quarterly)
%   FEDFUNDS      Effective Federal Funds Rate (Annualized, Percent, Monthly)
%   PCEC          Personal Consumption Expenditures (USD billions, Quarterly) 
%   GPDI          Gross Private Domestic Investment (USD billions, Quarterly)
%
%   All data, regardless of the reporting frequency, is reported by FRED at 
%   the beginning of each period. With the exception of Federal Funds, all 
%   series are seasonally adjusted and reported quarterly at the beginning 
%   of each quarter. Federal funds are reported monthly at the beginning of 
%   each month. 
%
%   The observations in timetable Data are synchronized to a quarterly 
%   periodicity with an end-of-quarter reporting convention.
%
%   For example, FRED reports 2012:Q1 GDP dated 01-Jan-2012 and 2012:M3 Federal
%   Funds dated 01-Mar-2012. When synchronized to a common end-of-quarter
%   periodicity both series are associated with 31-Mar-2012, the last day of 
%   the first quarter of 2012. For any given year YYYY, the data for Q1, Q2, 
%   Q3, and Q4 correspond to 31-Mar-YYYY, 30-Jun-YYYY, 30-Sep-YYYY, and 
%   31-Dec-YYYY, respectively.

% Copyright 2018 The MathWorks, Inc.

%
% Set the FRED time series loaded and returned.
%

series = {'GDP', 'GDPDEF', 'COE', 'HOANBS', 'FEDFUNDS', 'PCEC', 'GPDI'};
        
%
% Open Datafeed Toolbox connection to FRED.
%

connection = fred;

%
% Fetch the FRED data and merge into a timetable.
%

Data  = timetable;        % Initialize the timetable

for i = 1:numel(series)
%
%   Fetch data from FRED.
%
    FredData = fetch(connection, series{i});
%
%   Convert FRED serial date numbers to datetimes needed by timetable.
%
    Time = datetime(FredData.Data(:,1), 'ConvertFrom', 'datenum');
%
%   Create the time table (TT) to store the FRED time series.
%
    TT = timetable(Time, FredData.Data(:,2), 'VariableNames', series(i));
%
%   Synchronize/merge the time series retaining all available dates.
%
    Data = synchronize(Data, TT, 'union');
end

close(connection);

%
% Adjust the data to report the last non-NaN value (i.e., ignore missing 
% values) of each series that occurs in each quarter. 
%
% For quarterly data reported at the beginning of each quarter, this removes 
% missing observations (NaNs) but does not otherwise change the dates 
% associated with non-missing data. 
%
% For monthly FEDFUNDS reported at the beginning of each month, it reports 
% the last monthly observation in each quarter at the beginning of the quarter, 
% and therefore converts the monthly series to a quarterly periodicity.
%

Data = retime(Data, 'quarterly', 'lastvalue');

%
% Convert beginning-of-quarter dates to end-of-quarter dates.
%

Data.Time = dateshift(Data.Time, 'end', 'quarter');

%
% Trim the date range to start at 1957:Q1, then retain the most recent data
% by default.
%

StartDate = datetime(1957, 3, 31); % (Year,Month,Day) triplet = '31-Mar-1957'

if nargin == 0
   EndDate = Data.Time(end);
end

Data = Data(timerange(StartDate, EndDate, 'closed'), :);
Data = rmmissing(Data, 1);
Data.Properties.Description = 'U.S. Quarterly Macroeconomic Data';

end