Overview (Financial Time Series Toolbox)

Financial Time Series Toolbox

Using the Constructor

The object constructor function fints has five different syntaxes. These forms exist to simplify object construction. The syntaxes vary according to the types of input arguments presented to the constructor. The syntaxes are

Single Matrix Input

See Time-of-Day Information Excluded.
See Time-of-Day Information Included.

Separate Vector Input

See Time-of-Day Information Excluded.
See Time-of-Day Information Included.

Single Matrix Input

The date information provided with this syntax must be in serial date number format. The date number may or may not include time-of-day information.

Note If you are unfamiliar with the concepts of date strings and serial date numbers, consult the section Handling and Converting Dates in the Financial Toolbox documentation.

Time-of-Day Information Excluded.

```
fts = fints(dates_and_data)
```

In this simplest form of syntax, the input must be at least a two-column matrix. The first column contains the dates in serial date format; the second column is the data series. The input matrix can have more than two columns, each additional column representing a different data series or set of observations.

If the input is a two-column matrix, the output object contains four fields: desc, freq, dates, and series1. The description field, desc, defaults to blanks '', and the frequency indicator field, freq, defaults to 0. The dates field, dates, contains the serial dates from the first column of the input matrix, while the data series field, series1, has the data from the second column of the input matrix.

The first example makes two financial time series objects. The first one has only one data series, while the other has more than one. A random vector provides the values for the data series. The range of dates is arbitrarily chosen using the today function:

date_series = (today:today+100)';
data_series = exp(randn(1, 101))';
dates_and_data = [date_series data_series];
fts1 = fints(dates_and_data);

Examine the contents of the object fts1 just created. The actual date series you observe will vary according to the day when you run the example (the value of today). Also, your values in series1 will differ from those shown, depending upon the sequence of random numbers generated:

fts1 = 

    desc:  (none)
    freq:  Unknown (0)

    'dates:  (101)'    'series1:  (101)'
    '12-Jul-1999'      [         0.3124]
    '13-Jul-1999'      [         3.2665]
    '14-Jul-1999'      [         0.9847]
    '15-Jul-1999'      [         1.7095]
    '16-Jul-1999'      [         0.4885]
    '17-Jul-1999'      [         0.5192]
    '18-Jul-1999'      [         1.3694]
    '19-Jul-1999'      [         1.1127]
    '20-Jul-1999'      [         6.3485]
    '21-Jul-1999'      [         0.7595]
    '22-Jul-1999'      [         9.1390]
    '23-Jul-1999'      [         4.5201]
    '24-Jul-1999'      [         0.1430]
    '25-Jul-1999'      [         0.1863]
    '26-Jul-1999'      [         0.5635]
    '27-Jul-1999'      [         0.8304]
    '28-Jul-1999'      [         1.0090]...

The output is truncated for brevity. There are actually 101 data points in the object.

Note that the desc field displays as (none) instead of '', and that the contents of the object display as cell array elements. Although the object displays as such, it should be thought of as a MATLAB structure containing the default field names for a single data series object: desc, freq, dates, and series1.

Now create an object with more than one data series in it:

date_series = (today:today+100)';
data_series1 = exp(randn(1, 101))';
data_series2 = exp(randn(1, 101))';
dates_and_data = [date_series data_series1 data_series2];
fts2 = fints(dates_and_data);

Now look at the object created (again in abbreviated form):

fts2 = 

    desc:  (none)
    freq:  Unknown (0)

    'dates:  (101)'    'series1:  (101)'    'series2:  (101)'
    '12-Jul-1999'      [         0.5816]    [         1.2816]
    '13-Jul-1999'      [         5.1253]    [         0.9262]
    '14-Jul-1999'      [         2.2824]    [         5.6869]
    '15-Jul-1999'      [         1.2596]    [         5.0631]
    '16-Jul-1999'      [         1.9574]    [         1.8709]
    '17-Jul-1999'      [         0.6017]    [         1.0962]
    '18-Jul-1999'      [         2.3546]    [         0.4459]
    '19-Jul-1999'      [         1.3080]    [         0.6304]
    '20-Jul-1999'      [         1.8682]    [         0.2451]
    '21-Jul-1999'      [         0.3509]    [         0.6876]
    '22-Jul-1999'      [         4.6444]    [         0.6244]
    '23-Jul-1999'      [         1.5441]    [         5.7621]
    '24-Jul-1999'      [         0.1470]    [         2.1238]
    '25-Jul-1999'      [         1.5999]    [         1.0671]
    '26-Jul-1999'      [         3.5764]    [         0.7462]
    '27-Jul-1999'      [         1.8937]    [         1.0863]
    '28-Jul-1999'      [         3.9780]    [         2.1516]...

The second data series name defaults to series2, as expected.

Before you can perform any operations on the object, you must set the frequency indicator field freq to the valid frequency of the data series contained in the object. You may leave the description field desc blank.

To set the frequency indicator field to a daily frequency, enter

fts2.freq = 1, or

fts2.freq = 'daily'

See the fints function description in the Function Reference for a list of frequency indicators.

Time-of-Day Information Included.

The serial date number used with this form of the fints function can incorporate time-of-day information. When time-of-day information is present, the output of the function contains a field times that indicates the time of day.

If you recode a previous example to include time-of-day information, you can see the additional column present in the output object:

time_series = (now:now+100)';
data_series = exp(randn(1, 101))';
times_and_data = [time_series data_series];
fts1 = fints(times_and_data);

fts1 = 
 
    desc:  (none)
    freq:  Unknown (0)

    'dates:  (101)'    'times:  (101)'    'series1:  (101)'
    '29-Nov-2001'      '14:57'            [         0.5816]
    '30-Nov-2001'      '14:57'            [         5.1253]
    '01-Dec-2001'      '14:57'            [         2.2824]
    '02-Dec-2001'      '14:57'            [         1.2596]...

Separate Vector Input

The date information provided with this syntax may be in serial date number or date string format. The date information may or may not include time-of-day information.

Time-of-Day Information Excluded.

```
fts = fints(dates, data)
```

In this second syntax the dates and data series are entered as separate vectors to fints, the financial time series object constructor function. The dates vector must be a column vector, while the data series data can be a column vector (if there is only one data series) or a column-oriented matrix (for multiple data series). A column-oriented matrix, in this context, indicates that each column is a set of observations. Different columns are different sets of data series.

Here is an example:

dates = (today:today+100)';
data_series1 = exp(randn(1, 101))';
data_series2 = exp(randn(1, 101))';
data = [data_series1 data_series2];
fts = fints(dates, data)
fts = 

    desc:  (none)
    freq:  Unknown (0)

    'dates:  (101)'    'series1:  (101)'    'series2:  (101)'
    '12-Jul-1999'      [         0.5816]    [         1.2816]
    '13-Jul-1999'      [         5.1253]    [         0.9262]
    '14-Jul-1999'      [         2.2824]    [         5.6869]
    '15-Jul-1999'      [         1.2596]    [         5.0631]
    '16-Jul-1999'      [         1.9574]    [         1.8709]
    '17-Jul-1999'      [         0.6017]    [         1.0962]
    '18-Jul-1999'      [         2.3546]    [         0.4459]
    '19-Jul-1999'      [         1.3080]    [         0.6304]
    '20-Jul-1999'      [         1.8682]    [         0.2451]
    '21-Jul-1999'      [         0.3509]    [         0.6876]
    '22-Jul-1999'      [         4.6444]    [         0.6244]
    '23-Jul-1999'      [         1.5441]    [         5.7621]
    '24-Jul-1999'      [         0.1470]    [         2.1238]
    '25-Jul-1999'      [         1.5999]    [         1.0671]
    '26-Jul-1999'      [         3.5764]    [         0.7462]
    '27-Jul-1999'      [         1.8937]    [         1.0863]
    '28-Jul-1999'      [         3.9780]    [         2.1516]...

The result is exactly the same as the first syntax. The only difference between the first and second syntax is the way the inputs are entered into the constructor function.

Time-of-Day Information Included.

With this form of the function you can enter the time-of-day information either as a serial date number or as a date string. If more than one serial date and time is present, the entry must be in the form of a column-oriented matrix. If more than one string date and time is present, the entry must be a column-oriented cell array of dates and times.

With date string input the dates and times can initially be separate column-oriented date and time series, but you must concatenate them into a single column-oriented cell array before entering them as the first input to fints.

For date string input the allowable formats are:

'ddmmmyy hh:mm' or 'ddmmmyyyy hh:mm'
'mm/dd/yy hh:mm' or 'mm/dd/yyyy hh:mm'
'dd-mmm-yy hh:mm' or 'dd-mmm-yyyy hh:mm'
'mmm.dd,yy hh:mm' or 'mmm.dd,yyyy hh:mm'

The next example shows time-of-day information input as serial date numbers in a column-oriented matrix:

f = fints([now;now+1],(1:2)')

f = 
 
    desc:  (none)
    freq:  Unknown (0)

    'dates:  (2)'    'times:  (2)'    'series1:  (2)'
    '29-Nov-2001'    '15:22'          [            1]
    '30-Nov-2001'    '15:22'          [            2]

If the time-of-day information is in date string format, you must provide it to fints as a column-oriented cell array:

f = fints({'01-Jan-2001 12:00';'02-Jan-2001 12:00'},(1:2)')

f = 
 
    desc:  (none)
    freq:  Unknown (0)

    'dates:  (2)'    'times:  (2)'    'series1:  (2)'
    '01-Jan-2001'    '12:00'          [            1]
    '02-Jan-2001'    '12:00'          [            2]

If the dates and times are in date string format and contained in separate matrices, you must concatenate them before using the date and time information as input to fints:

dates = ['01-Jan-2001'; '02-Jan-2001'; '03-Jan-2001'];
times = ['12:00';'12:00';'12:00'];
dates_time = cellstr([dates,repmat(' ',size(dates,1),1),times]);
f = fints(dates_time,(1:3)')

f = 
 
    desc:  (none)
    freq:  Unknown (0)

    'dates:  (3)'    'times:  (3)'    'series1:  (3)'
    '01-Jan-2001'    '12:00'          [            1]
    '02-Jan-2001'    '12:00'          [            2]
    '03-Jan-2001'    '12:00'          [            3]

Data Name Input

```
fts = fints(dates, data, datanames)
```

The third syntax lets you specify the names for the data series with the argument datanames. The datanames argument may be a MATLAB string for a single data series. For multiple data series names, it must be a cell array of string(s).

Look at two examples, one with a single data series and a second with two. The first example sets the data series name to the specified name First:

dates = (today:today+100)';
data = exp(randn(1, 101))';
fts1 = fints(dates, data, 'First')

fts1 = 

    desc:  (none)
    freq:  Unknown (0)

    'dates:  (101)'    'First:  (101)'
    '12-Jul-1999'      [       0.4615]
    '13-Jul-1999'      [       1.1640]
    '14-Jul-1999'      [       0.7140]
    '15-Jul-1999'      [       2.6400]
    '16-Jul-1999'      [       0.8983]
    '17-Jul-1999'      [       2.7552]
    '18-Jul-1999'      [       0.6217]
    '19-Jul-1999'      [       1.0714]
    '20-Jul-1999'      [       1.4897]
    '21-Jul-1999'      [       3.0536]
    '22-Jul-1999'      [       1.8598]
    '23-Jul-1999'      [       0.7500]
    '24-Jul-1999'      [       0.2537]
    '25-Jul-1999'      [       0.5037]
    '26-Jul-1999'      [       1.3933]
    '27-Jul-1999'      [       0.3687]...

The second example provides two data series named First and Second:

dates = (today:today+100)';
data_series1 = exp(randn(1, 101))';
data_series2 = exp(randn(1, 101))';
data = [data_series1 data_series2];
fts2 = fints(dates, data, {'First', 'Second'})

fts2 = 
    desc:  (none)
    freq:  Unknown (0)

    'dates:  (101)'    'First:  (101)'    'Second:  (101)'
    '12-Jul-1999'      [       1.2305]    [        0.7396]
    '13-Jul-1999'      [       1.2473]    [        2.6038]
    '14-Jul-1999'      [       0.3657]    [        0.5866]
    '15-Jul-1999'      [       0.6357]    [        0.4061]
    '16-Jul-1999'      [       4.0530]    [        0.4096]
    '17-Jul-1999'      [       0.6300]    [        1.3214]
    '18-Jul-1999'      [       1.0333]    [        0.4744]
    '19-Jul-1999'      [       2.2228]    [        4.9702]
    '20-Jul-1999'      [       2.4518]    [        1.7758]
    '21-Jul-1999'      [       1.1479]    [        1.3780]
    '22-Jul-1999'      [       0.1981]    [        0.8595]
    '23-Jul-1999'      [       0.1927]    [        1.3713]
    '24-Jul-1999'      [       1.5353]    [        3.8332]
    '25-Jul-1999'      [       0.4784]    [        0.1067]
    '26-Jul-1999'      [       1.7593]    [        3.6434]
    '27-Jul-1999'      [       0.2505]    [        0.6849]
    '28-Jul-1999'      [       1.5845]    [        1.0025]...

Note Data series names must be valid MATLAB variable names. The only allowed nonalphanumeric character is the underscore (_) character.

Because freq for fts2 has not been explicitly indicated, the frequency indicator for fts2 is set to Unknown. Set the frequency indicator field freq before you attempt any operations on the object. You will not be able to use the object until the frequency indicator field is set to a valid indicator.

Frequency Indicator Input

fts = fints(dates, data, datanames, freq)

With the fourth syntax you can set the frequency indicator field when you create the financial time series object. The frequency indicator field freq is set as the fourth input argument. You will not be able to use the financial time series object until freq is set to a valid indicator. Valid frequency indicators are

UNKNOWN, Unknown, unknown, U, u,0
DAILY, Daily, daily, D, d,1     
WEEKLY, Weekly, weekly, W, w,2     
MONTHLY, Monthly, monthly, M, m,3     
QUARTERLY, Quarterly, quarterly, Q, q,4     
SEMIANNUAL, Semiannual, semiannual, S, s,5   
ANNUAL, Annual, annual, A, a,6

The previous example contained sets of daily data. The freq field displayed as Unknown (0) because the frequency indicator was not explicitly set. The command

fts = fints(dates, data, {'First', 'Second'}, 1);

sets the freq indicator to Daily(1) when creating the financial time series object:

fts = 

    desc:  (none)
    freq:  Daily (1)

    'dates:  (101)'    'First:  (101)'    'Second:  (101)'
    '12-Jul-1999'      [       1.2305]    [        0.7396]
    '13-Jul-1999'      [       1.2473]    [        2.6038]
    '14-Jul-1999'      [       0.3657]    [        0.5866]
    '15-Jul-1999'      [       0.6357]    [        0.4061]
    '16-Jul-1999'      [       4.0530]    [        0.4096]
    '17-Jul-1999'      [       0.6300]    [        1.3214]
    '18-Jul-1999'      [       1.0333]    [        0.4744]...

When you create the object using this syntax, you can use the other valid frequency indicators for a particular frequency. For a daily data set you can use DAILY, Daily, daily, D, or d. Similarly, with the other frequencies, you can use the valid string indicators or their numeric counterparts.

Description Field Input

fts = fints(dates, data, datanames, freq, desc)

With the fifth syntax you can explicitly set the description field as the fifth input argument. The description can be anything you want. It is not used in any operations performed on the object.

This example sets the desc field to 'Test TS'.

dates = (today:today+100)';
data_series1 = exp(randn(1, 101))';
data_series2 = exp(randn(1, 101))';
data = [data_series1 data_series2];
fts = fints(dates, data, {'First', 'Second'}, 1, 'Test TS')

fts = 
    desc:  Test TS
    freq:  Daily (1)

    'dates:  (101)'    'First:  (101)'    'Second:  (101)'
    '12-Jul-1999'      [       0.5428]    [        1.2491]
    '13-Jul-1999'      [       0.6649]    [        6.4969]
    '14-Jul-1999'      [       0.2428]    [        1.1163]
    '15-Jul-1999'      [       1.2550]    [        0.6628]
    '16-Jul-1999'      [       1.2312]    [        1.6674]
    '17-Jul-1999'      [       0.4869]    [        0.3015]
    '18-Jul-1999'      [       2.1335]    [        0.9081]...

Now the description field is filled with the specified string 'Test TS' when the constructor is called.

Creating Financial Time Series Objects Transforming a Text File