Hypothesiser
- class stonesoup.hypothesiser.base.Hypothesiser[source]
Bases:
stonesoup.base.Base
Hypothesiser base class
Given a track and set of detections, generate hypothesis of association.
- hypothesise(track: Track, detections: Set[Detection], timestamp: datetime.datetime, **kwargs) Sequence[stonesoup.types.hypothesis.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:
stonesoup.hypothesiser.base.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 timesupdater (
Updater
) – Updater used to get measurement predictionmeasure (
Measure
) – Measure class used to calculate the distance between two states.missed_distance (
float
, optional) – Distance for a missed detection. Default is set to infinityinclude_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.
- 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 detectionstimestamp (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
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]
Bases:
stonesoup.hypothesiser.base.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 timesupdater (
Updater
) – Updater used to get measurement predictionclutter_spatial_density (
float
) – Spatial density of clutter - tied to probability of false detectionprob_detect (
Probability
, optional) – Target Detection Probabilityprob_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
- 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 detectionstimestamp (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
Gaussian Mixture
- class stonesoup.hypothesiser.gaussianmixture.GaussianMixtureHypothesiser(hypothesiser: Hypothesiser, order_by_detection: bool = False)[source]
Bases:
stonesoup.hypothesiser.base.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 pairsorder_by_detection (
bool
, optional) – Flag to order theMultipleHypothesis
list by detection or component
- 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
components (list of
WeightedGaussianState
) – Components representing the state of the target spacedetections (set of
Detection
) – Retrieved measurementstimestamp (datetime.datetime) – Time of the detections/predicted states
- Returns
Each
MultipleHypothesis
in the list contains a list ofSingleHypothesis
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]
Bases:
stonesoup.hypothesiser.base.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 timesupdater (
HMMUpdater
) – Updater used to get measurement predictionprob_detect (
Probability
, optional) – Target Detection Probabilityprob_gate (
Probability
, optional) – Gate Probability - prob. gate contains true measurement if detected
- 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
track (
Track
) – The track object to hypothesise on. Composed ofCategoricalState
types.detections (
set
) – A set ofCategoricalDetection
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
Composite
- class stonesoup.hypothesiser.composite.CompositeHypothesiser(sub_hypothesisers: Sequence[Hypothesiser])[source]
Bases:
stonesoup.hypothesiser.base.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[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 spacedetections (
set
) – A set ofCompositeDetection
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 ofSingleHypothesis
objects- Return type