Add docs

Author: benjeffery

python/CHANGELOG.rst

@@ -12,12 +12,20 @@
   associated with each individual as a numpy array.
   (:user:`benjeffery`, :pr:`3153`)
 
+- Add ``TreeSequence.map_to_vcf_model`` method to return a mapping of
+  the tree sequence to the VCF model. 
+  (:user:`benjeffery`, :pr:`3163`)
 
 **Fixes**
 
 - Correct assertion message when tables are compared with metadata ignored.
   (:user:`benjeffery`, :pr:`3162`, :issue:`3161`)
 
+**Changes** 
+
+- ``TreeSequence.write_vcf`` now warns instead of errors if an individual has a mix
+  of sample and non-sample nodes when no specific individuals are provided.
+
 --------------------
 [0.6.3] - 2025-04-28
 --------------------

python/tskit/trees.py

@@ -6435,16 +6435,15 @@ def write_vcf(
         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 sample nodes are included in increasing order of individual ID.
+        with only sample nodes are included in increasing order of individual ID.
 
         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, or whose
-        nodes are not all samples.
+        individuals that are not associated with any nodes.
 
         Mixed-sample individuals (e.g., those associated with one node
         that is a sample and another that is not) in the data model will
-        result in an error by default. However, such individuals can be
+        be ignored by default. However, such individuals can be
         excluded using the ``individuals`` argument.
 
         If there are no individuals in the tree sequence,
@@ -10536,11 +10535,43 @@ def map_to_vcf_model(
         individual_names=None,
     ):
         """
-        Returns a list of lists of node IDs, where each sublist contains the
-        sample nodes associated with the same individual.
-        If `individuals` is not specified (the default) nodes for all individuals where
-        all of their nodes are samples are returned. If `individuals` is specified,
-        only the nodes for the specified individuals are returned.
+        Maps the sample nodes in this tree sequence to a representation suitable for
+        VCF output, using the individuals if present.
+
+        Creates a VcfModelMapping object that contains both the nodes-to-individual
+        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.
+
+        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.
+        - 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.
+
+        :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.
+        :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.
+        :param str name_metadata_key: The key in the individual metadata to use
+            for individual names. Cannot be specified simultaneously with
+            individual_names.
+        :param list individual_names: The names to use for each individual. Cannot
+            be specified simultaneously with name_metadata_key.
+        :return: A VcfModelMapping containing the node-to-individual mapping and
+            individual names.
+        :rtype: VcfModelMapping
+        :raises ValueError: If both name_metadata_key and individual_names are specified,
+            if ploidy is specified when individuals are present, if an invalid individual
+            ID is specified, if a specified individual has no nodes, or if the number of
+            individuals doesn't match the number of names.
         """
 
         if name_metadata_key is not None and individual_names is not None:

python/tskit/vcf.py

@@ -135,8 +135,6 @@ def __init__(
                 '"position_transform = lambda x: np.fmax(1, x)"'
             )
 
-
-
     def __write_header(self, output):
         print("##fileformat=VCFv4.2", file=output)
         print(f"##source=tskit {provenance.__version__}", file=output)