From 28f98daba473da2407df3a0d395637a4e45df1d1 Mon Sep 17 00:00:00 2001 From: Yan Wong Date: Sun, 8 Jun 2025 14:39:29 +0100 Subject: [PATCH 1/2] Add a note about counting leaves in a tree. --- docs/python-api.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/python-api.md b/docs/python-api.md index 14cf33f16a..622483a0f5 100644 --- a/docs/python-api.md +++ b/docs/python-api.md @@ -507,6 +507,14 @@ Descendant nodes Tree.num_samples Tree.num_tracked_samples +Note that :meth:Tree.num_samples provides an efficient way to count samples under a node. +However, samples and leaves are not always equivalent: some samples may be internal nodes, +some leaves may not be samples (in unsimplified tree sequences), and the same node can be +a leaf in one tree but internal in another. While `tree.num_samples` often equals the leaf +count (particularly in simplified tree sequences without internal samples), a strict leaf +count requires tree traversal, e.g. via `num_leaves = len(list(tree.leaves()))`. + + Multiple nodes .. autosummary:: Tree.is_descendant From 8017b460f72de84aa3464dd8a51a823bf09bc98f Mon Sep 17 00:00:00 2001 From: Yan Wong Date: Sun, 8 Jun 2025 17:54:33 +0100 Subject: [PATCH 2/2] Correct meth syntax --- docs/python-api.md | 8 ++++---- python/tskit/trees.py | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/python-api.md b/docs/python-api.md index 622483a0f5..10a52c8c6c 100644 --- a/docs/python-api.md +++ b/docs/python-api.md @@ -507,12 +507,12 @@ Descendant nodes Tree.num_samples Tree.num_tracked_samples -Note that :meth:Tree.num_samples provides an efficient way to count samples under a node. +Note that :meth:`Tree.num_samples` provides an efficient way to count samples under a node. However, samples and leaves are not always equivalent: some samples may be internal nodes, some leaves may not be samples (in unsimplified tree sequences), and the same node can be -a leaf in one tree but internal in another. While `tree.num_samples` often equals the leaf -count (particularly in simplified tree sequences without internal samples), a strict leaf -count requires tree traversal, e.g. via `num_leaves = len(list(tree.leaves()))`. +a leaf in one tree but internal in another. While ``tree.num_samples()`` often equals the +leaf count (particularly in simplified tree sequences without internal samples), a strict +leaf count requires tree traversal, e.g. via ``num_leaves = len(list(tree.leaves()))``. Multiple nodes diff --git a/python/tskit/trees.py b/python/tskit/trees.py index 2fed70e65e..12c0355f37 100644 --- a/python/tskit/trees.py +++ b/python/tskit/trees.py @@ -7103,7 +7103,7 @@ def concatenate( ): r""" Concatenate a set of tree sequences to the right of this one, by repeatedly - calling {meth}`union` with an (optional) + calling :meth:`~TreeSequence.union` with an (optional) node mapping for each of the ``others``. If any node mapping is ``None`` only map the sample nodes between the input tree sequence and this one, based on the numerical order of sample node IDs. @@ -7117,14 +7117,14 @@ def concatenate( :param Union[list, None] node_mappings: An list of node mappings for each input tree sequence in ``args``. Each should either be an array of integers of the same length as the number of nodes in the equivalent - input tree sequence (see :meth:`union` for details), or ``None``. - If ``None``, only sample nodes are mapped to each other. + input tree sequence (see :meth:`~TreeSequence.union` for details), or + ``None``. If ``None``, only sample nodes are mapped to each other. Default: ``None``, treated as ``[None] * len(args)``. :param bool record_provenance: If True (default), record details of this call to ``concatenate`` in the returned tree sequence's provenance information (Default: True). :param bool add_populations: If True (default), nodes new to ``self`` will - be assigned new population IDs (see :meth:`union`) + be assigned new population IDs (see :meth:`~TreeSequence.union`) """ if node_mappings is None: node_mappings = [None] * len(args)