Skip to content

das2_psd

Jump to bottom
C. Piker edited this page Aug 18, 2021 · 9 revisions

das2_psd - A power spectral density stream operator

NAME

das2_psd - Estimate the power spectral density of set of signals using Discrete Fourier Transforms.

SYNOPSIS

das2_psd [options] length slide_denominator

DESCRIPTION

das2_psd is a classic Unix filter, reading das2 streams on standard input and producing a transformed stream containing power spectral density estimates computed using a Discrete Fourier Transform (DFT). In general for each length of input values, the output will contain length/2 +1 output values. For this program length must be an even number, but need not be a power of two.

Input data are gathered into DFT buffers in the following manner:

  • Values with regular time cadence are read into a buffer of size length. If the cadence is broken, values are discarded and accumulation starts over.

  • Once the buffer has been filled, a power spectral density calculation is preformed on the input values and output as a Z dataset.

  • Values are shifted down by length/slide_denominator points and filling continues

The following table relates slide_denominator and percentage overlap for sliding DFTs:

Slide Denominator Percent Overlap
1 0%
2 50%
3 66%
4 75%
5 80%
... ...

Stream morphology changes

The shape of the stream will change when transformed. Stream morphology changes fall into three categories:

  • Case A: X column with multiple independent Y columns

    I/O Number Packets Shape
    Input length X_coord, Y1_point, Y2_point, Y3_point
    Output 1 X_center, Z1_set, Z2_set, Z3_set

    So the das2_psd adds an extra physical dimension to the stream. Where once only the X coordinates were present, now both X and Y coordinates are included as much of the X resolution has been lost to create the new Y (i.e. frequency) dimension. For each length X values, only the center value is output.

  • Case B: X column with multiple independent Y sets

    I/O Number Packets Shape
    Input 1 X_coord, Y1_set, Y2_set, Y3_set
    Output 1-N X_coord, Z1_set, Z2_set, Z3_set

    For Y sets, X offset values must be included. When transformed X offset values associated with each Y set are lost to create the new Y coordinates.

  • Case C: X column independent Y columns and Y sets

    I/O Number Packets Shape
    Input 1 X_coord, Y1_point, Y2_set, Y3_set
    Output 1-N X_coord, Y1_point, Z2_set, Z3_set

    In case C (mixed line-plot and table data) above, the Y values are treated as extra coordinate parameters and just copied to the output stream. The X offset values associated with each input Y set are, again, lost to create new Y coordinates.

Mode change detection

Mode changes in the input data stream are detected and trigger new output stream packet definitions. In the example below the sampling rate of a magnetometer drops to have it's normal duty cycle, During this period, the "frequency" table of the output stream is not the same as the surrounding regions. Mode change example plot

COMMAND LINE OPTIONS

-h,--help

Display help text to standard output and exit.

-v,--version

Display source version information and exit.

-d,--keep-dc

By default the DC component of the waveform is shifted out by subtracting the average value from each point. Use this option to keep the DC component

-c "DATUM",--cadence="DATUM"

The display interpolation DATUM that makes sense for waveform data is often way too small for spectrograms. For streams transformed in a new one of 2x the length of the DFT is emitted. Use this parameter to override the xTagWidth that would normally be transmitted. Note: A space is required between unit value and the unit string, so this argument will need quotes.

-n,--no-skip

Do not skip over input packet types that cannot be transformed, instead exit the program with an error message. Individual data packets that cannot be transformed are always skipped.

-x,--trans-x

A series of packets can be equally spaced in either the X or the Y dimension. By default s are assumed to be waveform packets which have a regular Y spacing but irregular X spacing. Use this option to force all transforms to be over the X dimension.

-m "ID,DATUM" ,--map "ID,DATUM"

For set the packet ID to use when ever a particular sample time is detected. This allows for consistent packet ID assignment for datasets with variable sample rates and Thus simpler reduced-resolution cache sets (see das2_cache_rdr for mor info). If this option is not selected packet ID are assigned in order base on the detected sample rate in the input stream.

-j,--max-jitter BREAK

Only applies to transforms over the X direction. For X,Y,Y streams, each packet contains one independent value. Due to limited precision in X values, the sampling period may appear to change between consecutive packets when, in fact, the input data were collected at fixed intervals.

To determine if a variation in the sampling period should be treated as a break in a continuous set of samples, the Jitter Fraction computed for each three points via:

                    FRACTION = |difference(τ₁ , τ₀) / average(τ₁ , τ₀)|

                 where  τ₀ = x₁ - x₀  and   τ₁ = x₂ - x₁  for any three X
                 points.

If FRACTION is bigger then BREAK, then the waveform accumlators are cleared and a new waveform accumlation process is started. If FRACITON is BREAK or smaller, it is considered to be simple digitization jitter and ignored.

By default BREAK is 0.01, though may be changed via this option.

LIMITATIONS

Transforms for input packets are always preformed in the Y dimension and never cross packet boundaries. Thus if the LENGTH argument is larger the number of items in all packets, no output is generated.

Transforming N packets in the X dimension, to N s in the 1/X dimension is useful, but not yet supported.

AUTHOR C. Piker

SEE ALSO das2_bin_avg, das2_bin_avgsec, das2_ascii and the das2 docs for a general introduction.

Clone this wiki locally