Hypothesiser

class stonesoup.hypothesiser.base.Hypothesiser[source]

Bases: Base

Hypothesiser base class

Given a track and set of detections, generate hypothesis of association.

hypothesise(track: Track, detections: Set[Detection], timestamp: datetime, **kwargs) → Sequence[Hypothesis][source]

Hypothesise track and detection association

Parameters:

track (Track) – Track which hypotheses will be generated for.
detections (set of Detection) – Detections used to generate hypotheses.
timestamp (datetime.datetime) – A timestamp used when evaluating the state and measurement predictions. Note that if a given detection has a non empty timestamp, then prediction will be performed according to the timestamp of the detection.

Returns:

Ordered sequence of “best” to “worse” hypothesis.

Return type:

sequence of Hypothesis

Simple

class stonesoup.hypothesiser.simple.SimpleHypothesiser(predictor: Predictor, updater: Updater = None, check_timestamp: bool = True, predict_measurement: bool = False)[source]

Bases: Hypothesiser

Simple Hypothesiser class

Generate track predictions at detection times and create hypotheses for each detection, as well as a missed detection hypothesis.

Parameters:

predictor (Predictor) – Predict tracks to detection times
updater (Updater, optional) – Updater used to get measurement prediction. Only required if predict_measurement is True. Default is None
check_timestamp (bool, optional) – Check that all detections have the same timestamp. Default is True
predict_measurement (bool, optional) – Predict measurement for each detection. Default is True

predictor: Predictor: Predict tracks to detection times

updater: Updater: Updater used to get measurement prediction. Only required if predict_measurement is True. Default is None

check_timestamp: bool: Check that all detections have the same timestamp. Default is True

predict_measurement: bool: Predict measurement for each detection. Default is True

hypothesise(track: Track, detections: Set[Detection], timestamp: datetime, **kwargs) → MultipleHypothesis[source]

Evaluate and return all track association hypotheses.

For a given track and a set of N available detections, return a MultipleHypothesis object with N+1 detections (first detection is a ‘MissedDetection’).

Parameters:

track (Track) – The track object to hypothesise on
detections (set of Detection) – The available detections
timestamp (datetime.datetime) – A timestamp used when evaluating the state and measurement predictions. Note that if a given detection has a non-empty timestamp, then prediction will be performed according to the timestamp of the detection.

Returns:

A container of SingleHypothesis objects

Return type:

MultipleHypothesis

Distance

class stonesoup.hypothesiser.distance.DistanceHypothesiser(predictor: Predictor, updater: Updater, measure: Measure, missed_distance: float = inf, include_all: bool = False, predict_with_measurements: bool = False)[source]

Bases: Hypothesiser

Prediction Hypothesiser based on a Measure

Generate track predictions at detection times and score each hypothesised prediction-detection pair using the distance of the supplied Measure class.

Parameters:

predictor (Predictor) – Predict tracks to detection times
updater (Updater) – Updater used to get measurement prediction
measure (Measure) – Measure class used to calculate the distance between two states.
missed_distance (float, optional) – Distance for a missed detection. Default is set to infinity
include_all (bool, optional) – If True, hypotheses beyond missed distance will be returned. Default False
predict_with_measurements (bool, optional) – Whether to pass measurement/detection to the predictor. Default False

predictor: Predictor: Predict tracks to detection times

updater: Updater: Updater used to get measurement prediction

measure: Measure: Measure class used to calculate the distance between two states.

missed_distance: float: Distance for a missed detection. Default is set to infinity

include_all: bool: If True, hypotheses beyond missed distance will be returned. Default False

predict_with_measurements: bool: Whether to pass measurement/detection to the predictor. Default False

hypothesise(track, detections, timestamp, **kwargs)[source]

Evaluate and return all track association hypotheses.

For a given track and a set of N available detections, return a MultipleHypothesis object with N+1 detections (first detection is a ‘MissedDetection’), each with an associated distance measure..

Parameters:

track (Track) – The track object to hypothesise on
detections (set of Detection) – The available detections
timestamp (datetime.datetime) – A timestamp used when evaluating the state and measurement predictions. Note that if a given detection has a non empty timestamp, then prediction will be performed according to the timestamp of the detection.

Returns:

A container of SingleDistanceHypothesis objects

Return type:

MultipleHypothesis

Probability

class stonesoup.hypothesiser.probability.PDAHypothesiser(predictor: Predictor, updater: Updater, clutter_spatial_density: float = None, prob_detect: Probability = Probability(0.85), prob_gate: Probability = Probability(0.95), include_all: bool = False)[source]

Bases: Hypothesiser

Hypothesiser based on Probabilistic Data Association (PDA)

Generate track predictions at detection times and calculate probabilities for all prediction-detection pairs for single prediction and multiple detections.

Parameters:

predictor (Predictor) – Predict tracks to detection times
updater (Updater) – Updater used to get measurement prediction
clutter_spatial_density (float, optional) – Spatial density of clutter - tied to probability of false detection. Default is None where the clutter spatial density is calculated based on assumption that all but one measurement within the validation region of the track are clutter.
prob_detect (Probability, optional) – Target Detection Probability
prob_gate (Probability, optional) – Gate Probability - prob. gate contains true measurement if detected
include_all (bool, optional) – If True, hypotheses outside probability gates will be returned. This requires that the clutter spatial density is also provided, as it may not be possible toestimate this. Default False

predictor: Predictor: Predict tracks to detection times

updater: Updater: Updater used to get measurement prediction

clutter_spatial_density: float: Spatial density of clutter - tied to probability of false detection. Default is None where the clutter spatial density is calculated based on assumption that all but one measurement within the validation region of the track are clutter.

prob_detect: Probability: Target Detection Probability

prob_gate: Probability: Gate Probability - prob. gate contains true measurement if detected

include_all: bool: If True, hypotheses outside probability gates will be returned. This requires that the clutter spatial density is also provided, as it may not be possible toestimate this. Default False

hypothesise(track, detections, timestamp, **kwargs)[source]

Evaluate and return all track association hypotheses.

For a given track and a set of N detections, return a MultipleHypothesis with N+1 detections (first detection is a ‘MissedDetection’), each with an associated probability. Probabilities are assumed to be exhaustive (sum to 1) and mutually exclusive (two detections cannot be the correct association at the same time).

Detection 0: missed detection, none of the detections are associated with the track. Detection \(i, i \in {1...N}\): detection i is associated with the track.

The probabilities for these detections are calculated as follow:

\[\begin{split}\beta_i(k) = \begin{cases} \frac{\mathcal{L}_{i}(k)}{1-P_{D}P_{G}+\sum_{j=1}^{m(k)} \mathcal{L}_{j}(k)}, \quad i=1,...,m(k) \\ \frac{1-P_{D}P_{G}}{1-P_{D}P_{G}+\sum_{j=1}^{m(k)} \mathcal{L}_{j}(k)}, \quad i=0 \end{cases}\end{split}\]

where

\[\mathcal{L}_{i}(k) = \frac{\mathcal{N}[z_{i}(k);\hat{z}(k|k-1), S(k)]P_{D}}{\lambda}\]

\(\lambda\) is the clutter density

\(P_{D}\) is the detection probability

\(P_{G}\) is the gate probability

\(\mathcal{N}[z_{i}(k);\hat{z}(k|k-1),S(k)]\) is the likelihood ratio of the measurement \(z_{i}(k)\) originating from the track target rather than the clutter.

NOTE: Since all probabilities have the same denominator and are normalized later, the denominator can be discarded.

References:

[1] “The Probabilistic Data Association Filter: Estimation in the Presence of Measurement Origin Uncertainty” - https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=5338565

[2] “Robotics 2 Data Association” (Lecture notes) - http://ais.informatik.uni-freiburg.de/teaching/ws11/robotics2/pdfs/rob2-20-dataassociation.pdf

Parameters:

track (Track) – The track object to hypothesise on
detections (set of Detection) – The available detections
timestamp (datetime.datetime) – A timestamp used when evaluating the state and measurement predictions. Note that if a given detection has a non empty timestamp, then prediction will be performed according to the timestamp of the detection.

Returns:

A container of SingleProbabilityHypothesis objects

Return type:

MultipleHypothesis

Gaussian Mixture

class stonesoup.hypothesiser.gaussianmixture.GaussianMixtureHypothesiser(hypothesiser: Hypothesiser, order_by_detection: bool = False)[source]

Bases: Hypothesiser

Gaussian Mixture Prediction Hypothesiser based on an underlying Hypothesiser

Generates a list of MultipleHypothesis, where each MultipleHypothesis in the list contains SingleHypotheses pertaining to an individual component-detection hypothesis

Parameters:

hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
order_by_detection (bool, optional) – Flag to order the MultipleHypothesis list by detection or component

hypothesiser: Hypothesiser: Underlying hypothesiser used to generate detection-target pairs

order_by_detection: bool: Flag to order the MultipleHypothesis list by detection or component

hypothesise(components, detections, timestamp, **kwargs)[source]

Form hypotheses for associations between Detections and Gaussian Mixture components.

Parameters:

components (list of WeightedGaussianState) – Components representing the state of the target space
detections (set of Detection) – Retrieved measurements
timestamp (datetime.datetime) – Time of the detections/predicted states

Returns:

Each MultipleHypothesis in the list contains a list of SingleHypothesis pertaining to the same Gaussian component unless order_by_detection is true, then they pertain to the same Detection.

Return type:

list of MultipleHypothesis

class stonesoup.hypothesiser.gaussianmixture.GaussianMixtureKDTreeHypothesiser(hypothesiser: Hypothesiser, predictor: Predictor, updater: Updater, order_by_detection: bool = False, number_of_neighbours: int = None, max_distance: float = inf, max_distance_covariance_multiplier: float = None)[source]

Bases: DetectionKDTreeMixIn, GaussianMixtureHypothesiser

Parameters:

hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
predictor (Predictor) – Predict tracks to detection times
updater (Updater) – Updater used to get measurement prediction
order_by_detection (bool, optional) – Flag to order the MultipleHypothesis list by detection or component
number_of_neighbours (int, optional) – Number of neighbours to find. Default None, which means all points within the max_distance are returned.
max_distance (float, optional) – Max distance to return points. Default inf
max_distance_covariance_multiplier (float, optional) – If set, the max distance will be limited to maximum of covariance diagonal of the track state, multiplied by this attribute, or max_distance, whichever is smallest. Default None where only max_distance is used.

Categorical

class stonesoup.hypothesiser.categorical.HMMHypothesiser(predictor: HMMPredictor, updater: HMMUpdater, prob_detect: Probability = Probability(0.99), prob_gate: Probability = Probability(0.95))[source]

Bases: Hypothesiser

Hypothesiser based on categorical distribution accuracy.

This hypothesiser generates track predictions at detection times and scores each hypothesised prediction-detection pair according to the accuracy of the corresponding measurement prediction compared to the detection.

Parameters:

predictor (HMMPredictor) – Predictor used to predict tracks to detection times
updater (HMMUpdater) – Updater used to get measurement prediction
prob_detect (Probability, optional) – Target Detection Probability
prob_gate (Probability, optional) – Gate Probability - prob. gate contains true measurement if detected

predictor: HMMPredictor: Predictor used to predict tracks to detection times

updater: HMMUpdater: Updater used to get measurement prediction

prob_detect: Probability: Target Detection Probability

prob_gate: Probability: Gate Probability - prob. gate contains true measurement if detected

hypothesise(track, detections, timestamp, **kwargs)[source]

Evaluate and return all track association hypotheses.

For a given track and a set of N available detections, return a MultipleHypothesis object with N+1 detections (first detection is a ‘MissedDetection’), each with an associated accuracy (of prediction emission to measurement), considered the probability of the hypothesis being true.

Parameters:

track (Track) – The track object to hypothesise on. Composed of CategoricalState types.
detections (set) – A set of CategoricalDetection objects, representing the available detections.
timestamp (datetime.datetime) – A timestamp used when evaluating the state and measurement predictions. Note that if a given detection has a non empty timestamp, then prediction will be performed according to the timestamp of the detection.

Returns:

A container of SingleProbabilityHypothesis objects

Return type:

MultipleHypothesis

Composite

class stonesoup.hypothesiser.composite.CompositeHypothesiser(sub_hypothesisers: Sequence[Hypothesiser])[source]

Bases: Hypothesiser

Composite hypothesiser type

A composition of ordered sub-hyposisers (Hypothesiser). Hypothesises each sub-state of a track-detection pair using a corresponding sub-hypothesiser.

Parameters:: sub_hypothesisers (Sequence[Hypothesiser]) – Sequence of sub-hypothesisers comprising the composite hypothesiser. Must not be empty. These must be hypothesisers that return probability-weighted hypotheses, in order for composite hypothesis weights to be calculated.

sub_hypothesisers: Sequence[Hypothesiser]: Sequence of sub-hypothesisers comprising the composite hypothesiser. Must not be empty. These must be hypothesisers that return probability-weighted hypotheses, in order for composite hypothesis weights to be calculated.

hypothesise(track, detections, timestamp)[source]

Evaluate and return all track association hypotheses.

For a given track and a set of N available detections, return a MultipleHypothesis object composed of N+1 CompositeProbabilityHypothesis (including a null hypothesis), each with an associated probability.

Parameters:

track (Track) – The track object to hypothesise on, existing in a composite state space
detections (set) – A set of CompositeDetection objects, representing the available detections.
timestamp (datetime.datetime) – A timestamp used when evaluating the state and measurement predictions. Note that if a given detection has a non empty timestamp, then prediction will be performed according to the timestamp of the detection.

Returns:

A container of CompositeHypothesis objects, each of which containing a sequence of SingleHypothesis objects

Return type:

MultipleHypothesis

Multi-Frame Assignment

class stonesoup.hypothesiser.mfa.MFAHypothesiser(hypothesiser: Hypothesiser)[source]

Bases: Hypothesiser

Multi-Frame Assignment Hypothesiser based on an underlying Hypothesiser

Generates a list of SingleHypotheses pertaining to individual component-detection hypotheses

Note

This is to be used in conjunction with the MFADataAssociator

References

Xia, Y., Granström, K., Svensson, L., García-Fernández, Á.F., and Williams, J.L., 2019. Multiscan Implementation of the Trajectory Poisson Multi-Bernoulli Mixture Filter. J. Adv. Information Fusion, 14(2), pp. 213–235.

Parameters:: hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs

hypothesiser: Hypothesiser: Underlying hypothesiser used to generate detection-target pairs

hypothesise(track, detections, timestamp, detections_tuple, **kwargs)[source]

Form hypotheses for associations between Detections and a given track.

Parameters:

track (Track) – The track object to hypothesise on
detections (set of Detection) – Retrieved measurements
timestamp (datetime) – Time of the detections/predicted states
detections_tuple (tuple of Detection) – Original tuple of detections required for consistent indexing

Returns:

A container of SingleProbabilityHypothesis objects, pertaining to individual component-detection hypotheses

Return type:

MultipleHypothesis