Python API¶
This page provides detailed documentation for the tskit
Python API.
Trees and tree sequences¶
The TreeSequence
class represents a sequence of correlated trees
output by a simulation. The Tree
class represents a single
tree in this sequence.
These classes are the interfaces used to interact with the trees
and mutational information stored in a tree sequence returned from a simulation.
There are also methods for loading data into these objects, either from the native
format using tskit.load()
, or from another sources
using tskit.load_text()
or TableCollection.tree_sequence()
.
Top levelclasses¶

class
tskit.
TreeSequence
¶ A single tree sequence, as defined by the data model. A TreeSequence instance can be created from a set of tables using
TableCollection.tree_sequence()
; or loaded from a set of text files usingload_text()
; or, loaded from a native binary file usingload()
.TreeSequences are immutable. To change the data held in a particular tree sequence, first get the table information as a
TableCollection
instance (usingdump_tables()
), edit those tables using the tables api, and create a new tree sequence usingTableCollection.tree_sequence()
.The
trees()
method iterates over all trees in a tree sequence, and thevariants()
method iterates over all sites and their genotypes.
aslist
()¶ Returns the trees in this tree sequence as a list. Each tree is represented by a different instance of
Tree
. As such, this method is inefficient and may use a large amount of memory, and should not be used when performance is a consideration. Thetrees()
method is the recommended way to efficiently iterate over the trees in a tree sequence.Returns: A list of the trees in this tree sequence. Return type: list

at
(position)¶ Returns the tree covering the specified genomic location. The returned tree will have
tree.interval[0]
<=position
<tree.interval[1]
. See alsoTree.seek()
.Returns: A new instance of Tree
positioned to cover the specified position.Return type: Tree

at_index
(index)¶ Returns the tree at the specified index. See also
Tree.seek_index()
.Returns: A new instance of Tree
positioned at the specified index.Return type: Tree

breakpoints
()¶ Returns an iterator over the breakpoints along the chromosome, including the two extreme points 0 and L. This is equivalent to
>>> [0] + [t.get_interval()[1] for t in self.trees()]
although we do not build an explicit list.
Returns: An iterator over all the breakpoints along the simulated sequence. Return type: iter

dump
(path, zlib_compression=False)¶ Writes the tree sequence to the specified file path.
Parameters:

dump_tables
()¶ A copy of the tables defining this tree sequence.
Returns: A TableCollection
containing all tables underlying the tree sequence.Return type: TableCollection

dump_text
(nodes=None, edges=None, sites=None, mutations=None, individuals=None, populations=None, provenances=None, precision=6, encoding='utf8', base64_metadata=True)¶ Writes a text representation of the tables underlying the tree sequence to the specified connections.
If Base64 encoding is not used, then metadata will be saved directly, possibly resulting in errors reading the tables back in if metadata includes whitespace.
Parameters:  nodes (stream) – The filelike object (having a .write() method) to write the NodeTable to.
 edges (stream) – The filelike object to write the EdgeTable to.
 sites (stream) – The filelike object to write the SiteTable to.
 mutations (stream) – The filelike object to write the MutationTable to.
 individuals (stream) – The filelike object to write the IndividualTable to.
 populations (stream) – The filelike object to write the PopulationTable to.
 provenances (stream) – The filelike object to write the ProvenanceTable to.
 precision (int) – The number of digits of precision.
 encoding (string) – Encoding used for text representation.
 base64_metadata (bool) – If True, metadata is encoded using Base64 encoding; otherwise, as plain text.

edge_diffs
()¶ Returns an iterator over all the edges that are inserted and removed to build the trees as we move from lefttoright along the tree sequence. The iterator yields a sequence of 3tuples,
(interval, edges_out, edges_in)
. Theinterval
is a pair(left, right)
representing the genomic interval (seeTree.interval
). Theedges_out
value is a tuple of the edges that were justremoved to create the tree covering the interval (hence,edges_out
will always be empty for the first tree). Theedges_in
value is a tuple of edges that were just inserted to contruct the tree convering the current interval.Returns: An iterator over the (interval, edges_out, edges_in) tuples. Return type: iter(tuple, tuple, tuple)

edges
()¶ Returns an iterator over all the edges in this tree sequence. Edges are returned in the order required for a valid tree sequence. So, edges are guaranteed to be ordered such that (a) all parents with a given ID are contiguous; (b) edges are returned in nondescreasing order of parent time ago; (c) within the edges for a given parent, edges are sorted first by child ID and then by left coordinate.
Returns: An iterator over all edges. Return type: iter( Edge
)

first
()¶ Returns the first tree in this
TreeSequence
. To iterate over all trees in the sequence, use thetrees()
method.Returns: The first tree in this tree sequence. Return type: Tree
.

genotype_matrix
()¶ Returns an \(m \times n\) numpy array of the genotypes in this tree sequence, where \(m\) is the number of sites and \(n\) the number of samples. The genotypes are the indexes into the array of
alleles
, as described for theVariant
class. The value 0 always corresponds to the ancestal state, and values > 0 represent distinct derived states.Warning
This method can consume a very large amount of memory! If all genotypes are not needed at once, it is usually better to access them sequentially using the
variants()
iterator.Returns: The full matrix of genotypes. Return type: numpy.ndarray (dtype=np.uint8)

haplotypes
()¶ Returns an iterator over the haplotypes resulting from the trees and mutations in this tree sequence as a string. The iterator returns a total of \(n\) strings, each of which contains \(s\) characters (\(n\) is the sample size returned by
tskit.TreeSequence.num_samples
and \(s\) is the number of sites returned bytskit.TreeSequence.num_sites
). The first string returned is the haplotype for sample 0, and so on. For a given haplotypeh
, the value ofh[j]
is the observed allelic state at sitej
.See also the
variants()
iterator for sitecentric access to sample genotypes.This method is only supported for singleletter alleles.
Returns: An iterator over the haplotype strings for the samples in this tree sequence. Return type: iter Raises: LibraryError if called on a tree sequence containing multiletter alleles.

individual
(id_)¶ Returns the individual in this tree sequence with the specified ID.
Return type: Individual

individuals
()¶ Returns an iterator over all the individuals in this tree sequence.
Returns: An iterator over all individuals. Return type: iter( Individual
)

last
()¶ Returns the last tree in this
TreeSequence
. To iterate over all trees in the sequence, use thetrees()
method.Returns: The last tree in this tree sequence. Return type: Tree
.

mean_descendants
(reference_sets)¶ Computes for every node the mean number of samples in each of the reference_sets that descend from that node, averaged over the portions of the genome for which the node is ancestral to any sample. The output is an array, C[node, j], which reports the total length of all genomes in reference_sets[j] that inherit from node, divided by the total length of the genome on which node is an ancestor to any sample in the tree sequence.
Note
This interface may change, particularly the normalization by proportion of the genome that node is an ancestor to anyone.
Parameters: reference sets (iterable) – A list of lists of node IDs. Returns: An array with dimensions (number of nodes in the tree sequence, number of reference sets)

migrations
()¶ Returns an iterator over all the migrations in this tree sequence.
Migrations are returned in nondecreasing order of the
time
value.Returns: An iterator over all migrations. Return type: iter( Migration
)

mutation
(id_)¶ Returns the mutation in this tree sequence with the specified ID.
Return type: Mutation

mutations
()¶ Returns an iterator over all the mutations in this tree sequence. Mutations are returned in order of nondecreasing site ID. See the
Mutation
class for details on the available fields for each mutation.The returned iterator is equivalent to iterating over all sites and all mutations in each site, i.e.:
>>> for site in tree_sequence.sites(): >>> for mutation in site.mutations: >>> yield mutation
Returns: An iterator over all mutations in this tree sequence. Return type: iter( Mutation
)

nodes
()¶ Returns an iterator over all the nodes in this tree sequence.
Returns: An iterator over all nodes. Return type: iter( Node
)

num_edges
¶ Returns the number of edges in this tree sequence.
Returns: The number of edges in this tree sequence. Return type: int

num_individuals
¶ Returns the number of individuals in this tree sequence.
Returns: The number of individuals in this tree sequence. Return type: int

num_migrations
¶ Returns the number of migrations in this tree sequence.
Returns: The number of migrations in this tree sequence. Return type: int

num_mutations
¶ Returns the number of mutations in this tree sequence.
Returns: The number of mutations in this tree sequence. Return type: int

num_nodes
¶ Returns the number of nodes in this tree sequence.
Returns: The number of nodes in this tree sequence. Return type: int

num_populations
¶ Returns the number of populations in this tree sequence.
Returns: The number of populations in this tree sequence. Return type: int

num_provenances
¶ Returns the number of provenances in this tree sequence.
Returns: The number of provenances in this tree sequence. Return type: int

num_samples
¶ Returns the number of samples in this tree sequence. This is the number of sample nodes in each tree.
Returns: The number of sample nodes in this tree sequence. Return type: int

num_sites
¶ Returns the number of sites in this tree sequence.
Returns: The number of sites in this tree sequence. Return type: int

num_trees
¶ Returns the number of distinct trees in this tree sequence. This is equal to the number of trees returned by the
trees()
method.Returns: The number of trees in this tree sequence. Return type: int

pairwise_diversity
(samples=None)¶ Returns the value of \(\pi\), the pairwise nucleotide site diversity, the average number of mutations per unit of genome length that differ between a randomly chosen pair of samples. If samples is specified, calculate the diversity within this set.
Note
This method does not currently support sites that have more than one mutation. Using it on such a tree sequence will raise a LibraryError with an “Unsupported operation” message.
Parameters: samples (iterable) – The set of samples within which we calculate the diversity. If None, calculate diversity within the entire sample. Returns: The pairwise nucleotide site diversity. Return type: float

population
(id_)¶ Returns the population in this tree sequence with the specified ID.
Return type: Population

populations
()¶ Returns an iterator over all the populations in this tree sequence.
Returns: An iterator over all populations. Return type: iter( Population
)

provenances
()¶ Returns an iterator over all the provenances in this tree sequence.
Returns: An iterator over all provenances. Return type: iter( Provenance
)

samples
(population=None, population_id=None)¶ Returns an array of the sample node IDs in this tree sequence. If the
population
parameter is specified, only return sample IDs from this population.Parameters: Returns: A numpy array of the node IDs for the samples of interest.
Return type: numpy.ndarray (dtype=np.int32)

sequence_length
¶ Returns the sequence length in this tree sequence. This defines the genomic scale over which tree coordinates are defined. Given a tree sequence with a sequence length \(L\), the constituent trees will be defined over the halfclosed interval \([0, L)\). Each tree then covers some subset of this interval — see
tskit.Tree.get_interval()
for details.Returns: The length of the sequence in this tree sequence in bases. Return type: float

simplify
(samples=None, filter_zero_mutation_sites=None, map_nodes=False, reduce_to_site_topology=False, filter_populations=True, filter_individuals=True, filter_sites=True, record_provenance=True)¶ Returns a simplified tree sequence that retains only the history of the nodes given in the list
samples
. Ifmap_nodes
is true, also return a numpy array mapping the node IDs in this tree sequence to their node IDs in the simplified tree tree sequence. If a nodeu
is not present in the new tree sequence, the value of this mapping will be NULL (1).In the returned tree sequence, the node with ID
0
corresponds tosamples[0]
, node1
corresponds tosamples[1]
, and so on. Besides the samples, node IDs in the returned tree sequence are then allocated sequentially in time order.If you wish to simplify a set of tables that do not satisfy all requirements for building a TreeSequence, then use
TableCollection.simplify()
.If the
reduce_to_site_topology
parameter is True, the returned tree sequence will contain only topological information that is necessary to represent the trees that contain sites. If there are zero sites in this tree sequence, this will result in an output tree sequence with zero edges. When the number of sites is greater than zero, every tree in the output tree sequence will contain at least one site. For a given site, the topology of the tree containing that site will be identical (up to node ID remapping) to the topology of the corresponding tree in the input tree sequence.If
filter_populations
,filter_individuals
orfilter_sites
is True, any of the corresponding objects that are not referenced elsewhere are filtered out. As this is the default behaviour, it is important to realise IDs for these objects may change through simplification. By setting these parameters to False, however, the corresponding tables can be preserved without changes.Parameters:  samples (list) – The list of nodes for which to retain information. This may be a numpy array (or arraylike) object (dtype=np.int32).
 filter_zero_mutation_sites (bool) – Deprecated alias for
filter_sites
.  map_nodes (bool) – If True, return a tuple containing the resulting tree sequence and a numpy array mapping node IDs in the current tree sequence to their corresponding node IDs in the returned tree sequence. If False (the default), return only the tree sequence object itself.
 reduce_to_site_topology (bool) – Whether to reduce the topology down to the trees that are present at sites. (Default: False)
 filter_populations (bool) – If True, remove any populations that are not referenced by nodes after simplification; new population IDs are allocated sequentially from zero. If False, the population table will not be altered in any way. (Default: True)
 filter_individuals (bool) – If True, remove any individuals that are not referenced by nodes after simplification; new individual IDs are allocated sequentially from zero. If False, the individual table will not be altered in any way. (Default: True)
 filter_sites (bool) – If True, remove any sites that are not referenced by mutations after simplification; new site IDs are allocated sequentially from zero. If False, the site table will not be altered in any way. (Default: True)
 record_provenance (bool) – If True, record details of this call to simplify in the returned tree sequence’s provenance information (Default: True).
Returns: The simplified tree sequence, or (if
map_nodes
is True) a tuple consisting of the simplified tree sequence and a numpy array mapping source node IDs to their corresponding IDs in the new tree sequence.Return type: TreeSequence or a (TreeSequence, numpy.array) tuple

sites
()¶ Returns an iterator over all the sites in this tree sequence. Sites are returned in order of increasing ID (and also position). See the
Site
class for details on the available fields for each site.Returns: An iterator over all sites. Return type: iter( Site
)

tables
¶ A copy of the tables underlying this tree sequence. See also
dump_tables()
.Warning
This propery currently returns a copy of the tables underlying a tree sequence but it may return a readonly view in the future. Thus, if the tables will subsequently be updated, please use the
dump_tables()
method instead as this will always return a new copy of the TableCollection.Returns: A TableCollection
containing all a copy of the tables underlying this tree sequence.Return type: TableCollection

trees
(tracked_samples=None, sample_counts=True, sample_lists=False, tracked_leaves=None, leaf_counts=None, leaf_lists=None)¶ Returns an iterator over the trees in this tree sequence. Each value returned in this iterator is an instance of
Tree
. Upon successful termination of the iterator, the tree will be in the “cleared” null state.The
sample_counts
,sample_lists
andtracked_samples
parameters are passed to theTree
constructor, and control the options that are set in the returned tree instance.Warning: Do not store the results of this iterator in a list! For performance reasons, the same underlying object is used for every tree returned which will most likely lead to unexpected behaviour. If you wish to obtain a list of trees in a tree sequence please use
ts.aslist()
instead.Parameters:  tracked_samples (list) – The list of samples to be tracked and
counted using the
Tree.get_num_tracked_samples()
method.  sample_counts (bool) – If True, support constant time sample counts
via the
Tree.num_samples()
andTree.get_num_tracked_samples()
methods.  sample_lists (bool) – If True, provide more efficient access
to the samples beneath a give node using the
Tree.samples()
method.
Returns: An iterator over the sparse trees in this tree sequence.
Return type: iter
 tracked_samples (list) – The list of samples to be tracked and
counted using the

variants
(as_bytes=False, samples=None)¶ Returns an iterator over the variants in this tree sequence. See the
Variant
class for details on the fields of each returned object. By default thegenotypes
for the variants are numpy arrays, corresponding to indexes into thealleles
array. If theas_bytes
parameter is true, these allelic values are recorded directly into a bytes array.Note
The
as_bytes
parameter is kept as a compatibility option for older code. It is not the recommended way of accessing variant data, and will be deprecated in a later release. Another method will be provided to obtain the allelic states for each site directly.Parameters: as_bytes (bool) – If True, the genotype values will be returned as a Python bytes object. This is useful in certain situations (i.e., directly printing the genotypes) or when numpy is not available. Otherwise, genotypes are returned as a numpy array (the default). Returns: An iterator of all variants this tree sequence. Return type: iter( Variant
)

write_vcf
(output, ploidy=1, contig_id='1')¶ Writes a VCF formatted file to the specified filelike object. If a ploidy value is supplied, allele values are combined among adjacent samples to form a phased genotype of the required ploidy. For example, if we have a ploidy of 2 and a sample of size 6, then we will have 3 diploid samples in the output, consisting of the combined alleles for samples [0, 1], [2, 3] and [4, 5]. If we had alleles 011110 at a particular variant, then we would output the genotypes 01, 11 and 10 in VCF. Sample names are generated by appending the index to the prefix
msp_
such that we would have the sample namesmsp_0
,msp_1
andmsp_2
in the running example.Warning
This output function does not currently use information in the
IndividualTable
, and so will only correctly produce nonhaploid output if the nodes corresponding to each individual are contiguous as described above.Example usage:
with open("output.vcf", "w") as vcf_file: tree_sequence.write_vcf(vcf_file, 2)
The VCF output can also be compressed using the
gzip
module, if you wish:import gzip with gzip.open("output.vcf.gz", "wt") as f: ts.write_vcf(f)
However, this gzipped VCF may not be fully compatible with downstream tools such as tabix, which may require the VCF use the specialised bgzip format. A general way to convert VCF data to various formats is to pipe the text produced by
tskit
intobcftools
, as done here:import os import subprocess read_fd, write_fd = os.pipe() write_pipe = os.fdopen(write_fd, "w") with open("output.bcf", "w") as bcf_file: proc = subprocess.Popen( ["bcftools", "view", "O", "b"], stdin=read_fd, stdout=bcf_file) ts.write_vcf(write_pipe) write_pipe.close() os.close(read_fd) proc.wait() if proc.returncode != 0: raise RuntimeError("bcftools failed with status:", proc.returncode)
This can also be achieved on the command line use the
tskit vcf
command, e.g.:$ tskit vcf example.trees  bcftools view O b > example.bcf
Parameters:


class
tskit.
Tree
(tree_sequence, tracked_samples=None, sample_counts=True, sample_lists=False)¶ A single tree in a
TreeSequence
. Please see the Moving along a tree sequence section for information on how efficiently access trees sequentially or obtain a list of individual trees in a tree sequence.The
sample_counts
andsample_lists
parameters control the features that are enabled for this tree. Ifsample_counts
is True, then it is possible to count the number of samples underneath a particular node in constant time using thenum_samples()
method. Ifsample_lists
is True a more efficient algorithm is used in theTree.samples()
method.The
tracked_samples
parameter can be used to efficiently count the number of samples in a given set that exist in a particular subtree using theTree.num_tracked_samples()
method. It is an error to use thetracked_samples
parameter when thesample_counts
flag is False.The
Tree
class is a statemachine which has a state corresponding to each of the trees in the parent tree sequence. We transition between these states by using the seek functions likeTree.first()
,Tree.last()
,Tree.seek()
andTree.seek_index()
. There is one more state, the socalled “null” or “cleared” state. This is the state that aTree
is in immediately after initialisation; it has an index of 1, and no edges. We can also enter the null state by callingTree.next()
on the last tree in a sequence, callingTree.prev()
on the first tree in a sequence or calling calling theTree.clear()
method at any time.The highlevel TreeSequence seeking and iterations methods (e.g,
TreeSequence.trees
) are built on these lowlevel statemachine seek operations. We recommend these higher level operations for most users.Parameters:  tree_sequence (TreeSequence) – The parent tree sequence.
 tracked_samples (list) – The list of samples to be tracked and
counted using the
Tree.num_tracked_samples()
method.  sample_counts (bool) – If True, support constant time sample counts
via the
Tree.num_samples()
andTree.num_tracked_samples()
methods.  sample_lists (bool) – If True, provide more efficient access
to the samples beneath a give node using the
Tree.samples()
method.

branch_length
(u)¶ Returns the length of the branch (in generations) joining the specified node to its parent. This is equivalent to
>>> tree.time(tree.parent(u))  tree.time(u)
Note that this is not related to the value returned by
length
, which describes the length of the interval covered by the tree in genomic coordinates.Parameters: u (int) – The node of interest. Returns: The branch length from u to its parent. Return type: float

children
(u)¶ Returns the children of the specified node
u
as a tuple of integer node IDs. Ifu
is a leaf, return the empty tuple.Parameters: u (int) – The node of interest. Returns: The children of u
as a tuple of integersReturn type: tuple(int)

clear
()¶ Resets this tree back to the initial null state. Calling this method on a tree already in the null state has no effect.

copy
()¶ Returns a deep copy of this tree. The returned tree will have identical state to this tree.
Returns: A copy of this tree. Return type: Tree

draw
(path=None, width=None, height=None, node_labels=None, node_colours=None, mutation_labels=None, mutation_colours=None, format=None, edge_colours=None)¶ Returns a drawing of this tree.
When working in a Jupyter notebook, use the
IPython.display.SVG
function to display the SVG output from this function inline in the notebook:>>> SVG(tree.draw())
The unicode format uses unicode box drawing characters to render the tree. This allows rendered trees to be printed out to the terminal:
>>> print(tree.draw(format="unicode")) 6 ┏━┻━┓ ┃ 5 ┃ ┏━┻┓ ┃ ┃ 4 ┃ ┃ ┏┻┓ 3 0 1 2
The
node_labels
argument allows the user to specify custom labels for nodes, or no labels at all:>>> print(tree.draw(format="unicode", node_labels={})) ┃ ┏━┻━┓ ┃ ┃ ┃ ┏━┻┓ ┃ ┃ ┃ ┃ ┃ ┏┻┓ ┃ ┃ ┃ ┃
Parameters:  path (str) – The path to the file to write the output. If None, do not write to file.
 width (int) – The width of the image in pixels. If not specified, either defaults to the minimum size required to depict the tree (text formats) or 200 pixels.
 height (int) – The height of the image in pixels. If not specified, either defaults to the minimum size required to depict the tree (text formats) or 200 pixels.
 node_labels (map) – If specified, show custom labels for the nodes that are present in the map. Any nodes not specified in the map will not have a node label.
 node_colours (map) – If specified, show custom colours for the nodes
given in the map. Any nodes not specified in the map will take the default
colour; a value of
None
is treated as transparent and hence the node symbol is not plotted. (Only supported in the SVG format.)  mutation_labels (map) – If specified, show custom labels for the mutations that are present in the map. Any nodes not specified in the map will not have a node label. (Showing mutations is currently only supported in the SVG format)
 mutation_colours (map) – If specified, show custom colours for the mutations
given in the map. As for
node_colours
, unspecified mutations take the default colour, andNone
values result in the symbol being omitted. (Only supported in the SVG format.)  format (str) – The format of the returned image. Currently supported are ‘svg’, ‘ascii’ and ‘unicode’.
 edge_colours (map) – If specified, show custom colours for the edge
joining each node in the map to its parent. As for
node_colours
, unspecified edges take the default colour, andNone
values result in the edge being omitted. (Only supported in the SVG format.)
Returns: A representation of this tree in the requested format.
Return type:

first
()¶ Seeks to the first tree in the sequence. This can be called whether the tree is in the null state or not.

index
¶ Returns the index this tree occupies in the parent tree sequence. This index is zero based, so the first tree in the sequence has index 0.
Returns: The index of this tree. Return type: int

interval
¶ Returns the coordinates of the genomic interval that this tree represents the history of. The interval is returned as a tuple \((l, r)\) and is a halfopen interval such that the left coordinate is inclusive and the right coordinate is exclusive. This tree therefore applies to all genomic locations \(x\) such that \(l \leq x < r\).
Returns: A tuple (l, r) representing the leftmost (inclusive) and rightmost (exclusive) coordinates of the genomic region covered by this tree. Return type: tuple

is_descendant
(u, v)¶ Returns True if the specified node u is a descendant of node v and False otherwise. A node \(u\) is a descendant of another node \(v\) if \(v\) is on the path from \(u\) to root. A node is considered to be a descendant of itself, so
tree.is_descendant(u, u)
will be True for any valid node.Parameters: Returns: True if u is a descendant of v.
Return type: Raises: ValueError – If u or v are not valid node IDs.

is_internal
(u)¶ Returns True if the specified node is not a leaf. A node is internal if it has one or more children in the current tree.
Parameters: u (int) – The node of interest. Returns: True if u is not a leaf node. Return type: bool

is_leaf
(u)¶ Returns True if the specified node is a leaf. A node \(u\) is a leaf if it has zero children.
Parameters: u (int) – The node of interest. Returns: True if u is a leaf node. Return type: bool

is_sample
(u)¶ Returns True if the specified node is a sample. A node \(u\) is a sample if it has been marked as a sample in the parent tree sequence.
Parameters: u (int) – The node of interest. Returns: True if u is a sample. Return type: bool

last
()¶ Seeks to the last tree in the sequence. This can be called whether the tree is in the null state or not.

leaves
(u=None)¶ Returns an iterator over all the leaves in this tree that are underneath the specified node. If u is not specified, return all leaves in the tree.
Parameters: u (int) – The node of interest. Returns: An iterator over all leaves in the subtree rooted at u. Return type: iterator

length
¶ Returns the length of the genomic interval that this tree represents. This is defined as \(r  l\), where \((l, r)\) is the genomic interval returned by
interval
.Returns: The length of the genomic interval covered by this tree. Return type: int

mrca
(u, v)¶ Returns the most recent common ancestor of the specified nodes.
Parameters: Returns: The most recent common ancestor of u and v.
Return type:

mutations
()¶ Returns an iterator over all the mutations in this tree. Mutations are returned in order of nondecreasing site ID. See the
Mutation
class for details on the available fields for each mutation.The returned iterator is equivalent to iterating over all sites and all mutations in each site, i.e.:
>>> for site in tree.sites(): >>> for mutation in site.mutations: >>> yield mutation
Returns: An iterator over all mutations in this tree. Return type: iter( Mutation
)

newick
(precision=14, root=None, node_labels=None)¶ Returns a newick encoding of this tree. If the
root
argument is specified, return a representation of the specified subtree, otherwise the full tree is returned. If the tree has multiple roots then seperate newick strings for each rooted subtree must be found (i.e., we do not attempt to concatenate the different trees).By default, leaf nodes are labelled with their numerical ID + 1, and internal nodes are not labelled. Arbitrary node labels can be specified using the
node_labels
argument, which maps node IDs to the desired labels.Warning
Node labels are not Newick escaped, so care must be taken to provide labels that will not break the encoding.
Parameters:  precision (int) – The numerical precision with which branch lengths are printed.
 root (int) – If specified, return the tree rooted at this node.
 node_labels (map) – If specified, show custom labels for the nodes that are present in the map. Any nodes not specified in the map will not have a node label.
Returns: A newick representation of this tree.
Return type:

next
()¶ Seeks to the next tree in the sequence. If the tree is in the initial null state we seek to the first tree (equivalent to calling
first()
). Callingnext
on the last tree in the sequence results in the tree being cleared back into the null initial state (equivalent to callingclear()
). The return value of the function indicates whether the tree is in a nonnull state, and can be used to loop over the trees:# Iterate over the trees from lefttoright tree = tskit.Tree(tree_sequence) while tree.next() # Do something with the tree. print(tree.index) # tree is now back in the null state.
Returns: True if the tree has been transformed into one of the trees in the sequence; False if the tree has been transformed into the null state. Return type: bool

nodes
(root=None, order='preorder')¶ Returns an iterator over the nodes in this tree. If the root parameter is provided, iterate over the nodes in the subtree rooted at this node. If this is None, iterate over all nodes. If the order parameter is provided, iterate over the nodes in required tree traversal order.
Parameters: Returns: An iterator over the nodes in the tree in some traversal order.
Return type: iterator

num_mutations
¶ Returns the total number of mutations across all sites on this tree.
Returns: The total number of mutations over all sites on this tree. Return type: int

num_nodes
¶ Returns the number of nodes in the
TreeSequence
this tree is in. Equivalent totree.tree_sequence.num_nodes
. To find the number of nodes that are reachable from all roots uselen(list(tree.nodes()))
.Return type: int

num_roots
¶ The number of roots in this tree, as defined in the
roots
attribute.Requires O(number of roots) time.
Return type: int

num_samples
(u=None)¶ Returns the number of samples in this tree underneath the specified node (including the node itself). If u is not specified return the total number of samples in the tree.
If the
TreeSequence.trees()
method is called withsample_counts=True
this method is a constant time operation. If not, a slower traversal based algorithm is used to count the samples.Parameters: u (int) – The node of interest. Returns: The number of samples in the subtree rooted at u. Return type: int

num_sites
¶ Returns the number of sites on this tree.
Returns: The number of sites on this tree. Return type: int

num_tracked_samples
(u=None)¶ Returns the number of samples in the set specified in the
tracked_samples
parameter of theTreeSequence.trees()
method underneath the specified node. If the input node is not specified, return the total number of tracked samples in the tree.This is a constant time operation.
Parameters: u (int) – The node of interest. Returns: The number of samples within the set of tracked samples in the subtree rooted at u. Return type: int Raises: RuntimeError – if the TreeSequence.trees()
method is not called withsample_counts=True
.

parent
(u)¶ Returns the parent of the specified node. Returns the
NULL
if u is the root or is not a node in the current tree.Parameters: u (int) – The node of interest. Returns: The parent of u. Return type: int

population
(u)¶ Returns the population associated with the specified node. Equivalent to
tree.tree_sequence.node(u).population
.Parameters: u (int) – The node of interest. Returns: The ID of the population associated with node u. Return type: int

prev
()¶ Seeks to the previous tree in the sequence. If the tree is in the initial null state we seek to the last tree (equivalent to calling
last()
). Callingprev
on the first tree in the sequence results in the tree being cleared back into the null initial state (equivalent to callingclear()
). The return value of the function indicates whether the tree is in a nonnull state, and can be used to loop over the trees:# Iterate over the trees from righttoleft tree = tskit.Tree(tree_sequence) while tree.prev() # Do something with the tree. print(tree.index) # tree is now back in the null state.
Returns: True if the tree has been transformed into one of the trees in the sequence; False if the tree has been transformed into the null state. Return type: bool

root
¶ The root of this tree. If the tree contains multiple roots, a ValueError is raised indicating that the
roots
attribute should be used instead.Returns: The root node. Return type: int Raises: ValueError
if this tree contains more than one root.

roots
¶ The list of roots in this tree. A root is defined as a unique endpoint of the paths starting at samples. We can define the set of roots as follows:
roots = set() for u in tree_sequence.samples(): while tree.parent(u) != tskit.NULL: u = tree.parent(u) roots.add(u) # roots is now the set of all roots in this tree. assert sorted(roots) == sorted(tree.roots)
The roots of the tree are returned in a list, in no particular order.
Requires O(number of roots) time.
Returns: The list of roots in this tree. Return type: list

sample_size
¶ Returns the sample size for this tree. This is the number of sample nodes in the tree.
Returns: The number of sample nodes in the tree. Return type: int

samples
(u=None)¶ Returns an iterator over all the samples in this tree that are underneath the specified node. If u is a sample, it is included in the returned iterator. If u is not specified, return all samples in the tree.
If the
TreeSequence.trees()
method is called withsample_lists=True
, this method uses an efficient algorithm to find the samples. If not, a simple traversal based method is used.Parameters: u (int) – The node of interest. Returns: An iterator over all samples in the subtree rooted at u. Return type: iterator

seek
(position)¶ Sets the state to represent the tree that covers the specified position in the parent tree sequence. After a successful return of this method we have
tree.interval[0]
<=position
<tree.interval[1]
.Parameters: position (float) – The position along the sequence length to seek to. Raises: ValueError – If 0 < position or position >= TreeSequence.sequence_length
.

seek_index
(index)¶ Sets the state to represent the tree at the specified index in the parent tree sequence. Negative indexes following the standard Python conventions are allowed, i.e.,
index=1
will seek to the last tree in the sequence.Parameters: index (int) – The tree index to seek to. Raises: IndexError – If an index outside the acceptable range is provided.

sites
()¶ Returns an iterator over all the sites in this tree. Sites are returned in order of increasing ID (and also position). See the
Site
class for details on the available fields for each site.Returns: An iterator over all sites in this tree. Return type: iter( Site
)

time
(u)¶ Returns the time of the specified node in generations. Equivalent to
tree.tree_sequence.node(u).time
.Parameters: u (int) – The node of interest. Returns: The time of u. Return type: float

tmrca
(u, v)¶ Returns the time of the most recent common ancestor of the specified nodes. This is equivalent to:
>>> tree.time(tree.mrca(u, v))
Parameters: Returns: The time of the most recent common ancestor of u and v.
Return type:

total_branch_length
¶ Returns the sum of all the branch lengths in this tree (in units of generations). This is equivalent to
>>> sum( >>> tree.branch_length(u) for u in tree.nodes() >>> if u not in self.roots)
Returns: The sum of all the branch lengths in this tree. Return type: float

tree_sequence
¶ Returns the tree sequence that this tree is from.
Returns: The parent tree sequence for this tree. Return type: TreeSequence
Constants¶

tskit.NULL == 1
Special reserved value representing a null ID.

tskit.FORWARD == 1
Constant representing the forward direction of travel (i.e., increasing genomic coordinate values).

tskit.REVERSE == 1
Constant representing the reverse direction of travel (i.e., decreasing genomic coordinate values).
Simple container classes¶
These classes are simple shallow containers representing the entities defined
in the Definitions. These classes are not intended to be instantiated
directly, but are the return types for the various iterators provided by the
TreeSequence
and Tree
classes.

class
tskit.
Individual
¶ An individual in a tree sequence. Since nodes correspond to genomes, individuals are associated with a collection of nodes (e.g., two nodes per diploid). See Nodes, Genomes, or Individuals? for more discussion of this distinction.
Modifying the attributes in this class will have no effect on the underlying tree sequence data.
Variables:  id (int) – The integer ID of this individual. Varies from 0 to
TreeSequence.num_individuals
 1.  flags (int) – The bitwise flags for this individual.
 location (numpy.ndarray) – The spatial location of this individual as a numpy array. The location is an empty array if no spatial location is defined.
 nodes – The IDs of the nodes that are associated with this individual as a numpy array (dtype=np.int32). If no nodes are associated with the individual this array will be empty.
 metadata (bytes) – The metadata for this individual.
 id (int) – The integer ID of this individual. Varies from 0 to

class
tskit.
Node
¶ A node in a tree sequence, corresponding to a single genome. The
time
andpopulation
are attributes of theNode
, rather than theIndividual
, as discussed in Nodes, Genomes, or Individuals?.Modifying the attributes in this class will have no effect on the underlying tree sequence data.
Variables:  id (int) – The integer ID of this node. Varies from 0 to
TreeSequence.num_nodes
 1.  flags (int) – The bitwise flags for this node.
 time (float) – The birth time of this node.
 population (int) – The integer ID of the population that this node was born in.
 individual (int) – The integer ID of the individual that this node was a part of.
 metadata (bytes) – The metadata for this node.
 id (int) – The integer ID of this node. Varies from 0 to

class
tskit.
Edge
¶ An edge in a tree sequence.
Modifying the attributes in this class will have no effect on the underlying tree sequence data.
Variables:  left (float) – The left coordinate of this edge.
 right (float) – The right coordinate of this edge.
 parent (int) – The integer ID of the parent node for this edge.
To obtain further information about a node with a given ID, use
TreeSequence.node()
.  child (int) – The integer ID of the child node for this edge.
To obtain further information about a node with a given ID, use
TreeSequence.node()
.

class
tskit.
Site
¶ A site in a tree sequence.
Modifying the attributes in this class will have no effect on the underlying tree sequence data.
Variables:  id (int) – The integer ID of this site. Varies from 0 to
TreeSequence.num_sites
 1.  position (float) – The floating point location of this site in genome coordinates.
Ranges from 0 (inclusive) to
TreeSequence.sequence_length
(exclusive).  ancestral_state (str) – The ancestral state at this site (i.e., the state inherited by nodes, unless mutations occur).
 metadata (bytes) – The metadata for this site.
 mutations (list[
Mutation
]) – The list of mutations at this site. Mutations within a site are returned in the order they are specified in the underlyingMutationTable
.
 id (int) – The integer ID of this site. Varies from 0 to

class
tskit.
Mutation
¶ A mutation in a tree sequence.
Modifying the attributes in this class will have no effect on the underlying tree sequence data.
Variables:  id (int) – The integer ID of this mutation. Varies from 0 to
TreeSequence.num_mutations
 1.  site (int) – The integer ID of the site that this mutation occurs at. To obtain
further information about a site with a given ID use
TreeSequence.site()
.  node (int) – The integer ID of the first node that inherits this mutation.
To obtain further information about a node with a given ID, use
TreeSequence.node()
.  derived_state (str) – The derived state for this mutation. This is the state inherited by nodes in the subtree rooted at this mutation’s node, unless another mutation occurs.
 parent (int) – The integer ID of this mutation’s parent mutation. When multiple
mutations occur at a site along a path in the tree, mutations must
record the mutation that is immediately above them. If the mutation does
not have a parent, this is equal to the
NULL
(1). To obtain further information about a mutation with a given ID, useTreeSequence.mutation()
.  metadata (bytes) – The metadata for this site.
 id (int) – The integer ID of this mutation. Varies from 0 to

class
tskit.
Variant
¶ A variant represents the observed variation among the samples for a given site. A variant consists (a) of a reference to the
Site
instance in question; (b) the alleles that may be observed at the samples for this site; and (c) the genotypes mapping sample IDs to the observed alleles.Each element in the
alleles
tuple is a string, representing the actual observed state for a given sample. The first element of this tuple is guaranteed to be the same as the site’sancestral_state
value. The list of alleles is also guaranteed not to contain any duplicates. However, allelic values may be listed that are not referred to by any samples. For example, if we have a site that is fixed for the derived state (i.e., we have a mutation over the tree root), all genotypes will be 1, but the alleles list will be equal to('0', '1')
. Other than the ancestral state being the first allele, the alleles are listed in no particular order, and the ordering should not be relied upon.The
genotypes
represent the observed allelic states for each sample, such thatvar.alleles[var.genotypes[j]]
gives the string allele for sample IDj
. Thus, the elements of the genotypes array are indexes into thealleles
list. The genotypes are provided in this way via a numpy array to enable efficient calculations.Modifying the attributes in this class will have no effect on the underlying tree sequence data.
Variables:  site (
Site
) – The site object for this variant.  alleles (tuple(str)) – A tuple of the allelic values that may be observed at the samples at the current site. The first element of this tuple is always the sites’s ancestral state.
 genotypes (numpy.ndarray) – An array of indexes into the list
alleles
, giving the state of each sample at the current site.
 site (

class
tskit.
Migration
¶ A migration in a tree sequence.
Modifying the attributes in this class will have no effect on the underlying tree sequence data.
Variables:  left (float) – The left end of the genomic interval covered by this migration (inclusive).
 right (float) – The right end of the genomic interval covered by this migration (exclusive).
 node (int) – The integer ID of the node involved in this migration event.
To obtain further information about a node with a given ID, use
TreeSequence.node()
.  source (int) – The source population ID.
 dest (int) – The destination population ID.
 time (float) – The time at which this migration occured at.

class
tskit.
Population
¶ A population in a tree sequence.
Modifying the attributes in this class will have no effect on the underlying tree sequence data.
Variables:  id (int) – The integer ID of this population. Varies from 0 to
TreeSequence.num_populations
 1.  metadata (bytes) – The metadata for this population.
 id (int) – The integer ID of this population. Varies from 0 to
Loading data¶
There are several methods for loading data into a TreeSequence
instance. The simplest and most convenient is the use the tskit.load()
function to load a tree sequence file. For small
scale data and debugging, it is often convenient to use the
tskit.load_text()
to read data in the text file format. The TableCollection.tree_sequence()
function
efficiently creates a TreeSequence
object from a set of tables
using the Tables API.

tskit.
load
(path)¶ Loads a tree sequence from the specified file path. This file must be in the tree sequence file format produced by the
TreeSequence.dump()
method.Parameters: path (str) – The file path of the .trees
file containing the tree sequence we wish to load.Returns: The tree sequence object containing the information stored in the specified file path. Return type: tskit.TreeSequence

tskit.
load_text
(nodes, edges, sites=None, mutations=None, individuals=None, populations=None, sequence_length=0, strict=True, encoding='utf8', base64_metadata=True)¶ Parses the tree sequence data from the specified filelike objects, and returns the resulting
TreeSequence
object. The format for these files is documented in the Text file formats section, and is produced by theTreeSequence.dump_text()
method. Further properties required for an input tree sequence are described in the Valid tree sequence requirements section. This method is intended as a convenient interface for importing external data into tskit; the binary file format using bytskit.load()
is many times more efficient than this text format.The
nodes
andedges
parameters are mandatory and must be filelike objects containing text with whitespace delimited columns, parsable byparse_nodes()
andparse_edges()
, respectively.sites
,mutations
,individuals
andpopulations
are optional, and must be parsable byparse_sites()
,parse_individuals()
,parse_populations()
, andparse_mutations()
, respectively.TODO: there is no method to parse the remaining tables at present, so only tree sequences not requiring Population and Individual tables can be loaded. This will be fixed: https://github.com/tskitdev/msprime/issues/498
The
sequence_length
parameter determines theTreeSequence.sequence_length
of the returned tree sequence. If it is 0 or not specified, the value is taken to be the maximum right coordinate of the input edges. This parameter is useful in degenerate situations (such as when there are zero edges), but can usually be ignored.The
strict
parameter controls the field delimiting algorithm that is used. Ifstrict
is True (the default), we require exactly one tab character separating each field. Ifstrict
is False, a more relaxed whitespace delimiting algorithm is used, such that any run of whitespace is regarded as a field separator. In most situations,strict=False
is more convenient, but it can lead to error in certain situations. For example, if a deletion is encoded in the mutation table this will not be parseable whenstrict=False
.After parsing the tables,
sort_tables()
is called to ensure that the loaded tables satisfy the tree sequence ordering requirements. Note that this may result in the IDs of various entities changing from their positions in the input file.Parameters:  nodes (stream) – The filelike object containing text describing a
NodeTable
.  edges (stream) – The filelike object containing text
describing an
EdgeTable
.  sites (stream) – The filelike object containing text describing a
SiteTable
.  mutations (stream) – The filelike object containing text
describing a
MutationTable
.  individuals (stream) – The filelike object containing text
describing a
IndividualTable
.  populations (stream) – The filelike object containing text
describing a
PopulationTable
.  sequence_length (float) – The sequence length of the returned tree sequence. If not supplied or zero this will be inferred from the set of edges.
 strict (bool) – If True, require strict tab delimiting (default). If False, a relaxed whitespace splitting algorithm is used.
 encoding (string) – Encoding used for text representation.
 base64_metadata (bool) – If True, metadata is encoded using Base64 encoding; otherwise, as plain text.
Returns: The tree sequence object containing the information stored in the specified file paths.
Return type:  nodes (stream) – The filelike object containing text describing a
Tables¶
The tables API provides an efficient way of working
with and interchanging tree sequence data. Each table
class (e.g, NodeTable
, EdgeTable
) has a specific set of
columns with fixed types, and a set of methods for setting and getting the data
in these columns. The number of rows in the table t
is given by len(t)
.
Each table supports accessing the data either by row or column. To access the
row j
in table t
simply use t[j]
. The value returned by such an
access is an instance of collections.namedtuple()
, and therefore supports
either positional or named attribute access. To access the data in
a column, we can use standard attribute access which will return a numpy array
of the data. For example:
>>> import tskit
>>> t = tskit.EdgeTable()
>>> t.add_row(left=0, right=1, parent=10, child=11)
0
>>> t.add_row(left=1, right=2, parent=9, child=11)
1
>>> print(t)
id left right parent child
0 0.00000000 1.00000000 10 11
1 1.00000000 2.00000000 9 11
>>> t[0]
EdgeTableRow(left=0.0, right=1.0, parent=10, child=11)
>>> t[1]
EdgeTableRow(left=1.0, right=2.0, parent=9, child=11)
>>> t.left
array([ 0., 1.])
>>> t.parent
array([10, 9], dtype=int32)
>>> len(t)
2
>>>
Tables also support the pickle
protocol, and so can be easily
serialised and deserialised (for example, when performing parallel
computations using the multiprocessing
module).
>>> serialised = pickle.dumps(t)
>>> t2 = pickle.loads(serialised)
>>> print(t2)
id left right parent child
0 0.00000000 1.00000000 10 11
1 1.00000000 2.00000000 9 11
However, pickling will not be as efficient as storing tables in the native format.
Tables support the equality operator ==
based on the data
held in the columns:
>>> t == t2
True
>>> t is t2
False
>>> t2.add_row(0, 1, 2, 3)
2
>>> print(t2)
id left right parent child
0 0.00000000 1.00000000 10 11
1 1.00000000 2.00000000 9 11
2 0.00000000 1.00000000 2 3
>>> t == t2
False
Text columns¶
As described in the Encoding ragged columns, working with variable length columns is somewhat more involved. Columns encoding text data store the encoded bytes of the flattened strings, and the offsets into this column in two separate arrays.
Consider the following example:
>>> t = tskit.SiteTable()
>>> t.add_row(0, "A")
>>> t.add_row(1, "BB")
>>> t.add_row(2, "")
>>> t.add_row(3, "CCC")
>>> print(t)
id position ancestral_state metadata
0 0.00000000 A
1 1.00000000 BB
2 2.00000000
3 3.00000000 CCC
>>> t[0]
SiteTableRow(position=0.0, ancestral_state='A', metadata=b'')
>>> t[1]
SiteTableRow(position=1.0, ancestral_state='BB', metadata=b'')
>>> t[2]
SiteTableRow(position=2.0, ancestral_state='', metadata=b'')
>>> t[3]
SiteTableRow(position=3.0, ancestral_state='CCC', metadata=b'')
Here we create a SiteTable
and add four rows, each with a different
ancestral_state
. We can then access this information from each
row in a straightforward manner. Working with the data in the columns
is a little trickier, however:
>>> t.ancestral_state
array([65, 66, 66, 67, 67, 67], dtype=int8)
>>> t.ancestral_state_offset
array([0, 1, 3, 3, 6], dtype=uint32)
>>> tskit.unpack_strings(t.ancestral_state, t.ancestral_state_offset)
['A', 'BB', '', 'CCC']
Here, the ancestral_state
array is the UTF8 encoded bytes of the flattened
strings, and the ancestral_state_offset
is the offset into this array
for each row. The unpack_strings()
function, however, is a convient
way to recover the original strings from this encoding. We can also use the
pack_strings()
to insert data using this approach:
>>> a, off = tskit.pack_strings(["0", "12", ""])
>>> t.set_columns(position=[0, 1, 2], ancestral_state=a, ancestral_state_offset=off)
>>> print(t)
id position ancestral_state metadata
0 0.00000000 0
1 1.00000000 12
2 2.00000000
When inserting many rows with standard infinite sites mutations (i.e.,
ancestral state is “0”), it is more efficient to construct the
numpy arrays directly than to create a list of strings and use
pack_strings()
. When doing this, it is important to note that
it is the encoded byte values that are stored; by default, we
use UTF8 (which corresponds to ASCII for simple printable characters).:
>>> t_s = tskit.SiteTable()
>>> m = 10
>>> a = ord("0") + np.zeros(m, dtype=np.int8)
>>> off = np.arange(m + 1, dtype=np.uint32)
>>> t_s.set_columns(position=np.arange(m), ancestral_state=a, ancestral_state_offset=off)
>>> print(t_s)
id position ancestral_state metadata
0 0.00000000 0
1 1.00000000 0
2 2.00000000 0
3 3.00000000 0
4 4.00000000 0
5 5.00000000 0
6 6.00000000 0
7 7.00000000 0
8 8.00000000 0
9 9.00000000 0
>>> t_s.ancestral_state
array([48, 48, 48, 48, 48, 48, 48, 48, 48, 48], dtype=int8)
>>> t_s.ancestral_state_offset
array([ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10], dtype=uint32)
Here we create 10 sites at regular positions, each with ancestral state equal to
“0”. Note that we use ord("0")
to get the ASCII code for “0” (48), and create
10 copies of this by adding it to an array of zeros. We have done this for
illustration purposes: it is equivalent (though slower for large examples) to do
a, off = tskit.pack_strings(["0"] * m)
.
Mutations can be handled similarly:
>>> t_m = tskit.MutationTable()
>>> site = np.arange(m, dtype=np.int32)
>>> d, off = tskit.pack_strings(["1"] * m)
>>> node = np.zeros(m, dtype=np.int32)
>>> t_m.set_columns(site=site, node=node, derived_state=d, derived_state_offset=off)
>>> print(t_m)
id site node derived_state parent metadata
0 0 0 1 1
1 1 0 1 1
2 2 0 1 1
3 3 0 1 1
4 4 0 1 1
5 5 0 1 1
6 6 0 1 1
7 7 0 1 1
8 8 0 1 1
9 9 0 1 1
>>>
Binary columns¶
Columns storing binary data take the same approach as
Text columns to encoding
variable length data.
The difference between the two is
only raw bytes
values are accepted: no character encoding or
decoding is done on the data. Consider the following example:
>>> t = tskit.NodeTable()
>>> t.add_row(metadata=b"raw bytes")
>>> t.add_row(metadata=pickle.dumps({"x": 1.1}))
>>> t[0].metadata
b'raw bytes'
>>> t[1].metadata
b'\x80\x03}q\x00X\x01\x00\x00\x00xq\x01G?\xf1\x99\x99\x99\x99\x99\x9as.'
>>> pickle.loads(t[1].metadata)
{'x': 1.1}
>>> print(t)
id flags population time metadata
0 0 1 0.00000000000000 cmF3IGJ5dGVz
1 0 1 0.00000000000000 gAN9cQBYAQAAAHhxAUc/8ZmZmZmZmnMu
>>> t.metadata
array([ 114, 97, 119, 32, 98, 121, 116, 101, 115, 128, 3,
125, 113, 0, 88, 1, 0, 0, 0, 120, 113, 1,
71, 63, 15, 103, 103, 103, 103, 103, 102, 115, 46], dtype=int8)
>>> t.metadata_offset
array([ 0, 9, 33], dtype=uint32)
Here we add two rows to a NodeTable
, with different
metadata. The first row contains a simple
byte string, and the second contains a Python dictionary serialised using
pickle
. We then show several different (and seemingly incompatible!)
different views on the same data.
When we access the data in a row (e.g., t[0].metadata
) we are returned
a Python bytes object containing precisely the bytes that were inserted.
The pickled dictionary is encoded in 24 bytes containing unprintable
characters, and when we unpickle it using pickle.loads()
, we obtain
the original dictionary.
When we print the table, however, we see some data which is seemingly unrelated to the original contents. This is because the binary data is base64 encoded to ensure that it is printsafe (and doesn’t break your terminal). (See the Metadata section for more information on the use of base64 encoding.).
Finally, when we print the metadata
column, we see the raw byte values
encoded as signed integers. As for Text columns,
the metadata_offset
column encodes the offsets into this array. So, we
see that the first metadata value is 9 bytes long and the second is 24.
The pack_bytes()
and unpack_bytes()
functions are also useful
for encoding data in these columns.
Table classes¶
This section describes the methods and variables available for each table class. For description and definition of each table’s meaning and use, see the table definitions.

class
tskit.
IndividualTable
¶ A table defining the individuals in a tree sequence. Note that although each Individual has associated nodes, reference to these is not stored in the individual table, but rather reference to the individual is stored for each node in the
NodeTable
. This is similar to the way in which the relationship between sites and mutations is modelled.Warning: The numpy arrays returned by table attribute accesses are copies of the underlying data. In particular, this means that you cannot edit the values in the columns by updating the attribute arrays.
NOTE: this behaviour may change in future.
Variables:  flags (numpy.ndarray, dtype=np.uint32) – The array of flags values.
 location (numpy.ndarray, dtype=np.float64) – The flattened array of floating point location values. See Encoding ragged columns for more details.
 location_offset (numpy.ndarray, dtype=np.uint32) – The array of offsets into the location column. See Encoding ragged columns for more details.
 metadata (numpy.ndarray, dtype=np.int8) – The flattened array of binary metadata values. See Binary columns for more details.
 metadata_offset (numpy.ndarray, dtype=np.uint32) – The array of offsets into the metadata column. See Binary columns for more details.

add_row
(flags=0, location=None, metadata=None)¶ Adds a new row to this
IndividualTable
and returns the ID of the corresponding individual.Parameters:  flags (int) – The bitwise flags for the new node.
 location (arraylike) – A list of numeric values or onedimensional numpy array describing the location of this individual. If not specified or None, a zerodimensional location is stored.
 metadata (bytes) – The binaryencoded metadata for the new node. If not specified or None, a zerolength byte string is stored.
Returns: The ID of the newly added node.
Return type:

append_columns
(flags=None, location=None, location_offset=None, metadata=None, metadata_offset=None)¶ Appends the specified arrays to the end of the columns in this
IndividualTable
. This allows many new rows to be added at once.The
flags
array is mandatory and defines the number of extra individuals to add to the table. Thelocation
andlocation_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns. Themetadata
andmetadata_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns. See Binary columns for more information.Parameters:  flags (numpy.ndarray, dtype=np.uint32) – The bitwise flags for each individual. Required.
 location (numpy.ndarray, dtype=np.float64) – The flattened location array. Must be specified along
with
location_offset
. If not specified or None, an empty location value is stored for each individual.  location_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
location
array.  metadata (numpy.ndarray, dtype=np.int8) – The flattened metadata array. Must be specified along
with
metadata_offset
. If not specified or None, an empty metadata value is stored for each individual.  metadata_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
metadata
array.

asdict
()¶ Returns a dictionary mapping the names of the columns in this table to the corresponding numpy arrays.

clear
()¶ Deletes all rows in this table.

copy
()¶ Returns a deep copy of this table.

set_columns
(flags=None, location=None, location_offset=None, metadata=None, metadata_offset=None)¶ Sets the values for each column in this
IndividualTable
using the values in the specified arrays. Overwrites any data currently stored in the table.The
flags
array is mandatory and defines the number of individuals the table will contain. Thelocation
andlocation_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns. Themetadata
andmetadata_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns. See Binary columns for more information.Parameters:  flags (numpy.ndarray, dtype=np.uint32) – The bitwise flags for each individual. Required.
 location (numpy.ndarray, dtype=np.float64) – The flattened location array. Must be specified along
with
location_offset
. If not specified or None, an empty location value is stored for each individual.  location_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
location
array.  metadata (numpy.ndarray, dtype=np.int8) – The flattened metadata array. Must be specified along
with
metadata_offset
. If not specified or None, an empty metadata value is stored for each individual.  metadata_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
metadata
array.

class
tskit.
NodeTable
¶ A table defining the nodes in a tree sequence. See the definitions for details on the columns in this table and the tree sequence requirements section for the properties needed for a node table to be a part of a valid tree sequence.
Warning: The numpy arrays returned by table attribute accesses are copies of the underlying data. In particular, this means that you cannot edit the values in the columns by updating the attribute arrays.
NOTE: this behaviour may change in future.
Variables:  time (numpy.ndarray, dtype=np.float64) – The array of time values.
 flags (numpy.ndarray, dtype=np.uint32) – The array of flags values.
 population (numpy.ndarray, dtype=np.int32) – The array of population IDs.
 individual (numpy.ndarray, dtype=np.int32) – The array of individual IDs that each node belongs to.
 metadata (numpy.ndarray, dtype=np.int8) – The flattened array of binary metadata values. See Binary columns for more details.
 metadata_offset (numpy.ndarray, dtype=np.uint32) – The array of offsets into the metadata column. See Binary columns for more details.

add_row
(flags=0, time=0, population=1, individual=1, metadata=None)¶ Adds a new row to this
NodeTable
and returns the ID of the corresponding node.Parameters:  flags (int) – The bitwise flags for the new node.
 time (float) – The birth time for the new node.
 population (int) – The ID of the population in which the new node was born.
Defaults to
NULL
.  individual (int) – The ID of the individual in which the new node was born.
Defaults to
NULL
.  metadata (bytes) – The binaryencoded metadata for the new node. If not specified or None, a zerolength byte string is stored.
Returns: The ID of the newly added node.
Return type:

append_columns
(flags=None, time=None, population=None, individual=None, metadata=None, metadata_offset=None)¶ Appends the specified arrays to the end of the columns in this
NodeTable
. This allows many new rows to be added at once.The
flags
,time
andpopulation
arrays must all be of the same length, which is equal to the number of nodes that will be added to the table. Themetadata
andmetadata_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns. See Binary columns for more information.Parameters:  flags (numpy.ndarray, dtype=np.uint32) – The bitwise flags for each node. Required.
 time (numpy.ndarray, dtype=np.float64) – The time values for each node. Required.
 population (numpy.ndarray, dtype=np.int32) – The population values for each node. If not specified
or None, the
NULL
value is stored for each node.  individual (numpy.ndarray, dtype=np.int32) – The individual values for each node. If not specified
or None, the
NULL
value is stored for each node.  metadata (numpy.ndarray, dtype=np.int8) – The flattened metadata array. Must be specified along
with
metadata_offset
. If not specified or None, an empty metadata value is stored for each node.  metadata_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
metadata
array.

asdict
()¶ Returns a dictionary mapping the names of the columns in this table to the corresponding numpy arrays.

clear
()¶ Deletes all rows in this table.

copy
()¶ Returns a deep copy of this table.

set_columns
(flags=None, time=None, population=None, individual=None, metadata=None, metadata_offset=None)¶ Sets the values for each column in this
NodeTable
using the values in the specified arrays. Overwrites any data currently stored in the table.The
flags
,time
andpopulation
arrays must all be of the same length, which is equal to the number of nodes the table will contain. Themetadata
andmetadata_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns. See Binary columns for more information.Parameters:  flags (numpy.ndarray, dtype=np.uint32) – The bitwise flags for each node. Required.
 time (numpy.ndarray, dtype=np.float64) – The time values for each node. Required.
 population (numpy.ndarray, dtype=np.int32) – The population values for each node. If not specified
or None, the
NULL
value is stored for each node.  individual (numpy.ndarray, dtype=np.int32) – The individual values for each node. If not specified
or None, the
NULL
value is stored for each node.  metadata (numpy.ndarray, dtype=np.int8) – The flattened metadata array. Must be specified along
with
metadata_offset
. If not specified or None, an empty metadata value is stored for each node.  metadata_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
metadata
array.

class
tskit.
EdgeTable
¶ A table defining the edges in a tree sequence. See the definitions for details on the columns in this table and the tree sequence requirements section for the properties needed for an edge table to be a part of a valid tree sequence.
Warning: The numpy arrays returned by table attribute accesses are copies of the underlying data. In particular, this means that you cannot edit the values in the columns by updating the attribute arrays.
NOTE: this behaviour may change in future.
Variables:  left (numpy.ndarray, dtype=np.float64) – The array of left coordinates.
 right (numpy.ndarray, dtype=np.float64) – The array of right coordinates.
 parent (numpy.ndarray, dtype=np.int32) – The array of parent node IDs.
 child (numpy.ndarray, dtype=np.int32) – The array of child node IDs.

add_row
(left, right, parent, child)¶ Adds a new row to this
EdgeTable
and returns the ID of the corresponding edge.Parameters: Returns: The ID of the newly added edge.
Return type:

append_columns
(left, right, parent, child)¶ Appends the specified arrays to the end of the columns of this
EdgeTable
. This allows many new rows to be added at once.All four parameters are mandatory, and must be numpy arrays of the same length (which is equal to the number of additional edges to add to the table).
Parameters:  left (numpy.ndarray, dtype=np.float64) – The left coordinates (inclusive).
 right (numpy.ndarray, dtype=np.float64) – The right coordinates (exclusive).
 parent (numpy.ndarray, dtype=np.int32) – The parent node IDs.
 child (numpy.ndarray, dtype=np.int32) – The child node IDs.

asdict
()¶ Returns a dictionary mapping the names of the columns in this table to the corresponding numpy arrays.

clear
()¶ Deletes all rows in this table.

copy
()¶ Returns a deep copy of this table.

set_columns
(left=None, right=None, parent=None, child=None)¶ Sets the values for each column in this
EdgeTable
using the values in the specified arrays. Overwrites any data currently stored in the table.All four parameters are mandatory, and must be numpy arrays of the same length (which is equal to the number of edges the table will contain).
Parameters:  left (numpy.ndarray, dtype=np.float64) – The left coordinates (inclusive).
 right (numpy.ndarray, dtype=np.float64) – The right coordinates (exclusive).
 parent (numpy.ndarray, dtype=np.int32) – The parent node IDs.
 child (numpy.ndarray, dtype=np.int32) – The child node IDs.

class
tskit.
MigrationTable
¶ A table defining the migrations in a tree sequence. See the definitions for details on the columns in this table and the tree sequence requirements section for the properties needed for a migration table to be a part of a valid tree sequence.
Warning: The numpy arrays returned by table attribute accesses are copies of the underlying data. In particular, this means that you cannot edit the values in the columns by updating the attribute arrays.
NOTE: this behaviour may change in future.
Variables:  left (numpy.ndarray, dtype=np.float64) – The array of left coordinates.
 right (numpy.ndarray, dtype=np.float64) – The array of right coordinates.
 node (numpy.ndarray, dtype=np.int32) – The array of node IDs.
 source (numpy.ndarray, dtype=np.int32) – The array of source population IDs.
 dest (numpy.ndarray, dtype=np.int32) – The array of destination population IDs.
 time (numpy.ndarray, dtype=np.float64) – The array of time values.

add_row
(left, right, node, source, dest, time)¶ Adds a new row to this
MigrationTable
and returns the ID of the corresponding migration.Parameters: Returns: The ID of the newly added migration.
Return type:

append_columns
(left, right, node, source, dest, time)¶ Appends the specified arrays to the end of the columns of this
MigrationTable
. This allows many new rows to be added at once.All six parameters are mandatory, and must be numpy arrays of the same length (which is equal to the number of additional migrations to add to the table).
Parameters:  left (numpy.ndarray, dtype=np.float64) – The left coordinates (inclusive).
 right (numpy.ndarray, dtype=np.float64) – The right coordinates (exclusive).
 node (numpy.ndarray, dtype=np.int32) – The node IDs.
 source (numpy.ndarray, dtype=np.int32) – The source population IDs.
 dest (numpy.ndarray, dtype=np.int32) – The destination population IDs.
 time (numpy.ndarray, dtype=np.int64) – The time of each migration.

asdict
()¶ Returns a dictionary mapping the names of the columns in this table to the corresponding numpy arrays.

clear
()¶ Deletes all rows in this table.

copy
()¶ Returns a deep copy of this table.

set_columns
(left=None, right=None, node=None, source=None, dest=None, time=None)¶ Sets the values for each column in this
MigrationTable
using the values in the specified arrays. Overwrites any data currently stored in the table.All six parameters are mandatory, and must be numpy arrays of the same length (which is equal to the number of migrations the table will contain).
Parameters:  left (numpy.ndarray, dtype=np.float64) – The left coordinates (inclusive).
 right (numpy.ndarray, dtype=np.float64) – The right coordinates (exclusive).
 node (numpy.ndarray, dtype=np.int32) – The node IDs.
 source (numpy.ndarray, dtype=np.int32) – The source population IDs.
 dest (numpy.ndarray, dtype=np.int32) – The destination population IDs.
 time (numpy.ndarray, dtype=np.int64) – The time of each migration.

class
tskit.
SiteTable
¶ A table defining the sites in a tree sequence. See the definitions for details on the columns in this table and the tree sequence requirements section for the properties needed for a site table to be a part of a valid tree sequence.
Warning: The numpy arrays returned by table attribute accesses are copies of the underlying data. In particular, this means that you cannot edit the values in the columns by updating the attribute arrays.
NOTE: this behaviour may change in future.
Variables:  position (numpy.ndarray, dtype=np.float64) – The array of site position coordinates.
 ancestral_state (numpy.ndarray, dtype=np.int8) – The flattened array of ancestral state strings. See Text columns for more details.
 ancestral_state_offset (numpy.ndarray, dtype=np.uint32) – The offsets of rows in the ancestral_state array. See Text columns for more details.
 metadata (numpy.ndarray, dtype=np.int8) – The flattened array of binary metadata values. See Binary columns for more details.
 metadata_offset (numpy.ndarray, dtype=np.uint32) – The array of offsets into the metadata column. See Binary columns for more details.

add_row
(position, ancestral_state, metadata=None)¶ Adds a new row to this
SiteTable
and returns the ID of the corresponding site.Parameters: Returns: The ID of the newly added site.
Return type:

append_columns
(position, ancestral_state, ancestral_state_offset, metadata=None, metadata_offset=None)¶ Appends the specified arrays to the end of the columns of this
SiteTable
. This allows many new rows to be added at once.The
position
,ancestral_state
andancestral_state_offset
parameters are mandatory, and must be 1D numpy arrays. The length of theposition
array determines the number of additional rows to add the table. Theancestral_state
andancestral_state_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns (see Text columns for more information). Themetadata
andmetadata_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns (see Binary columns for more information).Parameters:  position (numpy.ndarray, dtype=np.float64) – The position of each site in genome coordinates.
 ancestral_state (numpy.ndarray, dtype=np.int8) – The flattened ancestral_state array. Required.
 ancestral_state_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
ancestral_state
array.  metadata (numpy.ndarray, dtype=np.int8) – The flattened metadata array. Must be specified along
with
metadata_offset
. If not specified or None, an empty metadata value is stored for each node.  metadata_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
metadata
array.

asdict
()¶ Returns a dictionary mapping the names of the columns in this table to the corresponding numpy arrays.

clear
()¶ Deletes all rows in this table.

copy
()¶ Returns a deep copy of this table.

set_columns
(position=None, ancestral_state=None, ancestral_state_offset=None, metadata=None, metadata_offset=None)¶ Sets the values for each column in this
SiteTable
using the values in the specified arrays. Overwrites any data currently stored in the table.The
position
,ancestral_state
andancestral_state_offset
parameters are mandatory, and must be 1D numpy arrays. The length of theposition
array determines the number of rows in table. Theancestral_state
andancestral_state_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns (see Text columns for more information). Themetadata
andmetadata_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns (see Binary columns for more information).Parameters:  position (numpy.ndarray, dtype=np.float64) – The position of each site in genome coordinates.
 ancestral_state (numpy.ndarray, dtype=np.int8) – The flattened ancestral_state array. Required.
 ancestral_state_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
ancestral_state
array.  metadata (numpy.ndarray, dtype=np.int8) – The flattened metadata array. Must be specified along
with
metadata_offset
. If not specified or None, an empty metadata value is stored for each node.  metadata_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
metadata
array.

class
tskit.
MutationTable
¶ A table defining the mutations in a tree sequence. See the definitions for details on the columns in this table and the tree sequence requirements section for the properties needed for a mutation table to be a part of a valid tree sequence.
Warning: The numpy arrays returned by table attribute accesses are copies of the underlying data. In particular, this means that you cannot edit the values in the columns by updating the attribute arrays.
NOTE: this behaviour may change in future.
Variables:  site (numpy.ndarray, dtype=np.int32) – The array of site IDs.
 node (numpy.ndarray, dtype=np.int32) – The array of node IDs.
 derived_state (numpy.ndarray, dtype=np.int8) – The flattened array of derived state strings. See Text columns for more details.
 derived_state_offset (numpy.ndarray, dtype=np.uint32) – The offsets of rows in the derived_state array. See Text columns for more details.
 parent (numpy.ndarray, dtype=np.int32) – The array of parent mutation IDs.
 metadata (numpy.ndarray, dtype=np.int8) – The flattened array of binary metadata values. See Binary columns for more details.
 metadata_offset (numpy.ndarray, dtype=np.uint32) – The array of offsets into the metadata column. See Binary columns for more details.

add_row
(site, node, derived_state, parent=1, metadata=None)¶ Adds a new row to this
MutationTable
and returns the ID of the corresponding mutation.Parameters:  site (int) – The ID of the site that this mutation occurs at.
 node (int) – The ID of the first node inheriting this mutation.
 derived_state (str) – The state of the site at this mutation’s node.
 parent (int) – The ID of the parent mutation. If not specified,
defaults to
NULL
.  metadata (bytes) – The binaryencoded metadata for the new node. If not specified or None, a zerolength byte string is stored.
Returns: The ID of the newly added mutation.
Return type:

append_columns
(site, node, derived_state, derived_state_offset, parent=None, metadata=None, metadata_offset=None)¶ Appends the specified arrays to the end of the columns of this
MutationTable
. This allows many new rows to be added at once.The
site
,node
,derived_state
andderived_state_offset
parameters are mandatory, and must be 1D numpy arrays. Thesite
andnode
(alsoparent
, if supplied) arrays must be of equal length, and determine the number of additional rows to add to the table. Thederived_state
andderived_state_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns (see Text columns for more information). Themetadata
andmetadata_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns (see Binary columns for more information).Parameters:  site (numpy.ndarray, dtype=np.int32) – The ID of the site each mutation occurs at.
 node (numpy.ndarray, dtype=np.int32) – The ID of the node each mutation is associated with.
 derived_state (numpy.ndarray, dtype=np.int8) – The flattened derived_state array. Required.
 derived_state_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
derived_state
array.  parent (numpy.ndarray, dtype=np.int32) – The ID of the parent mutation for each mutation.
 metadata (numpy.ndarray, dtype=np.int8) – The flattened metadata array. Must be specified along
with
metadata_offset
. If not specified or None, an empty metadata value is stored for each node.  metadata_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
metadata
array.

asdict
()¶ Returns a dictionary mapping the names of the columns in this table to the corresponding numpy arrays.

clear
()¶ Deletes all rows in this table.

copy
()¶ Returns a deep copy of this table.

set_columns
(site=None, node=None, derived_state=None, derived_state_offset=None, parent=None, metadata=None, metadata_offset=None)¶ Sets the values for each column in this
MutationTable
using the values in the specified arrays. Overwrites any data currently stored in the table.The
site
,node
,derived_state
andderived_state_offset
parameters are mandatory, and must be 1D numpy arrays. Thesite
andnode
(alsoparent
, if supplied) arrays must be of equal length, and determine the number of rows in the table. Thederived_state
andderived_state_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns (see Text columns for more information). Themetadata
andmetadata_offset
parameters must be supplied together, and meet the requirements for Encoding ragged columns (see Binary columns for more information).Parameters:  site (numpy.ndarray, dtype=np.int32) – The ID of the site each mutation occurs at.
 node (numpy.ndarray, dtype=np.int32) – The ID of the node each mutation is associated with.
 derived_state (numpy.ndarray, dtype=np.int8) – The flattened derived_state array. Required.
 derived_state_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
derived_state
array.  parent (numpy.ndarray, dtype=np.int32) – The ID of the parent mutation for each mutation.
 metadata (numpy.ndarray, dtype=np.int8) – The flattened metadata array. Must be specified along
with
metadata_offset
. If not specified or None, an empty metadata value is stored for each node.  metadata_offset (numpy.ndarray, dtype=np.uint32.) – The offsets into the
metadata
array.

class
tskit.
PopulationTable
¶ A table defining the populations referred to in a tree sequence. The PopulationTable stores metadata for populations that may be referred to in the NodeTable and MigrationTable”. Note that although nodes may be associated with populations, this association is stored in the
NodeTable
: only metadata on each population is stored in the population table.Warning: The numpy arrays returned by table attribute accesses are copies of the underlying data. In particular, this means that you cannot edit the values in the columns by updating the attribute arrays.
NOTE: this behaviour may change in future.
Variables:  metadata (numpy.ndarray, dtype=np.int8) – The flattened array of binary metadata values. See Binary columns for more details.
 metadata_offset (numpy.ndarray, dtype=np.uint32) – The array of offsets into the metadata column. See Binary columns for more details.

add_row
(metadata=None)¶ Adds a new row to this
PopulationTable
and returns the ID of the corresponding population.Parameters: metadata (bytes) – The binaryencoded metadata for the new population. If not specified or None, a zerolength byte string is stored. Returns: The ID of the newly added population. Return type: int

asdict
()¶ Returns a dictionary mapping the names of the columns in this table to the corresponding numpy arrays.

clear
()¶ Deletes all rows in this table.

copy
()¶ Returns a deep copy of this table.

class
tskit.
ProvenanceTable
¶ A table recording the provenance (i.e., history) of this table, so that the origin of the underlying data and sequence of subsequent operations can be traced. Each row contains a “record” string (recommended format: JSON) and a timestamp.
Todo
The format of the record field will be more precisely specified in the future.
Variables:  record (numpy.ndarray, dtype=np.int8) – The flattened array containing the record strings. Text columns for more details.
 record_offset (numpy.ndarray, dtype=np.uint32) – The array of offsets into the record column. See Text columns for more details.
 timestamp (numpy.ndarray, dtype=np.int8) – The flattened array containing the timestamp strings. Text columns for more details.
 timestamp_offset (numpy.ndarray, dtype=np.uint32) – The array of offsets into the timestamp column. See Text columns for more details.

add_row
(record, timestamp=None)¶ Adds a new row to this ProvenanceTable consisting of the specified record and timestamp. If timestamp is not specified, it is automatically generated from the current time.
Parameters:

asdict
()¶ Returns a dictionary mapping the names of the columns in this table to the corresponding numpy arrays.

clear
()¶ Deletes all rows in this table.

copy
()¶ Returns a deep copy of this table.
Table Collections¶
Each of the table classes defines a different aspect of the structure of
a tree sequence. It is convenient to be able to refer to a set of these
tables which together define a tree sequence. We
refer to this grouping of related tables as a TableCollection
.
The TableCollection
and TreeSequence
classes are
deeply related. A TreeSequence
instance is based on the information
encoded in a TableCollection
. Tree sequences are immutable, and
provide methods for obtaining trees from the sequence. A TableCollection
is mutable, and does not have any methods for obtaining trees.
The TableCollection
class essentially exists to allow the
dynamic creation of tree sequences.

class
tskit.
TableCollection
(sequence_length=0)¶ A collection of mutable tables defining a tree sequence. See the Data model section for definition on the various tables and how they together define a
TreeSequence
. Arbitrary data can be stored in a TableCollection, but there are certain requirements that must be satisfied for these tables to be interpreted as a tree sequence.To obtain a
TreeSequence
instance corresponding to the current state of aTableCollection
, please use thetree_sequence()
method.Variables:  individuals (IndividualTable) – The individual table.
 nodes (NodeTable) – The node table.
 edges (EdgeTable) – The edge table.
 migrations (MigrationTable) – The migration table.
 sites (SiteTable) – The site table.
 mutations (MutationTable) – The mutation table.
 populations (PopulationTable) – The population table.
 provenances (ProvenanceTable) – The provenance table.
 sequence_length (float) – The sequence length defining the coordinate space.
 file_uuid (str) – The UUID for the file this TableCollection is derived from, or None if not derived from a file.

asdict
()¶ Returns a dictionary representation of this TableCollection.
Note: the semantics of this method changed at tskit 1.0.0. Previously a map of table names to the tables themselves was returned.

build_index
()¶ Builds an index on this TableCollection. Any existing indexes are automatically dropped.

compute_mutation_parents
()¶ Modifies the tables in place, computing the
parent
column of the mutation table. For this to work, the node and edge tables must be valid, and the site and mutation tables must be sorted (seeTableCollection.sort()
). This will produce an error if mutations are not sorted (i.e., if a mutation appears before its mutation parent) unless the two mutations occur on the same branch, in which case there is no way to detect the error.The
parent
of a given mutation is the ID of the next mutation encountered traversing the tree upwards from that mutation, orNULL
if there is no such mutation.

deduplicate_sites
()¶ Modifies the tables in place, removing entries in the site table with duplicate
position
(and keeping only the first entry for each site), and renumbering thesite
column of the mutation table appropriately. This requires the site table to be sorted by position.

drop_index
()¶ Drops an indexes present on this table collection. If the table are not currently indexed this method has no effect.

has_index
()¶ Returns True if this TableCollection is indexed.

simplify
(samples=None, filter_zero_mutation_sites=None, reduce_to_site_topology=False, filter_populations=True, filter_individuals=True, filter_sites=True)¶ Simplifies the tables in place to retain only the information necessary to reconstruct the tree sequence describing the given
samples
. This will change the ID of the nodes, so that the nodesamples[k]
will have IDk
in the result. The resulting NodeTable will have only the firstlen(samples)
individuals marked as samples. The mapping from node IDs in the current set of tables to their equivalent values in the simplified tables is also returned as a numpy array. If an arraya
is returned by this function andu
is the ID of a node in the input table, thena[u]
is the ID of this node in the output table. For any nodeu
that is not mapped into the output tables, this mapping will equal1
.Tables operated on by this function must: be sorted (see
TableCollection.sort()
)), have children be born strictly after their parents, and the intervals on which any individual is a child must be disjoint. Other than this the tables need not satisfy remaining requirements to specify a valid tree sequence (but the resulting tables will).Please see the
TreeSequence.simplify()
method for a description of the remaining parameters.Parameters:  samples (list[int]) – A list of node IDs to retain as samples. If not specified or None, use all nodes marked with the IS_SAMPLE flag.
 filter_zero_mutation_sites (bool) – Deprecated alias for
filter_sites
.  reduce_to_site_topology (bool) – Whether to reduce the topology down to the trees that are present at sites. (default: False).
 filter_populations (bool) – If True, remove any populations that are not referenced by nodes after simplification; new population IDs are allocated sequentially from zero. If False, the population table will not be altered in any way. (Default: True)
 filter_individuals (bool) – If True, remove any individuals that are not referenced by nodes after simplification; new individual IDs are allocated sequentially from zero. If False, the individual table will not be altered in any way. (Default: True)
 filter_sites (bool) – If True, remove any sites that are not referenced by mutations after simplification; new site IDs are allocated sequentially from zero. If False, the site table will not be altered in any way. (Default: True)
Returns: A numpy array mapping node IDs in the input tables to their corresponding node IDs in the output tables.
Return type: numpy array (dtype=np.int32)

sort
(edge_start=0)¶ Sorts the tables in place. This ensures that all tree sequence ordering requirements listed in the Valid tree sequence requirements section are met, as long as each site has at most one mutation (see below).
If the
edge_start
parameter is provided, this specifies the index in the edge table where sorting should start. Only rows with index greater than or equal toedge_start
are sorted; rows before this index are not affected. This parameter is provided to allow for efficient sorting when the user knows that the edges up to a given index are already sorted.The individual, node, population and provenance tables are not affected by this method.
Edges are sorted as follows:
 time of parent, then
 parent node ID, then
 child node ID, then
 left endpoint.
Note that this sorting order exceeds the edge sorting requirements for a valid tree sequence. For a valid tree sequence, we require that all edges for a given parent ID are adjacent, but we do not require that they be listed in sorted order.
Sites are sorted by position, and sites with the same position retain their relative ordering.
Mutations are sorted by site ID, and mutations with the same site retain their relative ordering. This does not currently rearrange tables so that mutations occur after their mutation parents, which is a requirement for valid tree sequences.
Parameters: edge_start (int) – The index in the edge table where sorting starts (default=0; must be <= len(edges)).

tree_sequence
()¶ Returns a
TreeSequence
instance with the structure defined by the tables in thisTableCollection
. If the table collection is not in canonical form (i.e., does not meet sorting requirements) or cannot be interpreted as a tree sequence an exception is raised. Thesort()
method may be used to ensure that input sorting requirements are met.Returns: A TreeSequence
instance reflecting the structures defined in this set of tables.Return type: TreeSequence
Table functions¶

tskit.
parse_nodes
(source, strict=True, encoding='utf8', base64_metadata=True, table=None)¶ Parse the specified filelike object containing a whitespace delimited description of a node table and returns the corresponding
NodeTable
instance. See the node text format section for the details of the required format and the node table definition section for the required properties of the contents.See
load_text()
for a detailed explanation of thestrict
parameter.Parameters:  source (stream) – The filelike object containing the text.
 strict (bool) – If True, require strict tab delimiting (default). If False, a relaxed whitespace splitting algorithm is used.
 encoding (string) – Encoding used for text representation.
 base64_metadata (bool) – If True, metadata is encoded using Base64 encoding; otherwise, as plain text.
 table (NodeTable) – If specified write into this table. If not,
create a new
NodeTable
instance.

tskit.
parse_edges
(source, strict=True, table=None)¶ Parse the specified filelike object containing a whitespace delimited description of a edge table and returns the corresponding
EdgeTable
instance. See the edge text format section for the details of the required format and the edge table definition section for the required properties of the contents.See
load_text()
for a detailed explanation of thestrict
parameter.Parameters:  source (stream) – The filelike object containing the text.
 strict (bool) – If True, require strict tab delimiting (default). If False, a relaxed whitespace splitting algorithm is used.
 table (EdgeTable) – If specified, write the edges into this table. If
not, create a new
EdgeTable
instance and return.

tskit.
parse_sites
(source, strict=True, encoding='utf8', base64_metadata=True, table=None)¶ Parse the specified filelike object containing a whitespace delimited description of a site table and returns the corresponding
SiteTable
instance. See the site text format section for the details of the required format and the site table definition section for the required properties of the contents.See
load_text()
for a detailed explanation of thestrict
parameter.Parameters:  source (stream) – The filelike object containing the text.
 strict (bool) – If True, require strict tab delimiting (default). If False, a relaxed whitespace splitting algorithm is used.
 encoding (string) – Encoding used for text representation.
 base64_metadata (bool) – If True, metadata is encoded using Base64 encoding; otherwise, as plain text.
 table (SiteTable) – If specified write site into this table. If not,
create a new
SiteTable
instance.

tskit.
parse_mutations
(source, strict=True, encoding='utf8', base64_metadata=True, table=None)¶ Parse the specified filelike object containing a whitespace delimited description of a mutation table and returns the corresponding
MutationTable
instance. See the mutation text format section for the details of the required format and the mutation table definition section for the required properties of the contents.See
load_text()
for a detailed explanation of thestrict
parameter.Parameters:  source (stream) – The filelike object containing the text.
 strict (bool) – If True, require strict tab delimiting (default). If False, a relaxed whitespace splitting algorithm is used.
 encoding (string) – Encoding used for text representation.
 base64_metadata (bool) – If True, metadata is encoded using Base64 encoding; otherwise, as plain text.
 table (MutationTable) – If specified, write mutations into this table.
If not, create a new
MutationTable
instance.

tskit.
pack_strings
(strings, encoding='utf8')¶ Packs the specified list of strings into a flattened numpy array of 8 bit integers and corresponding offsets using the specified text encoding. See Encoding ragged columns for details of this encoding of columns of variable length data.
Parameters: Returns: The tuple (packed, offset) of numpy arrays representing the flattened input data and offsets.
Return type: numpy.array (dtype=np.int8), numpy.array (dtype=np.uint32)

tskit.
unpack_strings
(packed, offset, encoding='utf8')¶ Unpacks a list of strings from the specified numpy arrays of packed byte data and corresponding offsets using the specified text encoding. See Encoding ragged columns for details of this encoding of columns of variable length data.
Parameters: Returns: The list of strings unpacked from the parameter arrays.
Return type:

tskit.
pack_bytes
(data)¶ Packs the specified list of bytes into a flattened numpy array of 8 bit integers and corresponding offsets. See Encoding ragged columns for details of this encoding.
Parameters: data (list[bytes]) – The list of bytes values to encode. Returns: The tuple (packed, offset) of numpy arrays representing the flattened input data and offsets. Return type: numpy.array (dtype=np.int8), numpy.array (dtype=np.uint32)

tskit.
unpack_bytes
(packed, offset)¶ Unpacks a list of bytes from the specified numpy arrays of packed byte data and corresponding offsets. See Encoding ragged columns for details of this encoding.
Parameters:  packed (numpy.ndarray) – The flattened array of byte values.
 offset (numpy.ndarray) – The array of offsets into the
packed
array.
Returns: The list of bytes values unpacked from the parameter arrays.
Return type:
Statistics¶
The tskit
API provides methods for efficiently calculating
population genetics statistics from a given TreeSequence
.

class
tskit.
LdCalculator
(tree_sequence)¶ Class for calculating linkage disequilibrium coefficients between pairs of mutations in a
TreeSequence
. This class requires the numpy library.This class supports multithreaded access using the Python
threading
module. Separate instances ofLdCalculator
referencing the same tree sequence can operate in parallel in multiple threads.Note
This class does not currently support sites that have more than one mutation. Using it on such a tree sequence will raise a LibraryError with an “Unsupported operation” message.
Parameters: tree_sequence (TreeSequence) – The tree sequence containing the mutations we are interested in. 
r2
(a, b)¶ Returns the value of the \(r^2\) statistic between the pair of mutations at the specified indexes. This method is not an efficient method for computing large numbers of pairwise; please use either
r2_array()
orr2_matrix()
for this purpose.Parameters: Returns: The value of \(r^2\) between the mutations at indexes
a
andb
.Return type:

r2_array
(a, direction=1, max_mutations=None, max_distance=None)¶ Returns the value of the \(r^2\) statistic between the focal mutation at index \(a\) and a set of other mutations. The method operates by starting at the focal mutation and iterating over adjacent mutations (in either the forward or backwards direction) until either a maximum number of other mutations have been considered (using the
max_mutations
parameter), a maximum distance in sequence coordinates has been reached (using themax_distance
parameter) or the start/end of the sequence has been reached. For every mutation \(b\) considered, we then insert the value of \(r^2\) between \(a\) and \(b\) at the corresponding index in an array, and return the entire array. If the returned array is \(x\) anddirection
istskit.FORWARD
then \(x[0]\) is the value of the statistic for \(a\) and \(a + 1\), \(x[1]\) the value for \(a\) and \(a + 2\), etc. Similarly, ifdirection
istskit.REVERSE
then \(x[0]\) is the value of the statistic for \(a\) and \(a  1\), \(x[1]\) the value for \(a\) and \(a  2\), etc.Parameters:  a (int) – The index of the focal mutation.
 direction (int) – The direction in which to travel when
examining other mutations. Must be either
tskit.FORWARD
ortskit.REVERSE
. Defaults totskit.FORWARD
.  max_mutations (int) – The maximum number of mutations to return \(r^2\) values for. Defaults to as many mutations as possible.
 max_distance (float) – The maximum absolute distance between the focal mutation and those for which \(r^2\) values are returned.
Returns: An array of double precision floating point values representing the \(r^2\) values for mutations in the specified direction.
Return type: numpy.ndarray
Warning: For efficiency reasons, the underlying memory used to store the returned array is shared between calls. Therefore, if you wish to store the results of a single call to
get_r2_array()
for later processing you must take a copy of the array!

r2_matrix
()¶ Returns the complete \(m \times m\) matrix of pairwise \(r^2\) values in a tree sequence with \(m\) mutations.
Returns: An 2 dimensional square array of double precision floating point values representing the \(r^2\) values for all pairs of mutations. Return type: numpy.ndarray

Provenance¶
We provide some preliminary support for validating JSON documents against the provenance schema. Programmatic access to provenance information is planned for future versions.

tskit.
validate_provenance
(provenance)¶ Validates the specified dictlike object against the tskit provenance schema. If the input does not represent a valid instance of the schema an exception is raised.
Parameters: provenance (dict) – The dictionary representing a JSON document to be validated against the schema. Raises: ProvenanceValidationError

tskit.
ProvenanceValidationError
¶