Macros in CatepillarSSA 3.3
Macros can help you to remember sequences of program procedures and then to perform them automatically. Not all operations of the program can be written by means of macros, however all basic operations are realized.
Macros are managed by Macros menu and by buttons on Hotkey Panel. You can show/hide these buttons by Macros|Show buttons menu.

•	Main actions with macros 
•	Open 
•	Edit 
•	Save 
•	Run 
•	How to write macros 
•	How to run the examples with macros 
•	List of macros with description of parameters 

Remark. If you run macros performing procedures that are not allowed by the current edition of the program (for examples, if you use Standard Edition and macros contain a call of the forecasting procedure), then it causes the error.

Main actions with macros
Ways to open:
•	set the name of a file containing macros by Macros|Load from file menu;
•	choose the recent macros by Macros|Recent macros menu;
•	use the Edit Macros window (called by Macros|Edit macros menu or by the button ) to create a new macros, edit the current macros or set the name of the file containing macros.

Ways to edit/cteate:
•	create or edit files with macros in any text editor (for example, in Notepad) that doesn't add extra symbols;
•	edit the current macros or create a new macros in Edit macros window (Macros|Edit macros menu or the button ); Examples menu helps to make it easier;
•	record a macros (i.e., remember sequences of program procedures as macros) by Macros|Record and Macros|Stop menu or by buttons  and  correspondingly; if you answer No to the question 'Would you like to clear the previous macros', then the written macros will be added to the current macros.

Ways to save:
•	by File|Save or File|Save As menu of the Edit macros window;
•	if the current macros were not saved, then, before the exit, CaterpillarSSA inquires whether to save the macros.

Ways to run:
•	by Macros|Run menu or by the button  of the open program; during macros performing, the image of the above button is transformed to  (and the item Stop becomes available in the Macros menu): you can stop macros by click on ; please note that only the button Stop of the active Progress Bar can stop the macros during the calculation process.
•	by run of the executable file of the CaterpillarsSSA program with the key '–m': you should place in quotes file names with full paths, for example:
"C:\Program Files\CaterpillarSSA 3.3\Caterplr.exe" -m"E:\Macros\ex1.ctm"

Comments to macros creation

1.	Note that the current folder (i.e., the folder by default) is a folder that was used during the last saving/opening operation (the same folder appears by the File|Open menu). It is recommended to indicate the full paths to files, which you use in your macros. Otherwise, you can change the current folder by the ChangeDir macro.
2.	Upper-case and lower-case letters aren't distinguished.
3.	Macros consist of sequence of procedures (with parameters or without) separated by ';'. Parameters are separated by ',' (order of parameters is arbitrary) and have the form <Parameter_name> = <Parameter_value>.
4.	Parameter values can be placed in single quotes. They must be placed in single quotes in two cases: if the parameter value is a text including separators (e.g. the space) or if the parameter value is a floating-point number, whereas the Windows settings for the decimal separator is ',' (then you should write: conflevel='0,95'). All below examples are designed to '.' as a decimal separator (then one can write: conflevel=0.95).
5.	You can insert comments to macros: the rest of a line after '//' is ignored. 
6.	Some parameters of macro procedures are required, some parameters are not. If an unrequired parameter is omitted, then its value is defined either by a fixed default value or by the current value preset in the program. See full description for details.
7.	Macros are just duplicates for actions that the user can make manually. That is why the leaning of parameters of the program, which the user sets manually, can help to understand macros parameters. 
8.	Performing of macros can be combined with manual actions. For example, one can load the time series manually and then run macros. 
9.	You can insert template for macros you need with (almost) full set of parameters by means of Examples menu in the Edit Macros window. 

How to run examples with macros

1. Change the path in the file setpath.ctm to the folder with examples of macros and data. These examples are located in the subdirectory DemoData in the CaterpillarSSA folder. This can be done by the following way (for example):
•	open the Edit Macros window by Macros|Edit Macros menu or by 
•	open the file setpath.ctm by File|Open menu of the Edit Macros window 
•	change in the macros ChangeDir the value of the parameter path to the correct folder with examples of macros and data;
•	save the corrected macros file by File|Save menu;
•	close the Edit Macros window by OK button.
2. Run setpath.ctm by the Macros|Run menu or by .
3. Now you can open and run examples ex1.ctm and ex2.ctm by the same way as described above. 

List of macros

1.	Open
Loading time series
2.	Transformation
Time series transformation
3.	Decomposition
Time series decomposition
4.	Grouping
Eigentriples (components) grouping
5.	Reconstruction
Time series reconstruction
6.	Approximation
Time series approximation
7.	Forecast
Time series forecasting
8.	Detect
Change-point detection
9.	MatrDetect
Matrix representation of change-point detection results
10.	Show
To show window
11.	ShowNext
To show the next window
12.	ShowPrev
To show the previous window
13.	Pause
To pause macros execution
14.	ОpenMetastockData
To import data from Metastock
15.	SaveData
To save data of the active window
16.	GraphExport
To export image of the active window
17.	Periodogram
To construct periodogram
18.	WindowClose
To close windows
19.	ChangeDir
To change the current directory
20.	LoadTemplate
To load options template from file
21.	Macros
To run macros from file
22.	Stop
To stop macros
23.	Quit
To exit from the application

Remarks to macros description. Required parameters are marked by bold font. If an unrequired parameter is omitted, then its value is defined either by a fixed default value (this is marked by '(def)' in macros description) or by the current value set up in the program before macros run. 

OPEN | Loading time series

Parameters:
1.	filename | Name of the file with time series.
2.	format | File format: 0 - unstructured (def), 1 - structured. If extension of the filename is 'ctu', 'cts', or 'xls', then this parameter is ignored.
3.	decsep | Decimal separator: 0 - ",", 1 - "." (def).
4.	encoding | Encoding: 0 - OEM, 1 - ANSI (def).
5.	space | Is the space symbol a delimiter? 0 – no, 1 - yes (def).
6.	tab | Is the tabulation symbol a delimiter? 0 – no, 1 - yes (def).
7.	semicolon | Is the semicolon symbol a delimiter? 0 – no, 1 - yes (def).
8.	comma | Is the comma symbol a delimiter? 0 – no, 1 - yes (def).
9.	delimone | How are consecutive delimiters recognized? 
0 – one delimiter (def), 1 – several delimiters.
10.	sheet | Sheet name of the Excel file.
11.	vars | List of variables for loading. Choice of all variables can be done by '*' (def).
12.	legs | Name of the variable with scale labels to axis X.

Examples:
Open (filename='airpass.cts');
open(filename='e:\filename.ctu', format=0, decsep=1, encoding=1, space=1, tab=1, semicolon=0, comma=0, delimone=0);
open(filename='D:\Program Files\CaterpillarSSA 3.3\DemoData\Wine.xls', format=1, decsep=1, encoding=1, space=0, tab=1, semicolon=0, comma=0, delimone=1, sheet='WINE', vars='Fort');

Return to the list of macros

TRANSFORMATION | Time series transformation

Parameters:
1.	vars | List of time series for transformation.
Value '*' indicates choice of all the time series. Values like 'Var*' mean that time series with names starting from 'Var' (e.g. 'Variab1','Var2' and so on) are chosen.
2.	return | Restoring the series loaded from file: 0 – no, 1 - yes.
3.	from | Number of the starting point of subseries.
4.	to | Number of the last point of subseries.
5.	step | Step of thinning.
6.	methodlin | Linear transformation: 0 - А*Х+В, 1 – standardization, 2 - normalization.
7.	lina | Value of "А" in the linear transformation formula (А*Х+В).
8.	linb | Value of "B" in the linear transformation formula (А*Х+В).
9.	invert | Inverting the time series values (the first value becomes the last and vice versa): 0 – no, 1 - yes.
10.	tosquare | Squaring the time series values: 0 – no, 1 - yes.

Examples:
Transformation (vars='*', To=100);
transformation(vars='Initial', return=0, from=1, to=100, step=1, methodlin=0, lina=1, linb=0, invert=0, tosquare=0);

Return to the list of macros

DECOMPOSITION | Time series decomposition

Parameters:
1.	series | Name of time series for setting window length (this is unrequired parameter essential for processing several time series of different lengths only).
2.	lag | Value of window length.
3.	centr | Centering: 0 – no (def), 1 - yes, 2 - double.
4.	prec | Decomposition precision (1-15). By default it is equal to 6 (def).
5.	maxcountpc | Should all principal components be calculated? 0 – no, 1 – yes (def).
6.	countpc | Number of principal components for calculation (this parameter is valid if maxcountpc=0).
7.	showvertchar | Do you want to see verticality characteristics? 0 - no, 1 - yes.
8.	showcovmatr | Do you want to see the covariance matrix? 0 – no, 1 – yes.
9.	showprgrmaver | Do you want to see the average periodogram? 0 – no, 1 – yes.
10.	axisprgrm | Type of Axis X values:
0 - periods, 1 – frequencies (this is valid if showprgrmaver=1).
11.	showprgrmmatr | Do you want to see the periodogram matrix? 0 – no, 1 – yes
12.	kindcovarmatr | Method for covariance matrix calculation:
0 - SVD (def),
1 - Diag. averaging,
2 - Toeplitz,
3 - Cyclical;
13.	calcevfrompc | Method for calculation of components (eigentriples) shares:
0 – by means of eigenvalues (def), 1 – by means of principal components (this value is senseless for the case kindcovarmatr=0).
14.	detection | Do you want to detect change points?: 0 - no (def), 1 – yes (this value is valid if centr=0 or 1).
15.	detstart | Start point of the base subseries for change-point detection (this is valid if detection=1).
16.	detcount | Length of the base subseries for change-point detection (this is valid if detection=1; the length of the base time series should be much less than the time series length and the window length should be corrected correspondingly).

Examples:
Decomposition (Series='sv', Lag=36, Centr=0, MaxCountPC=1, Prec=6);
decomposition(series='Initial', lag=12, centr=0, prec=6, maxcountpc=1, countpc=89, showvertchar=0, showcovmatr=0, showprgrmaver=0, axisprgrm=0, showprgrmmatr=0, kindcovarmatr=0, calcevfrompc=0, detection=0);

Return to the list of macros

GROUPING | Eigentriples (components) grouping

Parameters:
1.	groups | List of groups with the following notation (each group should be put in square brackets; components within a group should be separated by a comma):
a) '*' corresponds to no grouping (each group consists of one component) 
b) average corresponds to the first average component (this can be used after decomposition with centering)
c) average2 corresponds to the second average component (this can be used after decomposition with double centering)
d) 1, 2, ... indicate numbers of components. For sequential components the symbol '-' should be used, for examples, [3-6] instead of [3,4,5,6]. However, two sequential components should be separated by a comma, for example, [1,2]. 
2.	residual | Do you want to include the additional group consisting of the residual components? 0 - no, 1 - yes.

Examples:
Grouping (Groups='*',Residual = 0);
grouping(groups='average,[1],[2],[3]', residual=1);
grouping(groups='[1-4,6,7],[8,9],[10,11]', residual=1);

Return to the list of macros

RECONSTRUCTION | Time series reconstruction

Parameters:
1.	selgroups | List of selected groups. This list should be subset of the set produced at the Grouping stage (see the Grouping macro). Also, one can use notation '*' to choose all produced groups. 
2.	showpol | Do you want to see the characteristic polynomial? 0 – no, 1 – yes.
3.	showavererr | Do you want to see the averaging errors? 0 – no, 1 – yes.
4.	showresanalys | Do you want to perform analysis of reconstruction residuals? 0 - no, 1 - yes.

Examples:
Reconstruction(SelGroups='*');
reconstruction(selgroups='[1-4,6,7],[10,11]', showpol=1, showavererr=0, showresanalys=1);

Return to the list of macros

APPROXIMATION | Time series approximation

Parameters:
1.	start | Number of starting vector for approximation (start=1 is a standard choice).
2.	lstepuse | Type of approximation: 0 corresponds to global approximation, 1 corresponds to P-step (local) approximation.
3.	lstepval | Number of steps for P-step approximation (this is valid if lstepuse=1).
4.	method | Method of approximation: 0 – vector, 1 – recurrent, 2 – recurrent (custom).
5.	showresanalys | Do you want to perform analysis of approximation residuals? 0 - no, 1 - yes..
6.	showdistance | Do you want to see distances to the subspace? 0 – no, 1 – yes.
7.	showavererr | Do you want to see the averaging errors? 0 – no, 1 – yes (this is valid if method=0 and lstepuse=0).

Examples:
Approximation;
approximation(start=1, lstepuse=0, lstepval=0, method=1, showdistance=0, showavererr=0, showresanalys=0);

Return to the list of macros

FORECAST | Time series forecasting

Parameters:
1.	start | Number of the first forecasted point.
2.	count | Number of forecast points.
3.	method | Method of forecast: 0 – vector, 1 – recurrent, 2 – recurrent (custom).
4.	base | Base series for forecasting: 0 – reconstructed, 1 – initial, 2 – approximating (this value is valid if method=1 or 2)
5.	showpol | Do you want to see the characteristic polynomial? 0 – no, 1 – yes (this is valid if method=2).
6.	showconfintrvl | Do you want to construct confidence intervals: 0 - no, 1 – yes.
The following parameters are valid if showconfintrvl=1.
7.	confmethod | Method for construction of confidence intervals: 0 – empirical, 1 - bootstrap, 2 – channels (this value is admissible if base=0)
8.	confmodel | Mode of construction of confidence intervals: 0 corresponds to the normal distribution model, 1 corresponds to use of quantiles.
9.	conflevel | Confidence level (a real number between 0 and 1).
10.	confnumpoint | Number of points for confidence interval construction.
11.	conffrom | Number of the first point of the interval using for empirical confidence interval construction (this is valid if confmethod=0).
12.	confto | Number of the last point of the interval using for empirical confidence interval construction (this is valid if confmethod=0).
13.	mcarlsigma | Standard deviation of noise for the time series model used in construction of bootstrap confidence intervals (this is valid if confmethod=1). It is not recommended to use this parameter (if the standard deviation was not changed manually or by the Forecast macros, then its value is estimated on the base of the time series).
14.	mcarlrepeat | Number of simulations (the sample size) for construction of bootstrap confidence intervals (this is valid if confmethod=1).
15.	mcarlshowsim | Do you want to show the time series simulated for construction of bootstrap confidence intervals? 0 – no, 1 – yes (this is valid if confmethod=1).
16.	chanmode | Mode of channel construction: 0 – additive, 1 – multiplicative (this is valid if confmethod=2).
17.	chansizeauto | Way of calculation of channel width: 0 – custom, 1 – automatic (this is valid if confmethod=2).
18.	chansize | Channel size (this is valid if confmethod=2 and chansizeauto=0)

Examples:
Forecast(Count=84, method=1, ShowConfIntrvl=0);
forecast(start=90, count=10, method=1, base=0, showpol=0, showconfintrvl=1, confmethod=2, chanmode=0, chansizeauto=1);

Return to the list of macros

DETECT | Change-point detection

Parameters:
3.	selpc | List of components for change-point detection (components should be separated by a comma): 
a) average corresponds to the first average component (this can be used after decomposition with centering)
b) 1, 2, ... indicate numbers of components. For sequential components the symbol '-' can be used, for examples, '3-6' instead of '3,4,5,6'. However, two sequential components should be separated by a comma, for example, '1,2'. 
1.	calcmatr | Do you want to calculate the heterogeneity matrix?: 0 – no (def), 1 – yes.
2.	calcroot | Do you want to calculate roots of the characteristic polynomial? 0 – no (def), 1 – yes. 
3.	rootscount | Number of calculated modulus-ordered roots of the characteristic polynomial (this is valid if calcroot=1).
4.	det1_fix | Do you want to construct the detection function of first type ('symmetric') with the base interval of fixed length? 0 – no (def), 1 – yes.
5.	det2_fix | Do you want to construct the detection function of second type ('diagonal1') with the base interval of fixed length? 0 – no (def), 1 – yes.
6.	det3_fix | Do you want to construct the detection function of third type ('diagonal2') with the base interval of fixed length? 0 – no (def), 1 – yes.
7.	det4_fix | Do you want to construct the detection function of forth type ('row') with the base interval of fixed length? 0 – no (def), 1 – yes.
8.	det1_inc | Do you want to construct the detection function of first type ('symmetric') with the base interval of incremental length? 0 – no (def), 1 – yes.
9.	det2_inc | Do you want to construct the detection function of second type ('diagonal1') with the base interval of incremental length? 0 – no (def), 1 – yes.
10.	det3_inc | Do you want to construct the detection function of third type ('diagonal2') with the base interval of incremental length? 0 – no (def), 1 – yes.
11.	det4_inc | Do you want to construct the detection function of forth type ('row') with the base interval of incremental length? 0 – no (def), 1 – yes.
12.	det1_norm | Normalization for the detection function of first type:
0 – local (def), 1 – global.
13.	det2_norm | Normalization for the detection function of second type: 
0 – local (def), 1 – global.
14.	det3_norm | Normalization for the detection function of third type: 
0 – local (def), 1 – global.
15.	det4_norm | Normalization for the detection function of forth type: 
0 – local (def), 1 – global.
16.	det2_s | Integer value of the parameter for construction of the detection function of second type. 
17.	det3_s | Integer value of the parameter for construction of the detection function of third type.
18.	det4_s | Integer value of the parameter for construction of the detection function of forth type.
Examples:
Detect(SelPC = 'average,1-5',CalcMatr=1);
detect(selpc='1, 2, 3, 10, 11', calcmatr=1, calcroot=0, det1_fix=0, det2_fix=0, det3_fix=1, det4_fix=0, det1_inc=0, det2_inc=0, det3_inc=0, det4_inc=1, det1_norm=0, det2_norm=1, det3_norm=0, det4_norm=1, det2_s=96, det3_s=2, det4_s=98); 
Return to the list of macros

MATRDETECT | Matrix representation of change-point detection results

Parameters:
1.	countvec | Number of vectors from the test subseries for averaging procedure during construction of the heterogeneity matrix.
2.	norm | Normalization for heterogeneity calculation: 0 – local (def), 1 – global.
3.	showrowmatr | Do you want to see a row heterogeneity function? 0 – no (def), 1 – yes.
4.	showcolmatr | Do you want to see a column heterogeneity function? 0 – no (def), 1 – yes.
5.	rowmatr | Number of row of the heterogeneity matrix for construction of the row heterogeneity function (this is valid if showrowmatr=1). The value by default is 1 (def).
6.	colmatr | Number of column of the heterogeneity matrix for construction of the column heterogeneity function (this is valid if showcolmatr=1). The value by default is 1 (def).
7.	countroots | How many ordered by modulus roots of the characteristic polynomial do you want to depict? Roots are ordered by decrease of their moduli. Two conjugated roots are considered as one root. This parameter is valid if calcmatr=1, where 'calcmatr' is the parameter of the macros 'detect'. 
8.	sortby | Ordering the depicted roots: 0 – by modulus (def), 1 – by polar angle (by frequency)
9.	axisx | Characteristic of roots plotted on the axis X: 0 – real part (def), 1 – imaginary part, 2 – polar angle, 3 – modulus.
10.	axisy | Characteristic of roots plotted on the axis Y: 0 – real part (def), 1 – imaginary part, 2 – polar angle, 3 – modulus.

Examples:
MatrDetect;
matrdetect(countvec=10, norm=1, showrowmatr=1, showcolmatr=1, rowmatr=2, colmatr=3, countroots=5, sortby=1, axisx=3, axisy=2);

Return to the list of macros

SHOW | To show window

Parameter:
1.	windowname | Title of the window; it should coincide with one of titles of windows from the Windows menu of the program.

Example:
Show(windowname='Eigenfunctions');

Return to the list of macros

SHOWNEXT | To show the next window

No parameters.

Example:
ShowNext;

Return to the list of macros

SHOWPREV | To show the previous window

No parameters.

Example:
ShowNext;

Return to the list of macros

PAUSE | To pause macros execution

Parameters:
1.	msec | Number of milliseconds in the pause.
2.	beep | Do you want to hear a beep at the end of the pause? 0 – no (def), 1 – yes.
3.	breakkey | Do you want to break the pause by press of any key? 0 – no, 1 – yes (def).

Example:
pause(msec=3000, beep=0, breakkey=1);

Return to the list of macros

OPENMETASTOCKDATA | To import data from Metastock

Parameters:
1.	path | Path to the folder with Metastock data.
2.	symbols | List of ticker symbols for loading. Ticker symbol should be ended by a colon and a digit coding the type of series: 1 – Open, 2 – High, 3 – Low, 4 – Close, 5 – Volume. Symbols should be separated by a comma.

Example:
openmetastockdata(path='С:\MetaStock Data\Real-time Data\', symbols = 'OEX:4, NYSE:1');

Return to the list of macros

SAVEDATA | To save data of the active window

Parameters:
1.	filename | File name.
2.	prec | Precision of saved values (0-15).
3.	precfmt | Number format: 0 – scientific (exponential), 1 – number (fixed-point).
4.	encoding | Encoding: 0 - OEM, 1 - ANSI.
5.	vars | List of variables, which you want to save. The order of variables does matter. Value '*' indicates choice of all the variables. Values like 'Var*' mean that variables with names starting from 'Var' (e.g. 'Variab1','Var2' and so on) are chosen.
6.	inclnum | Do you want to save numbers of points? 0 – no, 1 – yes.
7.	inclcom | Do you want to save comments to data? 0 – no, 1 – yes. 
8.	comments | Text of comments substituting comments by default (this is valid if inclcom=1)
9.	method | How to save data in Excel file (with extension 'xls'):
0 – Overwrite the existing file
1 – Create a new sheet
2 – Replace the chosen sheet
3 – Add to the chosen sheet.
10.	sheet | Name of the chosen sheet (this is valid if method=2 or 3).

Examples:
Savedata (filename='a.cts', vars='*', comments='My test');
savedata(filename='e:\filename.xls', prec=5, precfmt=0, encoding=0, vars='Initial', inclnum=1, inclcom=0, method=0, sheet=1);

Return to the list of macros

GRAPHEXPORT | To export image of the active window

Parameters:
1.	filename | File name.
2.	format | Graphics format:
0 – bitmap (def)
1 – metafile
2 - enhanced metafile
3 – postscript.

Example:
graphexport(filename='C:\img.emf', format=2);

Return to the list of macros

PERIODOGRAM | To construct periodogram

Parameters:
1.	series | Time series for construction of the periodogram. The first time series from the base or top (if any) window is considered by default (def).
2.	axisx | Values plotted on the axis X: 0 - periods, 1 – frequencies.
3.	cut | Do you want to analyze a subseries? 0 – no, 1 – yes.
4.	from | The first point of the subseries (this is valid if cut=1)
5.	to | The last point of the subseries (this is valid if cut=1)
6.	addzero | Number of zero values added to the time series before periodogram calculation.
7.	centre | Do you want to centre the time series before periodogram calculation? 0 – no, 1 – yes.

Examples:
Periodogram(AxisX=1,Centre=1);
periodogram(series='Initial', axisx=0, cut=1, from=10, to=100, addzero=0, centre=1);

Return to the list of macros

WINDOWCLOSE | To close windows

Note: this macro is useful for closing windows with periodograms, since these windows should be closed manually.
Parameter:
all | What windows do you want to close? 0 – the active window (def), 1 – all windows.

Example:
windowclose(all=0);

Return to the list of macros

CHANGEDIR | To change the current directory

Parameter:
1.	path | Path to set a new current folder.

Example:
changedir (Path='e:\cat\data');

Return to the list of macros

LOADTEMPLATE | To load options template from file

Parameters:
1.	filename | Name of a file with template of graphics options.
2.	apply | How to apply the template to the windows open before? 0 – not to apply, 1 – apply to the active window (def), 2 – apply to all open windows. 

Example:
loadtemplate (filename='e:\default.cto', apply=1);

Return to the list of macros

MACROS | To run macros from file
Note: one can use this macro (combining with the pause macro and with loading time series from an updated Excel file) to simulate online processing.

Parameters:
1.	filename | Name of the file with macros.
2.	count | Number of repeats. The value by default is 1 (def).

Example:
macros(filename='e:\cater.ctm', count=3);

Return to the list of macros

STOP | To stop macros

No parameters.

Example:
Stop;

Return to the list of macros

QUIT | To exit from the application

Parameters:
1.	savereport | Do you want to save the log-file?
0 - no (def), 1 - yes. 
2.	filename | File name. The name by default is 'cater.ctp' (def).

Example:
quit(savereport=1, filename='e:\cater.ctp');

Return to the list of macros