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

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/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]

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