MSJointGeneralizedLabeledMultiBernoulli

class MSJointGeneralizedLabeledMultiBernoulli(**kwargs)

Bases: JointGeneralizedLabeledMultiBernoulli

Implementation of the Multiple Sensor JGLMB 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 MS-JGLMB filter.
extract_most_prob_states	Extracts the most probable hypotheses up to a threshold.
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_labels	Plots the best estimate for the states and labels.
predict	Prediction step of the JGLMB filter.
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.
labels	Read only list of extracted labels.
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_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.GeneralizedLabeledMultiBernoulli.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_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 MS-JGLMB filter.

This corrects the hypotheses based on the measurements and gates the measurements according to the class settings. It also updates the cardinality distribution. Because this calls the inner filter’s correct function, the keyword arguments must contain any information needed by that function.

Parameters:

• timestep (float) – Current timestep.

• meas (list) – List of lists representing sensor measurements containing Nm x 1 numpy arrays each representing a single measurement.

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

Todo

Fix the measurement gating

Return type:

None

extract_most_prob_states(thresh)

Extracts the most probable hypotheses up to a threshold.

Parameters:

thresh (float) – Minimum association probability to extract.

Returns:

• state_sets (list) – Each element is the state list from the normal carbs.swarm_estimator.tracker.GeneralizedLabeledMultiBernoulli.extract_states().

• label_sets (list) – Each element is the label list from the normal carbs.swarm_estimator.tracker.GeneralizedLabeledMultiBernoulli.extract_states()

• cov_sets (list) – Each element is the covariance list from the normal carbs.swarm_estimator.tracker.GeneralizedLabeledMultiBernoulli.extract_states() if the covariances are saved.

• probs (list) – Each element is the association probability for the extracted states.

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_labels(plt_inds, ttl='Labeled State Trajectories', x_lbl=None, y_lbl=None, meas_tx_fnc=None, **kwargs)

Plots the best estimate for the states and labels.

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]

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

• f_hndl

• true_states

• sig_bnd

• rng

• meas_inds

• lgnd_loc

Parameters:

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

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

• x_lbl (string, optional) – X-axis label for the plot.

• y_lbl (string, optional) – Y-axis label for the plot.

• meas_tx_fnc (callable, optional) – Takes in the measurement vector as an Nm x 1 numpy array and returns a numpy array representing the states to plot (size 2). The default is None.

Returns:

Instance of the matplotlib figure used

Return type:

Matplotlib figure

predict(timestep, filt_args={})

Prediction step of the JGLMB filter.

This predicts new hypothesis, and propogates them to the next time step. Because this calls the inner filter’s predict function, the keyword arguments must contain any information needed by that function.

Parameters:

• timestep (float) – Current timestep.

• filt_args (dict, optional) – Passed to the inner filter. The default is {}.

Return type:

None.

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 labels

Read only list of extracted labels.

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

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.