# General usage notes

Command line: All programs are called from the command line with certain options, most with an argument which may or may not be seperated with a blank. Options and their meanings are listed in the program specific sections of the manual. Running each program with the option `-h` also displays a short usage note.

Usage in pipes: Almost all programs expect one or more file names. These may appear anywhere on the command line, in fact everything that is not a valid option is treated as a file name. Except when indicated otherwise, a file name `-` indicates that `stdin` is used for input rather than a file. If no file name is given at all, `-` is assumed as a default. This can be convenient since you can use many of the routines in pipelines.

Output file names: The programs' output is written in most cases to `stdout` by default. This behaviour can be overridden in two steps. If the option `-o` is specified with no argument, output is done to files the names of which are formed from the input file names by appending a specific string. This can be a fixed sequence of characters or it can contain a running number in cases where multiple output files have to be produced. If the flag `-o` is specified with a file name argument, that file is used for output. Note that with multiple input files, the behaviour is somewhat awkward since every time the output file is opened for writing, the current content is destroyed. Thus it will eventually contain only output corresponding to the last input file.

Data file format: One value per line is read from time series data files. Any line that cannot be interpreted as data is taken as a comment and ignored.

Column selection (univariate): The default is that data is read from the first column, further columns are ignored. However, it is possible to read from other columns. You can specify the column with the option `-c`.

Column selection (multivariate): The general convention for multivariate column selection is as follows. Columns can be given as a comma seperated list with the option `-c#[,#]` . Wherever the number of columns is selectable, this can be done with the option `-m#` or the first number in its argument. The precedence of these settings are as follows:

`-m` overrides `-c`
`-c` overrides the default only if more columns are specified.

Verbosity levels: All programs accept an option `-V` that can have an integer argument. With this option, the level of verbosity of the output is controlled. At the very least, fatal or panic messages are printed. All other kinds of messages have integer level values which are powers of two. Thus for a specific selection of messages, just add these level values and pass the result to the `-V` option. For example, the specific documentation of a program may say:

> Verbosity levels (add what you want):

> 1 = input/output
> 2 = progress report
> 4 = mean squared error
> 8 = date and time

In that case, `-V 10` (8+2) would result in progress reports and date and time beeing printed, but no i/o reports and mean squared errors.

Usually, 1 causes input/output information (files opened etc.) and 128 echoes the first data item read. This is useful for strange file formats to check if the input is read correctly.

By the way, if you hate the version and copyright message but you don't want to switch off level 1, you can also compile the C programs with the constant OMIT_WHAT_I_DO defined, e.g. by saying

         > setenv CC "cc -DOMIT_WHAT_I_DO"

(tcsh syntax) before running configure. Thomas doubts that there is anyone except Rainer who needs this ;-)

Here is a list of options that occur most frequently:

> general | `-h` | display short usage message
> | `-V` | verbosity level
> input/output | `-l` | maximal length to be processed
> | `-x` | number of excluded transients
> | `-c` | read data from column
> | `-o` | alternale output file name
> embedding | `-d` | delay, minimal delay
> | `-D` | maximal delay
> | `-m` | embedding dimension, minimal embedding dimension
> | `-M` | maximal embedding dimension
> | `-q` | dimension to project on
> length scales | `-r` | (minimal) length scale in physical units
> | `-R` | same but maximal
> | `-e` | (minimal) length scale if data is rescaled to [0:1]
> | `-E` | same but maximal
> | `-v` | length scale as fraction of rms variance
> | `-%` | length scale in percent of rms variance
> neighbourhoods | `-k` | minimal number of neighbours
> | `-K` | maximal number of neighbours
> time windows | `-t` | Theiler window, minimal temporal separation of neighbours
> | `-T` | the reverse of `-t` : maximal temporal separation of neighbours
> prediction times | `-s` | number of time units to follow time evolution
> | `-L` | time interval to predict after end of data

general index * TISEAN home