trackingFilterTuner

Tracking filter tuner

Description

The trackingFilterTuner object creates a tracking filter tuner that tunes the tunable properties of a tracking filter object, such as the trackingEKF object. Use the FilterInitializationFcn property to initialize a tracking filter for tuning. Use the tune object function to tune the filter. Tuning the filter using trackingFilterTuner requires Optimization Toolbox™ or Global Optimization Toolbox depending on the solver algorithm you choose in the Solver property.

Creation

Syntax

tuner = trackingFilterTuner

tuner = trackingFilterTuner(Name=Value)

Description

tuner = trackingFilterTuner creates a tracking filter tuner with default property values.

tuner = trackingFilterTuner(Name=Value) specifies properties using one or more name-value arguments. For example, trackingFilterTuner(Solver="patternsearch") specifies the pattern search algorithm as the solver algorithm.

Properties

FilterInitializationFcn — Filter initialization function

"initcvekf" (default) | string scalar | charter array

Filter initialization function, specified as a string scalar or a character vector representing the name of a valid filter initialization function. For this property, a valid filter initialization function is a function that returns a tunable tracking filter object. As of R2022b, these tracking filter objects are tunable:

• trackingKF

• trackingEKF

• trackingUKF

• trackingCKF

You can use any of these built-in filter initialization functions.

• initcvkf

• initcakf

• initcvekf

• initcaekf

• initctekf

• initsingerekf

• initcvukf

• initcaukf

• initctukf

• initcvckf

• initcackf

• initctckf

To write a custom initialization function, refer to the code for any of the initialization functions. For example, type the following command in the command window to see the implementation for the initcvekf function.

edit initcvekf

Note

To specify the Cost property as "RMSE" or "NEES", the filter returned by the filter initialization function must use one of these built-in motion models:

• constvel

• constacc

• constturn

• singer

If the filter does not use one of these motion models, specify the Cost property as "Custom".

Note

If you specify the UseMex property to true, changing the value of the FilterInitializationFcn property triggers code generation.

Data Types: char | string

TunablePropertiesSource — Source of filter tunable properties

"Default" (default) | "Custom"

Source of filter tunable properties, specified as:

• "Default" — The filter object specified in the FilterInitializationFcn property defines the properties to be tuned, the tuned elements, and the tuning bounds. To get the tunable properties of the filter, use the tunableProperties object function of the tunable filter object.

• "Custom" — Specify the tunable properties as a tunableFilterProperties object in the CustomTunableProperties property.

Note

If you set the UseMex property to true, changing the value of the TunablePropertiesSource property triggers code generation.

Data Types: char | string

CustomTunableProperties — Custom tunable properties

tunableFilterProperties object

Custom tunable properties, specified as a tunableFilterProperties object. You can use the tunableProperties function of the filter object to obtain the default tunableFilterProperties object and modify it to obtain a custom tunableFilterProperties object.

Note

If you set the UseMex property to true, changing the value of the CustomTunableProperties property triggers code generation.

Dependencies

To enable this property, set the TunablePropertiesSource property to "Custom".

Data Types: object

Cost — Tuning cost

"RMSE" (default) | "NEES" | "Custom"

Tuning cost, specified as one of these options:

• "RMSE" — The tuner minimizes the root mean square of the error between the ground truth and the filter estimates over all the time steps and Monte-Carlo runs. To use this option, the filter returned by the FilterInitialization property must use one of these built-in motion models:

  • constvel

  • constacc

  • constturn

  • singer

  Use this option if the absolute distance between the truth and estimate is the most important aspect for your tuning. See Objective Function for RMSE for more algorithm details.

• "NEES" — The tuner minimizes the normalized estimate error squared between the ground truth and the filter estimates over all the time steps and Monte-Carlo runs. To use this option, the filter returned by the filter initialization function must use one of these built-in motion models:

  • constvel

  • constacc

  • constturn

  • singer

  Use this option if you want to optimize the state estimate error covariance for a consistent filter. See Objective Function for NEES for more algorithm details.

• "Custom" — Specify the cost function in the CustomCostFcn property. Use a custom cost function if any of these conditions is true:

  • You want to tune the filter using a custom cost.

  • The filter uses a motion model that is not a constvel, constacc, constturn, or singer motion model.

  • The truth table contains data other than target position and velocity.

Data Types: char | string

CustomCostFcn — Custom cost function

string scalar | character vector | function handle

Custom cost function, specified as a string scalar, a character vector, or a function handle. The custom cost function must use the following syntax:

cost = myCostFun(trackHistory,truth)

• trackHistory — N-by-M array of track structures, where N is the number of the rows in the truth time table and M is the number of Monte-Carlo runs specified in the detection log input of the tune object function. Each structure has these fields:

  • UpdateTime — The time at which the filter was updated, specified as a scalar.

  • State — The state estimate at the update time.

  • StateCovariance — The state estimate error covariance at the update time.

• truth — A truth time table that is the same as the truth time table input for the tune object function.

• cost — A scalar value representing the cost.

Dependencies

To enable this property, set the Cost property to "Custom".

Data Types: char | string | function_handle

Solver — Optimization solver

"fmincon" (default) | "patternsearch" | "particleswarm"

Optimization solver, specified as one of these options:

• "fmincon" — This option requires Optimization Toolbox. See fmincon (Optimization Toolbox) for details.

• "patternsearch" — This option requires Global Optimization Toolbox. See patternsearch (Global Optimization Toolbox) for details.

• "particleswarm" — This option requires Global Optimization Toolbox. See particleswarm (Global Optimization Toolbox) for details.

Data Types: char | string

UseMex — Enable using code generation

false or 0 (default) | true or 1

Enable using code generation, specified as a logical 0 (false) or 1 (true). Specifying true requires MATLAB^® Coder™ license.

If you set the property to true, the object first generates mex code and then runs the tuning based on the generated code. For large data sets, using generated code can expedite the tuning process.

Data Types: logical

UseParallel — Enable using parallel processing

false or 0 (default) | true or 1

Enable using parallel processing, specified as a logical 0 (false) or 1 (true). Specifying true requires Parallel Computing Toolbox™. For large data sets, using parallel processing can expedite the tuning process.

Note

If you set the UseMex property to true, changing the value of the useParallel property triggers code generation.

Data Types: logical

SolverOptions — Options to control solver

[] (default) | optimoptions object

Options to control the solver in the Solver property, specified as an optimoptions (Optimization Toolbox) object. The default value of [] represents the default setup for the solver.

Object Functions

tune	Tune tracking filter
exportToFunction	Export filter initialization function
plotFilterErrors	Plot tracking filter errors

Examples

Tune trackingEKF Using Tracking Filter Tuner

Load the tuning data containing the truth and detection data. The truth data has the position and velocity of one target for a duration of 9.5 seconds. The detection data has object detections of ten Monte-Carlo runs for the same period.

load("filterTuningData.mat","truth","detlog");

Create a trackingFilterTuner object.

tuner = trackingFilterTuner;

By default, the FiliterInitialization property of the tuner returns an initialization function that initializes a trackingEKF object.

initFcn = tuner.FilterInitializationFcn

initFcn = 
"initcvekf"

Initialize the trackingEKF object and display the untuned process noise.

filter = feval(tuner.FilterInitializationFcn,detlog{1});
disp(filter.ProcessNoise);

     1     0     0
     0     1     0
     0     0     1

Specify the SolverOptions property so that the tuner displays the tuning progress for every iteration and set the maximum number of iterations to 30.

tuner.SolverOptions = optimoptions("fmincon",Display ="iter", ...
    MaxIterations=30);

Using the tune object function, tune the filter with the detection log and the truth data. Return the tuned properties.

tunedProps = tune(tuner,detlog,truth);

Your initial point x0 is not between bounds lb and ub; FMINCON
shifted x0 to strictly satisfy the bounds.

                                            First-order      Norm of
 Iter F-count            f(x)  Feasibility   optimality         step
    0       7    9.294119e+00    0.000e+00    3.977e-02
    1      14    9.274890e+00    0.000e+00    3.653e-02    1.313e-01
    2      21    9.182690e+00    0.000e+00    3.089e-02    6.852e-01
    3      28    9.077721e+00    0.000e+00    4.671e-02    1.166e+00
    4      35    9.073360e+00    0.000e+00    4.441e-02    9.369e-02
    5      42    9.054802e+00    0.000e+00    4.320e-02    2.909e-01
    6      49    9.047225e+00    0.000e+00    2.914e-02    2.754e-01
    7      56    9.047721e+00    0.000e+00    1.084e-02    3.484e-02
    8      63    9.047374e+00    0.000e+00    4.113e-03    5.013e-02
    9      70    9.047364e+00    0.000e+00    2.893e-03    1.480e-02
   10      77    9.047318e+00    0.000e+00    1.734e-03    1.414e-02
   11      84    9.047302e+00    0.000e+00    9.999e-04    7.210e-03
   12      91    9.045889e+00    0.000e+00    1.152e-03    6.212e-02
   13      98    9.045539e+00    0.000e+00    8.820e-04    2.369e-02
   14     105    9.045480e+00    0.000e+00    8.302e-04    5.352e-03
   15     112    9.045468e+00    0.000e+00    6.217e-04    2.099e-03
   16     119    9.045470e+00    0.000e+00    2.000e-04    1.936e-03
   17     126    9.045223e+00    0.000e+00    1.153e-03    2.499e-02
   18     133    9.045106e+00    0.000e+00    3.033e-04    1.772e-02
   19     140    9.045095e+00    0.000e+00    1.018e-04    2.418e-03
   20     147    9.045095e+00    0.000e+00    1.007e-04    5.276e-04
   21     154    9.045095e+00    0.000e+00    9.443e-05    9.549e-04
   22     161    9.045095e+00    0.000e+00    8.803e-05    7.331e-04
   23     168    9.045095e+00    0.000e+00    7.113e-05    1.197e-03
   24     175    9.045094e+00    0.000e+00    1.094e-04    7.076e-04
   25     182    9.045094e+00    0.000e+00    1.111e-04    6.153e-04
   26     189    9.045094e+00    0.000e+00    7.520e-05    2.503e-04
   27     196    9.045094e+00    0.000e+00    4.000e-05    1.866e-04
   28     203    9.045034e+00    0.000e+00    3.476e-04    1.553e-02
   29     210    9.045015e+00    0.000e+00    3.322e-05    7.214e-03
   30     217    9.045013e+00    0.000e+00    1.526e-05    1.220e-03

Solver stopped prematurely.

fmincon stopped because it exceeded the iteration limit,
options.MaxIterations = 3.000000e+01.

Set the filter tunable properties by using the setTunedProperty object function of the filter. Display the tuned process noise.

setTunedProperties(filter,tunedProps);
disp(filter.ProcessNoise);

    0.0000    0.0001    0.0000
    0.0001    0.0149    0.0007
    0.0000    0.0007    0.0002

Plot the filter estimation error after tuning by using the plotFilterErrors object function.

plotFilterErrors(tuner)

Customize Tunable Properties and Tune Tracking Filter

Load the tuning data containing the truth and detection data. The truth data has the position and velocity of one target for a duration of 9.5 seconds. The detection data has object detections of ten Monte-Carlo runs for the same period.

load("filterTuningData.mat","truth","detlog");

Create a trackingFilterTuner object. Specify the FilterInitializationFcn property as "initcvkf" that corresponds to a trackingKF filter object with a constant velocity model.

tuner = trackingFilterTuner(FilterInitializationFcn ="initcvkf");

You can obtain the filter by evaluating the initialization function on an object detection.

filter = feval(tuner.FilterInitializationFcn,detlog{1})

filter = 
  trackingKF with properties:

               State: [6×1 double]
     StateCovariance: [6×6 double]

         MotionModel: '3D Constant Velocity'
        ProcessNoise: [3×3 double]

    MeasurementModel: [3×6 double]
    MeasurementNoise: [3×3 double]

     MaxNumOOSMSteps: 0

     EnableSmoothing: 0

To customize the tunable properties of the filter, first get the default tunable properties of the filter.

tps = tunableProperties(filter)

tps = 
Tunable properties for object of type: trackingKF

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:   [3.53553390593274 0 0 0 0 0;0 100 0 0 0 0;0 0 3.53553390593274 0 0 0;0 0 0 100 0 0;0 0 0 0 3.53553390593274 0;0 0 0 0 0 100]
   TunedQuantity:   Square root of initial value
   IsTuned:         false

Based on the display, the tuner tunes only the ProcessNoise property, which is a 3-by-3 matrix. Change the tunable elements to be only the diagonal elements by using the setPropertyTunability object function. Set the lower and upper bounds for tuning the diagonal elements.

setPropertyTunability(tps,"ProcessNoise",TunableElements=[1 5 9], ...
    LowerBound=[0.01 0.01 0.01],UpperBound = [20 20 20])

To enable custom tunable properties, set the TunablePropertiesSource and CustomTunable properties to "Custom" and tps, respectively.

tuner.TunablePropertiesSource = "Custom";
tuner.CustomTunableProperties = tps;

Using the tune object function, tune the filter with the detection log and the truth data.

tune(tuner,detlog,truth);

Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.

<stopping criteria details>

Generate the filter initialization function after tuning by using the exportToFunction object function.

exportToFunction(tuner,"tunedInitFcn")

Obtain the tuned filter by evaluating the tuned initialization function on an object detection. Show the tuned process noise.

tunedFilter = tunedInitFcn(detlog{1})

tunedFilter = 
  trackingKF with properties:

               State: [6×1 double]
     StateCovariance: [6×6 double]

         MotionModel: '3D Constant Velocity'
        ProcessNoise: [3×3 double]

    MeasurementModel: [3×6 double]
    MeasurementNoise: [3×3 double]

     MaxNumOOSMSteps: 0

     EnableSmoothing: 0

tunedFilter.ProcessNoise

ans = 3×3

    0.0001         0         0
         0    0.0149         0
         0         0    0.0001

Algorithms

Objective Function for RMSE

The state estimate error between the truth state x_k and the estimated state at time step k is defined as:

$$e_{x|k}=x_k-{\widehat{x}}_k.$$

The square error between the truth state and the corresponding estimated state is defined as:

$${ϵ}_{x,k}=e_{x,k}^T{e}_{x,k}.$$

Furthermore, for measurement data from multiple Monte Carlo runs, define the averaged square error at time k as:

$${\overline{ϵ}}_{x,k}=\frac{1}{M}{\displaystyle \sum _{i=1}^M{ϵ}_{x,k}^i,}$$

where M is the number of Monte Carlo runs. Then the objective function for RMSE-based filter tuning is:

$$J_{RMSE}=\sqrt{{\displaystyle \sum _{k=1}^T{\overline{ϵ}}_{x,k}/T}},$$

where T is the number of time steps. If multiple truth tables are provided, the object function is averaged as:

$${\overline{J}}_{RMSE}=\frac{1}{N_t}{\displaystyle \sum _{j=1}^{N_t}{J}_{RMSE}^j},$$

where N_t is the number of truth tables and J^j_RMSE is the RMSE object function for the j-th truth table.

Objective Function for NEES

The state estimate error between the truth state x_k and the estimated state at time step k is defined as:

$$e_{x|k}=x_k-{\widehat{x}}_k.$$

The normalized estimate error squared (NEES) between the truth state and the corresponding estimated state is defined as:

$${ϵ}_{x,k}=e_{x,k}^T{P}_k^{-1}{e}_{x,k},$$

where P_k is the state estimate error covariance matrix at time step k.

Furthermore, for measurement data from multiple Monte Carlo runs, define the averaged NEES at time k as:

$${\overline{ϵ}}_{x,k}=\frac{1}{M}{\displaystyle \sum _{i=1}^M{ϵ}_{x,k}^i,}$$

where M is the number of Monte Carlo runs. Then the objective function for NEES-based filter tuning is:

$$J_{NEES}=\left|\log \left(\frac{1}{n_x}{\displaystyle \sum _{k=1}^T{\overline{ϵ}}_{x,k}/T}\right)\right|,$$

where T is the number of time steps and n_x is the dimension of the state vector x.

If multiple truth tables are provided, the object function is averaged as:

$${\overline{J}}_{NEES}=\frac{1}{N_t}{\displaystyle \sum _{j=1}^{N_t}{J}_{NEES}^j},$$

where N_t is the number of truth tables and J^j_NEES is the NEES object function for the j-th truth table.

For a consistent filter, a filter that is neither overconfident or underconfident, the overall NEES value should be equal or close to n_x. As a result, the value of J_NEES should be close to 0 and the optimization algorithm penalizes any J_NEES value that is larger than 0.

References

[1] Chen, Zhaozhong, et al. “Time Dependence in Kalman Filter Tuning.” IEEE 24th International Conference on Information Fusion , IEEE, 2021, pp. 1–8.

Version History

Introduced in R2022b