tskit 1.0.0b3__cp312-cp312-win_amd64.whl → 1.0.1__cp312-cp312-win_amd64.whl

tskit/_version.py

@@ -1,4 +1,4 @@
 # Definitive location for the version number.
 # During development, should be x.y.z.devN
 # For beta should be x.y.zbN
-tskit_version = "1.0.0b3"
+tskit_version = "1.0.1"

tskit/drawing.py

@@ -31,10 +31,8 @@ import numbers
 import operator
 import warnings
 import xml.dom.minidom
+from collections.abc import Mapping
 from dataclasses import dataclass
-from typing import List
-from typing import Mapping
-from typing import Union
 
 import numpy as np
 
@@ -538,7 +536,7 @@ def clip_ts(ts, x_min, x_max, max_num_trees=None):
     return ts, tree_status, offsets
 
 
-def check_y_ticks(ticks: Union[List, Mapping, None]) -> Mapping:
+def check_y_ticks(ticks: list | Mapping | None) -> Mapping:
     """
     Later we might want to implement a tick locator function, such that e.g. ticks=5
     selects ~5 nicely spaced tick locations (with sensible behaviour for log scales)

tskit/genotypes.py

@@ -38,12 +38,13 @@ import tskit.util as util
 class Variant:
     """
     A variant in a tree sequence, describing the observed genetic variation
-    among samples for a given site. A variant consists of (a) a tuple of
-    **alleles** listing the potential allelic states which samples at this site
-    can possess; (b) an array of **genotypes** mapping sample IDs to the observed
-    alleles (c) a reference to the :class:`Site` at which the Variant has been decoded
-    and (d) an array of **samples** giving the node id to which the each element of
-    the genotypes array corresponds.
+    among the specified nodes (by default, the sample nodes) for a given site.
+    A variant consists of (a) a tuple of **alleles** listing the potential
+    allelic states which the requested nodes at this site can possess; (b) an
+    array of **genotypes** mapping node IDs to the observed alleles; (c) a
+    reference to the :class:`Site` at which the Variant has been decoded; and
+    (d) an array of **samples** giving the node ID to which each element of the
+    genotypes array corresponds.
 
     After creation a Variant is not yet decoded, and has no genotypes.
     To decode a Variant, call the :meth:`decode` method. The Variant class will then
@@ -72,12 +73,13 @@ class Variant:
     In this case, there is no indication of which allele is the ancestral state,
     as the ordering is determined by the user.
 
-    The ``genotypes`` represent the observed allelic states for each sample,
-    such that ``var.alleles[var.genotypes[j]]`` gives the string allele
-    for sample ID ``j``. Thus, the elements of the genotypes array are
+    The ``genotypes`` represent the observed allelic states for each requested
+    node, such that ``var.alleles[var.genotypes[j]]`` gives the string allele
+    for the node at index ``j`` (i.e., for ``variant.samples[j]``). Thus, the
+    elements of the genotypes array are
     indexes into the ``alleles`` list. The genotypes are provided in this
     way via a numpy numeric array to enable efficient calculations. To obtain a
-    (less efficient) array of allele strings for each sample, you can use e.g.
+    (less efficient) array of allele strings for each node, you can use e.g.
     ``np.asarray(variant.alleles)[variant.genotypes]``.
 
     When :ref:`missing data<sec_data_model_missing_data>` is present at a given
@@ -95,10 +97,11 @@ class Variant:
     :param TreeSequence tree_sequence: The tree sequence to which this variant
         belongs.
     :param array_like samples: An array of node IDs for which to generate
-        genotypes, or None for all sample nodes. Default: None.
+        genotypes, or ``None`` for all sample nodes. Non-sample nodes may also
+        be provided to generate genotypes for internal nodes. Default: ``None``.
     :param bool isolated_as_missing: If True, the genotype value assigned to
-        missing samples (i.e., isolated samples without mutations) is
-        :data:`.MISSING_DATA` (-1). If False, missing samples will be
+        isolated nodes without mutations (samples or non-samples) is
+        :data:`.MISSING_DATA` (-1). If False, such nodes will be
         assigned the allele index for the ancestral state.
         Default: True.
     :param tuple alleles: A tuple of strings defining the encoding of
@@ -143,7 +146,7 @@ class Variant:
     @property
     def alleles(self) -> tuple[str | None, ...]:
         """
-        A tuple of the allelic values which samples can possess at the current
+        A tuple of the allelic values which nodes can possess at the current
         site. Unless an encoding of alleles is specified when creating this
         variant instance, the first element of this tuple is always the site's
         ancestral state.
@@ -162,7 +165,7 @@ class Variant:
     def genotypes(self) -> np.ndarray:
         """
         An array of indexes into the list ``alleles``, giving the
-        state of each sample at the current site.
+        state of each requested node at the current site.
         """
         self._check_decoded()
         return self._ll_variant.genotypes
@@ -170,8 +173,8 @@ class Variant:
     @property
     def isolated_as_missing(self) -> bool:
         """
-        True if isolated samples are decoded to missing data. If False, isolated
-        samples are decoded to the ancestral state.
+        True if isolated nodes are decoded to missing data. If False, isolated
+        nodes are decoded to the ancestral state.
         """
         return self._ll_variant.isolated_as_missing
 
@@ -179,7 +182,7 @@ class Variant:
     def has_missing_data(self) -> bool:
         """
         True if there is missing data for any of the
-        samples at the current site.
+        requested nodes at the current site.
         """
         alleles = self._ll_variant.alleles
         return len(alleles) > 0 and alleles[-1] is None
@@ -187,7 +190,7 @@ class Variant:
     @property
     def num_missing(self) -> int:
         """
-        The number of samples with missing data at this site.
+        The number of requested nodes with missing data at this site.
         """
         return np.sum(self.genotypes == tskit.NULL)
 
@@ -199,7 +202,7 @@ class Variant:
         array: firstly missing data is not counted as an allele, and secondly,
         the site may contain mutations to alternative allele states (which are
         counted in the number of alleles) without the mutation being inherited
-        by any of the samples.
+        by any of the requested nodes.
         """
         return len(self.alleles) - self.has_missing_data
 

tskit/metadata.py

@@ -33,9 +33,9 @@ import json
 import pprint
 import struct
 import types
+from collections.abc import Mapping
 from itertools import islice
 from typing import Any
-from typing import Mapping
 
 import jsonschema
 import numpy as np

tskit/tables.py

@@ -32,9 +32,6 @@ import numbers
 import operator
 import warnings
 from dataclasses import dataclass
-from typing import Dict
-from typing import Optional
-from typing import Union
 
 import numpy as np
 
@@ -84,7 +81,7 @@ class IndividualTableRow(util.Dataclass):
     """
     See :attr:`Individual.parents`
     """
-    metadata: Optional[Union[bytes, dict]]
+    metadata: bytes | dict | None
     """
     See :attr:`Individual.metadata`
     """
@@ -124,7 +121,7 @@ class NodeTableRow(util.Dataclass):
     """
     See :attr:`Node.individual`
     """
-    metadata: Optional[Union[bytes, dict]]
+    metadata: bytes | dict | None
     """
     See :attr:`Node.metadata`
     """
@@ -154,7 +151,7 @@ class EdgeTableRow(util.Dataclass):
     """
     See :attr:`Edge.child`
     """
-    metadata: Optional[Union[bytes, dict]]
+    metadata: bytes | dict | None
     """
     See :attr:`Edge.metadata`
     """
@@ -192,7 +189,7 @@ class MigrationTableRow(util.Dataclass):
     """
     See :attr:`Migration.time`
     """
-    metadata: Optional[Union[bytes, dict]]
+    metadata: bytes | dict | None
     """
     See :attr:`Migration.metadata`
     """
@@ -214,7 +211,7 @@ class SiteTableRow(util.Dataclass):
     """
     See :attr:`Site.ancestral_state`
     """
-    metadata: Optional[Union[bytes, dict]]
+    metadata: bytes | dict | None
     """
     See :attr:`Site.metadata`
     """
@@ -244,7 +241,7 @@ class MutationTableRow(util.Dataclass):
     """
     See :attr:`Mutation.parent`
     """
-    metadata: Optional[Union[bytes, dict]]
+    metadata: bytes | dict | None
     """
     See :attr:`Mutation.metadata`
     """
@@ -279,7 +276,7 @@ class PopulationTableRow(util.Dataclass):
     """
 
     __slots__ = ["metadata"]
-    metadata: Optional[Union[bytes, dict]]
+    metadata: bytes | dict | None
     """
     See :attr:`Population.metadata`
     """
@@ -2737,8 +2734,8 @@ class ProvenanceTable(MutableBaseTable):
 @dataclasses.dataclass(eq=True, order=True)
 class IdentitySegment:
     """
-    A single segment of identity spanning a genomic interval for a
-    a specific ancestor node.
+    A single segment of identity by descent spanning a genomic interval
+    for a specific ancestor node.
     """
 
     left: float
@@ -2758,7 +2755,7 @@ class IdentitySegment:
 
 class IdentitySegmentList(collections.abc.Iterable, collections.abc.Sized):
     """
-    A summary of identity segments for some pair of samples in a
+    A summary of identity-by-descent segments for some pair of samples in a
     :class:`.IdentitySegments` result. If the ``store_segments`` argument
     has been specified to :meth:`.TreeSequence.ibd_segments`, this class
     can be treated as a sequence of :class:`.IdentitySegment` objects.
@@ -2769,7 +2766,9 @@ class IdentitySegmentList(collections.abc.Iterable, collections.abc.Sized):
 
     If ``store_segments`` is False, only the overall summary values
     such as :attr:`.IdentitySegmentList.total_span` and ``len()`` are
-    available.
+    available. Attempting to iterate over the list or access per-segment
+    arrays (``left``, ``right``, or ``node``) in this case will raise an
+    ``IdentitySegmentsNotStoredError``.
 
     .. warning:: The order of segments within an IdentitySegmentList is
         arbitrary and may change in the future
@@ -2833,7 +2832,7 @@ class IdentitySegmentList(collections.abc.Iterable, collections.abc.Sized):
 class IdentitySegments(collections.abc.Mapping):
     """
     A class summarising and optionally storing the segments of identity
-    by state returned by :meth:`.TreeSequence.ibd_segments`. See the
+    by descent returned by :meth:`.TreeSequence.ibd_segments`. See the
     :ref:`sec_identity` for more information and examples.
 
     Along with the documented methods and attributes, the class supports
@@ -2845,9 +2844,10 @@ class IdentitySegments(collections.abc.Mapping):
        for a given instance of this class are determined by the
        ``store_pairs`` and ``store_segments`` arguments provided to
        :meth:`.TreeSequence.ibd_segments`. For example, attempting
-       to access per-sample pair information if ``store_pairs``
-       is False will result in a (hopefully informative) error being
-       raised.
+       to access per-sample pair information (such as indexing with
+       ``[(a, b)]``, iterating over the mapping, or accessing
+       :attr:`.IdentitySegments.pairs`) if ``store_pairs`` is False will
+       result in an ``IdentityPairsNotStoredError`` being raised.
 
     .. warning:: This class should not be instantiated directly.
     """
@@ -3244,7 +3244,7 @@ class TableCollection(metadata.MetadataProvider):
         return self._ll_tables.asdict(force_offset_64)
 
     @property
-    def table_name_map(self) -> Dict:
+    def table_name_map(self) -> dict:
         """
         Returns a dictionary mapping table names to the corresponding
         table instances. For example, the returned dictionary will contain the
@@ -3262,7 +3262,7 @@ class TableCollection(metadata.MetadataProvider):
         }
 
     @property
-    def name_map(self) -> Dict:
+    def name_map(self) -> dict:
         # Deprecated in 0.4.1
         warnings.warn(
             "name_map is deprecated; use table_name_map instead",
@@ -3807,7 +3807,8 @@ class TableCollection(metadata.MetadataProvider):
         """
         Sorts the individual table in place, so that parents come before children,
         and the parent column is remapped as required. Node references to individuals
-        are also updated.
+        are also updated. This is a stricter order than is required for a valid tree
+        sequence.
         """
         self._ll_tables.sort_individuals()
         # TODO add provenance
@@ -3816,9 +3817,11 @@ class TableCollection(metadata.MetadataProvider):
         """
         This puts the tables in *canonical* form, imposing a stricter order on the
         tables than :ref:`required <sec_valid_tree_sequence_requirements>` for
-        a valid tree sequence. In particular, the individual
-        and population tables are sorted by the first node that refers to each
-        (see :meth:`TreeSequence.subset`). Then, the remaining tables are sorted
+        a valid tree sequence. In particular, the population table is sorted to
+        place populations with the lowest node IDs first, and the individual table
+        is sorted firstly as in :meth:`.sort_individuals` and secondarily
+        by the lowest ID of the nodes that refer to each individual
+        (see :meth:`TreeSequence.subset`). The remaining tables are sorted
         as in :meth:`.sort`, with the modification that mutations are sorted by
         site, then time (if known), then the mutation's node's time, then number
         of descendant mutations (ensuring that parent mutations occur before
@@ -4337,6 +4340,9 @@ class TableCollection(metadata.MetadataProvider):
         check_shared_equality=True,
         add_populations=True,
         record_provenance=True,
+        *,
+        all_edges=False,
+        all_mutations=False,
     ):
         """
         Modifies the table collection in place by adding the non-shared
@@ -4358,6 +4364,10 @@ class TableCollection(metadata.MetadataProvider):
             assigned new population IDs.
         :param bool record_provenance: Whether to record a provenance entry
             in the provenance table for this operation.
+        :param bool all_edges: If True, then all edges in ``other`` are added
+            to ``self``.
+        :param bool all_mutations: If True, then all mutations in ``other`` are added
+            to ``self``.
         """
         node_mapping = util.safe_np_int_cast(node_mapping, np.int32)
         self._ll_tables.union(
@@ -4365,6 +4375,8 @@ class TableCollection(metadata.MetadataProvider):
             node_mapping,
             check_shared_equality=check_shared_equality,
             add_populations=add_populations,
+            all_edges=all_edges,
+            all_mutations=all_mutations,
         )
         if record_provenance:
             other_records = [prov.record for prov in other.provenances]
@@ -4771,6 +4783,21 @@ class ImmutableTableCollection(metadata.MetadataProvider):
             ]
         )
 
+    def link_ancestors(self, samples, ancestors):
+        """
+        See :meth:`TableCollection.link_ancestors`.
+        """
+        samples = util.safe_np_int_cast(samples, np.int32)
+        ancestors = util.safe_np_int_cast(ancestors, np.int32)
+        ll_edge_table = self._llts.link_ancestors(samples, ancestors)
+        return EdgeTable(ll_table=ll_edge_table)
+
+    def map_ancestors(self, *args, **kwargs):
+        """
+        Deprecated alias for :meth:`link_ancestors`.
+        """
+        return self.link_ancestors(*args, **kwargs)
+
     _MUTATOR_METHODS = {
         "clear",
         "sort",
@@ -4794,8 +4821,6 @@ class ImmutableTableCollection(metadata.MetadataProvider):
         "ibd_segments",
         "fromdict",
         "simplify",
-        "link_ancestors",
-        "map_ancestors",
     }
 
     def copy(self):

tskit/text_formats.py

@@ -119,6 +119,7 @@ def write_nexus(
     include_alignments,
     reference_sequence,
     missing_data_character,
+    isolated_as_missing=None,
 ):
     # See TreeSequence.write_nexus for documentation on parameters.
     if precision is None:
@@ -154,6 +155,7 @@ def write_nexus(
         alignments = ts.alignments(
             reference_sequence=reference_sequence,
             missing_data_character=missing_data_character,
+            isolated_as_missing=isolated_as_missing,
         )
         for u, alignment in zip(ts.samples(), alignments):
             print(2 * indent, f"n{u}", " ", alignment, sep="", file=out)
@@ -196,6 +198,7 @@ def write_fasta(
     wrap_width,
     reference_sequence,
     missing_data_character,
+    isolated_as_missing=None,
 ):
     # See TreeSequence.write_fasta for documentation
     if wrap_width < 0 or int(wrap_width) != wrap_width:
@@ -208,6 +211,7 @@ def write_fasta(
     alignments = ts.alignments(
         reference_sequence=reference_sequence,
         missing_data_character=missing_data_character,
+        isolated_as_missing=isolated_as_missing,
     )
     for u, alignment in zip(ts.samples(), alignments):
         print(">", f"n{u}", sep="", file=output)