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)[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

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

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

  1. 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