Data Association

class stonesoup.dataassociator.base.DataAssociator(hypothesiser: Hypothesiser)[source]

Bases: 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: Hypothesiser: Generate a set of hypotheses for each track-detection pair

abstract associate(tracks: Set[Track], detections: Set[Detection], timestamp: datetime, **kwargs) → Mapping[Track, Hypothesis][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 and to predict to.

Returns

Mapping of track to Hypothesis

Return type

mapping of Track : Hypothesis

class stonesoup.dataassociator.base.Associator[source]

Bases: Base

Associator base class

An associator is used to associate objects for the generation of metrics. It returns a AssociationSet containing a set of Association objects.

class stonesoup.dataassociator.base.TrackToTrackAssociator[source]

Bases: Associator

Associates two sets of Track objects together

Neighbour

class stonesoup.dataassociator.neighbour.NearestNeighbour(hypothesiser: Hypothesiser)[source]

Bases: 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: Hypothesiser: Generate a set of hypotheses for each prediction-detection pair

associate(tracks, detections, timestamp, **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 and to predict to.

Returns

Mapping of track to Hypothesis

Return type

mapping of Track : Hypothesis

class stonesoup.dataassociator.neighbour.GlobalNearestNeighbour(hypothesiser: Hypothesiser)[source]

Bases: 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: Hypothesiser: Generate a set of hypotheses for each prediction-detection pair

associate(tracks, detections, timestamp, **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 and to predict to.

Returns

Mapping of track to Hypothesis

Return type

mapping of Track : Hypothesis

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

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 (dict of Track: 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: Hypothesiser)[source]

Bases: 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: Hypothesiser: Generate a set of hypotheses for each prediction-detection pair

associate(tracks, detections, timestamp, **kwargs)[source]

Associate a set of detections with predicted states.

Parameters

tracks (set of Track) – Current tracked objects
detections (set of Detection) – Retrieved measurements
timestamp (datetime.datetime) – Detection time to predict to

Returns

Key value pair of tracks with associated detection

Return type

dict

Probability

class stonesoup.dataassociator.probability.PDA(hypothesiser: Hypothesiser)[source]

Bases: 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: Hypothesiser: Generate a set of hypotheses for each prediction-detection pair

associate(tracks, detections, timestamp, **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 and to predict to.

Returns

Mapping of track to Hypothesis

Return type

mapping of Track : Hypothesis

class stonesoup.dataassociator.probability.JPDA(hypothesiser: PDAHypothesiser)[source]

Bases: 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: PDAHypothesiser: Generate a set of hypotheses for each prediction-detection pair

associate(tracks, detections, timestamp, **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 and to predict to.

Returns

Mapping of track to Hypothesis

Return type

mapping of Track : Hypothesis

Track-to-track Association

class stonesoup.dataassociator.tracktotrack.TrackToTrackCounting(association_threshold: float, consec_pairs_confirm: int = 3, consec_misses_end: int = 2, measure: Measure = None, pos_map: list = None, use_positional_only: bool = True, position_weighting: float = 0.6)[source]

Bases: TrackToTrackAssociator

Track to track associator based on the Counting Technique

Compares two sets of tracks, each formed of a sequence of State objects and returns an Association object for each time at which the two State within the tracks are assessed to be associated.

Uses an algorithm called the Counting Technique 1. 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 two State are separated by a distance greater than the threshold at the next time step.

References

1: J. Å. Sagild, A. Gullikstad Hem and E. F. Brekke, “Counting Technique versus Single-Time Test for Track-to-Track Association,” 2021 IEEE 24th International Conference on Information Fusion (FUSION), 2021, pp. 1-7

Note

Association is not prioritised based on historic associations or distance. If, at a specific time step, the State of one of the tracks is assessed as close to more than one track then an Association object will be return for all possible association combinations.

Parameters

association_threshold (float) – Threshold distance measure which states must be within for an association to be recorded
consec_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 3
consec_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 2
measure (Measure, optional) – Distance measure to use. Must use EuclideanWeighted() if use_positional_only set to True. Default is EuclideanWeighted() using use_positional_only and pos_map. Note if neither are provided this is equivalent to a standard Euclidean
pos_map (list, optional) – List of items specifying the mapping of the position components of the state space for tracks_set_1. Defaults to whole StateVector(), but must be provided whenever use_positional_only is set to True
use_positional_only (bool, optional) – If True, the differences in velocity/acceleration values for each state are ignored in the calculation for the association threshold. Default is True
position_weighting (float, optional) – If use_positional_only is set to False, this decides how much to weight position components compared to others (such as velocity). Default is 0.6

association_threshold: float: Threshold distance measure which states must be within for an association to be recorded

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: Measure: Distance measure to use. Must use EuclideanWeighted() if use_positional_only set to True. Default is EuclideanWeighted() using use_positional_only and pos_map. Note if neither are provided this is equivalent to a standard Euclidean

pos_map: list: List of items specifying the mapping of the position components of the state space for tracks_set_1. Defaults to whole StateVector(), but must be provided whenever use_positional_only is set to True

use_positional_only: bool: If True, the differences in velocity/acceleration values for each state are ignored in the calculation for the association threshold. Default is True

position_weighting: float: If use_positional_only is set to False, this decides how much to weight position components compared to others (such as velocity). Default is 0.6

associate_tracks(tracks_set_1: Set[Track], tracks_set_2: Set[Track])[source]

Associate two sets of tracks together.

Parameters

tracks_set_1 (set of Track objects) – Tracks to associate to track set 2
tracks_set_2 (set of Track objects) – Tracks to associate to track set 1

Returns

Contains a set of Association objects

Return type

AssociationSet

class stonesoup.dataassociator.tracktotrack.TrackToTruth(association_threshold: float, consec_pairs_confirm: int = 3, consec_misses_end: int = 2, measure: Measure = Euclidean(mapping=None, mapping2=None))[source]

Bases: TrackToTrackAssociator

Track to truth associator

Compares two sets of Track, each formed of a sequence of State objects and returns an Association object for each time at which a the two State within the Track are assessed to be associated. Tracks are considered to be associated with the Truth if the true State 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) – Threshold distance measure which states must be within for an association to be recorded
consec_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 3
consec_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 2
measure (Measure, optional) – Distance measure to use. Default Euclidean()

association_threshold: float: Threshold distance measure which states must be within for an association to be recorded

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: Measure: Distance measure to use. Default Euclidean()

associate_tracks(tracks_set: Set[Track], truth_set: Set[GroundTruthPath])[source]

Associate Tracks

Method compares to sets of Track objects and will determine associations between the two sets.

Parameters

tracks_set (set of Track objects) – Tracks to associate to truth
truth_set (set of GroundTruthPath objects) – Truth to associate to tracks

Returns

Contains a set of Association objects

Return type

AssociationSet

class stonesoup.dataassociator.tracktotrack.TrackIDbased[source]

Bases: TrackToTrackAssociator

Track ID based associator

Compares set of Track objects to set of GroundTruth objects, each formed of a sequence of State objects and returns an Association object for each time at which a the two State within the Track and GroundTruthPath 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 set
truths_set (list of GroundTruthPath objects) – Ground truths to associate to tracks set

Returns

Contains a set of Association objects

Return type

AssociationSet

Trees

class stonesoup.dataassociator.tree.DetectionKDTreeMixIn(hypothesiser: Hypothesiser, predictor: Predictor, updater: Updater, number_of_neighbours: int = None, max_distance: float = inf, max_distance_covariance_multiplier: float = None)[source]

Bases: Base

Detection kd-tree based mixin

Construct a kd-tree from detections and then use a Predictor and Updater to get prediction of track in measurement space. This is then queried against the kd-tree, and only matching detections are passed to the hypothesiser.

Notes

This is only suitable where measurements are in same space as each other (i.e. have the same measurement model) and at the same timestamp.

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

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

number_of_neighbours: int: Number of neighbours to find. Default None, which means all points within the max_distance are returned.

max_distance: float: Max distance to return points. Default inf

max_distance_covariance_multiplier: float: 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.

class stonesoup.dataassociator.tree.TPRTreeMixIn(hypothesiser: Hypothesiser, measurement_model: MeasurementModel, horizon_time: timedelta, pos_mapping: Sequence[int] = None, vel_mapping: Sequence[int] = None)[source]

Bases: Base

Detection TPR tree based mixin

Construct a TPR-tree to filter detections for generating hypotheses. This assumes tracks move in constant velocity like model, using the mean and covariance to define region to look for detections.

Notes

This requires that track state has a mean (position and velocity) and covariance, which is then approximated to a TPR node (position, velocity and time bounding box).

Parameters

hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
measurement_model (MeasurementModel) – Measurement model used within the TPR tree
horizon_time (datetime.timedelta) – How far the TPR tree should look into the future
pos_mapping (Sequence[int], optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping
vel_mapping (Sequence[int], optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each

hypothesiser: Hypothesiser: Underlying hypothesiser used to generate detection-target pairs

measurement_model: MeasurementModel: Measurement model used within the TPR tree

horizon_time: timedelta: How far the TPR tree should look into the future

pos_mapping: Sequence[int]: Mapping for position coordinates. Default None, which uses the measurement modelmapping

vel_mapping: Sequence[int]: Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each