# simulateTS

Simulate a time series with trend, time varying seasonal, level shift and irregular component

## Syntax

• out=simulateTS(T)example
• out=simulateTS(T,Name,Value)example

## Description

simulateTS simulates a time series with trend (up to third order), seasonality (constant or of varying amplitude) with a different number of harmonics and a level shift. Moreover, it is possible to add to the series the effect of explanatory variables.

 out =simulateTS(T) Simulated time series with linear trend.

 out =simulateTS(T, Name, Value) Same as above, but without homogenizing the y-scale.

## Examples

expand all

### Simulated time series with linear trend.

A time series of 100 observations is simulated from a model which contains a linear trend (with slope 1 and intercept 0), no seasonal component, no explanatory variables and a signal to noise ratio egual to 20

    out=simulateTS(100,'plots',1);


### Same as above, but without homogenizing the y-scale.

    close;
out=simulateTS(100,'plots',1,'samescale',false);


### Simulated time series with a linear time varying seasonal component.

A time series of 100 observations is simulated from a model which contains no trend, a linear time varying seasonal component with three harmonics, no explanatory variables and a signal to noise ratio egual to 20

    rng(1)
model=struct;
model.trend=[];
model.trendb=[];
model.seasonal=103;
model.seasonalb=40*[0.1 -0.5 0.2 -0.3 0.3 -0.1 0.222];
model.signal2noiseratio=20;
T=100;
out=simulateTS(T,'model',model,'plots',1);


### Simulated time series with a quadratic time varying seasonal component.

A time series of 100 observations is simulated from a model which contains no trend, a quadratic time varying seasonal component with one harmonic, no explanatory variables and a signal to noise ratio egual to 20

    rng(1)
model=struct;
model.trend=[];
model.trendb=[];
model.seasonal=201;
model.seasonalb=40*[0.1 -0.5 10.222 -10];
model.signal2noiseratio=20;
T=100;
out=simulateTS(T,'model',model,'plots',1);


### Simulated time series with quadratic trend, fixed seasonal and level shift.

A time series of 100 observations is simulated from a model which contains a quadratic trend, a seasonal component with two harmonics no explanatory variables and a level shift in position 30 with size 5000 and a signal to noise ratio egual to 20

    rng(1)
model=struct;
model.trend=2;
model.trendb=[5,10,-3];
model.seasonal=2;
model.seasonalb=100*[2 4 0.1 8];
model.signal2noiseratio=20;
model.lshift=30;
model.lshiftb=5000;
T=100;
out=simulateTS(T,'model',model,'plots',1);


### Simulated time series with quadratic trend, fixed seasonal and LS.

A time series of 100 observations is simulated from a model which contains a quadratic trend, a linear time varying seasonal component with two harmonics no explanatory variables and a level shift in position 30 with size -10000 and a signal to noise ratio egual to 20

    rng(1)
model=struct;
model.trend=2;
model.trendb=[5,10,-3];
model.seasonal=102;
model.seasonalb=100*[2 4 0.1 8 0.001];
model.signal2noiseratio=20;
model.lshift=30;
model.lshiftb=-10000;
T=100;
out=simulateTS(T,'model',model,'plots',1);


### Simulated time series with quadratic trend, fixed seasonal, LS and two explanatory variables.

    % A time series of 100 observations is simulated from a model
% which contains a quadratic trend, a linear time varying seasonal
% component with two harmonics, two explanatory variables and a level
% shift in position 30 with size -40000 and a signal to noise ratio
% egual to 10
rng(1)
model=struct;
model.trend=2;
model.trendb=[5,10,-3];
model.seasonal=102;
model.seasonalb=100*[2 4 0.1 8 0.001];
model.signal2noiseratio=10;
model.lshift=30;
model.lshiftb=-40000;
model.X=2;
model.Xb=[10000 20000];
T=100;
out=simulateTS(T,'model',model,'plots',1);


### Example of the use of option FileNameOutput.

In this example the simulated time series is saved into a file named ysimout.txt in the current folder

    FileNameOutput=[pwd filesep 'ysimout.txt'];
out=simulateTS(T,'FileNameOutput',FileNameOutput);


### Example of the use of option StartDate.

Suppose that the inital observation refers to February 2016.

    StartDate=[2016 2];
% The x axis of the plots contains the dates using format mmm-yyyy
out=simulateTS(T,'model',model,'plots',1,'StartDate',StartDate);


### Example of the use of option samescale.

Use a different scale for each panel in the output plot.

    out=simulateTS(T,'model',model,'plots',1,'samescale',false);


## Input Arguments

### T — time series length. Scalar.

T is a positive integer which defines the length of the simulated time series.

Data Types: single| double

### Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as  Name1,Value1,...,NameN,ValueN.

Example:  'model', model , 'plots',1 , 'StartDate',[2016,3] , 'nocheck',false , 'FileNameOutput',['C:' filesep 'myoutput' fielsep 'savesimdata.txt'] , 'samescale',false 

### model —model type.structure.

A structure which specifies the model used to simulate the time series. The structure contains the following fields:

Value Description
trend

scalar (order of the trend component).

trend = 1 implies linear trend with intercept, trend = 2 implies quadratic trend, etc.

If this field is empty the simulated time series will not contain a trend. The default value of model.trend is 1.

trendb

vector of doubles containining the beta coefficients for the trend. For example model.trend=1 and model.trendb=[3.2 2] generate a linear trend of the kind 3.2+2*t.

If this field is an empty double the simulated time series will not contain a trend. The default value of model.trendb is [0 1] that is a slope equal to 1 and intercept equal to 0.

s

scalar greater than zero which specifies the length of the seasonal period. For monthly data (default) s=12, for quartely data s=4, ...

The default value of model.s is 12 (that is monthly data are assumed)

seasonal

scalar (integer specifying number of frequencies, i.e. harmonics, in the seasonal component. Possible values for seasonal are $1, 2, ..., [s/2]$, where $[s/2]=floor(s/2)$.

For example:

if seasonal = 1 (default) we have:

$\beta_1 \cos( 2 \pi t/s) + \beta_2 sin ( 2 \pi t/s)$;

if seasonal = 2 we have:

$\beta_1 \cos( 2 \pi t/s) + \beta_2 \sin ( 2 \pi t/s) + \beta_3 \cos(4 \pi t/s) + \beta_4 \sin (4 \pi t/s)$.

Note that when $s$ is even the sine term disappears for $j=s/2$ and so the maximum number of trigonometric parameters is $s-1$.

If seasonal is a number greater than 100 then it is possible to specify how the seasonal component grows over time.

For example, seasonal = 101 implies a seasonal component which just uses one frequency which grows linearly over time as follows:

$(1+\beta_3 t)\times ( \beta_1 cos( 2 \pi t/s) + \beta_2 \sin ( 2 \pi t/s))$.

For example, seasonal = 201 implies a seasonal component which just uses one frequency which grows in a quadratic way over time as follows:

$(1+\beta_3 t + \beta_4 t^2)\times( \beta_1 \cos( 2 \pi t/s) + \beta_2 \sin ( 2 \pi t/s))$.

If this field is an empty double (default) the simulated time series will not contain a seasonal component.

seasonalb

vector of doubles containing the beta coefficients for the seasonal component.

For example model.seasonal = 201 and model model.trendb = [1.2 2.3 3.4 4.5] generates a seasonal component of the kind:

$(1+ 3.4 t + 4.5 t^2)\times( 1.2 \cos( 2 \pi t/s) + 2.3 \sin ( 2 \pi t/s))$.

If this field is an empty double (default) the simulated time series will not contain a seasonal component.

X

scalar or matrix of size T-by-nexpl. If model.X is a matrix of size T-by-nexpl, it contains the values of nexpl extra covariates which affect y. If model.X is a scalar equal to k, where k=1, 2, ... k explanatory variables using random numbers from the normal distribution are generated.

If this field is an empty double (default) the simulated time series will not be affected by explanatory variables.

Xb

vector of doubles containing the beta coefficients for the explanatory variables.

For example model.X = 2 and model.Xb = [4,5] generate two additional explanatory variables of the kind: $4*randn(T,1) + 5*randn(T,1)$.

If this field is an empty double (default) the simulated time series will not contain explanatory variables.

lshift

scalar greater than 0 which specifies the position where to include a level shift component.

If this field is an empty double (default) the simulated time series will not contain a level shift.

lshiftb

scalar double which specifies the magnitude of the level shift component.

For example model.lshift = 26 and model.lshiftb = 3 generates the following explanatory variable $[zeros(25,1) + 3*ones(T-25+1,1)]$.

If this field is an empty double (default) the simulated time series will not contain a level shift.

Remark: the default model is for monthly data with a linear trend with slope 1 and intercept 0, no seasonal and no level shift, that is model=struct;

model.s=[];

model.trend=1;

model.trendb=[0 1] model.X=[];

model.lshift=[];

Example:  'model', model 

Data Types: struct

### plots —Plots on the screen.scalar.

If plots == 1 a six panel plot appears on the screen.

Top left panel contains the simulated time series y.

y=TR+SE+X+LS+I.

Top central panel contains the signal component (that is trend + seasonal + explanatory variables + level shift = TR + SE + LS + X).

Top right panel contains the trend component (TR).

Bottom left panel contains the (time varying) seasonal component (SE).

Bottom central panel contains the level shift component (LS).

Bottom right panel contains the explanatory variable component (X) if it is present, otherwise, it contains the irregular (I) component.

The default value of plot is 0, that is no plot is shown on the screen.

Example:  'plots',1 

Data Types: double

### StartDate —The time of the first observation.numeric vector of length 2.

Vector with two integers, which specify a natural time unit and a (1-based) number of samples into the time unit. For example, if model.s=12 (that is the data are monthly) and the first observation starts in March 2016, then StartDate=[2016,3]; Similarly, if models.s=4 (that is the data are quarterly) and the first observation starts in the second quarter or year 2014, then StartData=[2014,2]. The information in option StartDate will be used to create in the output the dates inside the time series object.

Example:  'StartDate',[2016,3] 

Data Types: double

### nocheck —Check input arguments.boolean.

If nocheck is true no check is performed on supplied input. Otherwise (default) every input of the structure model is checked.

Example:  'nocheck',false 

Data Types: double

### FileNameOutput —save simulated time series to txt file.character.

If FileNameOutput is empty (default) nothing is saved on the disk, else FileNameOutput will contain the path where to save the file on the disk.

Example:  'FileNameOutput',['C:' filesep 'myoutput' fielsep 'savesimdata.txt'] 

Data Types: Character

### samescale —same ylim in the output plot.logical.

If true (default), all underlying components of the time series are shown in the plot with the same scale.

Example:  'samescale',false 

Data Types: logical

## Output Arguments

### out — description Structure

structure which contains the following fields:

Value Description
y

the simulated time series.

Column vector of length T, which is sum of trend + (time varying) seasonal + explanatory variables + level shift + irregular = TR+SE+X+LS+I.

signal

signal (TR+SE+X+LS).

Column vector of length T, which is sum of trend + (time varying) seasonal + explanatory variables + level shift. Signal = out.y - out.irregular.

trend

trend (TR).

Column vector of length T which contains the trend component.

seasonal

(time varying) seasonal (SE).

Column vector of length T which contains the seasonal component. If there is no seasonal component outyhatseaso=0.

X

explanatory variables (X).

Column vector of length T which contains the component associated to the explanatory variables.

If there is no explanatory variable, out.X=0.

lshift

level shift (LS).

Column vector of length T which contains the level shift component.

If there is no level shift component out.lshift=0.

irregular

irregular component (I).

Column vector of length T which contains the irregular component.

When the signal to noise ratio tends to infinity the irregular component tends to 0.

## References

Rousseeuw, P.J., Perrotta D., Riani M. and Hubert, M. (2018), Robust Monitoring of Many Time Series with Application to Fraud Detection, "Econometrics and Statistics". [RPRH]