toannual

Convert to annual

toannual is not recommended. Use convert2annual instead.

Syntax

newfts = toannual(oldfts)
newfts = toannual(oldfts,'ParameterName',ParameterValue, ...)

Arguments

oldfts

Financial time series object.

Description

newfts = toannual(oldfts) converts a financial time series of any frequency to one of an annual frequency. The default end-of-year is the last business day of the December. toannual uses holidays.m to determine valid trading days.

Note

If oldfts contains time-of-day information, newfts displays the time-of-day as '00:00' for those days that did not previously exist in oldfts.

Empty ([ ]) passed as inputs for parameter pair values for toannual triggers the use of the defaults.

newfts = toannual(oldfts,'ParameterName',ParameterValue, ...) accepts parameter name/parameter value pairs as input, as specified in the following table.

Parameter Name	Parameter Value	Description
CalcMethod	CumSum	Returns the cumulative sum of the values within each year. Data for missing dates are given the value 0.
CalcMethod	Exact	Returns the exact value at the end-of-year date. No data manipulation occurs.
CalcMethod	Nearest	(Default) Returns the values located at the end-of-year dates. If there is missing data, Nearest returns the nearest data point preceding the end-of-year date.
CalcMethod	SimpAvg	Returns an averaged annual value that only takes into account dates with data (non-NaN) within each year.
CalcMethod	v21x	This mode is compatible with previous versions of this function (Version 2.1.x and earlier). It returns an averaged end-of-year value using a previous toannual algorithm. This algorithm takes into account all dates and data. For dates that do not contain any data, the data is assumed to be 0.
Note If you set CalcMethod to v21x, settings for all the following parameter name/parameter value pairs are not supported.
BusDays	0	Returns a financial time series that ranges from (or between) the first date to the last date in oldfts (includes NYSE nonbusiness days and holidays).
BusDays	1	(Default) Generates a monthly financial time series that ranges from the first date to the last date in oldfts (excludes NYSE nonbusiness days and holidays and weekends based on AltHolidays and Weekend). If an end-of-month date falls on a nonbusiness day or NYSE holiday, returns the last business day of the month. NYSE market closures, holidays, and weekends are observed if AltHolidays and Weekend are not supplied or empty ([]).
DateFilter	Absolute	(Default) Returns all annual dates between the start and end dates of oldfts. Some dates may be disregarded if BusDays = 1. Note The default is to create a time series with every date at the specified periodicity, which is with DateFilter = Absolute. If you use DateFilter = Relative, the endpoint effects do not apply since only your data defines which dates appear in the output time series object.
DateFilter	Relative	Returns only the annual dates that exist in oldfts. Some dates may be disregarded if BusDays = 1.
ED	0	Annual period ends on the last day or last business day of the month.
ED	1 - 31	Specifies a particular annual day. Months that do not contain the specified day return the last day (or last business day) of the month (for example, ED = 31 does not exist for February.)
EM	1 - 12	(Default) The annual period ends on the last day (or last business day) of the specified month. All subsequent annual dates are calculated from this month. Default annual month is December (12).
EndPtTol	[Begin, End]	Denotes the minimum number of days that constitute an odd annual period at the endpoints of the time series (before the first-time series date and after the last end-of-year date). Begin and End must be -1 or any positive integer greater than or equal to 0. A single value input for 'EndPtTol' is the same as specifying that single value for Begin and End. -1   Exclude odd annual period dates and data from calculations. 0    (Default) Include odd annual period dates and data in calculations. n   Number of days (any positive integer) that constitute an odd annual period. If there are insufficient days for a complete year, the endpoint data is ignored.
The following diagram is a general depiction of the factors involved in the determination of endpoints for this function.
TimeSpec	First	Returns only the observation that occurs at the first (earliest) time for a specific date.
TimeSpec	Last	(Default) Returns only the observation that occurs at the last (latest) time for a specific date.
AltHolidays		Vector of dates specifying an alternate set of market closure dates.
AltHolidays	-1	Excludes all holidays.
Weekend		Vector of length 7 containing 0's and 1's. The value 1 indicates a weekend day. The first element of this vector corresponds to Sunday. For example, when Saturday and Sunday are weekend days (default) then Weekend = [1 0 0 0 0 0 1].

Examples

Transform Time Series Object from Weekly to Annual Values

This example shows how to transform a time series object from weekly to annual values.

Load the data from the file predict_ret_data.mat and use the fints function to create a time series object with a weekly frequency.

load predict_ret_data.mat
x0 = fints(expdates, expdata, {'Metric'}, 'w', 'Index')

Warning: FINTS is not recommended. Use TIMETABLE instead. For more information, see <a href="matlab:web(fullfile(docroot, 'finance/convert-from-fints-to-timetables.html'))">Convert Financial Time Series Objects (fints) to Timetables</a>.

 
x0 = 
 
    desc:  Index
    freq:  Weekly (2)

    {'dates:  (53)'}    {'Metric:  (53)'}
    {'01-Jan-1999' }    {[      97.8872]}
    {'08-Jan-1999' }    {[      97.0847]}
    {'15-Jan-1999' }    {[     109.6312]}
    {'22-Jan-1999' }    {[     105.5743]}
    {'29-Jan-1999' }    {[     108.4028]}
    {'05-Feb-1999' }    {[     134.4882]}
    {'12-Feb-1999' }    {[     117.5581]}
    {'19-Feb-1999' }    {[     106.6683]}
    {'26-Feb-1999' }    {[     118.2912]}
    {'05-Mar-1999' }    {[     105.6835]}
    {'12-Mar-1999' }    {[     128.5836]}
    {'19-Mar-1999' }    {[     115.1746]}
    {'26-Mar-1999' }    {[     131.2854]}
    {'02-Apr-1999' }    {[     130.7116]}
    {'09-Apr-1999' }    {[     123.1684]}
    {'16-Apr-1999' }    {[     107.2975]}
    {'23-Apr-1999' }    {[      91.5625]}
    {'30-Apr-1999' }    {[      78.5738]}
    {'07-May-1999' }    {[      65.2904]}
    {'14-May-1999' }    {[      70.8581]}
    {'21-May-1999' }    {[      72.4807]}
    {'28-May-1999' }    {[      72.9190]}
    {'04-Jun-1999' }    {[      64.3460]}
    {'11-Jun-1999' }    {[      59.8743]}
    {'18-Jun-1999' }    {[      55.0026]}
    {'25-Jun-1999' }    {[      49.4032]}
    {'02-Jul-1999' }    {[      49.9485]}
    {'09-Jul-1999' }    {[      47.8061]}
    {'16-Jul-1999' }    {[      61.0517]}
    {'23-Jul-1999' }    {[      58.9313]}
    {'30-Jul-1999' }    {[      53.9584]}
    {'06-Aug-1999' }    {[      44.8472]}
    {'13-Aug-1999' }    {[      45.0463]}
    {'20-Aug-1999' }    {[      45.1088]}
    {'27-Aug-1999' }    {[      56.4897]}
    {'03-Sep-1999' }    {[      61.2449]}
    {'10-Sep-1999' }    {[      58.1012]}
    {'17-Sep-1999' }    {[      50.8974]}
    {'24-Sep-1999' }    {[      46.5143]}
    {'01-Oct-1999' }    {[      38.0806]}
    {'08-Oct-1999' }    {[      33.6664]}
    {'15-Oct-1999' }    {[      34.2992]}
    {'22-Oct-1999' }    {[      33.4202]}
    {'29-Oct-1999' }    {[      36.9287]}
    {'05-Nov-1999' }    {[      35.1278]}
    {'12-Nov-1999' }    {[      41.8128]}
    {'19-Nov-1999' }    {[      35.8199]}
    {'26-Nov-1999' }    {[      36.9495]}
    {'03-Dec-1999' }    {[      36.2880]}
    {'10-Dec-1999' }    {[      33.8457]}
    {'17-Dec-1999' }    {[      33.3868]}
    {'24-Dec-1999' }    {[      32.7737]}
    {'31-Dec-1999' }    {[      28.5665]}

Use toannual to obtain the annual aggregate for the x0 times series.

x1 = toannual(x0)

Warning: FINTS is not recommended. Use convert2annual instead.

 
x1 = 
 
    desc:  TOANNUAL: Index
    freq:  Annual (6)

    {'dates:  (1)'}    {'Metric:  (1)'}
    {'31-Dec-1999'}    {[     28.5665]}