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].
- static 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 hypotheseslikelihood_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:
- static 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:
- static 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:
- class pyehm.core.EHM2
Efficient Hypothesis Management 2 (EHM2)
An implementation of the EHM2 algorithm, as documented in [EHM2].
- static compute_association_probabilities(net: EHM2Net, 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 hypotheseslikelihood_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:
- static construct_net(validation_matrix: numpy.ndarray) EHM2Net
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:
- static construct_tree(validation_matrix: numpy.ndarray) EHM2Tree
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:
- static 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:
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 byEHM
.- 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
ofint
) – 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.EHM2NetNode(layer: int, track: int, subnet: int, identity: Set[int])
A node in the
EHM2Net
constructed byEHM2
.- Parameters:
layer (
int
) – Index of the network layer in which the node is placed.track (
int
) – Index of track this node relates to.subnet (
int
) – Index of subnet to which the node belongs.identity (
set
ofint
) – 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).
- 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.
- get_children(node: EHMNetNode) List[EHMNetNode]
Get the children of a node.
- Parameters:
node (
EHMNetNode
) – The node whose children should be returned- Returns:
List of child nodes
- Return type:
list
ofEHMNetNode
- get_edges(parent: EHMNetNode, child: EHMNetNode) List[int]
Get edges between two nodes.
- 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.
- Returns:
Indices of measurements representing the parent child relationship.
- Return type:
- get_parents(node: EHMNetNode) List[EHMNetNode]
Get the parents of a node.
- Parameters:
node (
EHMNetNode
) – The node whose parents should be returned- Returns:
List of parent nodes
- Return type:
list
ofEHMNetNode
- property nodes
The nodes comprising the net
- property nodes_forward
The net nodes, ordered by increasing layer
- property num_layers
Number of layers in the net
- property num_nodes
Number of nodes in the net
- property root
The root node of the net
- class pyehm.net.EHM2Net(root: EHM2NetNode, validation_matrix: numpy.ndarray)
Represents the nets constructed by
EHM2
.- Parameters:
root (
EHM2NetNode
) – 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).
- add_edge(parent: EHM2NetNode, child: EHM2NetNode, detection: int)
Add edge between two nodes, or update an already existing edge by adding the detection to it.
- Parameters:
parent (
EHM2NetNode
) – The parent node, i.e. the source of the edge.child (
EHM2NetNode
) – The child node, i.e. the target of the edge.detection (
int
) – Index of measurement representing the parent child relationship.
- add_node(node: EHM2NetNode, parent: EHM2NetNode, detection: int)
Add a new node in the network.
- Parameters:
node (
EHM2NetNode
) – The node to be added.parent (
EHM2NetNode
) – The parent of the node.detection (
int
) – Index of measurement representing the parent child relationship.
- get_children_per_detection(node: EHM2NetNode, detection: int) List[EHM2NetNode]
Get the children of a node for a particular detection.
- Parameters:
node (
EHM2NetNode
) – The node whose children should be returned.detection (
int
) – The target detection.
- get_nodes_per_layer_subnet(layer: int, subnet: int) List[EHM2NetNode]
Get nodes for a particular layer in a subnet.
- Parameters:
- Returns:
List of nodes in the target layer and subnet.
- Return type:
list
ofEHM2NetNode
- property nodes
The nodes comprising the net
- property nodes_forward
The net nodes, ordered by increasing layer
- property nodes_per_track
Dictionary containing the nodes per track
- property num_layers
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 clusterdetections (
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 | EHM2Net | EHM2Tree) Graph [source]
Get a NetworkX representation of a net or tree. Mainly used for plotting.
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
.
- pyehm.plotting.plot_net(net: EHMNet | EHM2Net, ax: Axes = None, annotate=True)[source]
Plot the net.
- Parameters:
ax (
matplotlib.axes.Axes
) – Axes on which to plot the net. IfNone
, a new figure and axes will be created.annotate (
bool
) – Flag that dictates whether to draw node and edge labels on the plotted net. The default isTrue
- pyehm.plotting.plot_tree(tree: EHM2Tree, ax: Axes = None, annotate=True)[source]
Plot the tree.
- Parameters:
tree (
EHM2Tree
) – The tree to plot.ax (
matplotlib.axes.Axes
) – Axes on which to plot the tree. IfNone
, a new figure and axes will be created.annotate (
bool
) – Flag that dictates whether to draw node labels on the plotted tree. The default isTrue
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