dsp.ParameterSmoother
Description
The dsp.ParameterSmoother
System object™ gradually updates the input filter parameters until the parameters reach the
desired value. The object uses a first-order IIR filter to smooth the parameters. For more
information, see Parameter Smoothing.
To smooth input parameters:
Create the
dsp.ParameterSmoother
object and set its properties.Call the object with arguments, as if it were a function.
To learn more about how System objects work, see What Are System Objects?
Creation
Syntax
Description
returns a parameter smoother object with a smoothing factor of 0.6.paramSmoother
= dsp.ParameterSmoother
returns a parameter smoother object with the number of parameters specified in
paramSmoother
= dsp.ParameterSmoother(numParam)numParam
.
returns a parameter smoother object with additional properties specified by one or more
paramSmoother
= dsp.ParameterSmoother(Name=Value
)Name-Value
arguments. For example,
SmoothingMode='Smoothing time',SmoothingTime=2
sets the smoothing
time to 2 seconds.
Properties
Unless otherwise indicated, properties are nontunable, which means you cannot change their
values after calling the object. Objects lock when you call them, and the
release
function unlocks them.
If a property is tunable, you can change its value at any time.
For more information on changing property values, see System Design in MATLAB Using System Objects.
NumParameters
— Number of parameters
1
(default) | positive integer
Number of parameters, specified as a positive integer.
Tunable: Yes
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
SmoothingMode
— Mode to use for smoothing
'Smoothing factor'
(default) | 'Smoothing time'
Mode to use for smoothing, specified as one of these:
'Smoothing factor'
–– Specify the smoothing factor through theSmoothingFactor
property.'Smoothing time'
–– Specify the smoothing time through theSmoothingTime
property.
For more information on these two modes, see Parameter Smoothing.
SmoothingFactor
— Smoothing factor
0.6
(default) | scalar in the range [0, 1)
Smoothing factor α, specified as a scalar in the range [0, 1). When α = 0, the object does not smooth the parameters. As α approaches 1, smoothing and therefore the number of redesigns increase. For more information on the effect of α on smoothing, see Parameter Smoothing.
Tunable: Yes
Dependencies
To enable this property, set the SmoothingMode
property to
'Smoothing factor'
.
Data Types: single
| double
SampleTime
— Sample time of input parameters
1
(default) | positive scalar
Sample time T of the input parameters, specified as a positive scalar in seconds. This value determines the frequency with which the object updates the instantaneous values of the input parameters until the parameters reach the target value.
Dependencies
To enable this property, set the SmoothingMode
property to
'Smoothing time'
.
Data Types: single
| double
SmoothingTime
— Smoothing time in seconds
10
(default) | nonnegative scalar
Smoothing time τ in seconds, specified as a nonnegative scalar.
This value indicates the time it takes for the parameter to change to
exp
(−T/τ)×current value +
(1−exp
(−T/τ))×target value,
where T is the value you specify in the
SampleTime
property. For more information on the effect of
τ on smoothing, see Parameter Smoothing.
Tunable: Yes
Dependencies
To enable this property, set the SmoothingMode
property to
'Smoothing time'
.
Data Types: single
| double
Usage
Syntax
Input Arguments
x
— Input parameter to smooth
scalar | vector | matrix
Input parameter to smooth, specified as a scalar, vector, or a matrix.
The number of input parameters must equal the value you specify in the
NumParameters
property.
Data Types: single
| double
Output Arguments
y
— Smoothed parameter
scalar | vector | matrix
Smoothed value of the parameter, returned as a scalar, vector, or a matrix. This is the instantaneous value of the parameter and it changes until the parameter reaches the target value.
The number of outputs the object returns equals the value you specify in the
NumParameters
property.
Data Types: single
| double
Object Functions
To use an object function, specify the
System object as the first input argument. For
example, to release system resources of a System object named obj
, use
this syntax:
release(obj)
Examples
Design Second-Order Section Filter by Varying Smoothing Factor
Design and implement a second-order section filter using the designBandpassIIR
function and the dsp.SOSFilter
object. Vary the lower and higher 3-dB cutoff frequencies and the stopband attenuation of the filter. Smooth these parameters using the dsp.ParameterSmoother
object. Vary the smoothing factor and note the change in how the object smooths these parameter values.
Set the target values of the three frequency specification parameters.
Lower 3-dB cutoff frequency to 0.8 in normalized frequency units.
Higher 3-dB cutoff frequency to 0.9 in normalized frequency units.
Stopband attenuation to 120 dB.
F3dB1 = 0.8; F3dB2 = 0.9; Astop = 120;
Initialize the dsp.ParameterSmoother
object with a smoothing factor of 0.995. As the smoothing factor approaches 1, smoothing increases and the parameter values change more gradually.
smooth = dsp.ParameterSmoother(3,SmoothingFactor=0.995)
smooth = dsp.ParameterSmoother with properties: NumParameters: 3 SmoothingMode: 'Smoothing factor' SmoothingFactor: 0.9950
Initialize the dsp.SOSFilter
object.
sosFilter = dsp.SOSFilter(CoefficientSource="Input port")
sosFilter = dsp.SOSFilter with properties: Structure: 'Direct form II transposed' CoefficientSource: 'Input port' HasScaleValues: false Use get to show all properties
Initialize the spectrumAnalyzer
object to plot the spectrum of the filter output. The two timescope
objects plot the variation in the parameters with time and the target values of the parameters.
sa = spectrumAnalyzer(PlotAsTwoSidedSpectrum=false,... AveragingMethod="exponential",ForgettingFactor=0.7,... SampleRate=2); tsFreq = timescope(SampleRate=2,... TimeSpanSource="property",TimeSpan=2999,... YLimits=[0 1],... ShowLegend=1,ChannelNames=["TargetF3dB1","TargetF3dB2","F3dB1","F3dB2"], ... Title="Smoothing Factor = 0.995"); tsAstop = timescope(SampleRate=2,... TimeSpanSource="property",TimeSpan=2999,... YLimits=[0 130],... ShowLegend=1,ChannelNames=["TargetAstop","Astop"],... Title="Smoothing Factor = 0.995");
Change the frequency specification parameters for a brief period during simulation. The dsp.ParameterSmoother
object smooths the values when they change. The target frequency specification parameters changes abruptly, but the smoothed values change more gradually. Design the second-order section filter using the smoothed values. Pass a random signal to the filter and plot the output spectrum in the spectrum analyzer. Since the input is a random signal, the output spectrum shows the frequency response of the filter.
With each iteration, the time scope plots update with the changing values of the parameters. The frequency response of the filter updates accordingly in the spectrum analyzer.
for idx = 1:6000 if idx == 2000 F3dB1 = 0.5; F3dB2 = 0.7; Astop = 80; elseif idx == 4000 F3dB1 = 0.8; F3dB2 = 0.9; Astop = 120; end [F3dB1S,F3dB2S,AstopS] = smooth(F3dB1,F3dB2,Astop); [b,a] = designBandpassIIR(HalfPowerFrequency1=F3dB1S,HalfPowerFrequency2=F3dB2S,StopbandAttenuation=AstopS,CascadeSectionsForm="sos"); y = sosFilter(randn(1024,1),b,a); sa(y); tsFreq(F3dB1,F3dB2,F3dB1S,F3dB2S) tsAstop(Astop,AstopS) end
Change Smoothing Factor
Change the smoothing factor of the dsp.ParameterSmoother
object to 0.8 and rerun the simulation. The parameters change more abruptly and reach the target values very quickly since the smoothing factor is low.
Vary Smoothing Time of Gain in Speech Signal
Change the gain of a speech signal. Smooth the gain parameter by specifying the smoothing time. Smoothing time and smoothing factor are equivalent ways of specifying the smoothing behavior of the parameters. This example shows the effect of changing the smoothing time on the gain of the speech signal.
Initialize the dsp.ParameterSmoother
object with a smoothing time of 2 seconds.
smooth = dsp.ParameterSmoother(1,SmoothingMode="Smoothing time",... SmoothingTime=2,SampleTime=1)
smooth = dsp.ParameterSmoother with properties: NumParameters: 1 SmoothingMode: 'Smoothing time' SampleTime: 1 SmoothingTime: 2
Create an audio file reader to read a speech signal containing 1024 samples per frame.
afr = dsp.AudioFileReader
afr = dsp.AudioFileReader with properties: Filename: '/mathworks/devel/bat/filer/batfs2561-0/Bdoc24b.2679053/build/runnable/matlab/toolbox/dsp/dsp/samples/speech_dft.mp3' PlayCount: 1 ReadRange: [1 Inf] SamplesPerFrame: 1024 OutputDataType: 'double' Use get to show all properties
Play the signal using the audioDeviceWriter
object.
adw = audioDeviceWriter(SampleRate=afr.SampleRate)
adw = audioDeviceWriter with properties: Device: 'Default' SampleRate: 22050 Use get to show all properties
Visualize the variation in the gain parameter using the timescope
object.
ts = timescope(ChannelNames=["Target Gain","Gain"],... TimeSpanSource="property",TimeSpan=100,... YLimits=[0 1.2],Title="Smoothing Time = 2 seconds");
Initialize the target gain to 1. Change the target gain to 0.1 for a brief period of the signal duration. The dsp.ParameterSmoother
object smooths the gain value when it changes. The time scope shows the smoothing behavior. The target gain value changes abruptly, but the smoothed gain changes more gradually.
targetgain = 1; for i = 1:100 gainS = smooth(targetgain); y = gainS*afr(); if i == 20 targetgain = 0.1; elseif i == 70 targetgain = 1; end adw(y); ts(targetgain,gainS) end
Change Smoothing Time
Change the smoothing time to 4 seconds. Rerun the simulation with this new smoothing time value. The smoothing is more gradual and the parameter takes longer time to reach its target value.
More About
Parameter Smoothing
Parameter smoothing gradually changes the values of parameters until the desired value is reached.
The algorithm uses a first-order IIR filter to smooth the parameter.
where:
g[n] is the instantaneous value of the parameter.
t[n] is the target value of the parameter.
α is the smoothing factor. When α = 0, the algorithm does not smooth the parameters. As α approaches 1, smoothing and therefore the number of redesigns increase.
Effect of α on Parameter Smoothing
Assume that the initial current value of the parameter g[0] is 0 and the target value t[n] is 1.
Here is the progression of the smoothed parameter using these values.
g[1] = 1−α
g[2] = 1−α2
g[3] = 1−α3
g[n] = 1−αn
Smoothing can also be expressed in terms of time by expressing α as exp
(−nT/τ), where T is the sample time of the parameter (in seconds) and τ is the smoothing time (in seconds).
Effect of τ on Parameter Smoothing
Assume that the initial current value of the parameter g[0] is 0 and the target value t[n] is 1. Also, assume that T divides τ perfectly.
Here is the progression of the smoothed parameter using these values.
In one time constant τ seconds, g[1] =
1−exp
(−1) = 0.6321, the parameter reaches 63.21% of the target
value.
In two time constants, g[2] = 1−exp
(−2) = 0.8647,
the parameter reaches 86.47 % of the target value.
In three time constants, g[3] = 1−exp
(−3) =
0.9502, the parameter reaches approximately 95% of the target value.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Version History
Introduced in R2024a
See Also
Functions
designLowpassFIR
|designHighpassFIR
|designBandpassFIR
|designBandstopFIR
|designHalfbandFIR
|designLowpassIIR
|designHighpassIIR
|designBandpassIIR
|designBandstopIIR
|designHalfbandIIR
|designNotchPeakIIR
Blocks
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)