Main Content

parameterCost

Get cost for tuning parameters

Since R2023a

collapse all in page

Syntax

cost = parameterCost(tuner)
cost = parameterCost(tuner,params)
cost = parameterCost(tuner,params,detectionLog,truth)

Description

cost = parameterCost(tuner) returns the cost of the untuned filter specified by the FilterInitializationFcn property of the tuner. The function obtains the cost based on the detection log and truth data used in the latest call to the tune object function. You must at least use the tune function once before using this syntax.

example

cost = parameterCost(tuner,params) additionally specifies the set of tunable parameters used to evaluate the tuning cost. You must at least use the tune object function once before using this syntax.

example

cost = parameterCost(tuner,params,detectionLog,truth) additionally specifies the detection log and truth data used to evaluate the tuning cost. You do not need to use the tune object function before using this syntax.

example

Examples

collapse all

Open Live Script

Load the tuning data containing the truth and detection data.

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

Create a trackingFilterTuner object. By default, the FilterInitializationFcn property of the tuner initializes a trackingEKF object.

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

Create a tunable parameter structure to evaluate the tuning cost directly.

params.ProcessNoise = filter.ProcessNoise;
params.StatesCovariance = filter.StateCovariance;
cost1 =  parameterCost(tuner,params,detlog,truth)
cost1 = 
9.2177

Alternately, you can first call the tune object function and evaluate tuning cost with and without the tuned parameters.

tunedParams = tune(tuner,detlog,truth);
Iter        RMSE          Step Size
   0       9.2177                
   1       9.1951          0.1509
   2       9.0458          1.5276
   3       9.0456          0.0176
   4       9.0452          0.0706
   5       9.0452          0.0142
   6       9.0452          0.0012
   7       9.0452          0.0119
   8       9.0452          0.0015
   9       9.0451          0.0500
  10       9.0450          0.0743
  11       9.0450          0.0312
  12       9.0450          0.0122

cost2 = parameterCost(tuner) 
cost2 = 
9.2177

cost3 = parameterCost(tuner,tunedParams) 
cost3 = 
9.0450

Input Arguments

collapse all

Tracking filter tuner, specified as a trackingFilterTuner object.

Tunable parameters, specified as an N-element array of structures. The fields of each structure must have the same name, class, and size as the output of the tune object function.

Data Types: struct

Detection log, specified as cell arrays of objectDetection objects.

Specify detectionLog based on the number of truth targets that you specify in the truth input argument.

  • One truth target — Specify detectionLog as a T-by-N cell array of objectDetection objects. N is the number of Monte-Carlo runs. The number of time steps T does not have to be equal to the number of rows in the truth table. The timestamp of each detection does not have to match the time in the truth table.

  • Multiple truth targets — Specify detectionLog as an M-element cells, where each cell contains a cell array of objectDetection objects for the corresponding truth timetable. M is the number of truth tables. Across the M cells, the detection time, the number of detections, and the number of Monte-Carlo runs do not have to be the same.

Truth data, specified as a structure, table, timetable, cell array of structures, cell array of tables, cell array of timetables.

You can specify truth for one or more truth targets.

  • One truth target — Specify truth as a truth structure, table, or timetable.

    When specified as a structure, the structure must contain a field Time and either Position and Velocity fields or a State field. parameterCost converts the structure to a timetable and uses it as defined below.

    When specified as a table, or timetable, the truth must have these variables as columns:

    • Time — Time of the truth information, specified as a single, double, or duration in each table row.

    • Position — Position of the target at the time, specified as a 1-by-3 real-valued vector in each table row.

    • Velocity — Velocity of the target at the time, specified as a 1-by-3 real-valued vector in each table row. This variable is optional.

    • State — State of the target at the time, specified as 1-by-S real-valued vector in each table row, where S is dimension of the state.

      Note

      • When you specify the State column, the tuner ignores the Position and Velocity columns if specified.

      • The definition of the State column must be exactly the same as the state definition in the tuned filter. For example, if the filter defines its state as [x y v q], where x and y are positions in a 2-D rectangular frame, v is the speed, and q is the heading angle, you must specify the timetable with a State column in the same [x y v q] definition.

  • Multiple truth targets — Specify truth as an M-element cell array of truth structures, tables, or timetables. Each truth structure, table, or timetable can have different initial and end times.

Output Arguments

collapse all

Tuning cost, returned as a real scalar when you do not specify the params input argument and returned as an N-element vector when you specify the params input argument. N is the number of tunable parameter structures specified in the params input. The definition of the cost is the same as the Cost property of the tuner.

Version History

Introduced in R2023a

expand all

See Also