Commit d6cd68f7 authored by thomas.forbriger's avatar thomas.forbriger
Browse files

ts/wf/foutra [TASK][DOC]: revise usage text

parent 0ee0cf6e
......@@ -13,31 +13,26 @@ infile input filename
-v be verbose
-D debug mode
-o overwrite output
-boxcar apply boxcar taper (i.e. no taper; default is Hanning)
-amplitude calculate amplitude spectrum
-power calculate power spectrum
-type type select input file type
-Type type select output file type
-avg[=n] smooth power spectrum by averaging over n samples
-rbw[=n] smooth power spectrum by averaging over n decades
-demean[=n] remove average (determined from n samples)
-detrend[=n] remove trend (determined from n samples)
-derivative[=n] take n-th derivative of time series
-scalerbw[=n] scale to mean value in n decades
-amplitude compute Fourier amplitude spectrum
-power compute power spectral density (or power spectrum)
-harmonic scale output appropriate fro harmonic signals
useful for two-tone-tests of linearity (see below)
-rms report rms values of input data
-boxcar apply boxcar taper (i.e. no taper; default is Hanning)
-demean[=n] remove average from input time series
(determined from n samples)
-detrend[=n] remove trend from input time series
(determined from n samples)
-divisor[=n] FFT becomes very inefficient if the factorization
of the number of samples includes large prime numbers.
This option removes the least number of samples to
the total number of samples a multiple of "n"
-ASCII[=base] write result to two-column ASCII files with basename 'base'
-logascii[=n] write ASCII data on logarithmic frequency axis with
one value per 'n' decades
-avgascii only average values for output to ASCII file
this option speeds up calculation together with
-scalerbw which increases computation time
with the square of frequency
-rms report rms values of input data
-harmonic scale output appropriate fro harmonic signals
useful for two-tone-tests of linearity (see below)
-pad n pad time series with zeroes; n gives the integer factor
for the number of samples; the raw amplitude spectrum
has to be understood as the spectrum of the whole
......@@ -52,5 +47,22 @@ infile input filename
useful for two-tone-test where spectral smoothing
of background noise is anticpated, while maintaining
the full resolution for harmonic peaks
-avg[=n] smooth power spectrum by averaging over n samples
values still specify power spectral density
-rbw[=n] smooth power spectrum by averaging over n decades
values still specify power spectral density
-derivative[=n] effectively take n-th derivative of time series
computation is done in the Fourier domain and has no effect on
time series
-scalerbw[=n] scale to mean value in n decades
output value then are not power spectral density but average
signal power in the specified bandwidth
-ASCII[=base] write result to two-column ASCII files with basename 'base'
-logascii[=n] write ASCII data on logarithmic frequency axis with
one value per 'n' decades
-avgascii only average values for output to ASCII file
this option speeds up calculation together with
-scalerbw which increases computation time
with the square of frequency
#
# ----- END OF foutra_options.txt -----
......@@ -2,39 +2,65 @@
# ============================================================================
# foutra: online usage information
# --------------------------------
#
foutra applies spectral analysis to time series data. Its primary purpose is
the computation of power spectral density (-power). Additionally it offers two
other modes of scaling. Values of the Fourier amplitude spectrum can be
written to file (-amplitude) as well as values of a spectral representation,
where peak values in the spectrum represent amplitudes of harmonic signals
present in the time series (-harmonic). If non of these modes is selected, a
tapered version of the input time series is written to the output file.
Output is written to a file in any of the time series data formats (-Type)
supported for output. Samples are then values along increasing frequency,
sampling interval is given in Hertz. The first sample in the file is at 0 Hz.
The last is the sample at Nyquist frequency.
As an option (-ASCII) output to plain ASCII is supported, where the first
column in each file specifies frequency in Hertz and the second column
specifies the corresponding spectral values. This format supports output with
logarithmic sampling along the frequency scale (-logascii).
Power spectral density
----------------------
Option: -power
If input units are K, then the output units of power spectra will
be K*K/Hz. The units for amplitude spectra then are K/Hz. If scaling
to the mean in a relative bandwidth is used (only applies for power
spectra; switch -scalerbw) the output units are K*K.
The Fourier transformation does not exist for harmonic signals.
The option "-harmonic" supports the analysis of a time limited
portion of an harmonic signal. If this option is set, the output
is scaled such that the spectral values of the peaks of harmonic
signals are the time domain amplitude in units of K.
The integral over the power spectral density calculated by foutra
over the total bandwidth (over all frequencies from 0 Hz to Nyquist
frequency) provides the total power of the signal (i.e. the
variance of the input signal, i.e. the square of the rms value).
This is called the one-sided power spectral density.
The input signal can be extended by padding with zeroes. This
mainly is used to obtain a smoother representation of the
corresponding spectral display where the amplitude of narrow
peaks might not fall on a spectral node when analysing harmonic
signals. The spectral representation consequently is scaled
to the length of the applied taper function (and not to the
full length of the padded time series) for harmonic
signal analysis and power spectral densities, since the
signal under investigation is understood as being infinite in
time. For amplitude spectra of transient signals (the default)
no scaling to a time window takes place, since padding with
zeroes is understood as not altering the signal.
Output is written in SFF. There the sampling interval provided
in the WID2 line specifies the frequency sampling interval of the
spectrum. The first coefficient in the file is at 0 Hz. The
last is the coefficient at Nyquist frequency.
Option -scalerbw selects the computation of average signal power in a finite
relative bandwidth (rather than power spectral density).
Amplitudes of harmonic signals
------------------------------
Option: -harmonic
The Fourier transformation does not exist for harmonic signals. The option
"-harmonic" supports the analysis of a time limited portion of a harmonic
signal. If this option is set, the output is scaled such that the peak values
in the spectrum equal the amplitude of the corresponding harmonic time domain
signal in units of K.
Details of the scaling used for this option are given in doxygen formatted
comments at the end of the source code file.
The input signal can be extended by padding with zeroes (-pad). This mainly is
used to obtain a smoother representation of the corresponding spectral display
where the amplitude of narrow peaks might not fall on a spectral node when
analysing harmonic signals. The spectral representation consequently is scaled
to the length of the applied taper function (and not to the full length of the
padded time series) for harmonic signal analysis and power spectral densities,
since the signal under investigation is understood as being infinite in time.
For amplitude spectra of transient signals (the default) no scaling to a time
window takes place, since padding with zeroes is understood as not altering
the signal.
#
# ----- END OF foutra_usage.txt -----
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment