phylox.dinetwork

The module containing the main class of this package: phylox.DiNetwork.

The phylox.DiNetwork class represents a directed phylogenetic network, i.e., a directed acyclic graph with labeled nodes. Although such networks conventionally only have one root, and the labels are only attached to leaves, this class can handle multi-rooted networks with internal (or no labels) as well. Note that not all methods in this package handle these different types of networks, and the safest usage is with binary networks, with one root and labelled leaves.

Functions

`remove_unlabeled_leaves`(network[, inplace])	Iteratively removes unlabeled leaves until none are left, then suppresses all degree-2 nodes.
`suppress_node`(network, node)	Suppresses a degree-2 node node and returns true if successful.

Classes

DiNetwork(*args, **kwargs)

A class for representing a directed phylogenetic network.

phylox.dinetwork.suppress_node(network, node)

Suppresses a degree-2 node node and returns true if successful. The new arc has length length(p,node)+length(node,c). Returns false if node is not a degree-2 node.

Parameters:

network (phylox.DiNetwork) – The network to suppress a node in.
node (str or int) – The node to suppress.

Returns:

True if the node was suppressed, False otherwise.

Return type:

bool

Examples

>>> from phylox import DiNetwork
>>> network = DiNetwork()
>>> network.add_edges_from([(0, 1, {'length': 1}), (1, 2, {'length': 1})])
>>> suppress_node(network, 1)
True
>>> network.edges(data=True)
OutEdgeDataView([(0, 2, {'length': 2})])

phylox.dinetwork.remove_unlabeled_leaves(network, inplace=True)

Iteratively removes unlabeled leaves until none are left, then suppresses all degree-2 nodes.

Parameters:

network (phylox.DiNetwork) – The network to remove unlabeled leaves from.
inplace (bool) – Whether to modify the network in place or return a copy.

Returns:

The network with unlabeled leaves removed.

Return type:

phylox.DiNetwork

Examples

>>> from phylox import DiNetwork
>>> from phylox.constants import LABEL_ATTR
>>> network = DiNetwork(
...     edges=[(0, 1), (1, 2), (1, 3), (3, 4), (3, 5)],
...     labels=[(2, 'a'), (4, 'b')],
... )
>>> network = remove_unlabeled_leaves(network)
>>> network.edges()
OutEdgeView([(0, 1), (1, 2), (1, 4)])
>>> network.nodes(data=True)
NodeDataView({0: {}, 1: {}, 2: {'label': 'a'}, 4: {'label': 'b'}})

class phylox.dinetwork.DiNetwork(*args: Any, **kwargs: Any)

Bases: DiGraph, CherryPickingMixin

A class for representing a directed phylogenetic network. Inherits from networkx.DiGraph.

Parameters:

edges – a list of edges of the network.
nodes – a list of nodes of the network.
labels – a list of tuples of the form (node, label) where node is a node of the network and label is a label of the node.
kwargs – additional keyword arguments.

classmethod from_newick(newick, add_root_edge=False)

Creates a PhyloX DiNetwork network from a newick string.

Parameters:

newick – a newick string.
add_root_edge – whether to add a root edge of length 0 if not explicitly defined by the newick string.

Returns:

a network.

property label_to_node_dict

Returns the dictionary mapping labels to nodes. Uses a cached property if available.

Returns:: the dictionary mapping labels to nodes.

property leaves

Returns the set of leaves of the network. Uses a cached property if available.

Returns:: the set of leaves of the network.

property reticulations

Returns the set of reticulations of the network. Uses a cached property if available.

Returns:: the set of reticulations of the network.

property roots

Returns the set of roots of the network. Uses a cached property if available.

Returns:: the set of roots of the network.

property reticulation_number

Returns the number of reticulations of the network. Uses a cached property if available.

Returns:: the number of reticulations of the network.

property labels

Returns the dictionary mapping labels to lists of nodes. Use this instead of label_to_node_dict if there are multiple nodes with the same label. Uses a cached property if available.

Returns:: the dictionary mapping labels to lists of nodes.

child(node, exclude=[], randomNodes=False, seed=None)

Finds a child node of a node.

Parameters:

node – a node of self.
exclude – a set of nodes of self.
randomNodes – a boolean value.
seed – a seed for the random number generator.

Returns:

a child of node that is not in the set of nodes exclude. If randomNodes, then this child node is selected uniformly at random from all candidates.

parent(node, exclude=[], randomNodes=False, seed=None)

Finds a parent of a node in a network.

Parameters:

node – a node in the network.
exclude – a set of nodes of the network.
randomNodes – a boolean value.
seed – a seed for the random number generator.

Returns:

a parent of node that is not in the set of nodes exclude. If randomNodes, then this parent is selected uniformly at random from all candidates.

is_reticulation(node)

Checks whether a node is a reticulation. I.e., whether it has in-degree > 1 and out-degree <= 1.

Parameters:: node – a node in the network.
Returns:: a boolean value.

is_leaf(node)

Checks whether a node is a leaf. I.e., whether it has out-degree = 0 and in-degree > 0.

Parameters:: node – a node in the network.
Returns:: a boolean value.

is_root(node)

Checks whether a node is a root. I.e., whether it has in-degree = 0 and out-degree > 0.

Parameters:: node – a node in the network.
Returns:: a boolean value.

is_tree_node(node)

Checks whether a node is a tree node. I.e., whether it has in-degree <= 1 and out-degree > 1.

Parameters:: node – a node in the network.
Returns:: a boolean value.

newick(simple=False)

Returns a newick string representing the network.

Parameters:: simple – Boolean, indicating whether to create a simple newick string without parameters
Returns:: a newick string.

find_unused_node(exclude=[])

Find an unused node in the network.

Parameters:: exclude (list) – A list of additional nodes to exclude from the search.
Returns:: The unused node.
Return type:: int

Examples

>>> from phylox import DiNetwork
>>> network = DiNetwork()
>>> network.add_edges_from([(0, 1), (1, 2), (2, 3)])
>>> network.find_unused_node()
-1
>>> network.find_unused_node(exclude=[-1])
-2

classmethod from_cherry_picking_sequence(sequence, heights=None, label_leaves=True)

Creates a PhyloX DiNetwork network from a cherry picking sequence, and possibly a matching sequence of heights of the cherries.

Parameters:

sequence – a cherry picking sequence (i.e., a list of 2-tuples)
heights – a list of positive floats with the same length as sequence. If None, the heights will be set to consecutive integers
label_leaves – Bool, whether to label the leaves with the nodes/labels used in the sequence

Returns:

a network.