NAME
nsfo -- compute global EEG descriptors
USAGE
nsfo [options] [infile [outfile]]
DESCRIPTION
The `nsfo' utility computes global EEG descriptors as defined
by Wackermann (1996,1999).
OPTIONS
The `nsfo' utility uses the standard getopt() interface to decode
command line options. Options have to by prefixed by a dash `-';
options that don't require an argument may be grouped together into
a compact string (i.e. `-1Tv' is aequivalent to `-1 -T -v').
The following is a list of options recognised by `nsfo':
-1 Compute Omega as a single descriptor.
-2 Compuute descriptors Sigma and Phi, not Omega.
-3 Compute all three descriptors, Sigma, Phi, Omega; this
is the default.
-c flags Center data before computing descriptors; flags may be
`s' (space domain), `t' (time domain), or `st' (space &
time domain).
Centering in space domain means subtracting the arithmetic
mean of values over all channels from each data vector
(average reference).
Centering in time means subtracting the arithmetic mean
of all sampling points from each channel (baseline zero).
-C Print covariance or correlation matrix to output (full matrix).
-f freq Sampling frequency in samples/time unit. This value has to
be specified if Phi is being computed.
-h n Skip first n lines of input. This option can be used
* to skip headers etc. from silly formatted ASCII files
* to compute the descriptors for consecutive data blocks
-l Print log(Omega) to output.
-L Print logarithms of all descriptors to output.
-N n,k Data size is n data vectors by k channels; these parameters
have always to be specified.
-n Suppress terminating line feed (`\n') in output.
-o fmt Numeric format string; fmt may be any printf() format string
suitable for output of a double float value; default is `%le'
(see also subsection OUTPUT).
-p n Precision of the diagonalisation procedure (see below,
subsection METHOD for details).
-R Use correlation matrix instead of the covariance matrix.
-s mask Select channels from the input data stream, as specified by
an encoded bit-string, mask (bit 1 => use channel, bit 0 =>
ignore channel). See below, section INPUT for details.
-T Print covariance or correlation matrix to output (lower
triangle only).
-v Print run-time messages to stderr. This may be useful when
invoking `nsfo' from a shell script.
-? Print usage info and exit.
-! Print version info and exit.
METHOD
The rationale of the global EEG descriptors is given in articles:
Wackermann J (1996) Beyond mapping: estimating complexity of
multichannel EEG recordings. Acta Neurobiol Exp 56:197-208.
Wackermann J (1999) Towards a quantitative characterisation of
functional states of the brain: from the non-linear methodology
to the global linear description. Int J Psychophysiol 34:65-80.
Evaluation of the descriptors Sigma and Phi requires only minimal
computation expenses (euclideian norms of original data vectors and
their first differences).
Evaluation of the descriptor Omega requieres computation of the
eigenvalues of the k x k covariance matrix (k = number of channels
entering the computation). The method used by `nsfo' is Jacobi's
diagonalisation, a method which is not the fastest but quite easy
to implement. This is an iterative method: the computation stops
when the largest absolute value of a non-diagonal element is less
than trace(C) / 10^n, where C is the covariance matrix and n is the
precision parameter specified by the option `p'. Default value for
n is 6 which provides quite well accuracy in most cases.
The (normalised) eigenvalues are combined to a single-valued
descriptor, Omega, using a formula (in TeX notation)
log(Omega) = - sum[i=1...k] lambda_i log(lambda_i)
In the article (Wackermann 1999), Omega is defined as exp() function
of the quantity defined above; the aim of taking exp() was to map
the interval [0,log k] to a more intuitive range [1,K] --- a rather
unfortunate idea --- and this is what `nsfo' writes to output.
However, it is strongly recommended to use log(Omega) for statistics;
use option `-l' (or `-L' when taking log's of all three descruiptors).
Note that the logarithms computed by `nsfo' are base 10.
INPUT
The `nsfo' utility reads ASCII files in any format recognised by
atod(). The data for separate channels have to separated by one
or more spaces or tabs but needn't follow any fixed format. There
is only one important limitation: the entire data vector has to be
read in a single line. Multi-channel data scattered over several
lines are not allowed.
The program makes it possible to compute global descriptors for
only a subset of selected channels, using option `-s'. The option
requires an argument which specifies a bit-string in a binary,
octal, or hexadecimal notation. The bit-strings are evaluated
from right to left (LSB indicates channel #1, MSB indicates the
lest channel).
For example, assume that the input is 19-channel EEG recorded from
the following scalp positions: Fp1, Fp2, F7, F3, Fz, F4, F8, T3, C3,
Cz, C4, T4, T5, P3, Pz, P4, T6, O1, O2. Then the selection mask for
the entire electrode data if the entire electrode array is `0x7ffff'
(hexadecimal) or `0o1777777' (octal) or `0b1111111111111111111'
(binary). The mask selecting only left hemisphere electrodes would
be `0b0100011000110001101', or `0o0430615', or `0x2318d'; and the
mask selecting only right hemisphere electrodes, respectively, would
be `0b1011000110001100010', or `0o1306142', or `0x58c62'.
OUTPUT
The `nsfo' utility writes the values of the descriptor(s) to outfile,
or to standard output if `-' is given for outfile or if outfile is
not specified at all.
The results are written to output in a format specified by the `-o'
option, followed by a printf() compliant format string; the default
format is `%le' (scientific notation). The default format may be
redefined by setting the OFMT variable in the working environment.
EXAMPLES
nsfo.exe -N 256,21 -f 128 -c st mydata.eeg mydata.out
Computes all three global descriptors from 256 samples of 21-channel
data stream, sampled at frequency 128 data vectors/second. Data is
read from file `mydata.eeg', centered in space and time domain, and
results are written to file `mydata.out'.
nsfo.exe -1l -N 1024,33 -s 0b111100000000000000000000000001111 gee
Computes log(Omega) for 1024 samples read from file `gee'. Only
8 channels (1-4 and 30-33) are selected from the 32-channel data
stream. The same selection mask could be written more compactly,
using hexadecimal notation: `-s 0x1e000000f'. Result is written
to stdout.
nsfo.exe -1 -N 500,19 -o "omega=%.4lf"
Computes Omega for 500 samples of 19-channel data stream read
from the standard input and writes the result to the standard
output in the format `omega=#.####'.
BUGS
Help info printed by `nsfo -?' mentions two more options `x' and
`X'. These options haven't been implemented and are simply ignored;
don't try.
There are probably more bugs; if you detect any, please send a report
to .