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 ...@@ -13,31 +13,26 @@ infile input filename
-v be verbose -v be verbose
-D debug mode -D debug mode
-o overwrite output -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 input file type
-Type type select output 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 -amplitude compute Fourier amplitude spectrum
-demean[=n] remove average (determined from n samples) -power compute power spectral density (or power spectrum)
-detrend[=n] remove trend (determined from n samples) -harmonic scale output appropriate fro harmonic signals
-derivative[=n] take n-th derivative of time series useful for two-tone-tests of linearity (see below)
-scalerbw[=n] scale to mean value in n decades
-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 -divisor[=n] FFT becomes very inefficient if the factorization
of the number of samples includes large prime numbers. of the number of samples includes large prime numbers.
This option removes the least number of samples to This option removes the least number of samples to
the total number of samples a multiple of "n" 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 -pad n pad time series with zeroes; n gives the integer factor
for the number of samples; the raw amplitude spectrum for the number of samples; the raw amplitude spectrum
has to be understood as the spectrum of the whole has to be understood as the spectrum of the whole
...@@ -52,5 +47,22 @@ infile input filename ...@@ -52,5 +47,22 @@ infile input filename
useful for two-tone-test where spectral smoothing useful for two-tone-test where spectral smoothing
of background noise is anticpated, while maintaining of background noise is anticpated, while maintaining
the full resolution for harmonic peaks 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 ----- # ----- END OF foutra_options.txt -----
...@@ -2,39 +2,65 @@ ...@@ -2,39 +2,65 @@
# ============================================================================ # ============================================================================
# foutra: online usage information # 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 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 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 to the mean in a relative bandwidth is used (only applies for power
spectra; switch -scalerbw) the output units are K*K. 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 The integral over the power spectral density calculated by foutra
over the total bandwidth (over all frequencies from 0 Hz to Nyquist over the total bandwidth (over all frequencies from 0 Hz to Nyquist
frequency) provides the total power of the signal (i.e. the frequency) provides the total power of the signal (i.e. the
variance of the input signal, i.e. the square of the rms value). variance of the input signal, i.e. the square of the rms value).
This is called the one-sided power spectral density. This is called the one-sided power spectral density.
The input signal can be extended by padding with zeroes. This Option -scalerbw selects the computation of average signal power in a finite
mainly is used to obtain a smoother representation of the relative bandwidth (rather than power spectral density).
corresponding spectral display where the amplitude of narrow
peaks might not fall on a spectral node when analysing harmonic Amplitudes of harmonic signals
signals. The spectral representation consequently is scaled ------------------------------
to the length of the applied taper function (and not to the Option: -harmonic
full length of the padded time series) for harmonic
signal analysis and power spectral densities, since the The Fourier transformation does not exist for harmonic signals. The option
signal under investigation is understood as being infinite in "-harmonic" supports the analysis of a time limited portion of a harmonic
time. For amplitude spectra of transient signals (the default) signal. If this option is set, the output is scaled such that the peak values
no scaling to a time window takes place, since padding with in the spectrum equal the amplitude of the corresponding harmonic time domain
zeroes is understood as not altering the signal. signal in units of K.
Output is written in SFF. There the sampling interval provided Details of the scaling used for this option are given in doxygen formatted
in the WID2 line specifies the frequency sampling interval of the comments at the end of the source code file.
spectrum. The first coefficient in the file is at 0 Hz. The
last is the coefficient at Nyquist frequency. 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 ----- # ----- 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