API Reference

Core API

The core components of PyEHM are the EHM and EHM2 classes, that constitute implementations of the EHM [EHM1] and EHM2 [EHM2] algorithms for data association.

The interfaces of these classes are documented below.

class pyehm.core.EHM

Efficient Hypothesis Management (EHM)

An implementation of the EHM algorithm, as documented in [EHM1].

compute_association_probabilities(net: EHMNet, likelihood_matrix: numpy.ndarray) → numpy.ndarray

Compute the joint association weights, as described in Section 3.3 of [EHM1]

Parameters:

net (EHMNet) – A net object representing the valid joint association hypotheses
likelihood_matrix (numpy.ndarray) – A matrix of shape (num_tracks, num_detections + 1) containing the unnormalised likelihoods for all combinations of tracks and detections. The first column corresponds to the null hypothesis.

Returns:

A matrix of shape (num_tracks, num_detections + 1) containing the normalised association probabilities for all combinations of tracks and detecrtons. The first column corresponds to the null hypothesis.

Return type:

numpy.ndarray

construct_net(validation_matrix: numpy.ndarray) → EHMNet

Construct the EHM net as per Section 3.1 of [EHM1]

Parameters:: validation_matrix (numpy.ndarray) – An indicator matrix of shape (num_tracks, num_detections + 1) indicating the possible (aka. valid) associations between tracks and detections. The first column corresponds to the null hypothesis (hence contains all ones).
Returns:: The constructed net object
Return type:: EHMNet

construct_tree(validation_matrix: numpy.ndarray) → EHMTree

Construct the EHM2 tree as per section 4.3 of [EHM2]

Parameters:: validation_matrix (numpy.ndarray) – An indicator matrix of shape (num_tracks, num_detections + 1) indicating the possible (aka. valid) associations between tracks and detections. The first column corresponds to the null hypothesis (hence contains all ones).
Returns:: The constructed tree object
Return type:: EHMTree

run(validation_matrix: numpy.ndarray, likelihood_matrix: numpy.ndarray) → numpy.ndarray

Run EHM to compute and return association probabilities

Parameters:

validation_matrix (numpy.ndarray) – An indicator matrix of shape (num_tracks, num_detections + 1) indicating the possible (aka. valid) associations between tracks and detections. The first column corresponds to the null hypothesis (hence contains all ones).
likelihood_matrix (numpy.ndarray) – A matrix of shape (num_tracks, num_detections + 1) containing the unnormalised likelihoods for all combinations of tracks and detections. The first column corresponds to the null hypothesis.

Returns:

A matrix of shape (num_tracks, num_detections + 1) containing the normalised association probabilities for all combinations of tracks and detections. The first column corresponds to the null hypothesis.

Return type:

numpy.ndarray

class pyehm.core.EHM2

Efficient Hypothesis Management 2 (EHM2)

An implementation of the EHM2 algorithm, as documented in [EHM2].

compute_association_probabilities(net: EHMNet, likelihood_matrix: numpy.ndarray) → numpy.ndarray

Compute the joint association weights, as described in Section 4.2 of [EHM2]

Parameters:

net (EHMNet) – A net object representing the valid joint association hypotheses
likelihood_matrix (numpy.ndarray) – A matrix of shape (num_tracks, num_detections + 1) containing the unnormalised likelihoods for all combinations of tracks and detections. The first column corresponds to the null hypothesis.

Returns:

A matrix of shape (num_tracks, num_detections + 1) containing the normalised association probabilities for all combinations of tracks and detecrtons. The first column corresponds to the null hypothesis.

Return type:

numpy.ndarray

construct_net(validation_matrix: numpy.ndarray) → EHMNet

Construct the EHM2 net as per Section 4 of [EHM2]

Parameters:: validation_matrix (numpy.ndarray) – An indicator matrix of shape (num_tracks, num_detections + 1) indicating the possible (aka. valid) associations between tracks and detections. The first column corresponds to the null hypothesis (hence contains all ones).
Returns:: The constructed net object
Return type:: EHMNet

construct_tree(validation_matrix: numpy.ndarray) → EHMTree

Construct the EHM2 tree as per section 4.3 of [EHM2]

Parameters:: validation_matrix (numpy.ndarray) – An indicator matrix of shape (num_tracks, num_detections + 1) indicating the possible (aka. valid) associations between tracks and detections. The first column corresponds to the null hypothesis (hence contains all ones).
Returns:: The constructed tree object
Return type:: EHMTree

run(validation_matrix: numpy.ndarray, likelihood_matrix: numpy.ndarray) → numpy.ndarray

Run EHM2 to compute and return association probabilities

Parameters:

validation_matrix (numpy.ndarray) – An indicator matrix of shape (num_tracks, num_detections + 1) indicating the possible (aka. valid) associations between tracks and detections. The first column corresponds to the null hypothesis (hence contains all ones).
likelihood_matrix (numpy.ndarray) – A matrix of shape (num_tracks, num_detections + 1) containing the unnormalised likelihoods for all combinations of tracks and detections. The first column corresponds to the null hypothesis.

Returns:

A matrix of shape (num_tracks, num_detections + 1) containing the normalised association probabilities for all combinations of tracks and detections. The first column corresponds to the null hypothesis.

Return type:

numpy.ndarray

Net API

The pyehm.net module contains classes that implement the structures (nets, nodes, trees) constructed by the EHM and EHM2 classes.

class pyehm.net.EHMNetNode(layer: int, identity: Set[int])

A node in the EHMNet constructed by EHM.

Parameters:

layer (int) – Index of the network layer in which the node is placed. Since a different layer in the network is built for each track, this also represented the index of the track this node relates to.
identity (set of int) – The identity of the node. As per Section 3.1 of [EHM1], “the identity for each node is an indication of how measurement assignments made for tracks already considered affect assignments for tracks remaining to be considered”.

class pyehm.net.EHMNet(root: EHMNetNode, validation_matrix: numpy.ndarray)

Represents the nets constructed by EHM.

Parameters:

root (EHMNetNode) – The net root node.
validation_matrix (numpy.ndarray) – An indicator matrix of shape (num_tracks, num_detections + 1) indicating the possible (aka. valid) associations between tracks and detections. The first column corresponds to the null hypothesis (hence contains all ones).
tree (EHMTree) – The tree representing the net layers structure.

add_edge(parent: EHMNetNode, child: EHMNetNode, detection: int)

Add edge between two nodes, or update an already existing edge by adding the detection to it.

Parameters:

parent (EHMNetNode) – The parent node, i.e. the source of the edge.
child (EHMNetNode) – The child node, i.e. the target of the edge.
detection (int) – Index of measurement representing the parent child relationship.

add_node(node: EHMNetNode, parent: EHMNetNode, detection: int)

Add a node to the network.

Parameters:

node (EHMNetNode) – The node to be added.
parent (EHMNetNode) – The parent of the node.
detection (int) – Index of measurement representing the parent child relationship.

property nodes: The nodes comprising the net

property nodes_forward: The net nodes, ordered by increasing layer

EHMNet.num_layers -> int: Number of layers in the net

property num_nodes: Number of nodes in the net

property root: The root node of the net

Utils API

The pyehm.utils module contains helper classes and functions.

class pyehm.utils.Cluster(tracks: List[int], detections: List[int] = [], validation_matrix: numpy.ndarray = numpy.array([]), likelihood_matrix: numpy.ndarray = numpy.array([]))

A cluster of tracks sharing common detections.

Parameters:

tracks (list of int) – Indices of tracks in cluster
detections (list of int) – Indices of detections in cluster. Defaults to an empty list.
validation_matrix (numpy.ndarray) – The validation matrix for tracks and detections in the cluster. Defaults to an empty array.
likelihood_matrix (numpy.ndarray) – The likelihood matrix for tracks and detections in the cluster. Defaults to an empty array.

pyehm.utils.gen_clusters(validation_matrix: numpy.ndarray, likelihood_matrix: numpy.ndarray = numpy.array([])) → List[Cluster]

Cluster tracks into groups sharing detections

Parameters:

validation_matrix (numpy.ndarray) – An indicator matrix of shape (num_tracks, num_detections + 1) indicating the possible (aka. valid) associations between tracks and detections. The first column corresponds to the null hypothesis (hence contains all ones).
likelihood_matrix (numpy.ndarray) – A matrix of shape (num_tracks, num_detections + 1) containing the unnormalised likelihoods for all combinations of tracks and detections. The first column corresponds to the null hypothesis. Defaults to an empty array, in which case the likelihood matrices of the generated clusters will also be empty arrays.

pyehm.utils.to_nx_graph(obj: EHMNet | EHMTree) → Graph[source]

Get a NetworkX representation of a net or tree. Mainly used for plotting.

Parameters:: obj (EHMNet | EHM2Net | EHMTree) – The object to convert to a NetworkX graph.
Returns:: The NetworkX graph representation of the object.
Return type:: networkx.Graph

Plotting API

The pyehm.plot module contains helper functions for plotting the nets and trees constructed by the EHM and EHM2 classes.

Warning

The plotting functions require Graphviz to be installed and on the PATH.

Plugins

Stone Soup

class pyehm.plugins.stonesoup.JPDAWithEHM(hypothesiser: PDAHypothesiser)[source]

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 efficiently compute the joint associations. See Maskell et al. (2004) [EHM1] for more details.

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

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 pyehm.plugins.stonesoup.JPDAWithEHM2(hypothesiser: PDAHypothesiser)[source]

Bases: JPDAWithEHM

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

This is an enhanced version of the JPDAWithEHM algorithm, that makes use of the Efficient Hypothesis Management 2 (EHM2) algorithm to efficiently compute the joint associations. See Horridge et al. (2006) [EHM2] for more details.

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