Analyze: Configuration parameter reference

General syntax

key=value
key
key=
@includefile
#comment

All arguments follow basically a key value syntax. The value might be completely omitted (including the equals sign). In this case a parameter specific default value is assigned, e.g. boolean options usually assign the true value by default. But if the argument ends with = then an empty value is assigned. This might not be valid for all data types.

• There is always exactly one parameter per command line argument or per line in an included file.

• If an argument starts with @ then this is an include directive. In this case all lines in the specified file are treated as parameters. Included files may include further files.

• Parameters set in included files can be overridden if they are assigned after the include. The last value wins.

• Arguments or lines starting with # are ignored.

Data types

boolean

Boolean parameters accept the values 1, true, yes or on as true and the values 0, false, no or off as false. Additionally the value toggle might be uses to change the current state.
If the value is omitted true is assumed.

integer

Integer parameters accept non-negative whole numbers. Depending on the parameter it may accept only a smaller domain.
Numbers starting with a leading 0 are octal, numbers starting with 0x hexadecimal. Powers of 2 can be entered with a trailing ^, e.g. ^12 = 2¹² = 4096.

floating point

Floating point parameters accept fractional and/or negative numbers and also decimal exponents but no thousands separator. Again the individual parameter might restrict the domain.

string

String parameters accept any single line string, but there is a length restriction of 1kB. Leading or trailing blanks are kept.
Note that the syntax key= will assign an empty string while just key will assign a null value or the default for this parameter.

constants

Constants do not accept any value, they just assign a constant value. E.g. the option loop assigns 0 to the parameter ln.

Alphabetic list

General options

fsamp=freq - sampling frequency of input data

This parameter should always be specified unless it is the default value of 48 kHz. analyze cannot read headers of PCM data files.

ff32 - read/write floating point samples

Read input (option in) and write output (option out) samples in 32 bit floating point format (rather than 16 bit integer).

fi16, fi24, fi32 - read/write integer samples

Read input (option in) and write output (option out) as signed integers in the platform's native byte order (unless xb is used).

xb - swap bytes of PCM data

Change endianess of PCM input and output data.

fftlen=num - analysis block length

Number of samples for one analysis cycle. This is also the length of the FFT. It is strongly recommended to use a power of 2 if you activated the FFT mode.
The default values is 8192.

rref=res - reference resistor

Scale the denominator by res before any further processing. By default no scaling takes place.
This option could be used to compensate for constant factors of your measurement setup like a reference resistors to measure the current or the amplifier gain.

dcfg=filename - dump effective configuration to filename

When this option is activated all configuration parameters are saved to filename after all arguments have been parsed and before any other processing. This includes parameters that are not explicitly set. The file format is compatible to Analyze configuration files, i.e. can be used for configuration input. It can also be used for further processing e.g. by a program like Gnuplot.

Input data options

in[=filename] - name of input file

Read PCM data to analyze from filename. If filename is - or omitted use stdin. The file name could be a transient source like a pipe or a character device.
This option implicitly enables the analysis part of the program.

wraw[=filename] - write raw data

Write raw data to filename. If the filename is omitted the data is written to raw.dat. These is the raw input data without any processing so far, except for option psa. It is intended for diagnostics only. → file format

psa=num - discard first num samples

Use this to discard spikes at the starting or to reach a steady state. You may also use this option to discard headers from PCM files like RIFF wave format.

pte - discard trailing input

If the analysis has completed (option ln) the input is read continuously, but the data is discarded. This can be useful if the data source behaves unexpectedly if the data drain is closed. This also causes analyze not to terminate before either the input stream is closed or an interrupt signal is received.

diff - differential input mode

normally: nominator or U(t) := channel 1 (L), denominator or I(t) := channel 2 (R)
differential mode: nominator or U(t) := channel 1 (L), denominator or I(t) := channel 2 − channel 1 (R-L)
Differential mode is useful if you want to do impedance measurements without a differential instrumentation amplifier. You could simply use a series of a reference resistor with the unknown impedance. But note that the difference of similar numbers may become very sensitive to channel differences for low currents. It is recommended to use at least the differential weight function in FFT mode to reduce this kind of errors.

xch - swap input channels

Swap left and right input channel. Normally the left channel contains the nominator and the right channel the denominator (reference). With this option the channels are swapped. You my combine this with differential mode.

al=num - add num cycles

Add num cycles of raw input data before starting analysis. This improves the SNR by the square root of num. Note that the reference signal must be cyclic to use this option.
This is effectively the same than taking a num times as large FFT size and taking only every num-th frequency channel, but it is significantly faster.

ainc - incremental mode

The raw input data is added in sets of the analysis length. This causes a increasing accuracy by building an average over more and more cycles. Note that the reference signal must be cyclic to use this option and it must be exactly synchronized to the sampling frequency.
This option is an alternative to sweep measurements.

olf=file - override nominator

Override nominator (left channel by default) with a column from file.

olc=column - column to override numerator

Column in the file to override the nominator. Requires olf.

orf=file - override denominator

Override denominator (right channel by default) with a column from file.

orc=ccolumn - column to override denominator

Column in the file to override the denominator. Requires orf.

Output data options

out=filename - write reference PCM data to filename

Write PCM data to filename. If filename is - or omitted use stdout. The file name could be a transient drain like a pipe or a character device.
This option implicitly enables the reference generator part of the program.

gain=dB - master gain

Apply this value in dB to the to 0dB FSR (full scan range) normalized reference output. Because of the scaling only negative values are reasonable.

symmout - symmetric stereo output

Invert the output of the second channel of single channel reference. This cannot be combined with stereo.

scale=power - noise type

Exponent of the energy distribution. 0 := white noise, -1 := pink noise. 0 by default.

rspec[=filename] - read design spectrum of the reference signal

Read the frequency domain reference signal from filename or spectrum.dat if filename is omitted. See → file format.
Using this option effectively disables all options related to the design spectrum creation, first of all fmin and fmax.

wspec[=filename] - write design spectrum of the reference signal

Writes the frequency domain reference signal to filename or spectrum.dat if filename is omitted. See → file format.

wref[=filename] - write time domain reference data

Writes one cycle of the reference signal to filename. If the filename is omitted ref.dat is used. See → file format.
The file is written only at setup once unless sweep mode is used.

aref - append reference data file

Append the reference data file instead of overwriting it. This is useful in sweep mode to get not only the latest reference in the file. See also option wref.

Control options

ln=num - number of cycles to process

The program terminates automatically after num analysis cycles. By default only a a single analysis is done.
The value applies to each individual step of the measurement, i.e. twice for the matrix calibration and for each frequency in sweep mode.

loop - do infinite analysis

The program continue to analyze until the input data has been finished or it is interrupted by a signal. This is useful to reflect changes of you measurement item in near real time.
It is recommended to check whether real time processing is possible with a reasonable system load with a limited number of cycles before using this option on a infinite transient data source.

mfft - FFT mode

Activate FFT mode for analysis.

mpca - PCA mode

Activate PCA mode for analysis.

msweep - enable sweep mode

In sweep mode the distinct frequencies are measured one after each other. This takes considerably longer than the fast FFT mode but it is also more robust against non-linearities and ambient noise. See documentation for further details.

stereo - two channel mode

In two channel mode (stereo) the used FFT frequencies are associated with two distinct channels alternatingly. This applies to the reference generator as well as to any averaging operation. A column in the result files indicates the channel association. Note that this doubles the measurement time in sweep mode. See multi multi channel measurements.

setupcmd=command - execute shell command at program start

After parameter parsing but before any other action command is passed to system().
Note that analyze waits for the command to complete. So you may setup some things that are used by other parameters here.

setupout=command - pipe command before start at program start

Write command to stdout after parameter parsing but before any other action.

initcmd=command - execute shell command before start of data processing

Before the first input samples are processed command is passed to system(). At this point global output files like the reference design spectrum have been written already.
Note that analyze waits for the command to complete. This gives you exclusive access to the data files.

initout=command - pipe command before start of data processing

Write command to stdout before the first input samples are processed. At this point global output files like the reference design spectrum have been written already.

plotcmd=command - execute shell command when new data is available

Each time a analysis is complete and the data has been written command is passed to system(). Note that analyze waits for the command to complete. This gives you exclusive access to the data files but it may also interfere with the real time processing of the input data. You may alternatively consider to pipe the command to stdout instead (option plotout), if you do not need this kind of synchronization.

plotout=command - pipe command when new data is available

Write command to stdout each time an analysis has completed. You can use this to synchronize plot programs when new data arrives.

postcmd=command - execute shell command after analysis has completed

When all analysis steps have been completed command is passed to system(). Note that analyze waits for the command to complete. You may alternatively consider to pipe the command to stdout instead (option postout), if you do not need this kind of synchronization.

postout=command - pipe command after analysis has completed

When all analysis steps have been completed write command to stdout.

FFT parameter

famin=freq, famax=freq - frequency range for LCR analysis

Minimum and maximum frequency for LCR data fit. This could be used to adapt the bandwidth of your setup. In contrast to fmin and fmax this has no influence on the data written to the result file. It applies only to the screen output (to stderr).

fmin=freq, fmax=freq - frequency range

Minimum and maximum frequency for the FFT analysis. This option applies to all processing steps including calculation of calibration etc. It could be used to remove artifacts at the frequency limits for graphical output.

h/f - use 1/f weight

This weight function can be useful for measurements with pink noise.

hd - weight function for differential mode

Use adapted weight function for differential input mode.

he - disable weights

Use an equal distributed weight function. Use this if your input SNR has no correlation with the signal amplitude at a certain frequency.

bin=size - average size FFT channels

Calculates the average over size subsequent frequency channels before any further processing. The averaging is done in polar coordinates so phase noise does not degrade the amplitude.
This could be used to reduce noise if the measurement response is not likely to change fast with frequency. But if your reference signal is periodic you should prefer a shorter block length together with averaging input samples.

fbin=factor - average FFT channels logarithmically

Calculates the average over size subsequent frequency channels to get approximately logarithmic frequency bins. The channels are averaged as long as they fit into the interval [f, f · (factor + 1)]. This option is particularly useful if the properties of the object tend to change over log f rather than f. In other words if the result is shown with logarithmic frequency axis.

finc=channels, flog=factor - linear and logarithmic increment for used frequencies

This is intended to be used with custom, discrete energy distributions. Subsequent used frequencies have at least the distance f_n+1 = f_n · factor + channels rounded to the closest frequency in the FFT result. Any channels in between are ignored.

harm=n - use harmonics

With this option the first n harmonics of any used frequency is reserved. In fact it is assumed that the reference signal does not contain energy at these frequencies and any response is the result of harmonic distortion. This could be used to do very fast measurements of harmonics of loudspeakers.
The setting must be chosen to match the reference signal. See analysis of harmonics.

pch=num - purge low FFT channels

This assigns zero to the first num channels of the FFT result. It is alternative to fmin that does not remove the lines from the data file and avoids uninitialized values in calibration files. But be careful not to use these coefficients as denominator of some following calculation step. To avoid division by zero exceptions a very small value is used rather than zero.

phcc - fit group delay

This option fits the group delay by calculation of the center of the cross correlation of the wanted signal and the reference signal.

The option is required if the wanted and the reference data are only synchronized at the sampling frequency but not at the origin of the cycle. Otherwise degradation of amplitude at higher frequencies when averaging of frequency channels is used may occur, because of errors in phase unwrapping. With this option activated the result is written to stderr additionally. The fitted group delay is removed from the output file in this case.

phl=delay - subtract group delay

Adjusts the phase data by exp(i ω delay). delay is in seconds.

wd[=filename] - write FFT data

Write detailed result of FFT analysis to filename. If =filename is omitted the data is written to file data.dat. → file format

win=typ - window function

Apply window function to data before FFT. The following window functions are implemented:
win=0 – rectangular = none (default)
win=1 – Bartlett window = triangular, abs(2 i/n 1)
win=2 – Hanning window, .5 + .5 cos(2π i/n)
win=3 – Hamming window, .54 + .46 cos(2 i/n)
win=4 – Blackman window, .42 + .5 cos(2π i/n) + .08 cos(4π i/n)
win=5 – Blackman Harris window, .35875 + .48829 cos(2π i/n) + .14128 cos(4π i/n) + .01168 cos(2π i/n)
A window function is only recommended if the reference signal cannot be made cyclic or the DAC and ADC do not operate coherent.

wwin[=filename] - write window function

This option writes the selected window function (option win) to filename. If =filename is omitted the window data is written to file window.dat. → file format

Synchronization options

sync[=count] - synchronize before start

Generate sync pattern before the reference signal for count cycles - by default 2.
This option also enables the synchronization before the main analysis starts. This takes the average group delay in the frequency range famin to famax and discards samples unless the synchronization pattern has completed.
This option is strongly recommended for sweep mode because otherwise you might not measure the frequency that you intend.

syncch=channel - synchronization channel

1 = use left channel = numerator only
2 = use right channel = denominator only
3 = use both channels (default)

synclvl=level - minimum SNR level of the cross correlation compared to the auto correlation of the sync reference

This level controls when input samples are considered to be a valid synchronization signal. It is a relative value.

syncend=factor - decrease of cross correlation for end of sync

If the cross correlation decreases at least to this factor this is the end of the synchronization preamble signal.

predelay=cycles - time to setup in FFT cycles

Number of FFT cycles used for setup. This is a fractional number. Since the total time used must be a multiple of the FFT length an additional gap is inserted at the end of the measurement to match the next whole number. Example:
The default value of 0.95 causes the measurement to take ln + 1 FFT cycles. 95% of an FFT cycle is the setup delay, then the measurement starts and after the measurement the remaining 5% of the FFT cycle the current reference is kept.
This is especially important in sweep mode where the reference changes after each frequency. It is a good advise not to use a whole number for this parameter in this case because otherwise small deviations at synchronization might degrade the measurement.

Calibration options

gg[=filename] - do gain calibration

The left and right channel is assumed to sample the same signal. The difference in the transfer functions is written to filename. If =filename is omitted the calibration data is written to file gain.dat. → file format

gr[=filename] - apply gain calibration

The result from an earlier gain calibration is read from filename and applied to the data before any further processing. If =filename is omitted the calibration data is read from gain.dat. → file format
The calibration is arbitrarily applied to the nominator signal. So you should not abuse the gain calibration to compensate for complex transfer functions, because the weight functions would be affected too.
If you combine this option with gg the result from an earlier gain calibration is applied to the data before another gain calibration is done. The residual result is written to the gain calibration file.

zg[=filename] - do matrix calibration

Generate the matrix calibration file. The Matrix calibration operates in two steps. In the first step the reference signal should be zero, in the second step the wanted signal should be zero. Between the steps there is a configured pause to adjust the setup. See documentation for further details.
If =filename is omitted the calibration data is written to file zero.dat.

zr[=filename] - apply matrix calibration

Use the matrix calibration from filename and apply it to the input data.
If =filename is omitted the calibration data is read from zero.dat. → file format
If this option is combined with zg then the result from an earlier matrix calibration is applied to the input data while another matrix calibration is done. The residuals are written to the matrix calibration file.

zn - use 2 point calibration

Adjust the sum of the complex amplitudes of nominator and denominator to 1. This has no effect on impedance or transfer function, but it gets important if you relate data of different measurements as e.g. the matrix calibration does.

lp=secs - pause between matrix calibration steps

Number of seconds between the two steps of the matrix calibration (option zg). The time is rounded up to full blocks.