ts2func

Convert time series arrays to functions of time and state

Syntax

F = ts2func(Array)

F = ts2func(___,Name,Value)

Description

F = ts2func(Array) encapsulates a time series array associated with a vector of real-valued observation times within a MATLAB^® function suitable for Monte Carlo simulation of an NVars-by-1 state vector X_t.

n periods.

F = ts2func(___,Name,Value) adds optional name-value pair arguments.

Examples

Dynamic Behavior of Market Parameters

As discussed in Creating SDE Objects, object parameters may be evaluated as if they are MATLAB® functions accessible by a common interface. This accessibility provides the impression of dynamic behavior regardless of whether the underlying parameters are truly time-varying. Furthermore, because parameters are accessible by a common interface, seemingly simple linear constructs may in fact represent complex, nonlinear designs.

For example, consider a univariate geometric Brownian motion (GBM) model of the form:

In this model, the return, μ(t), and volatility,σ(t), are dynamic parameters of time alone. However, when creating a gbm object to represent the underlying model, such dynamic behavior must be accessible by the common $\left(\mathit{t},{\mathit{X}}_{\mathit{t}}^{}\right)$interface. This reflects the fact that GBM models are restricted parameterizations that derive from the general SDE class.

As a convenience, you can specify parameters of restricted models, such as GBM models, as traditional MATLAB® arrays of appropriate dimension. In this case, such arrays represent a static special case of the more general dynamic situation accessible by the $\left(\mathit{t},{\mathit{X}}_{\mathit{t}}^{}\right)$ interface.

Moreover, when you enter parameters as functions, object constructors can verify that they return arrays of correct size by evaluating them at the initial time and state. Otherwise, object constructors have no knowledge of any particular functional form.

The following example illustrates a technique that includes dynamic behavior by mapping a traditional MATLAB® time series array to a callable function with a $\left(\mathit{t},{\mathit{X}}_{\mathit{t}}^{}\right)$ interface. It also compares the function with an otherwise identical model with constant parameters.

Because time series arrays represent dynamic behavior that must be captured by functions accessible by the $\left(\mathit{t},{\mathit{X}}_{\mathit{t}}^{}\right)$ interface, you need utilities to convert traditional time series arrays into callable functions of time and state. The following example shows how to do this using the conversion function ts2func (time series to function).

Load a daily historical data set containing three-month Euribor rates and closing index levels of France's CAC 40 spanning the time interval February 7, 2001 to April 24, 2006.

load Data_GlobalIdx2

Simulate risk-neutral sample paths of the CAC 40 index using a geometric Brownian motion (GBM) model:

where r(t) represents evolution of the risk-free rate of return.

Furthermore, assume that you need to annualize the relevant information derived from the daily data (annualizing the data is optional, but is useful for comparison to other examples), and that each calendar year comprises 250 trading days.

dt      = 1/250;
returns = tick2ret(Dataset.CAC);
sigma   = std(returns)*sqrt(250);
yields  = Dataset.EB3M;
yields  = 360*log(1 + yields);

Compare the resulting sample paths obtained from two risk-neutral historical simulation approaches, where the daily Euribor yields serve as a proxy for the risk-free rate of return.

The first approach specifies the risk-neutral return as the sample average of Euribor yields, and therefore assumes a constant (non-dynamic) risk-free return.

nPeriods = length(yields);  % Simulated observations
rng(5713,'twister')
obj    = gbm(mean(yields),diag(sigma),'StartState',100)

obj = 
   Class GBM: Generalized Geometric Brownian Motion
   ------------------------------------------------
     Dimensions: State = 1, Brownian = 1
   ------------------------------------------------
      StartTime: 0
     StartState: 100
    Correlation: 1
          Drift: drift rate function F(t,X(t)) 
      Diffusion: diffusion rate function G(t,X(t)) 
     Simulation: simulation method/function simByEuler
         Return: 0.0278117
          Sigma: 0.231906

[X1,T] = simulate(obj,nPeriods,'DeltaTime',dt);

In contrast, the second approach specifies the risk-neutral return as the historical time series of Euribor yields. It therefore assumes a dynamic, yet deterministic, rate of return; this example does not illustrate stochastic interest rates. To illustrate this dynamic effect, use the ts2func utility.

r = ts2func(yields,'Times',(0:nPeriods - 1)');

ts2func packages a specified time series array inside a callable function of time and state, and synchronizes it with an optional time vector. For instance:

r(0,100)

ans = 
0.0470

evaluates the function at (t = 0, ${\mathit{X}}_{\mathit{t}}^{}$ = 100) and returns the first observed Euribor yield.

However, you can also evaluate the resulting function at any intermediate time t and state ${\mathit{X}}_{\mathit{t}}^{}$:

r(7.5,200)

ans = 
0.0472

Furthermore, the following command produces the same result when called with time alone:

r(7.5)

ans = 
0.0472

The equivalence of these last two commands highlights some important features.

When you specify parameters as functions, they must evaluate properly when passed a scalar, real-valued sample time (t), and an NVars-by-1 state vector (${\mathit{X}}_{\mathit{t}}^{}$). They must also generate an array of appropriate dimensions, which in the first case is a scalar constant, and in the second case is a scalar, piecewise constant function of time alone. You are not required to use either time (t) or state (${\mathit{X}}_{\mathit{t}}^{}$). In the current example, the function evaluates properly when passed time followed by state, thereby satisfying the minimal requirements. The fact that it also evaluates correctly when passed only time simply indicates that the function does not require the state vector ${\mathit{X}}_{\mathit{t}}^{}$. The important point to make is that it works when you pass it $\left(\mathit{t},{\mathit{X}}_{\mathit{t}}^{}\right)$.

Furthermore, the ts2func function performs a zero-order-hold (ZOH) piecewise constant interpolation. The notion of piecewise constant parameters is pervasive throughout the SDE architecture, and is discussed in more detail in Optimizing Accuracy: About Solution Precision and Error.

Complete the comparison by performing the second simulation using the same initial random number state. Simulate paths using a dynamic, deterministic rate of return.

rng(5713,'twister')
obj = gbm(r, diag(sigma),'StartState',100)

obj = 
   Class GBM: Generalized Geometric Brownian Motion
   ------------------------------------------------
     Dimensions: State = 1, Brownian = 1
   ------------------------------------------------
      StartTime: 0
     StartState: 100
    Correlation: 1
          Drift: drift rate function F(t,X(t)) 
      Diffusion: diffusion rate function G(t,X(t)) 
     Simulation: simulation method/function simByEuler
         Return: function ts2func/vector2Function
          Sigma: 0.231906

X2  = simulate(obj,nPeriods,'DeltaTime',dt);

Plot the series of risk-free reference rates to compare the two simulation trials.

subplot(2,1,1)
plot(dates,100*yields)
datetick('x')
xlabel('Date')
ylabel('Annualized Yield (%)')
title('Risk Free Rate(3-Mo Euribor Continuously-Compounded)')
subplot(2,1,2)
plot(T,X1,'red',T,X2,'blue')
xlabel('Time (Years)')
ylabel('Index Level')
title('Constant vs. Dynamic Rate of Return: CAC 40')
legend({'Constant Interest Rates' 'Dynamic Interest Rates'},...
    'Location', 'Best')

The paths are close but not exact. The blue line in the last plot uses all the historical Euribor data, and illustrates a single trial of a historical simulation.

Input Arguments

Array — Time series array to encapsulate within a callable function of time and state

vector | 2-dimensional matrix | three-dimensional array

Time series array to encapsulate within a callable function of time and state, specified as a vector, two-dimensional matrix, or three-dimensional array

Data Types: double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: F = ts2func(yields,'Times',(0:nPeriods - 1)')

Times — Monotonically increasing observation times associated with the time series input array Array

zero-based, unit-increment vector of the same length as that of the dimension of Array (default) | vector

Monotonically increasing observation times associated with the time series input array (Array), specified as the comma-separated pair consisting of 'Times' and a vector.

Data Types: double

TimeDimension — Specifies which dimension of the input time series array Array is associated with time

1 (indicates that time is associated with the rows of Array) (default) | scalar integer

Specifies which dimension of the input time series array (Array) is associated with time, specified as the comma-separated pair consisting of 'TimeDimension' and a scalar integer.

Data Types: double

StateDimension — Specifies which dimension of the input time series array Array is associated with the NVars state variables

first dimension of Array not already associated with time is associated with first available dimension of Array not already assigned to TimeDimension (default) | positive scalar integer

Specifies which dimension of the input time series array (Array) is associated with the NVars state variables, specified as the comma-separated pair consisting of 'StateDimension' and a positive scalar integer.

Data Types: double

Deterministic — Flag to indicate whether the output function is a deterministic function of time alone

false (meaning F is a callable function of time and state, F(t,X)) (default) | scalar logical

Flag to indicate whether the output function is a deterministic function of time alone, specified as the comma-separated pair consisting of 'Determininistic' and a scalar integer flag.

If Deterministic is true, the output function F is a deterministic function of time, F(t), and the only input it accepts is a scalar, real-valued time t. If Deterministic is false, the output function F accepts two inputs, a scalar, real-valued time t followed by an NVars-by-1 state vectorX(t).

Data Types: logical

Output Arguments

F — Callable function F(t) of a real-valued scalar observation time t

vector | matrix | table | timetable

Callable function F(t) of a real-valued scalar observation time t, returned as a function.

If the optional input argument Deterministic is true, F is a deterministic function of time, F(t), and the only input it accepts is a scalar, real-valued time t. Otherwise, if Deterministic is false (the default), F accepts a scalar, real-valued time t followed by an NVars-by-1 state vector X(t).

Note

You can invoke F with a second input (such as an NVars-by-1 state vector X), which is a placeholder that ts2func ignores. For example, while F(t) and F(t,X) produce identical results, the latter directly supports SDE simulation methods.

Algorithms

• When you specify Array as a scalar or a vector (row or column), ts2func assumes that it represents a univariate time series.

• F returns an array with one less dimension than the input time series array Array with which F is associated. Thus, when Array is a vector, a 2-dimensional matrix, or a three-dimensional array, F returns a scalar, vector, or 2-dimensional matrix, respectively.

• When the scalar time t at which ts2func evaluates the function F does not coincide with an observation time in Times, F performs a zero-order-hold interpolation. The only exception is if t precedes the first element of Times, in which case F(t) = F(Times(1)).

• To support Monte Carlo simulation methods, the output function F returns an NVars-by-1 column vector or a two-dimensional matrix with NVars rows.

• The output function F is always a deterministic function of time, F(t), and may always be called with a single input regardless of the Deterministic flag. The distinction is that when Deterministic is false, the function F may also be called with a second input, an NVars-by-1 state vector X(t), which is a placeholder and ignored. While F(t) and F(t,X) produce identical results, the former specifically indicates that the function is a deterministic function of time, and may offer significant performance benefits in some situations.

References

[1] Ait-Sahalia, Y. “Testing Continuous-Time Models of the Spot Interest Rate.” The Review of Financial Studies, Spring 1996, Vol. 9, No. 2, pp. 385–426.

[2] Ait-Sahalia, Y. “Transition Densities for Interest Rate and Other Nonlinear Diffusions.” The Journal of Finance, Vol. 54, No. 4, August 1999.

[3] Glasserman, P. Monte Carlo Methods in Financial Engineering. New York, Springer-Verlag, 2004.

[4] Hull, J. C. Options, Futures, and Other Derivatives, 5th ed. Englewood Cliffs, NJ: Prentice Hall, 2002.

[5] Johnson, N. L., S. Kotz, and N. Balakrishnan. Continuous Univariate Distributions. Vol. 2, 2nd ed. New York, John Wiley & Sons, 1995.

[6] Shreve, S. E. Stochastic Calculus for Finance II: Continuous-Time Models. New York: Springer-Verlag, 2004.

Version History

Introduced in R2008a