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 timesupdater (
Updater
, optional) – Updater used to get measurement prediction. Only required if predict_measurement is True. Default is Nonecheck_timestamp (
bool
, optional) – Check that all detections have the same timestamp. Default is Truepredict_measurement (
bool
, optional) – Predict measurement for each detection. Default is True
- updater: Updater
Updater used to get measurement prediction. Only required if predict_measurement is True. Default is None
- 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 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
SingleHypothesis
objects- Return type:
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 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 Falsepredict_with_measurements (
bool
, optional) – Whether to pass measurement/detection to the predictor. 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 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 = 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 timesupdater (
Updater
) – Updater used to get measurement predictionclutter_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 Probabilityprob_gate (
Probability
, optional) – Gate Probability - prob. gate contains true measurement if detectedinclude_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
- 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 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:
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: 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
- 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 pairspredictor (
Predictor
) – Predict tracks to detection timesupdater (
Updater
) – Updater used to get measurement predictionorder_by_detection (
bool
, optional) – Flag to order theMultipleHypothesis
list by detection or componentnumber_of_neighbours (
int
, optional) – Number of neighbours to find. Default None, which means all points within themax_distance
are returned.max_distance (
float
, optional) – Max distance to return points. Default infmax_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, ormax_distance
, whichever is smallest. Default None where onlymax_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 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: 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 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:
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 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:
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:
- Returns:
A container of
SingleProbabilityHypothesis
objects, pertaining to individual component-detection hypotheses- Return type: