skbio.tree.TreeNode.shuffle#

TreeNode.shuffle(k=None, names=None, shuffler=None, n=1, **kwargs)[source]#

Randomly shuffle tip names of the tree.

Parameters:

kint, optional: The number of tips to shuffle. If provided, this number of tips will be randomly selected by shuffle_f, and only those names will be shuffled. Conflicts with names.
nameslist, optional: The specific tip names to shuffle. Conflicts with k.
shufflerint, np.random.Generator or callable, optional: Shuffling function, which must accept a list and modify in place. Default is the shuffle method of a NumPy random generator. If an integer is provided, a random generator will be constructed using this number as the seed.

Changed in version 0.6.3: Switched to NumPy’s new random generator. Can accept a random seed or random generator instance.

Renamed from shuffle_f. The old name is kept as an alias.
nint, optional: The number of iterations to perform. Must be a positive integer. Default is 1. If None or np.inf, iterations will be infinite.

Changed in version 0.6.3: Can accept None.

Yields:

TreeNode: Tree with shuffled tip names.

Raises:

ValueError: If k < 2 or n < 1.
ValueError: If both k and names are specified.
MissingNodeError: If names is specified but one of the names cannot be found.

See also

numpy.random.Generator.shuffle

Notes

This method does not create copies of the tree. Instead, tip names are shuffled in place in the original tree and the tree is yielded prior to the next round of shuffling. Tree caches will be cleared prior to shuffling.

k and names cannot be specified at the same time. If neither k nor names are provided, all tips will be shuffled.

Examples

Shuffle the names of a 4-tip tree for 5 times:

>>> from skbio import TreeNode
>>> tree = TreeNode.read(["((a,b),(c,d));"])
>>> for shuffled in tree.shuffle(shuffle_f=42, n=5):
...     print(shuffled)
((d,c),(b,a));

((a,b),(d,c));

((a,c),(d,b));

((d,b),(a,c));

((a,c),(d,b));