STMPoissonMultiBernoulliMixture

class STMPoissonMultiBernoulliMixture(**kwargs)

Bases: _STMPMBMBase, PoissonMultiBernoulliMixture

Implementation of a STM-PMBM filter.

__init__(**kwargs)

Initialize an object.

Parameters:

• in_filter – Inner filter object.

• prob_detection – Probability of detection.

• prob_survive – Probability of survival.

• birth_terms – Birth model.

• clutter_rate – Clutter rate per scan.

• clutter_den – Clutter density.

• inv_chi2_gate – Inverse Chi^2 gating threshold.

• save_covs – Flag for saving covariances.

• debug_plots – Flag for enabling debug plots.

• enable_spawning – Flag for enabling spawning.

• spawn_cov – Covariance for spawned targets.

• spawn_weight – Weight for spawned targets.

Methods

__init__	Initialize an object.
calculate_gospa	Calculates the OSPA distance between the truth at all timesteps.
calculate_ospa	Calculates the OSPA distance between the truth at all timesteps.
calculate_ospa2	Calculates the OSPA(2) distance between the truth at all timesteps.
cleanup	Performs the cleanup step of the filter.
correct	Correction step of the PMBM filter.
extract_states	Extracts the best state estimates.
load_filter_state	Initializes filter using saved filter state.
plot_card_dist	Plots the current cardinality distribution.
plot_card_history	Plots the cardinality history.
plot_gospa_history	Plots the GOSPA history.
plot_ospa2_history	Plots the OSPA2 history.
plot_ospa_history	Plots the OSPA history.
plot_states	Plots the best estimate for the states.
predict	Abstract method for the prediction step.
save_filter_state	Saves filter variables so they can be restored later.

Attributes

cardinality	Cardinality estimate.
covariances	Read only list of extracted covariances.
filter	Inner filter handling dynamics, must be a gncpy.filters.BayesFilter.
num_birth_terms	Number of terms in the birth model.
ospa_method	The distance metric used in the OSPA calculation (read only).
prob_death	Compliment of carbs.swarm_estimator.RandomFinitSetBase.prob_survive.
prob_miss_detection	Compliment of swarm_estimator.RandomFiniteSetBase.prob_detection.
states	Read only list of extracted states.

calculate_gospa(truth: Iterable[Iterable[ndarray]], c: float, p: float, a: int, core_method: SingleObjectDistance | None = None, true_covs: Iterable[Iterable[ndarray]] | None = None, state_inds: Iterable[int] | None = None)

Calculates the OSPA distance between the truth at all timesteps.

Wrapper for serums.distances.calculate_ospa().

Parameters:

• truth (list) – Each element represents a timestep and is a list of N x 1 numpy array, one per true agent in the swarm.

• c (float) – Distance cutoff for considering a point properly assigned. This influences how cardinality errors are penalized. For \(p = 1\) it is the penalty given false point estimate.

• p (int) – The power of the distance term. Higher values penalize outliers more.

• a (int) – The normalization factor of the distance term. Appropriately penalizes missed or false detection of tracks rather than normalizing by the total maximum cardinality.

• core_method (serums.enums.SingleObjectDistance, Optional) – The main distance measure to use for the localization component. The default value of None implies SingleObjectDistance.EUCLIDEAN.

• true_covs (list, Optional) – Each element represents a timestep and is a list of N x N numpy arrays corresonponding to the uncertainty about the true states. Note the order must be consistent with the truth data given. This is only needed for core methods SingleObjectDistance.HELLINGER. The defautl value is None.

• state_inds (list, optional) – Indices in the state vector to use, will be applied to the truth data as well. The default is None which means the full state is used.

calculate_ospa(truth: Iterable[Iterable[ndarray]], c: float, p: float, core_method: SingleObjectDistance | None = None, true_covs: Iterable[Iterable[ndarray]] | None = None, state_inds: Iterable[int] | None = None)

Calculates the OSPA distance between the truth at all timesteps.

Wrapper for serums.distances.calculate_ospa().

Parameters:

• truth (list) – Each element represents a timestep and is a list of N x 1 numpy array, one per true agent in the swarm.

• c (float) – Distance cutoff for considering a point properly assigned. This influences how cardinality errors are penalized. For \(p = 1\) it is the penalty given false point estimate.

• p (int) – The power of the distance term. Higher values penalize outliers more.

• core_method (serums.enums.SingleObjectDistance, Optional) – The main distance measure to use for the localization component. The default value of None implies SingleObjectDistance.EUCLIDEAN.

• true_covs (list, Optional) – Each element represents a timestep and is a list of N x N numpy arrays corresonponding to the uncertainty about the true states. Note the order must be consistent with the truth data given. This is only needed for core methods SingleObjectDistance.HELLINGER. The defautl value is None.

• state_inds (list, optional) – Indices in the state vector to use, will be applied to the truth data as well. The default is None which means the full state is used.

calculate_ospa2(truth, c, p, win_len, true_covs=None, core_method=SingleObjectDistance.MANHATTAN, state_inds=None)

Calculates the OSPA(2) distance between the truth at all timesteps.

Wrapper for serums.distances.calculate_ospa2().

Parameters:

• truth (list) – Each element represents a timestep and is a list of N x 1 numpy array, one per true agent in the swarm.

• c (float) – Distance cutoff for considering a point properly assigned. This influences how cardinality errors are penalized. For \(p = 1\) it is the penalty given false point estimate.

• p (int) – The power of the distance term. Higher values penalize outliers more.

• win_len (int) – Number of samples to include in window.

• core_method (serums.enums.SingleObjectDistance, Optional) – The main distance measure to use for the localization component. The default value is SingleObjectDistance.MANHATTAN.

• true_covs (list, Optional) – Each element represents a timestep and is a list of N x N numpy arrays corresonponding to the uncertainty about the true states. Note the order must be consistent with the truth data given. This is only needed for core methods SingleObjectDistance.HELLINGER. The defautl value is None.

• state_inds (list, optional) – Indices in the state vector to use, will be applied to the truth data as well. The default is None which means the full state is used.

cleanup(enable_prune=True, enable_cap=True, enable_bern_prune=True, enable_extract=True, extract_kwargs=None)

Performs the cleanup step of the filter.

This can prune, cap, and extract states. It must be called once per timestep, even if all three functions are disabled. This is to ensure that internal counters for tracking linear timestep indices are properly incremented. If this is called with enable_extract set to true then the extract states method does not need to be called separately. It is recommended to call this function instead of carbs.swarm_estimator.tracker.PoissonMultiBernoulliMixture.extract_states() directly.

Parameters:

• enable_prune (bool, optional) – Flag indicating if prunning should be performed. The default is True.

• enable_cap (bool, optional) – Flag indicating if capping should be performed. The default is True.

• enable_bern_prune (bool, optional) – Flag indicating if bernoulli pruning should be performed. The default is True.

• enable_extract (bool, optional) – Flag indicating if state extraction should be performed. The default is True.

• extract_kwargs (dict, optional) – Additional arguments to pass to extract_states(). The default is None. Only used if extracting states.

Return type:

None.

correct(timestep, meas, filt_args={})

Correction step of the PMBM filter.

Notes

This corrects the hypotheses based on the measurements and gates the measurements according to the class settings. It also updates the cardinality distribution.

Parameters:

• timestep (float) – Current timestep.

• meas (list) – List of Nm x 1 numpy arrays each representing a measuremnt.

• filt_args (dict, optional) – keyword arguments to pass to the inner filters correct function. The default is {}.

Return type:

None

extract_states(update=True, calc_states=True)

Extracts the best state estimates.

This extracts the best states from the distribution. It should be called once per time step after the correction function. This calls both the inner filters predict and correct functions so the keyword arguments must contain any additional variables needed by those functions.

Parameters:

• update (bool, optional) – Flag indicating if the label history should be updated. This should be done once per timestep and can be disabled if calculating states after the final timestep. The default is True.

• calc_states (bool, optional) – Flag indicating if the states should be calculated based on the label history. This only needs to be done before the states are used. It can simply be called once after the end of the simulation. The default is true.

Returns:

idx_cmp – Index of the hypothesis table used when extracting states.

Return type:

int

load_filter_state(filt_state)

Initializes filter using saved filter state.

filt_state

Dictionary generated by save_filter_state().

Type:

dict

plot_card_dist(ttl=None, **kwargs)

Plots the current cardinality distribution.

This assumes that the cardinality distribution has been calculated by the class.

Keywrod arguments are processed with gncpy.plotting.init_plotting_opts(). This function implements

• f_hndl

Parameters:

ttl (string) – Title of the plot, if None a default title is generated. The default is None.

Returns:

Instance of the matplotlib figure used

Return type:

Matplotlib figure

plot_card_history(time_units='index', time=None, ttl='Cardinality History', **kwargs)

Plots the cardinality history.

Parameters:

• time_units (string, optional) – Text representing the units of time in the plot. The default is ‘index’.

• time (numpy array, optional) – Vector to use for the x-axis of the plot. If none is given then vector indices are used. The default is None.

• ttl (string, optional) – Title of the plot.

• **kwargs (dict) – Additional plotting options for gncpy.plotting.init_plotting_opts() function. Values implemented here are f_hndl, and any values relating to title/axis text formatting.

Returns:

fig – Figure object the data was plotted on.

Return type:

matplotlib figure

plot_gospa_history(time_units='index', time=None, main_opts=None, sub_opts=None, plot_subs=True)

Plots the GOSPA history.

This requires that the GOSPA has been calcualted by the approriate function first.

Parameters:

• time_units (string, optional) – Text representing the units of time in the plot. The default is ‘index’.

• time (numpy array, optional) – Vector to use for the x-axis of the plot. If none is given then vector indices are used. The default is None.

• main_opts (dict, optional) – Additional plotting options for gncpy.plotting.init_plotting_opts() function. Values implemented here are f_hndl, and any values relating to title/axis text formatting. The default of None implies the default options are used for the main plot.

• sub_opts (dict, optional) – Additional plotting options for gncpy.plotting.init_plotting_opts() function. Values implemented here are f_hndl, and any values relating to title/axis text formatting. The default of None implies the default options are used for the sub plot.

• plot_subs (bool, optional) – Flag indicating if the component statistics (cardinality and localization) should also be plotted.

Returns:

figs – Dictionary of matplotlib figure objects the data was plotted on.

Return type:

dict

plot_ospa2_history(time_units='index', time=None, main_opts=None, sub_opts=None, plot_subs=True)

Plots the OSPA2 history.

This requires that the OSPA2 has been calcualted by the approriate function first.

Parameters:

• time_units (string, optional) – Text representing the units of time in the plot. The default is ‘index’.

• time (numpy array, optional) – Vector to use for the x-axis of the plot. If none is given then vector indices are used. The default is None.

• main_opts (dict, optional) – Additional plotting options for gncpy.plotting.init_plotting_opts() function. Values implemented here are f_hndl, and any values relating to title/axis text formatting. The default of None implies the default options are used for the main plot.

• sub_opts (dict, optional) – Additional plotting options for gncpy.plotting.init_plotting_opts() function. Values implemented here are f_hndl, and any values relating to title/axis text formatting. The default of None implies the default options are used for the sub plot.

• plot_subs (bool, optional) – Flag indicating if the component statistics (cardinality and localization) should also be plotted.

Returns:

figs – Dictionary of matplotlib figure objects the data was plotted on.

Return type:

dict

plot_ospa_history(time_units='index', time=None, main_opts=None, sub_opts=None, plot_subs=True)

Plots the OSPA history.

This requires that the OSPA has been calcualted by the approriate function first.

Parameters:

• time_units (string, optional) – Text representing the units of time in the plot. The default is ‘index’.

• time (numpy array, optional) – Vector to use for the x-axis of the plot. If none is given then vector indices are used. The default is None.

• main_opts (dict, optional) – Additional plotting options for gncpy.plotting.init_plotting_opts() function. Values implemented here are f_hndl, and any values relating to title/axis text formatting. The default of None implies the default options are used for the main plot.

• sub_opts (dict, optional) – Additional plotting options for gncpy.plotting.init_plotting_opts() function. Values implemented here are f_hndl, and any values relating to title/axis text formatting. The default of None implies the default options are used for the sub plot.

• plot_subs (bool, optional) – Flag indicating if the component statistics (cardinality and localization) should also be plotted.

Returns:

figs – Dictionary of matplotlib figure objects the data was plotted on.

Return type:

dict

plot_states(plt_inds, state_lbl='States', ttl=None, state_color=None, x_lbl=None, y_lbl=None, **kwargs)

Plots the best estimate for the states.

This assumes that the states have been extracted. It’s designed to plot two of the state variables (typically x/y position). The error ellipses are calculated according to [2]

Keyword arguments are processed with gncpy.plotting.init_plotting_opts(). This function implements

• f_hndl

• true_states

• sig_bnd

• rng

• meas_inds

• lgnd_loc

• marker

Parameters:

• plt_inds (list) – List of indices in the state vector to plot

• state_lbl (string) – Value to appear in legend for the states. Only appears if the legend is shown

• ttl (string, optional) – Title for the plot, if None a default title is generated. The default is None.

• x_lbl (string) – Label for the x-axis.

• y_lbl (string) – Label for the y-axis.

Returns:

Instance of the matplotlib figure used

Return type:

Matplotlib figure

predict(timestep, filt_args={})

Abstract method for the prediction step.

This must be overridden in the inherited class. It is recommended to keep the same structure/order for the arguments for consistency between the inherited classes.

save_filter_state()

Saves filter variables so they can be restored later.

Note that to pickle the resulting dictionary the dill package may need to be used due to potential pickling of functions.

property cardinality

Cardinality estimate.

property covariances

Read only list of extracted covariances.

This is a list with 1 element per timestep, and each element is a list of the best covariances extracted at that timestep. The order of each element corresponds to the state order.

Raises:

RuntimeWarning – If the class is not saving the covariances, and returns an empty list.

property filter

Inner filter handling dynamics, must be a gncpy.filters.BayesFilter.

property num_birth_terms

Number of terms in the birth model.

property ospa_method

The distance metric used in the OSPA calculation (read only).

property prob_death

Compliment of carbs.swarm_estimator.RandomFinitSetBase.prob_survive.

property prob_miss_detection

Compliment of swarm_estimator.RandomFiniteSetBase.prob_detection.

property states

Read only list of extracted states.

This is a list with 1 element per timestep, and each element is a list of the best states extracted at that timestep. The order of each element corresponds to the label order.