Fix up docs

Author: benjeffery

python/tests/test_highlevel.py

@@ -5685,6 +5685,12 @@ def test_no_individuals_default_ploidy(self):
         for i in range(4):
             assert result.individuals_name[i] == f"tsk_{i}"
 
+        with pytest.raises(
+            ValueError,
+            match="Cannot include non-sample nodes when individuals are not present",
+        ):
+            ts.map_to_vcf_model(include_non_sample_nodes=True)
+
     def test_no_individuals_custom_ploidy(self):
         ts = tskit.Tree.generate_balanced(6).tree_sequence
         assert ts.num_individuals == 0

python/tskit/trees.py

@@ -6432,20 +6432,21 @@ def write_vcf(
         :ref:`sec_export_vcf_constructing_gt` section for more details
         and examples.
 
-        If individuals that are associated with sample nodes are defined in the
+        If individuals are defined in the
         data model (see :ref:`sec_individual_table_definition`), the genotypes
-        for each of the individual's samples are combined into a phased
-        multiploid values at each site. By default, all individuals associated
-        with only sample nodes are included in increasing order of individual ID.
+        for each of the individual's nodes are combined into a phased
+        multiploid values at each site. By default, all individuals are
+        included with their sample nodes, individuals with no nodes are
+        omitted. The ``include_non_sample_nodes`` argument can be used to
+        included non-sample nodes in the output VCF.
 
         Subsets or permutations of the sample individuals may be specified
-        using the ``individuals`` argument. It is an error to specify any
-        individuals that are not associated with any nodes.
+        using the ``individuals`` argument.
 
         Mixed-sample individuals (e.g., those associated with one node
         that is a sample and another that is not) in the data model will
-        be ignored by default. However, such individuals can be
-        excluded using the ``individuals`` argument.
+        only have the sample nodes output by default. However, non-sample
+        nodes can be included using the ``include_non_sample_nodes`` argument.
 
         If there are no individuals in the tree sequence,
         synthetic individuals are created by combining adjacent samples, and
@@ -6546,6 +6547,8 @@ def write_vcf(
             output to the VCF, otherwise if one is present an error will be raised.
             The VCF spec does not allow for sites at position 0. However, in practise
             many tools will be fine with this. Default: False.
+        :param bool include_non_sample_nodes: If True, include non-sample nodes
+            in the output VCF. By default, only sample nodes are included.
         """
         if allow_position_zero is None:
             allow_position_zero = False
@@ -10545,20 +10548,21 @@ def map_to_vcf_model(
         mapping as a 2D array of (individuals, nodes) and the individual names. The
         mapping is created by first checking if the tree sequence contains individuals.
         If it does, the mapping is created using the individuals in the tree sequence.
-        If it does not, the mapping is created using the sample nodes and the
-        specified ploidy.
+        Be default only the sample nodes of the individuals are included in the mapping,
+        unless `include_non_sample_nodes` is set to True, in which case all nodes
+        belonging to the individuals are included. Any individuals without any nodes
+        are ignored and not included in the mapping.
+        If no individuals are present, the mapping is created using only the sample nodes
+        and the specified ploidy.
 
         If neither `name_metadata_key` nor `individual_names` is not specified, the
         individual names are set to "tsk_{individual_id}" for each individual.
 
-        Warnings are emmitted if any sample nodes do not have an individual ID, or if
-        individuals are not specified and the tree sequence contains individuals
-        that have no nodes associated with them, or individuals have a mix of sample
-        and non-sample nodes.
+        Warnings are emmitted if any sample nodes do not have an individual ID.
 
         :param list individuals: Specific individual IDs to include in the VCF. If not
-            specified and the tree sequence contains individuals, all individuals whose
-            nodes all have the flag NODE_IS_SAMPLE set are included.
+            specified and the tree sequence contains individuals, all individuals are
+            included at least one node.
         :param int ploidy: The ploidy, or number of nodes per individual. Only used when
             the tree sequence does not contain individuals. Cannot be used if the tree
             sequence contains individuals. Defaults to 1 if not specified.
@@ -10567,6 +10571,9 @@ def map_to_vcf_model(
             individual_names.
         :param list individual_names: The names to use for each individual. Cannot
             be specified simultaneously with name_metadata_key.
+        :param bool include_non_sample_nodes: If True, include all nodes belonging to
+            the individuals in the mapping. If False, only include sample nodes.
+            Deafults to False.
         :return: A VcfModelMapping containing the node-to-individual mapping and
             individual names.
         :raises ValueError: If both name_metadata_key and individual_names are specified,
@@ -10587,6 +10594,12 @@ def map_to_vcf_model(
                 "Cannot specify ploidy when individuals are present in the tree sequence"
             )
 
+        if self.num_individuals == 0 and include_non_sample_nodes:
+            raise ValueError(
+                "Cannot include non-sample nodes when individuals are not present in "
+                "the tree sequence"
+            )
+
         if self.num_individuals > 0 and np.any(
             np.logical_and(
                 self.nodes_individual == tskit.NULL,