LTPDA Toolbox™

Method ao/whiten1D

  WHITEN1D whitens the input time-series.
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
  DESCRIPTION: WHITEN1D whitens the input time-series. The filter is built
               by fitting to the model provided. If no model is provided, a
               fit is made to a spectral-density estimate of the
               time-series (made using psd+bin_data or lpsd).
               Note: The function assumes that the input model corresponds
               to the one-sided psd of the data to be whitened.
 
  ALGORITHM:
             1) If no model provided, make psd+bin_data or lpsd
                of time-series and take it as a model
                for the data power spectral density
             2) Fit a set of partial fraction z-domain filters using
                utils.math.psd2wf. The fit is automatically stopped when
                the accuracy tolerance is reached.
             3) Convert to array of MIIR filters
             4) Assemble into a parallel filterbank object
             5) Filter time-series in parallel
 
 
  CALL:         b = whiten1D(a, pl)
                [b1,b2,...,bn] = whiten1D(a1,a2,...,an, pl);
 
  INPUT:
                - as are time-series analysis objects or a vector of
                analysis objects
                - pl is a plist with the input parameters
 
  OUTPUT:
                - bs "whitened" time-series AOs. The whitening filters used
                are stored in the objects procinfo field under the
                parameter 'Filter'.
 
  Parameters Description
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Method Details
Access	public
Defining Class	ao
Sealed	0
Static	0

Parameter Description

Sets for this method …
Default
PSD
LPSD

Default
no description
Key	Default Value	Options	Description
whiten1D
FLIM	[0.001 0.029999999999999999]	none	Band to calculate the scaling power
SCALEOUT	0	0 1	Scale your output by the inband power
MODEL	[]	none	A frequency-series AO describing the model response to build the filter from. As an alternative, the user can choose a model estimation technique: PSD - using `psd` + `bin_data` LPSD - using `lpsd`
buildWhitener1D
RANGE	[]	none	The frequency range to evaluate the fitting. An empty value or [-inf inf] will include the whole range. The remaining part of the model will be completed according to the option chosen in the 'complete' parameter.
COMPLETE_HF	'flat'	'flat' 'lowpass'	Choose how to complete the frequency range up to fs/2. Assumes flat response Assumes 4 poles low-pass type response
FS	[]	none	The sampling frequency to design the output filter on. If it is not a positive number, it will be taken from the model
MAXITER	30	none	Maximum number of iterations in fit routine.
POLETYPE	1	1 2 3	Choose the pole type for fitting: use real starting poles generates complex conjugate poles of the type `a.exp(thetapij)`with `theta = linspace(0,pi,N/2+1)` generates complex conjugate poles of the type `a.exp(thetapij)` with `theta = linspace(0,pi,N/2+2)`
MINORDER	2	none	Minimum order to fit with.
MAXORDER	25	none	Maximum order to fit with.
WEIGHTS	'1/abs'	'equal' '1/abs' '1/abs^2'	Choose weighting method: equal weights for each point weight with `1/abs(model)` weight with `1/abs(model).^2`
PLOT	0	0 1	Plot results of each fitting step.
DISP	0	0 1	Display the progress of the fitting iteration.
MSEVARTOL	0.10000000000000001	none	Mean Squared Error Variation - Check if the relative variation of the mean squared error is smaller than the value specified. This option is useful for finding the minimum of Chi-squared.
FITTOL	0.01	none	Mean Squared Error Value - Check if the mean squared error value is lower than the value specified.
RAND_STREAM	[]	none	Internal MATLAB state of the pseudorandom number generator. You can set the state with a structure which should contain all properties of the MATLAB class RandStream

Example
plist('FLIM', [[0.001 0.029999999999999999]], 'SCALEOUT', [false], 'MODEL', [[]], 'RANGE', [[]], 'COMPLETE_HF', 'flat', 'FS', [[]], 'MAXITER', [30], 'POLETYPE', [1], 'MINORDER', [2], 'MAXORDER', [25], 'WEIGHTS', '1/abs', 'PLOT', [false], 'DISP', [false], 'MSEVARTOL', [0.10000000000000001], 'FITTOL', [0.01], 'RAND_STREAM', [[]])

PSD
no description
Key	Default Value	Options	Description
whiten1D
FLIM	[0.001 0.029999999999999999]	none	Band to calculate the scaling power
SCALEOUT	0	0 1	Scale your output by the inband power
buildWhitener1D
MODEL	'PSD'	none	A model estimation technique in the case of tsdata input: PSD - using `psd` + `bin_data` LPSD - using `lpsd`
RANGE	[]	none	The frequency range to evaluate the fitting. An empty value or [-inf inf] will include the whole range. The remaining part of the model will be completed according to the option chosen in the 'complete' parameter.
COMPLETE_HF	'flat'	'flat' 'lowpass'	Choose how to complete the frequency range up to fs/2. Assumes flat response Assumes 4 poles low-pass type response
FS	[]	none	The sampling frequency to design the output filter on. If it is not a positive number, it will be taken from the model
MAXITER	30	none	Maximum number of iterations in fit routine.
POLETYPE	1	1 2 3	Choose the pole type for fitting: use real starting poles generates complex conjugate poles of the type `a.exp(thetapij)`with `theta = linspace(0,pi,N/2+1)` generates complex conjugate poles of the type `a.exp(thetapij)` with `theta = linspace(0,pi,N/2+2)`
MINORDER	2	none	Minimum order to fit with.
MAXORDER	25	none	Maximum order to fit with.
WEIGHTS	'1/abs'	'equal' '1/abs' '1/abs^2'	Choose weighting method: equal weights for each point weight with `1/abs(model)` weight with `1/abs(model).^2`
PLOT	0	0 1	Plot results of each fitting step.
DISP	0	0 1	Display the progress of the fitting iteration.
MSEVARTOL	0.10000000000000001	none	Mean Squared Error Variation - Check if the relative variation of the mean squared error is smaller than the value specified. This option is useful for finding the minimum of Chi-squared.
FITTOL	0.01	none	Mean Squared Error Value - Check if the mean squared error value is lower than the value specified.
RAND_STREAM	[]	none	Internal MATLAB state of the pseudorandom number generator. You can set the state with a structure which should contain all properties of the MATLAB class RandStream
psd
NFFT	-1	none	The number of samples in each fft [default: length of input data]. A string value containing the variable 'fs' can also be used, e.g., `plist('Nfft', '2*fs')`
WIN	'BH92'	'Rectangular' 'Welch' 'Bartlett' 'Hanning' 'Hamming' 'Nuttall3' 'Nuttall4' 'Nuttall3a' 'Nuttall3b' 'Nuttall4a' 'Nuttall4b' 'Nuttall4c' 'BH92' 'SFT3F' 'SFT3M' 'FTNI' 'SFT4F' 'SFT5F' 'SFT4M' 'FTHP' 'HFT70' 'FTSRS' 'SFT5M' 'HFT90D' 'HFT95' 'HFT116D' 'HFT144D' 'HFT169D' 'HFT196D' 'HFT223D' 'HFT248D' 'Kaiser' 'levelledHanning'	The window to be applied to the data to remove the discontinuities at edges of segments. [default: taken from user prefs] Only the design parameters of the window object are used. Enter a string value containing the window name e.g. `plist('Win', 'Kaiser', 'psll', 200)` `plist('Win', 'BH92')`
PSLL	200	none	The peak sidelobe level for Kaiser windows. Note: it is ignored for all other windows
OLAP	50	none	The segment percent overlap [-1 == take from window function]
ORDER, N	1	none	The order of segment detrending: -1 - no detrending 0 - subtract mean 1 - subtract linear fit N - subtract fit of polynomial, order N
NAVS	16	none	Force number of averages. If set, and if Nfft was set to 0 or -1, the number of points for each window will be calculated to match the request.
DROP WINDOW SAMPLES	1	1 0	Drop the recommended (by the window) number of samples of the final computed spectral series.
TIMES, SPLIT	[]	none	The time range to analyze. If not empty, sets the time interval to operate on. As in ao/split, the interval can be specified by: a vector of doubles a timespan object a cell array of time strings a vector of time objects
SCALE	'PSD'	'PSD' 'ASD' 'PS' 'AS'	The scaling of output. Choose from: PSD - Power Spectral Density ASD - Amplitude (linear) Spectral Density PS - Power Spectrum AS - Amplitude (linear) Spectrum
bin_data
METHOD	'MEAN'	none	method for binning. Choose from: mean median max min rms weighted mean (weights can be input or are taken from data dy)
XSCALE	'LOG'	'LOG' 'LIN'	scaling of binning. Choose from: log - logaritmic lin - linear
RESOLUTION	50	none	When setting logaritmic x scale, it sets the number of points per decade. When setting linear x scale, it sets the number of points.
XVALS	[]	none	List of x values to evaluate the binning between. It may be a vector or an ao, in which case it will take the x field
INHERIT_DY	1	1 0	Choose what to do in the case of mean, and bins with only one point. Choose from: 'true' - take the uncertainty from the original data, if defined 'false' - set it to Inf so it weighs 0 in averaged means

Example
plist('FLIM', [[0.001 0.029999999999999999]], 'SCALEOUT', [false], 'MODEL', 'PSD', 'RANGE', [[]], 'COMPLETE_HF', 'flat', 'FS', [[]], 'MAXITER', [30], 'POLETYPE', [1], 'MINORDER', [2], 'MAXORDER', [25], 'WEIGHTS', '1/abs', 'PLOT', [false], 'DISP', [false], 'MSEVARTOL', [0.10000000000000001], 'FITTOL', [0.01], 'RAND_STREAM', [[]], 'NFFT', [-1], 'WIN', 'BH92', 'PSLL', [200], 'OLAP', [50], 'ORDER', [1], 'NAVS', [16], 'DROP WINDOW SAMPLES', [true], 'TIMES', [[]], 'SCALE', 'PSD', 'METHOD', 'MEAN', 'XSCALE', 'LOG', 'RESOLUTION', [50], 'XVALS', [[]], 'INHERIT_DY', [true])

Example

plist('FLIM', [[0.001 0.029999999999999999]], 'SCALEOUT', [false], 'MODEL', 'PSD', 'RANGE', [[]], 'COMPLETE_HF', 'flat', 'FS', [[]], 'MAXITER', [30], 'POLETYPE', [1], 'MINORDER', [2], 'MAXORDER', [25], 'WEIGHTS', '1/abs', 'PLOT', [false], 'DISP', [false], 'MSEVARTOL', [0.10000000000000001], 'FITTOL', [0.01], 'RAND_STREAM', [[]], 'NFFT', [-1], 'WIN', 'BH92', 'PSLL', [200], 'OLAP', [50], 'ORDER', [1], 'NAVS', [16], 'DROP WINDOW SAMPLES', [true], 'TIMES', [[]], 'SCALE', 'PSD', 'METHOD', 'MEAN', 'XSCALE', 'LOG', 'RESOLUTION', [50], 'XVALS', [[]], 'INHERIT_DY', [true])

LPSD
no description
Key	Default Value	Options	Description
whiten1D
FLIM	[0.001 0.029999999999999999]	none	Band to calculate the scaling power
SCALEOUT	0	0 1	Scale your output by the inband power
buildWhitener1D
MODEL	'LPSD'	none	A model estimation technique in the case of tsdata input: PSD - using `psd` + `bin_data` LPSD - using `lpsd`
RANGE	[]	none	The frequency range to evaluate the fitting. An empty value or [-inf inf] will include the whole range. The remaining part of the model will be completed according to the option chosen in the 'complete' parameter.
COMPLETE_HF	'flat'	'flat' 'lowpass'	Choose how to complete the frequency range up to fs/2. Assumes flat response Assumes 4 poles low-pass type response
FS	[]	none	The sampling frequency to design the output filter on. If it is not a positive number, it will be taken from the model
MAXITER	30	none	Maximum number of iterations in fit routine.
POLETYPE	1	1 2 3	Choose the pole type for fitting: use real starting poles generates complex conjugate poles of the type `a.exp(thetapij)`with `theta = linspace(0,pi,N/2+1)` generates complex conjugate poles of the type `a.exp(thetapij)` with `theta = linspace(0,pi,N/2+2)`
MINORDER	2	none	Minimum order to fit with.
MAXORDER	25	none	Maximum order to fit with.
WEIGHTS	'1/abs'	'equal' '1/abs' '1/abs^2'	Choose weighting method: equal weights for each point weight with `1/abs(model)` weight with `1/abs(model).^2`
PLOT	0	0 1	Plot results of each fitting step.
DISP	0	0 1	Display the progress of the fitting iteration.
MSEVARTOL	0.10000000000000001	none	Mean Squared Error Variation - Check if the relative variation of the mean squared error is smaller than the value specified. This option is useful for finding the minimum of Chi-squared.
FITTOL	0.01	none	Mean Squared Error Value - Check if the mean squared error value is lower than the value specified.
RAND_STREAM	[]	none	Internal MATLAB state of the pseudorandom number generator. You can set the state with a structure which should contain all properties of the MATLAB class RandStream
lpsd
WIN	'BH92'	'Rectangular' 'Welch' 'Bartlett' 'Hanning' 'Hamming' 'Nuttall3' 'Nuttall4' 'Nuttall3a' 'Nuttall3b' 'Nuttall4a' 'Nuttall4b' 'Nuttall4c' 'BH92' 'SFT3F' 'SFT3M' 'FTNI' 'SFT4F' 'SFT5F' 'SFT4M' 'FTHP' 'HFT70' 'FTSRS' 'SFT5M' 'HFT90D' 'HFT95' 'HFT116D' 'HFT144D' 'HFT169D' 'HFT196D' 'HFT223D' 'HFT248D' 'Kaiser' 'levelledHanning'	The window to be applied to the data to remove the discontinuities at edges of segments. [default: taken from user prefs] Only the design parameters of the window object are used. Enter a string value containing the window name e.g. `plist('Win', 'Kaiser', 'psll', 200)` `plist('Win', 'BH92')`
PSLL	200	none	The peak sidelobe level for Kaiser windows. Note: it is ignored for all other windows
OLAP	-1	none	The segment percent overlap [-1 == take from window function]
ORDER, N	0	-1 0 1 2 3 4 5 6 7 8 9	The order of segment detrending: -1 - no detrending 0 - subtract mean 1 - subtract linear fit N - subtract fit of polynomial, order N
DROP WINDOW SAMPLES	1	1 0	Drop the recommended (by the window) number of samples of the final computed spectral series.
TIMES, SPLIT	[]	none	The time range to analyze. If not empty, sets the time interval to operate on. As in ao/split, the interval can be specified by: a vector of doubles a timespan object a cell array of time strings a vector of time objects
KDES	100	none	The desired number of averages.
JDES	1000	none	The desired number of spectral frequencies to compute.
LMIN	0	none	The minimum segment length.
SCALE	'PSD'	'PSD' 'ASD' 'PS' 'AS'	The scaling of output. Choose from: PSD - Power Spectral Density ASD - Amplitude (linear) Spectral Density PS - Power Spectrum AS - Amplitude (linear) Spectrum

Example
plist('FLIM', [[0.001 0.029999999999999999]], 'SCALEOUT', [false], 'MODEL', 'LPSD', 'RANGE', [[]], 'COMPLETE_HF', 'flat', 'FS', [[]], 'MAXITER', [30], 'POLETYPE', [1], 'MINORDER', [2], 'MAXORDER', [25], 'WEIGHTS', '1/abs', 'PLOT', [false], 'DISP', [false], 'MSEVARTOL', [0.10000000000000001], 'FITTOL', [0.01], 'RAND_STREAM', [[]], 'WIN', 'BH92', 'PSLL', [200], 'OLAP', [-1], 'ORDER', [0], 'DROP WINDOW SAMPLES', [true], 'TIMES', [[]], 'KDES', [100], 'JDES', [1000], 'LMIN', [0], 'SCALE', 'PSD')

Example

plist('FLIM', [[0.001 0.029999999999999999]], 'SCALEOUT', [false], 'MODEL', 'LPSD', 'RANGE', [[]], 'COMPLETE_HF', 'flat', 'FS', [[]], 'MAXITER', [30], 'POLETYPE', [1], 'MINORDER', [2], 'MAXORDER', [25], 'WEIGHTS', '1/abs', 'PLOT', [false], 'DISP', [false], 'MSEVARTOL', [0.10000000000000001], 'FITTOL', [0.01], 'RAND_STREAM', [[]], 'WIN', 'BH92', 'PSLL', [200], 'OLAP', [-1], 'ORDER', [0], 'DROP WINDOW SAMPLES', [true], 'TIMES', [[]], 'KDES', [100], 'JDES', [1000], 'LMIN', [0], 'SCALE', 'PSD')

Some information of the method ao/whiten1D are listed below:
Class name	ao
Method name	whiten1D
Category	Signal Processing
Package name	ltpda
VCS Version	967b0eec0dece803a81af8ef54ad2f8c784b20b2
Min input args	1
Max input args	-1
Min output args	1
Max output args	-1
Can be used as modifier	1
Supported numeric types	{'double'}

Method: ao/validateSpectrumMod

Method: ao/whiten2D

Method ao/whiten1D

Parameter Description

Default

Example

PSD

Example

LPSD

Example