Hypothesiser

class stonesoup.hypothesiser.base.Hypothesiser[source]

Hypothesiser base class

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

hypothesise(track: Track, detections: , timestamp: datetime.datetime, **kwargs) [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

Distance

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

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

predictor: stonesoup.predictor.base.Predictor

Predict tracks to detection times

updater: stonesoup.updater.base.Updater

Updater used to get measurement prediction

measure: stonesoup.measures.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

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, prob_detect: Probability = Probability(0.85), prob_gate: Probability = Probability(0.95))[source]

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) – Spatial density of clutter - tied to probability of false detection

• prob_detect (Probability, optional) – Target Detection Probability

• prob_gate (Probability, optional) – Gate Probability - prob. gate contains true measurement if detected

predictor: stonesoup.predictor.base.Predictor

Predict tracks to detection times

updater: stonesoup.updater.base.Updater

Updater used to get measurement prediction

clutter_spatial_density: float

Spatial density of clutter - tied to probability of false detection

prob_detect: stonesoup.types.numeric.Probability

Target Detection Probability

prob_gate: stonesoup.types.numeric.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 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/ws10/robotics2/pdfs/rob2-15-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]

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: stonesoup.hypothesiser.base.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
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

Categorical

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

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: stonesoup.predictor.categorical.HMMPredictor

Predictor used to predict tracks to detection times

updater: stonesoup.updater.categorical.HMMUpdater

Updater used to get measurement prediction

prob_detect: stonesoup.types.numeric.Probability

Target Detection Probability

prob_gate: stonesoup.types.numeric.Probability

Gate Probability - prob. gate contains true measurement if detected

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 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
Returns

A container of SingleProbabilityHypothesis objects

Return type

MultipleHypothesis

Composite

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

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[stonesoup.hypothesiser.base.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