setPropertyTunability

Modify property tunability

Since R2022b

Syntax

setPropertyTunability(tps,prop,Name=Value)

Description

setPropertyTunability(tps,prop,Name=Value) modifies the tunability of the property prop of a tracking filter object, through a tunableFilterProperties object, tps, using name-value arguments. For example, setPropertyTunability(tps,"StateCovariance",IsTuned=true) sets the StateCovariance property to be tuned through the tunableFilterProperties object tps.

Examples

Obtain and Modify Tunable Properties of trackingEKF

Create a trackingEKF object using the initcvekf function.

filter = initcvekf(objectDetection(0,[0;0;0]));

Obtain the tunable properties of the filter using the tunableProperties object function.

tps = tunableProperties(filter)

tps = 
Tunable properties for object of type: trackingEKF

Property:      ProcessNoise
   PropertyValue:   [1 0 0;0 1 0;0 0 1]
   TunedQuantity:   Square root
   IsTuned:         true
       TunedQuantityValue:  [1 0 0;0 1 0;0 0 1]
       TunableElements:     [1 4 5 7 8 9]
       LowerBound:          [0 0 0 0 0 0]
       UpperBound:          [10 10 10 10 10 10]
Property:      StateCovariance
   PropertyValue:   [1 0 0 0 0 0;0 100 0 0 0 0;0 0 1 0 0 0;0 0 0 100 0 0;0 0 0 0 1 0;0 0 0 0 0 100]
   TunedQuantity:   Square root of initial value
   IsTuned:         false

From the display, the ProcessNoise property is tuned and the StateCovariance property is not tuned by default.

Set the StateCovariance property as tuned.

setPropertyTunability(tps,"StateCovariance",IsTuned=true);
disp(tps);

Tunable properties for object of type: trackingEKF

Property:      ProcessNoise
   PropertyValue:   [1 0 0;0 1 0;0 0 1]
   TunedQuantity:   Square root
   IsTuned:         true
       TunedQuantityValue:  [1 0 0;0 1 0;0 0 1]
       TunableElements:     [1 4 5 7 8 9]
       LowerBound:          [0 0 0 0 0 0]
       UpperBound:          [10 10 10 10 10 10]
Property:      StateCovariance
   PropertyValue:   [1 0 0 0 0 0;0 100 0 0 0 0;0 0 1 0 0 0;0 0 0 100 0 0;0 0 0 0 1 0;0 0 0 0 0 100]
   TunedQuantity:   Square root of initial value
   IsTuned:         true
       TunedQuantityValue:  [1 0 0 0 0 0;0 10 0 0 0 0;0 0 1 0 0 0;0 0 0 10 0 0;0 0 0 0 1 0;0 0 0 0 0 10]
       TunableElements:     [1 7 8 13 14 15 19 20 21 22 25 26 27 28 29 31 32 33 34 35 36]
       LowerBound:          [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
       UpperBound:          [100 100 100 100 100 100 100 100 100 100 100 100 100 100 100 100 100 100 100 100 100]

Set the tuned elements for the process noise matrix as the diagonal elements with specified bounds. Also, set the tuned elements for the state covariance matrix as the diagonal elements with specified bounds.

setPropertyTunability(tps,"ProcessNoise",TunableElements=sub2ind([3,3],[1 2 3],[1 2 3]), ...
    LowerBound=[0 0 0],UpperBound=[10 10 10]);
setPropertyTunability(tps,"StateCovariance",TunableElements=sub2ind([6,6],1:6,1:6), ...
    LowerBound=zeros(1,6),UpperBound=100*ones(1,6));
disp(tps)

Tunable properties for object of type: trackingEKF

Property:      ProcessNoise
   PropertyValue:   [1 0 0;0 1 0;0 0 1]
   TunedQuantity:   Square root
   IsTuned:         true
       TunedQuantityValue:  [1 0 0;0 1 0;0 0 1]
       TunableElements:     [1 5 9]
       LowerBound:          [0 0 0]
       UpperBound:          [10 10 10]
Property:      StateCovariance
   PropertyValue:   [1 0 0 0 0 0;0 100 0 0 0 0;0 0 1 0 0 0;0 0 0 100 0 0;0 0 0 0 1 0;0 0 0 0 0 100]
   TunedQuantity:   Square root of initial value
   IsTuned:         true
       TunedQuantityValue:  [1 0 0 0 0 0;0 10 0 0 0 0;0 0 1 0 0 0;0 0 0 10 0 0;0 0 0 0 1 0;0 0 0 0 0 10]
       TunableElements:     [1 8 15 22 29 36]
       LowerBound:          [0 0 0 0 0 0]
       UpperBound:          [100 100 100 100 100 100]

Obtain and Specify Tunable Properties of trackingIMM

Create a trackingIMM object using the initekfimm function.

filter = initekfimm(objectDetection(0,[0;0;0]));

Obtain the tunable properties of the filter using the tuanbleProperties object function.

tps = tunableProperties(filter)

tps = 
Tunable properties for object of type: trackingIMM

Property:      TransitionProbabilities
   PropertyValue:   [0.9 0.05 0.05;0.05 0.9 0.05;0.05 0.05 0.9]
   TunedQuantity:   Rows sum to one
   IsTuned:         true
       TunedQuantityValue:  [0.9 0.05 0.05;0.05 0.9 0.05;0.05 0.05 0.9]
       TunableElements:     [1 2 3 4 5 6 7 8 9]
       LowerBound:          [0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001]
       UpperBound:          [1 1 1 1 1 1 1 1 1]
Property:      ModelProbabilities
   PropertyValue:   [0.333333333333333;0.333333333333333;0.333333333333333]
   TunedQuantity:   Columns sum to one
   IsTuned:         true
       TunedQuantityValue:  [0.333333333333333;0.333333333333333;0.333333333333333]
       TunableElements:     [1 2 3]
       LowerBound:          [0.001 0.001 0.001]
       UpperBound:          [1 1 1]

The filter contains 3 tracking filters
   Show tunable properties for filter 1
   Show tunable properties for filter 2
   Show tunable properties for filter 3

Set the ModelProbabilities property to untuned.

setPropertyTunability(tps,"ModelProbabilities",IsTuned=false);
disp(tps);

Tunable properties for object of type: trackingIMM

Property:      TransitionProbabilities
   PropertyValue:   [0.9 0.05 0.05;0.05 0.9 0.05;0.05 0.05 0.9]
   TunedQuantity:   Rows sum to one
   IsTuned:         true
       TunedQuantityValue:  [0.9 0.05 0.05;0.05 0.9 0.05;0.05 0.05 0.9]
       TunableElements:     [1 2 3 4 5 6 7 8 9]
       LowerBound:          [0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001]
       UpperBound:          [1 1 1 1 1 1 1 1 1]
Property:      ModelProbabilities
   PropertyValue:   [0.333333333333333;0.333333333333333;0.333333333333333]
   TunedQuantity:   Columns sum to one
   IsTuned:         false

The filter contains 3 tracking filters
   Show tunable properties for filter 1
   Show tunable properties for filter 2
   Show tunable properties for filter 3

Set the tuned elements for the process noise matrices in the three trackingEKF objects. In this example, set the tunable elements as the diagonal elements with specified bounds.

setPropertyTunability(tps,"ProcessNoise",FilterIndex=1,TunableElements=sub2ind([3,3],[1 2 3],[1 2 3]), ...
    LowerBound=[0 0 0],UpperBound=[10 10 10]);
setPropertyTunability(tps,"ProcessNoise",FilterIndex=2,TunableElements=sub2ind([3,3],[1 2 3],[1 2 3]), ...
    LowerBound=[0 0 0],UpperBound=[10 10 10]);
setPropertyTunability(tps,"ProcessNoise",FilterIndex=3,TunableElements=sub2ind([3,3],[1 2 3],[1 2 3]), ...
    LowerBound=[0 0 0],UpperBound=[10 10 10]);

Input Arguments

tps — Tunable properties

tunableFilterProperties

Tunable properties, specified as a tunableFilterProperties object.

prop — Name of property to tune

string scalar | character vector

Name of property to tune, specified as a string scalar or a character vector of a valid tunable property name. See the display of the tunableFilterProperties object, tps, for a list of tunable properties.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: setPropertyTunability(tps,"StateCovariance",IsTuned=true)

IsTuned — Flag to tune property

true or 1 | false or 0

Flag to tune property, trackingFilterTuner, specified as a logical 1 (true) or 0 (false).

Data Types: logical

TunableElements — Tunable elements

N-element vector of indices

Tunable elements in the property, specified as an N-element vector of indices, where N is the number of tunable elements. Each index is a column-based index of the property value. For example, if you want to tune the diagonal elements of a 3-by-3 process noise matrix, specify this property as [1 5 9]. The tuner tunes only the specified elements.

Note

If you change the tunable elements, ensure that the LowerBound and UpperBound match the new elements.

Tip

To generate the indices for elements in a matrix, use the sub2ind function.

Example: [1 5 9]

LowerBound — Lower tuning bound

N-element vector of indices

Lower tuning bound of the tunable elements, specified as an N-element vector of scalars, where N is the number of tunable elements.

Example: [0 0 1]

UpperBound — Upper tuning bound

N-element vector of indices

Upper tuning bound of the tunable elements, specified as n N-element vector of scalars, where N is the number of tunable elements.

Example: [10 10 15]

FilterIndex — Index of tracking filter when tuning trackingIMM or trackingGSF

positive integer

Index of tracking filter when tuning a trackingIMM or trackingGSF object, specified as a positive integer. The integer must be less than or equal to the number of tracking filters specified in the TrackingFilters property of the object. When you specify this argument, the setPropertyTunability function modifies the tunability of a property of the tracking filter corresponding to the index.

Note

• You can specify this name-value argument only when you want to modify the tunability of a trackingIMM or trackingGSF object.

• To tune individual tracking filters of a trackingGSF object, create a tunableFilterProperties object using the tunableProperties object function and set its AsParameterizedFilter argument to false.

Example: 1

Version History

Introduced in R2022b