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