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

Illustrate the Dynamic Behavior of Market Parameters

Load the data.

load Data_GlobalIdx2

Simulate risk-neutral sample paths.

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

Simulate paths using a constant, 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);

Simulate paths using a dynamic, deterministic rate of return (get r)

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

Simulate paths using a dynamic, deterministic rate of return (r output 1)

r(0,100)

ans = 0.0470

Simulate paths using a dynamic, deterministic rate of return (r output 2)

r(7.5,200)

ans = 0.0472

Simulate paths using a dynamic, deterministic rate of return (r output 3)

r(7.5)

ans = 0.0472

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);

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')

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