das2_psd

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.

Unit Conversion

The das2 units module is use to determine output units automatically. In general das2 unit strings follow PDS3 conventions, though non SI units are also supported. For example:

   PSD( samples [V/m] in time [UTC] )     = power [ V**2 m**-2 Hz**-1 ] @ UTC
   PSD( pressure [bar] in location [km] ) = power [ bar**2 km ] @ km

Various input unit conventions are supported, but output is always in the canonical form:

A**power_of_A B**power_of_B ... 

Where exponentials are dropped for powers of 1.

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.

-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 more 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 accumulators are cleared and a new waveform accumulation process is started. If fraction 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.

Addendum

Limitations: Transforms are always performed over X-offset values if these are provided. If X-offset values are not provided, then transforms are applied to the X reference values in a packet. For now, the "time" axis is thus fixed by the form of the input data.

Author: C. Piker

See Also: das2_bin_avg, das2_bin_avgsec, das2_ascii and the das2 docs for a general introduction.

Source: das2_psd.c