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 = 212 = 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

Parameter Description Default Category
ainc incremental mode
off input data
al average over multiple cycles of samples
1 (off) input data
aref append reference data file (instead of overwriting)
overwrite
output data
bin average FFT channels
1 (off) FFT parameter
dcfg dump effective configuration to a file
general options
diff use differential input mode off input data
famin famax frequency range for LCR analysis fmin .. fmax FFT parameter
fbin average FFT channels with logarithmic bandwidth
0 (off) FFT parameter
general options
fftlen analysis block size 8192 general options
fi16 read/write 16 bit integer samples default general options
fi24 read/write 24 bit integer samples default general options
fi32 read/write 32 bit integer samples default general options
finc linear increment for used FFT channels
1.0 FFT parameter
flog logarithmic increment for used FFT channels 1.0 (off) FFT parameter
fmin fmax frequency range for analysis
0.001 .. Nyquist frequency FFT parameter
fsamp sampling frequency 48000 general options
gain master gain for reference output in dB FSR 0.0 output data
gg generate gain calibration file
calibration
gr use gain calibration file
calibration
h/f use 1/f weight

FFT parameter
harm take n harmonics into account
1 (off) FFT parameter
hd use weight function for differential input mode
FFT parameter
he disable weight function

FFT parameter
help show help screen with options

in name of PCM input file, - for stdin
input data
initcmd execute shell command before the main analysis

control options
initout write command to stdout before the main analysis
control options
ln number of cycles to process 1 control options
loop infinite number of cycles off control options
lp pause in seconds between measurements (at matrix calibration) 10 calibration
mfft mpca operation mode

control options
msweep use sweep mode
control options
olf olc file name and column to overwrite numerator
none / 1 input data
orf orc file name and column to overwrite denominator (reference)
none / 1 input data
out name of PCM data file to write reference signal to
output data
pch purge first frequency channels 1 (purge DC) FFT parameter
phcc fit group delay
off
FFT parameter
phl subtract constant group delay 0.0 (off) FFT parameter
plotcmd execute shell command after new data is available

control options
plotout write command to stdout after new data available
control options
postcmd execute shell command after all analysis has completed

control options
postout write command to stdout after all analysis has completed
control options
predelay time to setup in FFT cycles 0.95 synchronization options
0 (off) input data
pte read input data till the end
off input data
rref reference resistor
1.0 general options
rspec read frequency domain reference data from file
output data
scale noise type, energy distribution 0 (white noise) output data
setupcmd execute shell command at program start

control options
setupout write command to stdout at program start
control options
stereo two channel mode off control options
symmout symmetric stereo output 0 (off) output data
sync synchronize before start 0 (off) synchronization options
syncend decrease of cross correlation for end of synchronisation 0.8 synchronization options
syncch synchronization channel 3 (both) synchronization options
synclvl minimum cross correlation SNR 0.2 synchronization options
wd (over)write FFT data file on the fly
off FFT parameter
win select window function off (rectangular)
FFT parameter
wraw write raw data off input data
wref write time domain reference to file
output data
wspec write frequency domain reference to file
output data
wwin write window function to file
FFT parameter
xch swap input channels (L ↔ R) off input data
xb swap bytes of PCM data (change endianess) off general options
zg generate matrix calibration file off calibration
zn use 2 point matrix calibration off calibration
zr use matrix calibration file off calibration

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.
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.
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 [ff · (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 fn+1 = fn · 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.