sleap.skeleton#

Implementation of skeleton data structure and API.

This module implements and API for creating animal skeletons. The goal is to provide a common interface for defining the parts of the animal, their connection to each other, and needed meta-data.

class sleap.skeleton.EdgeType(value)[source]#

Type of edge in the skeleton graph.

The skeleton graph can store different types of edges to represent different things. All edges must specify one or more of the following types:

BODY - these edges represent connections between parts or landmarks.

SYMMETRY - these edges represent symmetrical relationships between parts (e.g. left and right arms)

class sleap.skeleton.Node(name: str, weight: float = 1.0)[source]#

This class represents node in the skeleton graph, i.e., a body part.

Note: Nodes can exist without being part of a skeleton.

name#

String name of the node.

Type: str

weight#

Weight of the node (not currently used).

Type: float

classmethod as_node(node: Union[str, sleap.skeleton.Node]) → sleap.skeleton.Node[source]#: Convert given node to Node object (if not already).

static from_names(name_list: str) → List[sleap.skeleton.Node][source]#: Convert list of node names to list of nodes objects.

matches(other: sleap.skeleton.Node) → bool[source]#

Check whether all attributes match between two nodes.

Parameters: other – The Node to compare to this one.
Returns: True if all attributes match, False otherwise.

class sleap.skeleton.Skeleton(name: Optional[str] = None)[source]#

The main object for representing animal skeletons.

The skeleton represents the constituent parts of the animal whose pose is being estimated.

_skeleton_idx#: An index variable used to give skeletons a default name that should be unique across all skeletons.

preview_image#

A byte string containing an encoded preview image for the skeleton. Used only for templates.

Type: Optional[bytes]

description#

A text description of the skeleton. Used only for templates.

Type: Optional[str]

_is_template#

Whether this skeleton is a template. Used only for templates.

Type: bool

add_edge(source: str, destination: str)[source]#

Add an edge between two nodes.

Parameters

source – The name of the source node.
destination – The name of the destination node.

Raises

ValueError – If source or destination nodes cannot be found, or if edge already exists between those nodes.

Returns

None.

add_node(name: str)[source]#

Add a node representing an animal part to the skeleton.

Parameters: name – The name of the node to add to the skeleton. This name must be unique within the skeleton.
Raises: ValueError – If name is not unique.

add_nodes(name_list: List[str])[source]#

Add a list of nodes representing animal parts to the skeleton.

Parameters: name_list – List of strings representing the nodes.

add_symmetry(node1: str, node2: str)[source]#

Specify that two parts (nodes) in skeleton are symmetrical.

Certain parts of an animal body can be related as symmetrical parts in a pair. For example, left and right hands of a person.

Parameters

node1 – The name of the first part in the symmetric pair
node2 – The name of the second part in the symmetric pair

Raises

ValueError – If node1 and node2 match, or if there is already a symmetry between them.

Returns

None

clear_edges()[source]#: Delete all edges in skeleton.

delete_edge(source: str, destination: str)[source]#

Delete an edge between two nodes.

Parameters

source – The name of the source node.
destination – The name of the destination node.

Raises

ValueError – If skeleton does not have either source node, destination node, or edge between them.

Returns

None

delete_node(name: str)[source]#

Remove a node from the skeleton.

The method removes a node from the skeleton and any edge that is connected to it.

Parameters: name – The name of the node to remove
Raises: ValueError – If node cannot be found.
Returns: None

delete_symmetry(node1: Union[str, sleap.skeleton.Node], node2: Union[str, sleap.skeleton.Node])[source]#

Delete a previously established symmetry between two nodes.

Parameters

node1 – One node (by Node object or name) in symmetric pair.
node2 – Other node in symmetric pair.

Raises

ValueError – If there’s no symmetry between node1 and node2.

Returns

None

property edge_inds: List[Tuple[int, int]]#

Get a list of edges as node indices.

Returns: A list of (src_node_ind, dst_node_ind), where indices are subscripts into the Skeleton.nodes list.

property edge_names: List[Tuple[str, str]]#

Get a list of edge name tuples.

Returns: list of (src_node.name, dst_node.name)

edge_to_index(source: Union[str, sleap.skeleton.Node], destination: Union[str, sleap.skeleton.Node]) → int[source]#: Return the index of edge from source to destination.

property edges: List[Tuple[sleap.skeleton.Node, sleap.skeleton.Node]]#

Get a list of edge tuples.

Returns: list of (src_node, dst_node)

property edges_full: List[Tuple[sleap.skeleton.Node, sleap.skeleton.Node, Any, Any]]#

Get a list of edge tuples with keys and attributes.

Returns: list of (src_node, dst_node, key, attributes)

find_neighbors(node: Union[str, sleap.skeleton.Node]) → List[sleap.skeleton.Node][source]#

Find nodes that are predecessors or successors from a node.

Parameters: node – Name or Node instance.
Returns: A list of Node objects that are neighbors to the node.

find_node(name: Union[str, sleap.skeleton.Node]) → sleap.skeleton.Node[source]#

Find node in skeleton by name of node.

Parameters: name – The name of the Node (or a Node)
Returns: Node, or None if no match found

static find_unique_nodes(skeletons: List[sleap.skeleton.Skeleton]) → List[sleap.skeleton.Node][source]#

Find all unique nodes from a list of skeletons.

Parameters: skeletons – The list of skeletons.
Returns: A list of unique Node objects.

classmethod from_dict(d: Dict, node_to_idx: Optional[Dict[sleap.skeleton.Node, int]] = None) → sleap.skeleton.Skeleton[source]#

Create skeleton from dict; used for loading from JSON.

Parameters

d – the dict from which to deserialize
node_to_idx – optional dict which maps Node`sto index in some list. This is used when saving :class:`Labels`where we want to serialize the :class:`Nodes outside the Skeleton object. If given, then we replace each Node with specified index before converting Skeleton. Otherwise, we convert Node objects with the rest of the Skeleton.

Returns

Skeleton.

classmethod from_json(json_str: str, idx_to_node: Optional[Dict[int, sleap.skeleton.Node]] = None) → sleap.skeleton.Skeleton[source]#

Instantiate Skeleton from JSON string.

Parameters

json_str – The JSON encoded Skeleton.
idx_to_node – optional dict which maps an int (indexing a list of Node objects) to the already deserialized Node. This should invert node_to_idx we used when saving. If not given, then we’ll assume each Node was left in the Skeleton when it was saved.

Returns

An instance of the Skeleton object decoded from the JSON.

classmethod from_names_and_edge_inds(node_names: List[str], edge_inds: Optional[List[Tuple[int, int]]] = None) → sleap.skeleton.Skeleton[source]#

Create skeleton from a list of node names and edge indices.

Parameters

node_names – List of strings defining the nodes.
edge_inds – List of tuples in the form (src_node_ind, dst_node_ind). If not specified, the resulting skeleton will have no edges.

Returns

The instantiated skeleton.

get_symmetry(node: Union[str, sleap.skeleton.Node]) → Optional[sleap.skeleton.Node][source]#

Return the node symmetric with the specified node.

Parameters: node – Node (by Node object or name) to query.
Raises: ValueError – If node has more than one symmetry.
Returns: The symmetric Node, None if no symmetry.

get_symmetry_name(node: Union[str, sleap.skeleton.Node]) → Optional[str][source]#

Return the name of the node symmetric with the specified node.

Parameters: node – Node (by Node object or name) to query.
Returns: Name of symmetric node, None if no symmetry.

property graph#: Return a view on the subgraph of body nodes and edges for skeleton.

property graph_symmetry#: Return subgraph of symmetric edges for skeleton.

has_edge(source_name: str, dest_name: str) → bool[source]#

Check whether the skeleton has an edge.

Parameters

source_name – The name of the source node for the edge.
dest_name – The name of the destination node for the edge.

Returns

True is yes, False if no.

has_node(name: str) → bool[source]#

Check whether the skeleton has a node.

Parameters: name – The name of the node to check for.
Returns: True for yes, False for no.

has_nodes(names: Iterable[str]) → bool[source]#

Check whether the skeleton has a list of nodes.

Parameters: names – The list names of the nodes to check for.
Returns: True for yes, False for no.

property is_arborescence: bool#: Return whether this skeleton graph forms an arborescence.

property is_template: bool#

Return whether this skeleton is a template.

If is_template is True, then the preview image and description are saved. If is_template is False, then the preview image and description are not saved.

Only provided template skeletons are considered templates. To save a new template skeleton, change this to True before saving.

classmethod load_all_hdf5(file: Union[str, h5py._hl.files.File], return_dict: bool = False) → Union[List[sleap.skeleton.Skeleton], Dict[str, sleap.skeleton.Skeleton]][source]#

Load all skeletons found in the HDF5 file.

Parameters

file – The file name or open h5py.File
return_dict – Whether the the return value should be a dict where the keys are skeleton names and values the corresponding skeleton. If False, then method will return just a list of the skeletons.

Returns

The skeleton instances stored in the HDF5 file. Either in List or Dict form.

classmethod load_hdf5(file: Union[str, h5py._hl.files.File], name: str) → List[sleap.skeleton.Skeleton][source]#

Load a specific skeleton (by name) from the HDF5 file.

Parameters

file – The file name or open h5py.File
name – The name of the skeleton.

Returns

The specified Skeleton instance stored in the HDF5 file.

classmethod load_json(filename: str, idx_to_node: Optional[Dict[int, sleap.skeleton.Node]] = None) → sleap.skeleton.Skeleton[source]#

Load a skeleton from a JSON file.

This method will load the Skeleton from JSON file saved with; save_json()

Parameters

filename – The file that contains the JSON.
idx_to_node – optional dict which maps an int (indexing a list of Node objects) to the already deserialized Node. This should invert node_to_idx we used when saving. If not given, then we’ll assume each Node was left in the Skeleton when it was saved.

Returns

The Skeleton object stored in the JSON filename.

classmethod load_mat(filename: str) → sleap.skeleton.Skeleton[source]#

Load the skeleton from a Matlab MAT file.

This is to support backwards compatibility with old LEAP MATLAB code and datasets.

Parameters: filename – The name of the skeleton file
Returns: An instance of the skeleton.

static make_cattr(idx_to_node: Optional[Dict[int, sleap.skeleton.Node]] = None) → cattr.converters.Converter[source]#

Make cattr.Convert() for Skeleton.

Make a cattr.Converter() that registers structure/unstructure hooks for Skeleton objects to handle serialization of skeletons.

Parameters: idx_to_node – A dict that maps node index to Node objects.
Returns: A cattr.Converter() instance for skeleton serialization and deserialization.

matches(other: sleap.skeleton.Skeleton) → bool[source]#

Compare this Skeleton to another, ignoring name and node identities.

Parameters: other – The other skeleton.
Returns: True if the skeleton graphs are isomorphic and node names.

property name: str#

Get the name of the skeleton.

Returns: A string representing the name of the skeleton.

property node_names: List[str]#

Get a list of node names.

Returns: A list of node names.

node_to_index(node: Union[str, sleap.skeleton.Node]) → int[source]#

Return the index of the node, accepts either Node or name.

Parameters: node – The name of the node or the Node object.
Raises: ValueError if node cannot be found in skeleton. –
Returns: The index of the node in the graph.

property nodes: List[sleap.skeleton.Node]#

Get a list of :class:`Node`s.

Returns: A list of :class:`Node`s

relabel_node(old_name: str, new_name: str)[source]#

Relabel a single node to a new name.

Parameters

old_name – The old name of the node.
new_name – The new name of the node.

Returns

None

relabel_nodes(mapping: Dict[str, str])[source]#

Relabel the nodes of the skeleton.

Parameters: mapping – A dictionary with the old labels as keys and new labels as values. A partial mapping is allowed.
Raises: ValueError – If node already present with one of the new names.
Returns: None

classmethod rename_skeleton(skeleton: sleap.skeleton.Skeleton, name: str) → sleap.skeleton.Skeleton[source]#

Make copy of skeleton with new name.

This property is immutable because it is used to hash skeletons. If you want to rename a Skeleton you must use this class method.

>>> new_skeleton = Skeleton.rename_skeleton(
>>>     skeleton=old_skeleton, name="New Name")

Parameters

skeleton – The skeleton to copy.
name – The name of the new skeleton.

Returns

A new deep copied skeleton with the changed name.

classmethod save_all_hdf5(file: Union[str, h5py._hl.files.File], skeletons: List[sleap.skeleton.Skeleton])[source]#

Convenience method to save a list of skeletons to HDF5 file.

Skeletons are saved as attributes of a /skeleton group in the file.

Parameters

file – The filename or the open h5py.File object.
skeletons – The list of skeletons to save.

Raises

ValueError – If multiple skeletons have the same name.

Returns

None

save_hdf5(file: Union[str, h5py._hl.files.File])[source]#

Wrapper for HDF5 saving which takes either filename or h5py.File.

Parameters: file – can be filename (string) or h5py.File object
Returns: None

save_json(filename: str, node_to_idx: Optional[Dict[sleap.skeleton.Node, int]] = None)[source]#

Save the Skeleton as JSON file.

Output the complete skeleton to a file in JSON format.

Parameters

filename – The filename to save the JSON to.
node_to_idx – optional dict which maps Node`sto index in some list. This is used when saving :class:`Labels`where we want to serialize the :class:`Nodes outside the Skeleton object. If given, then we replace each Node with specified index before converting Skeleton. Otherwise, we convert Node objects with the rest of the Skeleton.

Returns

None

property symmetric_inds: numpy.ndarray#: Return the symmetric nodes as an array of indices.

property symmetries: List[Tuple[sleap.skeleton.Node, sleap.skeleton.Node]]#

Get a list of all symmetries without duplicates.

Returns: list of (node1, node2)

property symmetries_full: List[Tuple[sleap.skeleton.Node, sleap.skeleton.Node, Any, Any]]#

Get a list of all symmetries with keys and attributes.

Note: The returned list will contain duplicates (node1, node2) and (node2, node1).

Returns: list of (node1, node2, key, attr)

property symmetry_names: List[Tuple[str, str]]#: List of symmetry edges as tuples of node names.

static to_dict(obj: sleap.skeleton.Skeleton, node_to_idx: Optional[Dict[sleap.skeleton.Node, int]] = None) → Dict[source]#

Convert skeleton to dict; used for saving as JSON.

Parameters

obj – the :object:`Skeleton` to convert
node_to_idx – optional dict which maps Node`sto index in some list. This is used when saving :class:`Labels`where we want to serialize the :class:`Nodes outside the Skeleton object. If given, then we replace each Node with specified index before converting Skeleton. Otherwise, we convert Node objects with the rest of the Skeleton.

Returns

dict with data from skeleton

to_json(node_to_idx: Optional[Dict[sleap.skeleton.Node, int]] = None) → str[source]#

Convert the Skeleton to a JSON representation.

Parameters: node_to_idx – optional dict which maps Node`sto index in some list. This is used when saving :class:`Labels`where we want to serialize the :class:`Nodes outside the Skeleton object. If given, then we replace each Node with specified index before converting Skeleton. Otherwise, we convert Node objects with the rest of the Skeleton.
Returns: A string containing the JSON representation of the skeleton.