tskit 1.0.0b2__cp313-cp313-win_amd64.whl → 1.0.1__cp313-cp313-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.0b2"
+tskit_version = "1.0.1"

tskit/combinatorics.py

@@ -541,6 +541,12 @@ class TopologyCounter:
         k = TopologyCounter._to_key(sample_set_indexes)
         self.topologies[k] = counter
 
+    def __iter__(self):
+        raise TypeError(
+            "TopologyCounter object is not iterable, "
+            "iterate over '.topologies' instead"
+        )
+
     @staticmethod
     def _to_key(sample_set_indexes):
         if not isinstance(sample_set_indexes, collections.abc.Iterable):

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/exceptions.py

@@ -60,3 +60,11 @@ class MetadataEncodingError(TskitException):
     """
     A metadata object was of a type that could not be encoded
     """
+
+
+class ImmutableTableError(ValueError):
+    """
+    Raised when attempting to modify an immutable table view.
+
+    Use TreeSequence.dump_tables() to get a mutable copy.
+    """

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,15 +33,16 @@ 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
 
 import tskit
 import tskit.exceptions as exceptions
+import tskit.util as util
 
 __builtins__object__setattr__ = builtins.object.__setattr__
 
@@ -1041,3 +1042,106 @@ class MetadataProvider:
             raise AssertionError(
                 f"Metadata differs: self={self.metadata} " f"other={other.metadata}"
             )
+
+
+NOTSET = object()  # Sentinel for unset default values
+
+
+class TableMetadataReader:
+    # Mixin for table classes that expose decoded metadata
+
+    @property
+    def metadata_schema(self) -> MetadataSchema:
+        """
+        The :class:`tskit.MetadataSchema` for this table.
+        """
+        # This isn't as inefficient as it looks because we're using an LRU cache on
+        # the parse_metadata_schema function. Thus, we're really only incurring the
+        # cost of creating the unicode string from the low-level schema and looking
+        # up the functools cache.
+        return parse_metadata_schema(self.ll_table.metadata_schema)
+
+    def metadata_vector(self, key, *, dtype=None, default_value=NOTSET):
+        """
+        Returns a numpy array of metadata values obtained by extracting ``key``
+        from each metadata entry, and using ``default_value`` if the key is
+        not present. ``key`` may be a list, in which case nested values are returned.
+        For instance, ``key = ["a", "x"]`` will return an array of
+        ``row.metadata["a"]["x"]`` values, iterated over rows in this table.
+
+        :param str key: The name, or a list of names, of metadata entries.
+        :param str dtype: The dtype of the result (can usually be omitted).
+        :param object default_value: The value to be inserted if the metadata key
+            is not present. Note that for numeric columns, a default value of None
+            will result in a non-numeric array. The default behaviour is to raise
+            ``KeyError`` on missing entries.
+        """
+        from collections.abc import Mapping
+
+        if default_value == NOTSET:
+
+            def getter(d, k):
+                return d[k]
+
+        else:
+
+            def getter(d, k):
+                return (
+                    d.get(k, default_value) if isinstance(d, Mapping) else default_value
+                )
+
+        if isinstance(key, list):
+            out = np.array(
+                [functools.reduce(getter, key, row.metadata) for row in self],
+                dtype=dtype,
+            )
+        else:
+            out = np.array(
+                [getter(row.metadata, key) for row in self],
+                dtype=dtype,
+            )
+        return out
+
+    def _make_row(self, *args):
+        return self.row_class(*args, metadata_decoder=self.metadata_schema.decode_row)
+
+
+class TableMetadataWriter(TableMetadataReader):
+    # Mixin for tables writing metadata
+
+    @TableMetadataReader.metadata_schema.setter
+    def metadata_schema(self, schema: MetadataSchema) -> None:
+        if not isinstance(schema, MetadataSchema):
+            raise TypeError(
+                "Only instances of tskit.MetadataSchema can be assigned to "
+                f"metadata_schema, not {type(schema)}"
+            )
+        self.ll_table.metadata_schema = repr(schema)
+
+    def packset_metadata(self, metadatas):
+        """
+        Packs the specified list of metadata values and updates the ``metadata``
+        and ``metadata_offset`` columns. The length of the metadatas array
+        must be equal to the number of rows in the table.
+
+        :param list metadatas: A list of metadata bytes values.
+        """
+        packed, offset = util.pack_bytes(metadatas)
+        data = self.asdict()
+        data["metadata"] = packed
+        data["metadata_offset"] = offset
+        self.set_columns(**data)
+
+    def drop_metadata(self, *, keep_schema=False):
+        """
+        Drops all metadata in this table. By default, the schema is also cleared,
+        except if ``keep_schema`` is True.
+
+        :param bool keep_schema: True if the current schema should be kept intact.
+        """
+        data = self.asdict()
+        data["metadata"] = []
+        data["metadata_offset"][:] = 0
+        self.set_columns(**data)
+        if not keep_schema:
+            self.metadata_schema = MetadataSchema.null()