Skip to main content
`Ctrl`+`K`

# skbio.tree.TreeNode.shuffle

TreeNode.shuffle(k=None, names=None, shuffler=None, n=1)

  Randomly shuffle tip names of the tree.

  Parameters:
    k int, 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`.

    names list, optional

      The specific tip names to shuffle. Conflicts with `k`.

    shuffler int, 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: Renamed from `shuffle_f`. The old name is kept as an alias but is deprecated.

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

    n int, 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(shuffler=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));