Data Association¶
-
class
stonesoup.dataassociator.base.
DataAssociator
(hypothesiser)[source]¶ Bases:
stonesoup.base.Base
Data Associator base class
A data associator is used to associate tracks and detections, and may also include an association of a missed detection. The associations generate are in the form a mapping each track to a hypothesis, based on “best” choice from hypotheses generate from a
Hypothesiser
.- Parameters
hypothesiser (
Hypothesiser
) – Generate a set of hypotheses for each track-detection pair
-
hypothesiser
: stonesoup.hypothesiser.base.Hypothesiser¶ Generate a set of hypotheses for each track-detection pair
-
abstract
associate
(tracks, detections, timestamp=None, **kwargs)[source]¶ Associate tracks and detections
- Parameters
tracks (set of
Track
) – Tracks which detections will be associated to.detections (set of
Detection
) – Detections to be associated to tracks.timestamp (datetime.datetime) – Timestamp to be used for missed detections.
- Returns
Mapping of track to Hypothesis
- Return type
mapping of
Track
:Hypothesis
-
class
stonesoup.dataassociator.base.
Associator
[source]¶ Bases:
stonesoup.base.Base
Associator base class
An associator is used to associate objects for the generation of metrics. It returns a
AssociationSet
containing a set ofAssociation
objects.
-
class
stonesoup.dataassociator.base.
TrackToTrackAssociator
[source]¶ Bases:
stonesoup.dataassociator.base.Associator
Associates two sets of
Track
objects together
Neighbour¶
-
class
stonesoup.dataassociator.neighbour.
NearestNeighbour
(hypothesiser)[source]¶ Bases:
stonesoup.dataassociator.base.DataAssociator
Nearest Neighbour Associator
Scores and associates detections to a predicted state using the Nearest Neighbour method.
- Parameters
hypothesiser (
Hypothesiser
) – Generate a set of hypotheses for each prediction-detection pair
-
hypothesiser
: stonesoup.hypothesiser.base.Hypothesiser¶ Generate a set of hypotheses for each prediction-detection pair
-
associate
(tracks, detections, timestamp)[source]¶ Associate detections with predicted states.
- Parameters
tracks (list of
Track
) – Current tracked objectsdetections (list of
Detection
) – Retrieved measurementstimestamp (datetime.datetime) – Detection time to predict to
- Returns
Key value pair of tracks with associated detection
- Return type
-
class
stonesoup.dataassociator.neighbour.
GlobalNearestNeighbour
(hypothesiser)[source]¶ Bases:
stonesoup.dataassociator.base.DataAssociator
Global Nearest Neighbour Associator
Scores and associates detections to a predicted state using the Global Nearest Neighbour method, assuming a distance-based hypothesis score.
- Parameters
hypothesiser (
Hypothesiser
) – Generate a set of hypotheses for each prediction-detection pair
-
hypothesiser
: stonesoup.hypothesiser.base.Hypothesiser¶ Generate a set of hypotheses for each prediction-detection pair
-
associate
(tracks, detections, timestamp)[source]¶ Associate a set of detections with predicted states.
- Parameters
tracks (list of
Track
) – Current tracked objectsdetections (list of
Detection
) – Retrieved measurementstimestamp (datetime.datetime) – Detection time to predict to
- Returns
Key value pair of tracks with associated detection
- Return type
-
static
isvalid
(joint_hypothesis)[source]¶ Determine whether a joint_hypothesis is valid.
Check the set of hypotheses that define a joint hypothesis to ensure a single detection is not associated to more than one track.
- Parameters
joint_hypothesis (
JointHypothesis
) – A set of hypotheses linking each prediction to a single detection- Returns
Whether joint_hypothesis is a valid set of hypotheses
- Return type
-
classmethod
enumerate_joint_hypotheses
(hypotheses)[source]¶ Enumerate the possible joint hypotheses.
Create a list of all possible joint hypotheses from the individual hypotheses and determine whether each is valid.
- Parameters
hypotheses (list of
Hypothesis
) – A list of all hypotheses linking predictions to detections, including missed detections- Returns
joint_hypotheses – A list of all valid joint hypotheses with a score on each
- Return type
list of
JointHypothesis
-
class
stonesoup.dataassociator.neighbour.
GNNWith2DAssignment
(hypothesiser)[source]¶ Bases:
stonesoup.dataassociator.base.DataAssociator
Global Nearest Neighbour Associator
Associates detections to a predicted state using the Global Nearest Neighbour method, utilising a 2D matrix of distances and a “shortest path” assignment algorithm.
- Parameters
hypothesiser (
Hypothesiser
) – Generate a set of hypotheses for each prediction-detection pair
-
hypothesiser
: stonesoup.hypothesiser.base.Hypothesiser¶ Generate a set of hypotheses for each prediction-detection pair
-
associate
(tracks, detections, timestamp)[source]¶ Associate a set of detections with predicted states.
- Parameters
tracks (set of
Track
) – Current tracked objectsdetections (set of
Detection
) – Retrieved measurementstimestamp (datetime.datetime) – Detection time to predict to
- Returns
Key value pair of tracks with associated detection
- Return type
Probability¶
-
class
stonesoup.dataassociator.probability.
PDA
(hypothesiser)[source]¶ Bases:
stonesoup.dataassociator.base.DataAssociator
Probabilistic Data Association (PDA)
Given a set of detections and a set of tracks, each track has a probability that it is associated to each specific detection.
- Parameters
hypothesiser (
Hypothesiser
) – Generate a set of hypotheses for each prediction-detection pair
-
hypothesiser
: stonesoup.hypothesiser.base.Hypothesiser¶ Generate a set of hypotheses for each prediction-detection pair
-
associate
(tracks, detections, timestamp)[source]¶ Associate detections with predicted states.
- Parameters
tracks (list of
Track
) – Current tracked objectsdetections (list of
Detection
) – Retrieved measurementstimestamp (datetime.datetime) – Detection time to predict to
- Returns
Key value pair of tracks with associated detection
- Return type
-
class
stonesoup.dataassociator.probability.
JPDA
(hypothesiser)[source]¶ Bases:
stonesoup.dataassociator.base.DataAssociator
Joint Probabilistic Data Association (JPDA)
Given a set of Detections and a set of Tracks, each Detection has a probability that it is associated with each specific Track. Rather than associate specific Detections/Tracks, JPDA calculates the new state of a Track based on its possible association with ALL Detections. The new state is a Gaussian Mixture, reduced to a single Gaussian. If
\[prob_{association(Detection, Track)} < \frac{prob_{association(MissedDetection, Track)}}{gate\ ratio}\]then Detection is assumed to be outside Track’s gate, and the probability of association is dropped from the Gaussian Mixture. This calculation takes place in the function
enumerate_JPDA_hypotheses()
.- Parameters
hypothesiser (
PDAHypothesiser
) – Generate a set of hypotheses for each prediction-detection pair
-
hypothesiser
: stonesoup.hypothesiser.probability.PDAHypothesiser¶ Generate a set of hypotheses for each prediction-detection pair
-
associate
(tracks, detections, timestamp)[source]¶ Associate detections with predicted states.
- Parameters
tracks (list of
Track
) – Current tracked objectsdetections (list of
Detection
) – Retrieved measurementstimestamp (datetime.datetime) – Detection time to predict to
- Returns
Key value pair of tracks with associated detection
- Return type
Track-to-track Association¶
-
class
stonesoup.dataassociator.tracktotrack.
TrackToTrack
(association_threshold=10, consec_pairs_confirm=3, consec_misses_end=2, measure=Euclidean(mapping=None))[source]¶ Bases:
stonesoup.dataassociator.base.TrackToTrackAssociator
Track to track associator
Compares two sets of
tracks
, each formed of a sequence ofState
objects and returns anAssociation
object for each time at which a the twoState
within thetracks
are assessed to be associated.Associations are triggered by track states being within a threshold distance for a given number of timestamps. Associations are terminated when either the two
tracks
end or the twoState
are separated by a distance greater than the threshold at the next time step.Note
Association is not prioritised based on historic associations or distance. If, at a specific time step, the
State
of one of thetracks
is assessed as close to more than one track then anAssociation
object will be return for all possible association combinations- Parameters
association_threshold (
float
, optional) – Threshold distance measure which states must be within for an association to be recorded.Default is 10consec_pairs_confirm (
int
, optional) – Number of consecutive time instances which track pairs are required to be within a specified threshold in order for an association to be formed. Default is 3consec_misses_end (
int
, optional) – Number of consecutive time instances which track pairs are required to exceed a specified threshold in order for an association to be ended. Default is 2measure (
Measure
, optional) – Distance measure to use. DefaultEuclidean()
-
association_threshold
: float¶ Threshold distance measure which states must be within for an association to be recorded.Default is 10
-
consec_pairs_confirm
: int¶ Number of consecutive time instances which track pairs are required to be within a specified threshold in order for an association to be formed. Default is 3
-
consec_misses_end
: int¶ Number of consecutive time instances which track pairs are required to exceed a specified threshold in order for an association to be ended. Default is 2
-
measure
: stonesoup.measures.Measure¶ Distance measure to use. Default
Euclidean()
-
associate_tracks
(tracks_set_1, tracks_set_2)[source]¶ Associate two sets of tracks together.
- Parameters
- Returns
Contains a set of
Association
objects- Return type
-
class
stonesoup.dataassociator.tracktotrack.
TrackToTruth
(association_threshold=10, consec_pairs_confirm=3, consec_misses_end=2, measure=Euclidean(mapping=None))[source]¶ Bases:
stonesoup.dataassociator.base.TrackToTrackAssociator
Track to truth associator
Compares two sets of
tracks
, each formed of a sequence ofState
objects and returns anAssociation
object for each time at which a the twoState
within thetracks
are assessed to be associated. Tracks are considered to be associated with the Truth if the trueState
is the closest to the track and within the specified distance for a specified number of time steps.Associations between Truth and Track if the Truth is no longer the ‘closest’ to the track or the distance exceeds the specified threshold for a specified number of consecutive time steps.
Associates will be ended by consec_misses_end before any new associations are considered even if consec_pairs_confirm < consec_misses_end
Note
Tracks can only be associated with one Truth (one-2-one relationship) at a given time step however a Truth track can be associated with multiple Tracks (one-2-many relationship).
- Parameters
association_threshold (
float
, optional) – Threshold distance measure which states must be within for an association to be recorded.Default is 10consec_pairs_confirm (
int
, optional) – Number of consecutive time instances which track-truth pairs are required to be within a specified threshold in order for an association to be formed. Default is 3consec_misses_end (
int
, optional) – Number of consecutive time instances which track-truth pairs are required to exceed a specified threshold in order for an association to be ended. Default is 2measure (
Measure
, optional) – Distance measure to use. DefaultEuclidean()
-
association_threshold
: float¶ Threshold distance measure which states must be within for an association to be recorded.Default is 10
-
consec_pairs_confirm
: int¶ Number of consecutive time instances which track-truth pairs are required to be within a specified threshold in order for an association to be formed. Default is 3
-
consec_misses_end
: int¶ Number of consecutive time instances which track-truth pairs are required to exceed a specified threshold in order for an association to be ended. Default is 2
-
measure
: stonesoup.measures.Measure¶ Distance measure to use. Default
Euclidean()
-
associate_tracks
(tracks_set, truth_set)[source]¶ Associate Tracks
Method compares to sets of
Track
objects and will determine associations between the two sets.- Parameters
- Returns
Contains a set of
Association
objects- Return type
-
class
stonesoup.dataassociator.tracktotrack.
TrackIDbased
[source]¶ Bases:
stonesoup.dataassociator.base.TrackToTrackAssociator
Track ID based associator
Compares set of
Track
objects to set ofGroundTruth
objects, each formed of a sequence ofState
objects and returns anAssociation
object for each time at which a the twoState
within theTrack
andGroundTruthPath
are assessed to be associated. Tracks are considered to be associated with the Ground Truth if the ID of the Track is the same as the ID of the Ground Truth.-
associate_tracks
(tracks_set, truths_set)[source]¶ Associate two sets of tracks together.
- Parameters
tracks_set (list of
Track
objects) – Tracks to associate to ground truths settruths_set (list of
GroundTruthPath
objects) – Ground truths to associate to tracks set
- Returns
Contains a set of
Association
objects- Return type
-