Data Association

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

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

abstractmethod associate(tracks: set[Track], detections: set[Detection], timestamp: datetime, **kwargs) → Mapping[Track, 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: Base

Associator base class

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

class stonesoup.dataassociator.base.TrackToTrackAssociator

Bases: Associator

Associates n sets of Track objects together

abstractmethod associate_tracks(*tracks_sets: set[Track]) → AssociationSet

Associate n sets of tracks together.

Parameters:

tracks_sets (n sets of Track objects) – Tracks to associate to other track sets

Returns:

Contains a set of Association objects

Return type:

AssociationSet

associated_and_unassociated_tracks(*tracks_sets: set[Track]) → tuple[AssociationSet, tuple[set[Track]]]

Associate n sets of tracks together. The unassociated tracks are returned with

the associated tracks.

Parameters:

tracks_sets (n sets of Track objects) – Tracks to associate to other track sets

Returns:

• AssociationSet – Contains a set of Association objects

• Tuple – n sets of tracks (that were input variables) minus any associated tracks

class stonesoup.dataassociator.base.TwoTrackToTrackAssociator

Bases: TrackToTrackAssociator

Associates two sets of Track objects together

abstractmethod associate_tracks(tracks_set_1: set[Track], tracks_set_2: set[Track]) → AssociationSet

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

General Association

class stonesoup.dataassociator.general.OneToOneAssociator(measure: BaseMeasure, association_threshold: float = None, maximise_measure: bool = False)

Bases: Associator

This a general one to one associator. It can be used to associate objects/values that have a BaseMeasure to compare them. Uses linear_sum_assignment() to find the minimum (or maximum) measure by combination objects from two sources.

Notes

As default the association threshold is set to +- a large number (1e10 was chosen arbitrarily). Infinity can’t be used, as it breaks the association algorithm.

Parameters:

• measure (BaseMeasure) – This will compare two objects that could be associated together and will provide an indication of the separation between the objects.

• association_threshold (float, optional) – The maximum (minimum if maximise_measure is true) value from the measure needed to associate two objects. If the default value of None is used then the association threshold is set to plus/minus an arbitrarily large number that shouldn’t limit associations.

• maximise_measure (bool, optional) – Should the association algorithm attempt to maximise or minimise the output of the measure.

measure: BaseMeasure

This will compare two objects that could be associated together and will provide an indication of the separation between the objects.

maximise_measure: bool

Should the association algorithm attempt to maximise or minimise the output of the measure.

association_threshold: float

The maximum (minimum if maximise_measure is true) value from the measure needed to associate two objects. If the default value of None is used then the association threshold is set to plus/minus an arbitrarily large number that shouldn’t limit associations.

associate(objects_a: Collection, objects_b: Collection) → tuple[AssociationSet, Collection, Collection]

Associate two collections of objects together. Calculate the measure between each object. linear_sum_assignment() is used to find the minimum (or maximum) measure by combination objects from two sources.

Parameters:

• objects_a (collection of objects to associate to the objects in objects_b)

• objects_b (collection of objects to associate to the objects in objects_a)

Returns:

Contains a set of Association objects

Return type:

AssociationSet

property fail_value

For an association to be valid is must be over (or under if maximise_measure is True) (non-inclusive). Therefore, setting the value to the association threshold will result in the association not taking place.

individual_weighting(a, b)

This wrapper around the measure function allows for filtering/error checking of the measure function. It can give an easy access point for subclasses that want to apply additional filtering or gating.

association_dict(objects_a: Collection, objects_b: Collection) → dict

This is a wrapper function around the associate() function. The two collections of objects are associated to each other. The objects are entered into a dictionary:

• The dictionary key is an object from either collection.

• The value is the object it is associated to. If the key object isn’t associated to an object then the value is None.

As the objects are used as dictionary keys, they must be hashable or a TypeError will be raised.

Parameters:

• objects_a (collection of hashable objects to associate to the objects in objects_b)

• objects_b (collection of hashable objects to associate to the objects in objects_a)

Returns:

Contains a set of Association objects

Return type:

AssociationSet

Neighbour

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

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)

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

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

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

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

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.JPDAwithLBP(hypothesiser: PDAHypothesiser)

Bases: JPDA

Joint Probabilistic Data Association with Loopy Belief Propagation

This is a faster alternative of the standard JPDA algorithm, which makes use of Loopy Belief Propagation (LBP) to efficiently approximately compute the marginal association probabilities of tracks to measurements. See Williams and Lau (2014) for further details.

Reference

Jason L. Williams and Rosalyn A. Lau, Approximate evaluation of marginal association probabilities with belief propagation, IEEE Transactions on Aerospace and Electronic Systems, vol 50(4), pp. 2942-2959, 2014.

param hypothesiser:

Generate a set of hypotheses for each prediction-detection pair

type hypothesiser:

PDAHypothesiser

associate(tracks, detections, timestamp, **kwargs)

Associate tracks and detections

Parameters:

• tracks (set of stonesoup.types.track.Track) – Tracks which detections will be associated to.

• detections (set of stonesoup.types.detection.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 stonesoup.types.track.Track : stonesoup.types.hypothesis.Hypothesis

class stonesoup.dataassociator.probability.JPDAwithEHM(hypothesiser: PDAHypothesiser)

Bases: JPDA

Joint Probabilistic Data Association with Efficient Hypothesis Management (EHM)

This is a faster alternative of the standard JPDA algorithm, which makes use of Efficient Hypothesis Management (EHM) to compute the exact marginal association probabilities of tracks to measurements. See [2] for further details.

References

[2]

S. Maskell, M. Briers, and R. Wright. “Fast mutual exclusion.” Signal and Data Processing of Small Targets 2004. Vol. 5428. SPIE, 2004.

Parameters:

hypothesiser (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

class stonesoup.dataassociator.probability.JPDAwithEHM2(hypothesiser: PDAHypothesiser)

Bases: JPDAwithEHM

Joint Probabilistic Data Association with Efficient Hypothesis Management 2 (EHM2)

This is a faster alternative of the standard JPDA algorithm, which makes use of Efficient Hypothesis Management 2 (EHM2) to compute the exact marginal association probabilities of tracks to measurements. EHM2 takes advantage of conditional independence of track-measurement pairs to achieve better computational performance than EHM in certain scenarios. See [3] for further details.

References

[3]

P. Horridge and S. Maskell, “Real-Time Tracking Of Hundreds Of Targets With Efficient Exact JPDAF Implementation,” 2006 9th International Conference on Information Fusion, Florence, Italy, 2006, pp. 1-8

Parameters:

hypothesiser (PDAHypothesiser) – Generate a set of hypotheses for each prediction-detection pair

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, one_to_one: bool = False)

Bases: TwoTrackToTrackAssociator

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

• one_to_one (bool, optional) – If True, it is ensured no two associations ever contain the same track at the same time

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

one_to_one: bool

If True, it is ensured no two associations ever contain the same track at the same time

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

Bases: TwoTrackToTrackAssociator

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 two State objects 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])

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

Track ID based associator

Compares a set of Track objects to a set of GroundTruth objects, each formed of a sequence of State objects and returns an Association object for each time at which two State objects 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

class stonesoup.dataassociator.tracktotrack.OneToOneTrackAssociator(measure: TrackMeasure, association_threshold: float = None, maximise_measure: bool = False)

Bases: TwoTrackToTrackAssociator, OneToOneAssociator

Uses the OneToOneAssociator to associate tracks together

Parameters:

• measure (TrackMeasure)

• association_threshold (float, optional) – The maximum (minimum if maximise_measure is true) value from the measure needed to associate two objects. If the default value of None is used then the association threshold is set to plus/minus an arbitrarily large number that shouldn’t limit associations.

• maximise_measure (bool, optional) – Should the association algorithm attempt to maximise or minimise the output of the measure.

measure: TrackMeasure

associate_tracks(*tracks_sets: set[Track]) → AssociationSet

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

CLEAR MOT Association

class stonesoup.dataassociator.clearmot.ClearMotAssociator(association_threshold: float, measure: Measure = Euclidean(mapping=None, mapping2=None))

Bases: TwoTrackToTrackAssociator

Track to truth associator used in the CLEAR MOT metrics paper[1].

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. A track keeps its association with the truth from previous timestep,even if there is a new track which is closer to the truth. Unassigned tracks and truths are matched using Munkres algorithm if they are below the specified distance threshold.

Note

A track can only be associated with one Truth (one-2-one relationship) at a given time step and vice versa.

Reference

[1] Evaluating Multiple Object Tracking Performance: The CLEAR MOT Metrics,

Bernardin et al, 2008

Parameters:

• association_threshold (float) – Threshold distance measure which states must be within for an association to be recorded

• 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

measure: Measure

Distance measure to use. Default Euclidean()

associate_tracks(tracks_set: set[Track], truth_set: set[GroundTruthPath]) → AssociationSet

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

stonesoup.dataassociator.clearmot.get_strictly_monotonously_increasing_intervals(arr: MutableSequence[int]) → list[tuple[int, int]]

Return (start <= t < end) index intervals where array elements are increasing by 1.

Args:

timesteps (MutableSequence[int]): array

Returns:

list[tuple[int, int]]: intervals with indices, where

array elements are increasing monotonically by 1

stonesoup.dataassociator.clearmot.pairwise(iterable: Iterable[Any]) → Generator[Any, None, None]

pairwise(‘ABCDEFG’) → AB BC CD DE EF FG

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)

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)

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 (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping

• vel_mapping (collections.abc.Sequence, 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

class stonesoup.dataassociator.tree.DetectionKDTreeNN(hypothesiser: Hypothesiser, predictor: Predictor, updater: Updater, number_of_neighbours: int = None, max_distance: float = inf, max_distance_covariance_multiplier: float = None)

Bases: DetectionKDTreeMixIn, NearestNeighbour

DetectionKDTreeNN from NearestNeighbour and DetectionKDTreeMixIn

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.

class stonesoup.dataassociator.tree.DetectionKDTreeGNN(hypothesiser: Hypothesiser, predictor: Predictor, updater: Updater, number_of_neighbours: int = None, max_distance: float = inf, max_distance_covariance_multiplier: float = None)

Bases: DetectionKDTreeMixIn, GlobalNearestNeighbour

DetectionKDTreeGNN from GlobalNearestNeighbour and DetectionKDTreeMixIn

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.

class stonesoup.dataassociator.tree.DetectionKDTreeGNN2D(hypothesiser: Hypothesiser, predictor: Predictor, updater: Updater, number_of_neighbours: int = None, max_distance: float = inf, max_distance_covariance_multiplier: float = None)

Bases: DetectionKDTreeMixIn, GNNWith2DAssignment

DetectionKDTreeGNN2D from GNNWith2DAssignment and DetectionKDTreeMixIn

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.

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

Bases: TPRTreeMixIn, NearestNeighbour

TPRTreeNN from NearestNeighbour and TPRTreeMixIn

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 (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping

• vel_mapping (collections.abc.Sequence, optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each

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

Bases: TPRTreeMixIn, GlobalNearestNeighbour

TPRTreeGNN from GlobalNearestNeighbour and TPRTreeMixIn

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 (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping

• vel_mapping (collections.abc.Sequence, optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each

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

Bases: TPRTreeMixIn, GNNWith2DAssignment

TPRTreeGNN2D from GNNWith2DAssignment and TPRTreeMixIn

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 (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping

• vel_mapping (collections.abc.Sequence, optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each

class stonesoup.dataassociator.tree.KDTreePDA(hypothesiser: Hypothesiser, predictor: Predictor, updater: Updater, number_of_neighbours: int = None, max_distance: float = inf, max_distance_covariance_multiplier: float = None)

Bases: DetectionKDTreeMixIn, PDA

KDTreePDA from PDA and DetectionKDTreeMixin

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.

class stonesoup.dataassociator.tree.KDTreeJPDA(hypothesiser: Hypothesiser, predictor: Predictor, updater: Updater, number_of_neighbours: int = None, max_distance: float = inf, max_distance_covariance_multiplier: float = None)

Bases: DetectionKDTreeMixIn, JPDA

KDTreeJPDA from JPDA and DetectionKDTreeMixin

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.

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

Bases: TPRTreeMixIn, PDA

TPRTreePDA from PDA and TPRTreeMixIn

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 (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping

• vel_mapping (collections.abc.Sequence, optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each

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

Bases: TPRTreeMixIn, JPDA

TPRTreeJPDA from JPDA and TPRTreeMixIn

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 (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping

• vel_mapping (collections.abc.Sequence, optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each

Multi-Frame Assignment

class stonesoup.dataassociator.mfa.MFADataAssociator(hypothesiser: MFAHypothesiser, slide_window: int)

Bases: DataAssociator

Data associator using multi-frame assignment algorithm over a sliding window.

References

1. 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 (MFAHypothesiser) – Generate a set of hypotheses for each prediction-detection pair

• slide_window (int) – Length of MFA slide window

hypothesiser: MFAHypothesiser

Generate a set of hypotheses for each prediction-detection pair

slide_window: int

Length of MFA slide window

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