Data Association

class stonesoup.dataassociator.base.DataAssociator(hypothesiser: Hypothesiser)

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: Set[Track], detections: Set[Detection], timestamp: datetime.datetime, **kwargs) → Mapping[stonesoup.types.track.Track, stonesoup.types.hypothesis.Hypothesis]

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

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 of Association objects.

class stonesoup.dataassociator.base.TrackToTrackAssociator

Bases: stonesoup.dataassociator.base.Associator

Associates two sets of Track objects together

Neighbour

class stonesoup.dataassociator.neighbour.NearestNeighbour(hypothesiser: Hypothesiser)

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, **kwargs)

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)

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, **kwargs)

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)

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)

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)

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, **kwargs)

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)

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, **kwargs)

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)

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, **kwargs)

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.TrackToTrack(association_threshold: float = 10, consec_pairs_confirm: int = 3, consec_misses_end: int = 2, measure: Measure = Euclidean(mapping=None, mapping2=None))

Bases: stonesoup.dataassociator.base.TrackToTrackAssociator

Track to track associator

Compares two sets of tracks, each formed of a sequence of State objects and returns an Association object for each time at which a the two State within the tracks 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 two State 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 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, optional) – Threshold distance measure which states must be within for an association to be recorded.Default is 10

• 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. Default Euclidean()

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: Set[Track], tracks_set_2: Set[Track])

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 = 10, consec_pairs_confirm: int = 3, consec_misses_end: int = 2, measure: Measure = Euclidean(mapping=None, mapping2=None))

Bases: stonesoup.dataassociator.base.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, optional) – Threshold distance measure which states must be within for an association to be recorded.Default is 10

• 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.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: Set[Track], truth_set: Set[GroundTruthPath])

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

Bases: stonesoup.dataassociator.base.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)

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)

Bases: stonesoup.dataassociator.base.DataAssociator

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 and at the same timestamp.

Parameters

• hypothesiser (Hypothesiser) – Generate a set of hypotheses for each track-detection pair

• 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

predictor: stonesoup.predictor.base.Predictor

Predict tracks to detection times

updater: stonesoup.updater.base.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

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

Bases: stonesoup.dataassociator.base.DataAssociator

Detection TPR tree based mixin

Construct a TPR-tree.

Parameters

• hypothesiser (Hypothesiser) – Generate a set of hypotheses for each track-detection pair

• 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

measurement_model: stonesoup.models.measurement.base.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]

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