TISEAN package
Contents
Porting TISEAN
This section will focus on demonstrating the capabilities of the TISEAN package.
Process
This section describes the process employed during porting TISEAN package into an Octave Package. This project was started as part of the Google Summer of Code 2015.
To aid in understanding the task there are some charts.
The first chart depicts what to do with each function in the function table. I mainly focuses on those functions that might already implemented in Octave.
The chart below depicts how to decide which type of port should be utilized.
Both of those charts can be combined into a large one that shows all of the work together.
Table of functions and progress
In reference to the TISEAN library alphabetical order of programs which is located here.
The choice whether a program exist in Octave is based only on comparing package/octave documentation with the TISEAN documentation. As of now I have not compared any code, nor checked if any sample data gives the same results from both functions (the octave ones and the TISEAN ones).
The legend to understand the table is as follows:
Green means the function is ported, tested or is not needed 
Red means the function was thought to have been similar but isn't 
Yellow means that the correlation between the TISEAN and Octave function needs to be verified 
No color means that nothing about this function has been determined 
Program Name  Program Description  Corresponding Octave Function  Lanuguage of Origin  How to port  Status 

arimamodel  Fit and possibly iterate an ARIMA model  generalizes TSA arma functions  C  wrapped in C++/mfile/octfile code  
armodel  Fit and possibly iterate an Autoregessive model  'aar' in TSA; see also: aarmam, adim, amarma, mvaar from TSA  C  wrapped in C++/mfile/octfile code  
arrun  Iterate an Autoregessive model  Same as above  FORTRAN  wrapped in C++/mfile/octfile code  
avd2  Simply smooth output of d2  Can be implemented with filter in core  C  
boxcount  Renyi Entopies of Qth order  None in GNU Octave (maybe in infotheory but it is not worth the pain)  C  wrapped in C++/mfile/octfile code  
c1  Fixed mass estimation of D1  None in GNU Octave  FORTRAN  wrapped in C++/mfile/octfile code  
c2d  Get local slopes from correlation integral  None in GNU Octave  FORTRAN  wrapped in C++/mfile/octfile code  
c2g  Gaussian kernel of C2  None in GNU Octave  FORTRAN  wrapped in C++/mfile/octfile code  
c2t  Takens estimator of D2  None in GNU Octave  FORTRAN  wrapped in C++/mfile/octfile code  
choose  Choose rows and/or columns from a data file  Does not need to be ported  FORTRAN    Not Needed 
compare  Compares two data sets  Does not need to be ported  FORTRAN    Not Needed 
corr, autocorr  Autocorrelation function  xcorr in signal  corr C, autocorr (faster according to documentation)  FORTRAN    Different usage, same result 
d2  Correlation dimension d2  None in GNU Octave  C  wrapped in C++/mfile/octfile code  
delay  Creates delay embedding  None in GNU Octave (easy to implement in Octave but not worth the effort)  C  wrapped in C++/mfile/octfile code  Ported&Tested 
endtoend  Determine endtoend mismatch  None in GNU Octave  FORTRAN  wrapped in C++/mfile/octfile code  Ported&Tested 
events  Interval/event conversion  None in GNU Octave  FORTRAN  To be reimplemented as mfile  
extrema  Determine the extrema of a time series  findpeaks in signal is *not* the same  C  
false_nearest  The false nearest neighbor algorithm  None in GNU Octave  C  wrapped in C++/mfile/octfile code  Ported&Tested 
ghkss  Nonlinear noise reduction  None in GNU Octave  C  wrapped in C++/mfile/octfile code  Ported&Tested 
henon  Create a Hénon time series  None in GNU Octave  FORTRAN  To be reimplemented as mfile  Ported&Checked 
histogram  Creates histograms  hist in core  C  Different usage, same result  
ikeda  Create an Ikeda time series  None in GNU Octave  FORTRAN  To be reimplemented as mfile  Ported&Tested 
intervals  Event/intervcal conversion  Might exist under different name  FORTRAN  To be reimplemented as mfile  
lazy  Simple nonlinear noise reduction  None in GNU Octave  FORTRAN  wrapped in C++/mfile/octfile code  Ported&Tested 
lfoar  Locally first order model vs. global AR model (old llar)  None in GNU Octave  C  wrapped in C++/mfile/octfile code  
lforun  Iterate a locally first order model (old nstep)  None in GNU Octave  C  wrapped in C++/mfile/octfile code  
lfotest  Test a locally first order model (old onestep)  None in GNU Octave  C  wrapped in C++/mfile/octfile code  
lorenz  Create a Lorenz time series  Can be implemented in GNU Octave using lsode or odepkg  FORTRAN  mfile  
low121  Time domain low pass filter  There are lowpass filters in Octave: buttap, cheb1ap, cheb2ap, ellipap, sftrans, but I don't think they perform this task  C  Reimplement as mfile  
lyap_k  Maximal Lyapunov exponent with the Kantz algorithm  None in GNU Octave  C  wrapped in C++/mfile/octfile code  
lyap_r  Maximal Lyapunov exponent with the Rosenstein algorithm  None in GNU Octave  C  wrapped in C++/mfile/octfile code  
lyap_spec  Full spectrum of Lyapunov exponents  None in GNU Octave  C  wrapped in C++/mfile/octfile code  
lzogm  Locally zeroth order model vs. global mean  None in GNU Octave  C  wrapped in C++/mfile/octfile code  Ported&Tested 
lzorun  Iterate a locally zeroth order model  None in GNU Octave  C  wrapped in C++/mfile/octfile code  Ported&Tested 
lzotest  Test a locally zeroth order model (old zeroth)  None in GNU Octave  C  wrapped in C++/mfile/octfile code  Ported&Tested 
makenoise  Produce noise  Rand exists  Should be implemented as mfile using Octave rand functions  wrapped in C++/mfile/octfile code  
mem_spec  Power spectrum using the maximum entropy principle  None in GNU Octave  C  wrapped in C++/mfile/octfile code  
mutual  Estimate the mutual information  None in GNU Octave  C  wrapped in C++/mfile/octfile code  Ported&Tested 
notch  Notch filter  pei_tseng_notch, needs to be verified  FORTRAN  wrapped in C++/mfile/octfile code  
nstat_z  Nonstationarity testing via crossprediction  None in GNU Octave  C  wrapped in C++/mfile/octfile code  
pca, pc  Principle component analysis  'pcacov' if likely the equivalent; pricomp in statistics  pca  C, pc  FORTRAN  wrapped in C++/mfile/octfile code  Ported&Tested 
poincare  Create Poincaré sections  None in GNU Octave  C  wrapped in C++/mfile/octfile code  Ported&Tested 
polyback  Fit a polynomial model (backward elimination)  polyfit, detrend, wpolyfit are not similar  C  wrapped in C++  Porting needed 
polynom  Fit a polynomial model  same as above  C  Ported&Tested  
polynomp  Fit a polynomial model (reads terms to fit from file)  same as above  C  
polypar  Creates parameter file for polynomp  same as above  C  
predict  Forecast discriminating statistics for surrogates  None in GNU Octave  FORTRAN  wrapped in C++/mfile/octfile code  Same as lzo_test; Not Needed 
randomize  General constraint randomization (surrogates)  There are random function, but I don't think this one exists  FORTRAN  wrapped in C++/mfile/octfile code  
randomize_spikeauto_exp_random  Surrogate data preserving event time autocorrelations  Same as above  FORTRAN  wrapped in C++/mfile/octfile code  
randomize_spikespec_exp_event  Surrogate data preserving event time power spectrum  Same as above  FORTRAN  wrapped in C++/mfile/octfile code  
rbf  Radial basis functions fit  None in GNU Octave  C  wrapped in C++/mfile/octfile code  
recurr  Creates a recurrence plot  None in GNU Octave  C  wrapped in C++/mfile/octfile code  
resample  Resamples data  interp1 is similar but cannot specify the polynomial order except for some given  C  wrapped in C++/mfile/octfile code  
rescale  Rescale data set  This is just multiplication by scalars  C  wrapped in C++/mfile/octfile code  Not Needed 
rms  Rescale data set and get mean, variance and data interval  This should be in Octave, cannot find...  FORTRNAN  wrapped in C++/mfile/octfile code  Not Needed 
sav_gol  SavitzkyGolay filter  sgolayfilt in signal  C  
spectrum  Power spectrum using FFT  abs (fft (;))  FORTRAN  Rewrite as mfile  Ported&Tested 
spikeauto  Autocorrelation function of event times  similar to above  FORTRAN  
spikespec  Power spectrum of event times  ar_psd, cpsd is the closest but I do not think they are the same  FORTRAN  
stp  Creates a spacetime separation plot  None in GNU Octave  FORTRAN  wrapped in C++/mfile/octfile code  
surrogates  Creates surrogate data  None in GNU Octave  FORTRAN  wrapped in C++/mfile/octfile code  Ported&Tested 
timerev  Time reversal discrimating statistics for surrogates  None in GNU Octave  FORTRAN  To be reimplemented as mfile  Ported&Tested 
upo  Finds unstable periodic orbits and estimates their stability  None in GNU Octave  FORTRAN  wrapped in C++/mfile/octfile code  Ported&Tested 
upoembed  Takes the output of upo and create data files out of it  None in GNU Octave  FORTAN  wrapped in C++/mfile/octfile code  Ported&Tested 
wiener1, wiener2  Wiener filter  Wiener process exists, might be similar  FORTRAN  wrapped in C++/mfile/octfile code  
xc2  Crosscorrelation integral  xcorr2  Needs to be verified that works the same way  FORTRAN  wrapped in C++/mfile/octfile code  
xcor  Crosscorrelations  xcorr  Needs to be verified that works same way  C  wrapped in C++/mfile/octfile code  
xrecur  Crossrecurrence Plot  xcorr, or xcorr2 or another function might cover this  C  wrapped in C++/mfile/octfile code  
xzero  Locally zeroth order crossprediction  None in GNU Octave  C  wrapped in C++/mfile/octfile code 
Tutorials
These tutorials are based on examples, tutorials and the articles located on the TISEAN website:
http://www.mpipksdresden.mpg.de/~tisean/Tisean_3.0.1/.
This tutorial will utilize the following dataset:
Please download it as the tutorial will reference it.
False Nearest Neighbors
This function uses a method to determine the minimum sufficient embedding dimension. It is based on the False Nearest Neighbors section of the TISEAN documentation. As a demonstration we will create a plot that contains an Ikeda Map, a Henon Map and a Henon Map corrupted by 10% of Gaussian noise.
Code: Analyzing false nearest neighbors 
# Create maps
ikd = ikeda (10000);
hen = henon (10000);
hen_noisy = hen + std (hen) * 0.02 .* (6 + sum (rand ([size(hen), 12]), 3));
# Create and plot false nearest neighbors
[dim_ikd, frac_ikd] = false_nearest (ikd(:,1));
[dim_hen, frac_hen] = false_nearest (hen(:,1));
[dim_hen_noisy, frac_hen_noisy] = false_nearest (hen_noisy(:,1));
plot (dim_ikd, frac_ikd, 'b*;Ikeda;',...
dim_hen, frac_hen, 'r+;Henon;',...
dim_hen_noisy, frac_hen_noisy, 'gx;Henon Noisy;');

The dim_*
variables hold the dimension (so here 1:5), and frac_*
contain the fraction of false nearest neighbors. From this chart we can obtain the sufficient embedding dimension for each system. For a Henon Map m = 2
is sufficient, but for an Ikeda map it is better to use m = 3
.
Finding Unstable Periodic Orbits
Here I will demonstrate how to find unstable periodic orbits. This section is based on the TISEAN documentation chapter Finding unstable periodic orbits. We will start by finding these orbits using function upo
.
Code: Finding unstable periodic orbits 
# Create maps
hen = henon (1000);
hen = hen + std (hen) * 0.02 .* (6 + sum (rand ([size(hen), 12]), 3));
# Find orbits
[lengths, data] = upo(hen(:,1), 2, 'p',6,'v',0.1, 'n', 100);

The vector lengths
contains the size of each of the found orbits and data
contains their coordinates. To obtain delay coordinates and plot these orbits onto the original data we will use upoembed
.
Code: Plotting unstable periodic orbits 
# Create delay coordinates for the orbits and data
up = upoembed (lengths, data, 1);
delay_hen = delay (hen(:,1));
# Plot all of the data
plot (delay_hen(:,1), delay_hen(:,2), 'r.;Noisy Henon;','markersize',2,...
up{4}(:,1), up{4}(:,2),'gx;Fixed Point;','markersize',20,'linewidth',1, ...
up{3}(:,1), up{3}(:,2),'b+;Period 2;','markersize',20,'linewidth',1, ...
up{2}(:,1), up{2}(:,2),'ms;Period 6;','markersize',20,'linewidth',1, ...
up{1}(:,1), up{1}(:,2),'cs;Period 6;','markersize',20,'linewidth',1);

The plotting options are passed to make the orbits more visible.
Nonlinear Prediction
In this section we will demonstrate some functions from the 'Nonlinear Prediction' chapter of the TISEAN documentation (located here). For now this section will only demonstrate functions that are connected to the Simple Nonlinear Prediction section.
There are three functions in this section: lzo_test
, lzo_gm
and lzo_run
. The first is used to estimate the forecast error for a set of chosen parameters, the second gives some global information about the fit and the third produces predicted points. Let us start with the first one (before starting this example remember to download 'amplitude.dat' from above and start Octave in the directory that contains it). The pairs of parameters (m,d)
where chosen after the TISEAN documentation.
Code: Analyzing forecast errors for various parameters 
# Load data
load amplitude.dat
# Create different forecast error results
steps = 200;
res1 = lzo_test (amplitude(1:end200), 'm', 2, 'd', 6, 's', steps);
res2 = lzo_test (amplitude(1:end200), 'm', 3, 'd', 6, 's', steps);
res3 = lzo_test (amplitude(1:end200), 'm', 4, 'd', 1, 's', steps);
res4 = lzo_test (amplitude(1:end200), 'm', 4, 'd', 6, 's', steps);
plot (res1(:,1), res1(:,2), 'r;m = 2, d = 6;', ...
res2(:,1), res2(:,2), 'g;m = 3, d = 6;',...
res3(:,1), res3(:,2), 'b;m = 4, d = 1;',...
res4(:,1), res4(:,2), 'm;m = 4, d = 6;');

It seems that the last pair (m = 4, d = 6)
is suitable. We will use it to determine the the best neighborhood to use when generating future points.
Code: Determining the best neighborhood size using lzo_gm 
gm = lzo_gm (amplitude(1:end200), 'm', 4, 'd', 6, 's', steps, 'rhigh', 20);

After analyzing gm
it is easy to observe that the least error is for the first neighborhood size of gm
which is equal to 0.49148. We will use it to produce the prediction vectors. Only the first 4800 datapoints from amplitude
are used in order to compare the predicted values with the actual ones for the last 200 points.
Code: Creating forecast points 
steps = 200;
forecast = lzo_run (amplitude(1:end200), 'm', 4, 'd', 6, 'r', 0.49148, 'l', steps);
forecast_noisy = lzo_run (amplitude(1:end200), 'm', 4, 'd', 6, 'r', 0.49148, ...
'dnoise', 10, 'l', steps);
plot (amplitude(end199:end), 'g;Actual Data;', ...
forecast, 'r.;Forecast Data;',...
forecast_noisy, 'bo;Forecast Data with 10% Dynamic Noise;');

The difference between finding the proper r
and not finding it can be very small.
The produced data is the best local zeroth order fit on the amplitude.dat
for (m = 4, d = 6)
.
Nonlinear Noise Reduction
This tutorial show different methods of the 'Nonlinear Noise Reduction' section of the TISEAN documentation (located here). It shows the use of simple nonlinear noise reduction (function lazy
) and locally projective nonlinear noise reduction (function ghkss
). To start let's create noisy data to work with.
Code: Creating a noisy henon map 
hen = henon (10000);
hen = hen(:,1); # We only need the first column
hen_noisy = hen + std (hen) * 0.02 .* (6 + sum (rand ([size(hen), 12]), 3));

This created a Henon map contaminated by 2% Gaussian noise à la TISEAN. In the tutorials and exercises on the TISEAN website this would be equivalent to calling makenoise %2
on the Henon map.
Next we will reduce the noise using simple nonlinear noise reduction lazy
.
Code: Simple nonlinear noise reduction 
clean = lazy (hen_noisy,7,0.06,3);
# Create delay vectors for both the clean and noisy data
delay_clean = delay (clean);
delay_noisy = delay (hen_noisy);
# Plot both on one chart
plot (delay_noisy(:,1), delay_noisy(:,2), 'b.;Noisy Data;','markersize',3,...
delay_clean(:,1), delay_clean(:,2), 'r.;Clean Data;','markersize',3)

On the chart created the red dots represent cleaned up data. It is much closer to the original than the noisy blue set.
Now we will do the same with ghkss
.
Code: Locally projective nonlinear noise reduction 
clean = ghkss (hen,'m',7,'q',2,'r',0.05,'k',20,'i',2);

The rest of the code is the same as the code used in the lazy
example.
Once both results are compared it is quite obvious that for this particular example ghkss
is superior to lazy
. The TISEAN documentation points out that this is not always the case.
Lyapunov Exponents
Here I will demonstrate how to use the function lyap_k
. It estimates the maximal Lyapunov exponent from a time series (more information available from the TISEAN documentation located here). In this tutorial we will estimate the maximal Lyapunov exponent for various embedding dimensions and then plot them.
Code: Creating Lyapunov exponents 
# Create time series
in = sin((1:2500).'./360) + cos((1:2500).'./180);
# Estimate Lyapunov exponents
mmax_val = 20
lyap_exp = lyap_k (in, 'mmin',2,'mmax',mmax_val,'d',6,'s',400,'t',500);

In this function the output (lyap_exp
is a 5 x 20
struct array. We will only use one row for the plot.
Code: Plotting Lyapunov exponents 
cla reset
hold on
for j=2:mmax_val
plot (lyap_exp(1,j1).exp(:,1),lyap_exp(1,j1).exp(:,2),'r');
endfor
xlabel ("t [flow samples]");
ylabel ("S(eps, embed, t)");
hold off

Dimensions and Entropies
This section is discussed on the TISEAN documentation page. One of the functions discussed is d2
. It is used to estimate the correlation sum, correlation dimension and correlation entropy of a time series. The time series used here will be the Henon map.
Code: Calculation correlation sum, dimension and entropy 
# Create maps
hen = henon (10000);
# Calculate the correlation sum, dimension and entropy
vals = d2 (hen, 'd', 1, 'm', 5, 't',50);
# Plot correlation sum
subplot (2,3,1)
do_plot_corr = @(x) loglog (x{1}(:,1),x{1}(:,2),'b');
hold on
arrayfun (do_plot_corr, {vals.c2});
hold off
xlabel ("Epsilon")
ylabel ("Correlation sums")
title ("c2");
# Plot correlation entropy
subplot (2,3,4)
do_plot_entrop = @(x) semilogx (x{1}(:,1),x{1}(:,2),'g');
hold on
arrayfun (do_plot_entrop, {vals.h2});
hold off
xlabel ("Epsilon")
ylabel ("Correlation entropies");
title ("h2")
# Plot correlation dimension
subplot (2,3,[2 3 5 6])
do_plot_slope = @(x) semilogx (x{1}(:,1),x{1}(:,2),'r');
hold on
arrayfun (do_plot_slope, {vals.d2});
hold off
xlabel ("Epsilon")
ylabel ("Local slopes")
title ("d2");

The output of d2
can be further processed using the following functions: av_d2
, c2t
, c2g
. This tutorial will show how to use av_d2
which smooths the output of d2
(usually used to smooth the "d2
" field of the output).
Code: Smooth output of d2 
# Smooth d2 output
figure 2
smooth = av_d2 (vals,'a',2);
# Plot the smoothed output
do_plot_slope = @(x) semilogx (x{1}(:,1),x{1}(:,2),'b');
hold on
arrayfun (do_plot_slope, {smooth.d2});
hold off
xlabel ("Epsilon")
ylabel ("Local slopes")
title ("Smooth");

Optionally the line "figure 2
" can be omitted, which will cause the smoothed version to be superimposed on the "raw" version that came straight from d2
.
External links
 Bitbucket repository where the porting is taking place.
 TISEAN package website where the package is described along with references to literature, tutorials and manuals.