# C API¶

This is the documentation for the tskit C API, a low-level library for manipulating and processing tree sequence data. The library is written using the C99 standard and is fully thread safe. Tskit uses kastore to define a simple storage format for the tree sequence data.

To see the API in action, please see Examples section.

## Overview¶

### Do I need the C API?¶

The tskit C API is generally useful in the following situations:

• You want to use the tskit API in a larger C/C++ application (e.g., in order to output data in the .trees format);

• You need to perform lots of tree traversals/loops etc to analyse some data that is in tree sequence form.

For high level operations that are not performance sensitive, the Python API is generally more useful. Python is much more convenient that C, and since the tskit Python module is essentially a wrapper for this C library, there’s often no real performance penalty for using it.

### API structure¶

Tskit uses a set of conventions to provide a pseudo object oriented API. Each ‘object’ is represented by a C struct and has a set of ‘methods’. This is most easily explained by an example:

#include <stdio.h>
#include <stdlib.h>
#include <tskit/tables.h>

#define check_tsk_error(val)                                                            \
if (val < 0) {                                                                      \
fprintf(stderr, "line %d: %s", __LINE__, tsk_strerror(val));                    \
exit(EXIT_FAILURE);                                                             \
}

int
main(int argc, char **argv)
{
int j, ret;
tsk_edge_table_t edges;

ret = tsk_edge_table_init(&edges, 0);
check_tsk_error(ret);
for (j = 0; j < 5; j++) {
ret = tsk_edge_table_add_row(&edges, 0, 1, j + 1, j, NULL, 0);
check_tsk_error(ret);
}
tsk_edge_table_print_state(&edges, stdout);
tsk_edge_table_free(&edges);

return EXIT_SUCCESS;
}


In this program we create a tsk_edge_table_t instance, add five rows using tsk_edge_table_add_row(), print out its contents using the tsk_edge_table_print_state() debugging method, and finally free the memory used by the edge table object. We define this edge table ‘class’ by using some simple naming conventions which are adhered to throughout tskit. This is simply a naming convention that helps to keep code written in plain C logically structured; there are no extra C++ style features. We use object oriented terminology freely throughout this documentation with this understanding.

In this convention, a class is defined by a struct class_name_t (e.g. edge_table_t) and its methods all have the form class_name_method_name whose first argument is always a pointer to an instance of the class (e.g., edge_table_add_row above). Each class has an initialise and free method, called class_name_init and class_name_free, respectively. The init method must be called to ensure that the object is correctly initialised (except for functions such as for tsk_table_collection_load() and tsk_table_collection_copy() which automatically initialise the object by default for convenience). The free method must always be called to avoid leaking memory, even in the case of an error occuring during initialisation. If class_name_init has been called succesfully, we say the object has been “initialised”; if not, it is “uninitialised”. After class_name_free has been called, the object is again uninitialised.

It is important to note that the init methods only allocate internal memory; the memory for the instance itself must be allocated either on the heap or the stack:

// Instance allocated on the stack
tsk_node_table_t nodes;
tsk_node_table_init(&nodes, 0);
tsk_node_table_free(&nodes);

// Instance allocated on the heap
tsk_edge_table_t *edges = malloc(sizeof(tsk_edge_table_t));
tsk_edge_table_init(edges, 0);
tsk_edge_table_free(edges);
free(edges);


### Error handling¶

C does not have a mechanism for propagating exceptions, and great care must be taken to ensure that errors are correctly and safely handled. The convention adopted in tskit is that every function (except for trivial accessor methods) returns an integer. If this return value is negative an error has occured which must be handled. A description of the error that occured can be obtained using the tsk_strerror() function. The following example illustrates the key conventions around error handling in tskit:

#include <stdio.h>
#include <stdlib.h>
#include <tskit.h>

int
main(int argc, char **argv)
{
int ret;
tsk_treeseq_t ts;

if (argc != 2) {
fprintf(stderr, "usage: <tree sequence file>");
exit(EXIT_FAILURE);
}
if (ret < 0) {
/* Error condition. Free and exit */
tsk_treeseq_free(&ts);
fprintf(stderr, "%s", tsk_strerror(ret));
exit(EXIT_FAILURE);
}
printf("Loaded tree sequence with %lld nodes and %lld edges from %s\n",
(long long) tsk_treeseq_get_num_nodes(&ts),
(long long) tsk_treeseq_get_num_edges(&ts),
argv[1]);
tsk_treeseq_free(&ts);

return EXIT_SUCCESS;
}


In this example we load a tree sequence from file and print out a summary of the number of nodes and edges it contains. After calling tsk_treeseq_load() we check the return value ret to see if an error occured. If an error has occured we exit with an error message produced by tsk_strerror(). Note that in this example we call tsk_treeseq_free() whether or not an error occurs: in general, once a function that initialises an object (e.g., X_init, X_copy or X_load) is called, then X_free must be called to ensure that memory is not leaked.

Most functions in tskit return an error status; we recommend that every return value is checked.

### Using tskit in your project¶

Tskit is built as a standard C library and so there are many different ways in which it can be included in downstream projects. It is possible to install tskit onto a system (i.e., installing a shared library and header files to a standard locations on Unix) and linking against it, but there are many different ways in which this can go wrong. In the interest of simplicity and improving the end-user experience we recommend embedding tskit directly into your applications.

There are many different build systems and approaches to compiling code, and so it’s not possible to give definitive documentation on how tskit should be included in downstream projects. Please see the build examples repo for some examples of how to incorporate tskit into different project structures and build systems.

Tskit uses the meson build system internally, and supports being used a meson subproject. We show an example in which this is combined with git submodules to neatly abstract many details of cross platform C development.

Some users may choose to check the source for tskit (and kastore) directly into their source control repositories. If you wish to do this, the code is in the c subdirectory of the tskit and kastore repos. The following header files should be placed in the search path: kastore.h, tskit.h, and tskit/*.h. The C files kastore.c and tskit*.c should be compiled. For those who wish to minimise the size of their compiled binaries, tskit is quite modular, and C files can be omitted if not needed. For example, if you are just using the Tables API then only the files tskit/core.[c,h] and tskit/tables.[c,h] are needed.

However you include tskit in your project, however, please ensure that it is a released version. Released versions are tagged on GitHub using the convention C_{VERSION}. The code can either be downloaded from GitHub on the releases page or checked out using git. For example, to check out the C_0.99.1 release:

$git clone https://github.com/tskit-dev/tskit.git$ cd tskit
$git checkout C_0.99.1  Git submodules may also be considered—see the example for how to set these up and to check out at a specific release. ## Basic Types¶ typedef int32_t tsk_id_t Tskit Object IDs. All objects in tskit are referred to by integer IDs corresponding to the row they occupy in the relevant table. The tsk_id_t type should be used when manipulating these ID values. The reserved value TSK_NULL (-1) defines missing data. typedef uint32_t tsk_size_t Tskit sizes. Sizes in tskit are defined by the tsk_size_t type. typedef uint32_t tsk_flags_t Container for bitwise flags. Bitwise flags are used in tskit as a column type and also as a way to specify options to API functions. ## Common options¶ TSK_DEBUG (1u << 31) Turn on debugging output. Not supported by all functions. TSK_NO_INIT (1u << 30) Do not initialise the parameter object. TSK_NO_CHECK_INTEGRITY (1u << 29) Do not run integrity checks before performing an operation. ## Tables API¶ The tables API section of tskit is defined in the tskit/tables.h header. ### Table collections¶ struct tsk_table_collection_t A collection of tables defining the data for a tree sequence. Public Members double sequence_length The sequence length defining the tree sequence’s coordinate space. char *metadata The tree-sequence metadata. char *metadata_schema The metadata schema. tsk_individual_table_t individuals The individual table. tsk_node_table_t nodes The node table. tsk_edge_table_t edges The edge table. tsk_migration_table_t migrations The migration table. tsk_site_table_t sites The site table. tsk_mutation_table_t mutations The mutation table. tsk_population_table_t populations The population table. tsk_provenance_table_t provenances The provenance table. struct tsk_bookmark_t A bookmark recording the position of all the tables in a table collection. Public Members tsk_size_t individuals The position in the individual table. tsk_size_t nodes The position in the node table. tsk_size_t edges The position in the edge table. tsk_size_t migrations The position in the migration table. tsk_size_t sites The position in the site table. tsk_size_t mutations The position in the mutation table. tsk_size_t populations The position in the population table. tsk_size_t provenances The position in the provenance table. int tsk_table_collection_init(tsk_table_collection_t *self, tsk_flags_t options) Initialises the table collection by allocating the internal memory and initialising all the constituent tables. This must be called before any operations are performed on the table collection. See the API structure for details on how objects are initialised and freed. Options Options can be specified by providing one or more of the following bitwise flags: TSK_NO_EDGE_METADATA Do not allocate space to store metadata in the edge table. Operations attempting to add non-empty metadata to the edge table will fail with error TSK_ERR_METADATA_DISABLED. Parameters • self – A pointer to an uninitialised tsk_table_collection_t object. • options – Allocation time options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_free(tsk_table_collection_t *self) Free the internal memory for the specified table collection. Parameters Returns Always returns 0. int tsk_table_collection_clear(tsk_table_collection_t *self, tsk_flags_t options) Clears data tables (and optionally provenances and metadata) in this table collection. By default this operation clears all tables except the provenance table, retaining table metadata schemas and the tree-sequnce level metadata and schema. Options Options can be specified by providing one or more of the following bitwise flags: TSK_CLEAR_PROVENANCE Additionally clear the provenance table TSK_CLEAR_METADATA_SCHEMAS Additionally clear the table metadata schemas TSK_CLEAR_TS_METADATA_AND_SCHEMA Additionally clear the tree-sequence metadata and schema No memory is freed as a result of this operation; please use tsk_table_collection_free() to free internal resources. Parameters Returns Return 0 on success or a negative value on failure. bool tsk_table_collection_equals(const tsk_table_collection_t *self, const tsk_table_collection_t *other, tsk_flags_t options) Returns true if the data in the specified table collection is equal to the data in this table collection. Returns true if the two table collections are equal. The indexes are not considered as these are derived from the tables. We also do not consider the file_uuid, since it is a property of the file that set of tables is stored in. Options Options to control the comparison can be specified by providing one or more of the following bitwise flags. By default (options=0) two table collections are considered equal if all of the tables are byte-wise identical, and the sequence lengths, metadata and metadata schemas of the two table collections are identical. TSK_CMP_IGNORE_PROVENANCE Do not include the provenance table in comparison. TSK_CMP_IGNORE_METADATA Do not include metadata when comparing the table collections. This includes both the top-level tree sequence metadata as well as the metadata for each of the tables (i.e, TSK_CMP_IGNORE_TS_METADATA is implied). All metadata schemas are also ignored. TSK_CMP_IGNORE_TS_METADATA Do not include the top-level tree sequence metadata and metadata schemas in the comparison. TSK_CMP_IGNORE_TIMESTAMPS Do not include the timestamp information when comparing the provenance tables. This has no effect if TSK_CMP_IGNORE_PROVENANCE is specified. Parameters Returns Return true if the specified table collection is equal to this table. int tsk_table_collection_copy(const tsk_table_collection_t *self, tsk_table_collection_t *dest, tsk_flags_t options) Copies the state of this table collection into the specified destination. By default the method initialises the specified destination table. If the destination is already initialised, the TSK_NO_INIT option should be supplied to avoid leaking memory. Parameters • self – A pointer to a tsk_table_collection_t object. • dest – A pointer to a tsk_table_collection_t object. If the TSK_NO_INIT option is specified, this must be an initialised provenance table. If not, it must be an uninitialised provenance table. • options – Bitwise option flags. Returns Return 0 on success or a negative value on failure. void tsk_table_collection_print_state(const tsk_table_collection_t *self, FILE *out) Print out the state of this table collection to the specified stream. This method is intended for debugging purposes and should not be used in production code. The format of the output should not be depended on and may change arbitrarily between versions. Parameters int tsk_table_collection_load(tsk_table_collection_t *self, const char *filename, tsk_flags_t options) Load a table collection from a file path. Loads the data from the specified file into this table collection. By default, the table collection is also initialised. The resources allocated must be freed using tsk_table_collection_free() even in error conditions. If the TSK_NO_INIT option is set, the table collection is not initialised, allowing an already initialised table collection to be overwritten with the data from a file. If the file contains multiple table collections, this function will load the first. Please see the tsk_table_collection_loadf() for details on how to sequentially load table collections from a stream. Options Options can be specified by providing one or more of the following bitwise flags: TSK_NO_INIT Do not initialise this tsk_table_collection_t before loading. Examples int ret; tsk_table_collection_t tables; ret = tsk_table_collection_load(&tables, "data.trees", 0); if (ret != 0) { fprintf(stderr, "Load error:%s\n", tsk_strerror(ret)); exit(EXIT_FAILURE); }  Parameters • self – A pointer to an uninitialised tsk_table_collection_t object if the TSK_NO_INIT option is not set (default), or an initialised tsk_table_collection_t otherwise. • filename – A NULL terminated string containing the filename. • options – Bitwise options. See above for details. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_loadf(tsk_table_collection_t *self, FILE *file, tsk_flags_t options) Load a table collection from a stream. Loads a tables definition from the specified file stream to this table collection. By default, the table collection is also initialised. The resources allocated must be freed using tsk_table_collection_free() even in error conditions. If the TSK_NO_INIT option is set, the table collection is not initialised, allowing an already initialised table collection to be overwritten with the data from a file. If the stream contains multiple table collection definitions, this function will load the next table collection from the stream. If the stream contains no more table collection definitions the error value TSK_ERR_EOF will be returned. Note that EOF is only returned in the case where zero bytes are read from the stream — malformed files or other errors will result in different error conditions. Please see the File streaming section for an example of how to sequentially load tree sequences from a stream. Options Options can be specified by providing one or more of the following bitwise flags: TSK_NO_INIT Do not initialise this tsk_table_collection_t before loading. Parameters • self – A pointer to an uninitialised tsk_table_collection_t object if the TSK_NO_INIT option is not set (default), or an initialised tsk_table_collection_t otherwise. • file – A FILE stream opened in an appropriate mode for reading (e.g. “r”, “r+” or “w+”) positioned at the beginning of a table collection definition. • options – Bitwise options. See above for details. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_dump(const tsk_table_collection_t *self, const char *filename, tsk_flags_t options) Write a table collection to file. Writes the data from this table collection to the specified file. Usually we expect that data written to a file will be in a form that can be read directly and used to create a tree sequence; that is, we assume that by default the tables are sorted and indexed. Following these assumptions, if the tables are not already indexed, we index the tables before writing to file to save the cost of building these indexes at load time. This behaviour requires that the tables are sorted. If this automatic indexing is not desired, it can be disabled using the TSK_NO_BUILD_INDEXES option. If an error occurs the file path is deleted, ensuring that only complete and well formed files will be written. Options Options can be specified by providing one or more of the following bitwise flags: TSK_NO_BUILD_INDEXES Do not build indexes for this table before writing to file. This is useful if you wish to write unsorted tables to file, as building the indexes will raise an error if the table is unsorted. Examples int ret; tsk_table_collection_t tables; ret = tsk_table_collection_init(&tables, 0); error_check(ret); tables.sequence_length = 1.0; // Write out the empty tree sequence ret = tsk_table_collection_dump(&tables, "empty.trees", 0); error_check(ret);  Parameters • self – A pointer to an initialised tsk_table_collection_t object. • filename – A NULL terminated string containing the filename. • options – Bitwise options. See above for details. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_dumpf(const tsk_table_collection_t *self, FILE *file, tsk_flags_t options) Write a table collection to a stream. Writes the data from this table collection to the specified FILE stream. Semantics are identical to tsk_table_collection_dump(). Please see the File streaming section for an example of how to sequentially dump and load tree sequences from a stream. Options Options can be specified by providing one or more of the following bitwise flags: TSK_NO_BUILD_INDEXES Do not build indexes for this table before writing to file. This is useful if you wish to write unsorted tables to file, as building the indexes will raise an error if the table is unsorted. Parameters • self – A pointer to an initialised tsk_table_collection_t object. • file – A FILE stream opened in an appropriate mode for writing (e.g. “w”, “a”, “r+” or “w+”). • options – Bitwise options. See above for details. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_record_num_rows(const tsk_table_collection_t *self, tsk_bookmark_t *bookmark) Record the number of rows in each table in the specified tsk_bookmark_t object. Parameters Returns Return 0 on success or a negative value on failure. int tsk_table_collection_truncate(tsk_table_collection_t *self, tsk_bookmark_t *bookmark) Truncates the tables in this table collection according to the specified bookmark. Truncate the tables in this collection so that each one has the number of rows specified in the parameter tsk_bookmark_t. Use the tsk_table_collection_record_num_rows() function to record the number rows for each table in a table collection at a particular time. Parameters • self – A pointer to a tsk_individual_table_t object. • bookmark – The number of rows to retain in each table. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_sort(tsk_table_collection_t *self, const tsk_bookmark_t *start, tsk_flags_t options) Sorts the tables in this collection. Some of the tables in a table collection must satisfy specific sortedness requirements in order to define a valid tree sequence. This method sorts the edge, site and mutation tables such that these requirements are guaranteed to be fulfilled. The individual, node, population and provenance tables do not have any sortedness requirements, and are therefore ignored by this method. The specified tsk_bookmark_t allows us to specify a start position for sorting in each of the tables; rows before this value are assumed to already be in sorted order and this information is used to make sorting more efficient. Positions in tables that are not sorted (individual, node, population and provenance) are ignored and can be set to arbitrary values. The table collection will always be unindexed after sort successfully completes. See the table sorting section for more details. For more control over the sorting process, see the Low-level sorting section. Options Options can be specified by providing one or more of the following bitwise flags: TSK_NO_CHECK_INTEGRITY Do not run integrity checks using tsk_table_collection_check_integrity() before sorting, potentially leading to a small reduction in execution time. This performance optimisation should not be used unless the calling code can guarantee reference integrity within the table collection. References to rows not in the table or bad offsets will result in undefined behaviour. Note The current implementation may sort in such a way that exceeds these requirements, but this behaviour should not be relied upon and later versions may weaken the level of sortedness. However, the method does guarantee that the resulting tables describes a valid tree sequence. Warning Sorting migrations is currently not supported and an error will be raised if a table collection containing a non-empty migration table is specified. Warning The current implementation only supports specifying a start position for the edge table and in a limited form for the site and mutation tables. Specifying a non-zero migration, start position results in an error. The start positions for the site and mutation tables can either be 0 or the length of the respective tables, allowing these tables to either be fully sorted, or not sorted at all. Parameters • self – A pointer to a tsk_individual_table_t object. • start – The position to begin sorting in each table; all rows less than this position must fulfill the tree sequence sortedness requirements. If this is NULL, sort all rows. • options – Sort options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_canonicalise(tsk_table_collection_t *self, tsk_flags_t options) Puts the tables into canonical form. Put tables into canonical form such that randomly reshuffled tables are guaranteed to always be sorted in the same order, and redundant information is removed. The canonical sorting exceeds the usual tree sequence sortedness requirements. Options: Options can be specified by providing one or more of the following bitwise flags: TSK_KEEP_UNREFERENCED By default, this will remove any unreferenced sites, populations, and individuals. If this flag is provided, these will be retained, with unreferenced individuals and populations at the end of the tables, in their original order. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_simplify(tsk_table_collection_t *self, const tsk_id_t *samples, tsk_size_t num_samples, tsk_flags_t options, tsk_id_t *node_map) Simplify the tables to remove redundant information. Simplification transforms the tables to remove redundancy and canonicalise tree sequence data. See the simplification section for more details. A mapping from the node IDs in the table before simplification to their equivalent values after simplification can be obtained via the node_map argument. If this is non NULL, node_map[u] will contain the new ID for node u after simplification, or TSK_NULL if the node has been removed. Thus, node_map must be an array of at least self->nodes.num_rows tsk_id_t values. Options: Options can be specified by providing one or more of the following bitwise flags: TSK_FILTER_SITES Remove sites from the output if there are no mutations that reference them. TSK_FILTER_POPULATIONS Remove populations from the output if there are no nodes or migrations that reference them. TSK_FILTER_INDIVIDUALS Remove individuals from the output if there are no nodes that reference them. TSK_REDUCE_TO_SITE_TOPOLOGY Reduce the topological information in the tables to the minimum necessary to represent the trees that contain sites. If there are zero sites this will result in an zero output 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. TSK_KEEP_UNARY By default simplify removes unary nodes (i.e., nodes with exactly one child) along the path from samples to root. If this option is specified such unary nodes will be preserved in the output. TSK_KEEP_INPUT_ROOTS By default simplify removes all topology ancestral the MRCAs of the samples. This option inserts edges from these MRCAs back to the roots of the input trees. TSK_KEEP_UNARY_IN_INDIVDUALS This acts like TSK_KEEP_UNARY (and is mutually exclusive with that flag). It keeps unary nodes, but only if the unary node is referenced from an individual. The table collection will always be unindexed after simplify successfully completes. Note Migrations are currently not supported by simplify, and an error will be raised if we attempt call simplify on a table collection with greater than zero migrations. See https://github.com/tskit-dev/tskit/issues/20 Parameters • self – A pointer to a tsk_individual_table_t object. • samples – Either NULL or an array of num_samples distinct and valid node IDs. If non-null the nodes in this array will be marked as samples in the output. If NULL, the num_samples parameter is ignored and the samples in the output will be the same as the samples in the input. This is equivalent to populating the samples array with all of the sample nodes in the input in increasing order of ID. • num_samples – The number of node IDs in the input samples array. Ignored if the samples array is NULL. • options – Simplify options; see above for the available bitwise flags. For the default behaviour, a value of 0 should be provided. • node_map – If not NULL, this array will be filled to define the mapping between nodes IDs in the table collection before and after simplification. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_subset(tsk_table_collection_t *self, const tsk_id_t *nodes, tsk_size_t num_nodes, tsk_flags_t options) Subsets and reorders a table collection according to an array of nodes. Reduces the table collection to contain only the entries referring to the provided list of nodes, with nodes reordered according to the order they appear in the nodes argument. Specifically, this subsets and reorders each of the tables as follows (but see options, below): 1. Nodes: if in the list of nodes, and in the order provided. 2. Individuals: if referred to by a retained node. 3. Populations: if referred to by a retained node, and in the order first seen when traversing the list of retained nodes. 4. Edges: if both parent and child are retained nodes. 5. Mutations: if the mutation’s node is a retained node. 6. Sites: if any mutations remain at the site after removing mutations. Retained individuals, edges, mutations, and sites appear in the same order as in the original tables. Note that only the information directly associated with the provided nodes is retained - for instance, subsetting to nodes=[A, B] does not retain nodes ancestral to A and B, and only retains the individuals A and B are in, and not their parents. This function does not require the tables to be sorted. Options: Options can be specified by providing one or more of the following bitwise flags: TSK_NO_CHANGE_POPULATIONS If this flag is provided, the population table will not be changed in any way. TSK_KEEP_UNREFERENCED If this flag is provided, then unreferenced sites, individuals, and populations will not be removed. If so, the site and individual tables will not be changed, and (unless TSK_NO_CHANGE_POPULATIONS is also provided) unreferenced populations will be placed last, in their original order. Note Migrations are currently not supported by susbset, and an error will be raised if we attempt call subset on a table collection with greater than zero migrations. Parameters • self – A pointer to a tsk_table_collection_t object. • nodes – An array of num_nodes valid node IDs. • num_nodes – The number of node IDs in the input nodes array. • options – Bitwise option flags. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_union(tsk_table_collection_t *self, const tsk_table_collection_t *other, const tsk_id_t *other_node_mapping, tsk_flags_t options) Forms the node-wise union of two table collections. Expands this table collection by adding the non-shared portions of another table collection to itself. The other_node_mapping encodes which nodes in other are equivalent to a node in self. The positions in the other_node_mapping array correspond to node ids in other, and the elements encode the equivalent node id in self or TSK_NULL if the node is exclusive to other. Nodes that are exclusive other are added to self, along with: 1. Individuals which are new to self. 2. Edges whose parent or child are new to self. 3. Sites which were not present in self. 4. Mutations whose nodes are new to self. By default, populations of newly added nodes are assumed to be new populations, and added to the population table as well. This operation will also sort the resulting tables, so the tables may change even if nothing new is added, if the original tables were not sorted. Options: Options can be specified by providing one or more of the following bitwise flags: TSK_UNION_NO_CHECK_SHARED By default, union checks that the portion of shared history between self and other, as implied by other_node_mapping, are indeed equivalent. It does so by subsetting both self and other on the equivalent nodes specified in other_node_mapping, and then checking for equality of the subsets. TSK_UNION_NO_ADD_POP By default, all nodes new to self are assigned new populations. If this option is specified, nodes that are added to self will retain the population IDs they have in other. Note Migrations are currently not supported by union, and an error will be raised if we attempt call union on a table collection with migrations. Parameters • self – A pointer to a tsk_table_collection_t object. • other – A pointer to a tsk_table_collection_t object. • other_node_mapping – An array of node IDs that relate nodes in other to nodes in self: the k-th element of other_node_mapping should be the index of the equivalent node in self, or TSK_NULL if the node is not present in self (in which case it will be added to self). • options – Union options; see above for the available bitwise flags. For the default behaviour, a value of 0 should be provided. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_set_metadata(tsk_table_collection_t *self, const char *metadata, tsk_size_t metadata_length) Set the metadata. Copies the metadata string to this table collection, replacing any existing. Parameters • self – A pointer to a tsk_table_collection_t object. • metadata – A pointer to a char array • metadata_length – The size of the metadata in bytes. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_set_metadata_schema(tsk_table_collection_t *self, const char *metadata_schema, tsk_size_t metadata_schema_length) Set the metadata schema. Copies the metadata schema string to this table collection, replacing any existing. Parameters • self – A pointer to a tsk_table_collection_t object. • metadata_schema – A pointer to a char array • metadata_schema_length – The size of the metadata schema in bytes. Returns Return 0 on success or a negative value on failure. bool tsk_table_collection_has_index(const tsk_table_collection_t *self, tsk_flags_t options) Returns true if this table collection is indexed. This method returns true if the table collection has an index for the edge table. It guarantees that the index exists, and that it is for the same number of edges that are in the edge table. It does not guarantee that the index is valid (i.e., if the rows in the edge have been permuted in some way since the index was built). See the Table indexes section for details on the index life-cycle. Parameters • self – A pointer to a tsk_table_collection_t object. • options – Bitwise options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return true if there is an index present for this table collection. int tsk_table_collection_drop_index(tsk_table_collection_t *self, tsk_flags_t options) Deletes the indexes for this table collection. Unconditionally drop the indexes that may be present for this table collection. It is not an error to call this method on an unindexed table collection. See the Table indexes section for details on the index life-cycle. Parameters • self – A pointer to a tsk_table_collection_t object. • options – Bitwise options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Always returns 0. int tsk_table_collection_build_index(tsk_table_collection_t *self, tsk_flags_t options) Builds indexes for this table collection. Builds the tree traversal indexes for this table collection. Any existing index is first dropped using tsk_table_collection_drop_index(). See the Table indexes section for details on the index life-cycle. Parameters • self – A pointer to a tsk_table_collection_t object. • options – Bitwise options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. int tsk_table_collection_set_indexes(tsk_table_collection_t *self, tsk_id_t *edge_insertion_order, tsk_id_t *edge_removal_order) Sets the edge insertion/removal index for this table collection. This method sets the edge insertion/removal index for this table collection The index arrays should have the same number of edges that are in the edge table. The index is not checked for validity. See the Table indexes section for details on the index life-cycle. Parameters • self – A pointer to a tsk_table_collection_t object. • edge_insertion_order – Array of tsk_id_t edge ids. • edge_removal_order – Array of tsk_id_t edge ids. Returns Return 0 on success or a negative value on failure. tsk_id_t tsk_table_collection_check_integrity(const tsk_table_collection_t *self, tsk_flags_t options) Runs integrity checks on this table collection. Checks the integrity of this table collection. The default checks (i.e., with options = 0) guarantee the integrity of memory and entity references within the table collection. All spatial values (along the genome) are checked to see if they are finite values and within the required bounds. Time values are checked to see if they are finite or marked as unknown. To check if a set of tables fulfills the requirements needed for a valid tree sequence, use the TSK_CHECK_TREES option. When this method is called with TSK_CHECK_TREES, the number of trees in the tree sequence is returned. Thus, to check for errors client code should verify that the return value is less than zero. All other options will return zero on success and a negative value on failure. More fine-grained checks can be achieved using bitwise combinations of the other options. Options: Options can be specified by providing one or more of the following bitwise flags: TSK_CHECK_EDGE_ORDERING Check edge ordering constraints for a tree sequence. TSK_CHECK_SITE_ORDERING Check that sites are in nondecreasing position order. TSK_CHECK_SITE_DUPLICATES Check for any duplicate site positions. TSK_CHECK_MUTATION_ORDERING Check contraints on the ordering of mutations. Any non-null mutation parents and known times are checked for ordering constraints. TSK_CHECK_INDIVIDUAL_ORDERING Check individual parents are before children, where specified. TSK_CHECK_INDEXES Check that the table indexes exist, and contain valid edge references. TSK_CHECK_TREES All checks needed to define a valid tree sequence. Note that this implies all of the above checks. It is sometimes useful to disregard some parts of the data model when performing checks: TSK_NO_CHECK_POPULATION_REFS Do not check integrity of references to populations. This can be safely combined with the other checks. Parameters Returns Return a negative error value on if any problems are detected in the tree sequence. If the TSK_CHECK_TREES option is provided, the number of trees in the tree sequence will be returned, on success. ### Individuals¶ struct tsk_individual_t A single individual defined by a row in the individual table. See the data model section for the definition of an individual and its properties. Public Members tsk_id_t id Non-negative ID value corresponding to table row. tsk_flags_t flags Bitwise flags. const double *location Spatial location. The number of dimensions is defined by location_length. tsk_size_t location_length Number of spatial dimensions. tsk_id_t *parents IDs of the parents. The number of parents given by parents_length tsk_size_t parents_length Number of parents. const char *metadata Metadata. tsk_size_t metadata_length Size of the metadata in bytes. struct tsk_individual_table_t The individual table. See the individual table definition for details of the columns in this table. Public Members tsk_size_t num_rows The number of rows in this table. tsk_size_t location_length The total length of the location column. tsk_size_t parents_length The total length of the parent column. tsk_size_t metadata_length The total length of the metadata column. tsk_flags_t *flags The flags column. double *location The location column. tsk_size_t *location_offset The location_offset column. tsk_id_t *parents The parents column. tsk_size_t *parents_offset The parents_offset column. char *metadata The metadata column. tsk_size_t *metadata_offset The metadata_offset column. char *metadata_schema The metadata schema. int tsk_individual_table_init(tsk_individual_table_t *self, tsk_flags_t options) Initialises the table by allocating the internal memory. This must be called before any operations are performed on the table. See the API structure for details on how objects are initialised and freed. Parameters • self – A pointer to an uninitialised tsk_individual_table_t object. • options – Allocation time options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. int tsk_individual_table_free(tsk_individual_table_t *self) Free the internal memory for the specified table. Parameters Returns Always returns 0. tsk_id_t tsk_individual_table_add_row(tsk_individual_table_t *self, tsk_flags_t flags, const double *location, tsk_size_t location_length, const tsk_id_t *parents, tsk_size_t parents_length, const char *metadata, tsk_size_t metadata_length) Adds a row to this individual table. Add a new individual with the specified flags, location, parents and metadata to the table. Copies of the location, parents and metadata parameters are taken immediately. See the table definition for details of the columns in this table. Parameters • self – A pointer to a tsk_individual_table_t object. • flags – The bitwise flags for the new individual. • location – A pointer to a double array representing the spatial location of the new individual. Can be NULL if location_length is 0. • location_length – The number of dimensions in the locations position. Note this the number of elements in the corresponding double array not the number of bytes. • parents – A pointer to a tsk_id array representing the parents of the new individual. Can be NULL if parents_length is 0. • parents_length – The number of parents. Note this the number of elements in the corresponding tsk_id array not the number of bytes. • metadata – The metadata to be associated with the new individual. This is a pointer to arbitrary memory. Can be NULL if metadata_length is 0. • metadata_length – The size of the metadata array in bytes. Returns Return the ID of the newly added individual on success, or a negative value on failure. int tsk_individual_table_clear(tsk_individual_table_t *self) Clears this table, setting the number of rows to zero. No memory is freed as a result of this operation; please use tsk_individual_table_free() to free the table’s internal resources. Note that the metadata schema is not cleared. Parameters Returns Return 0 on success or a negative value on failure. int tsk_individual_table_truncate(tsk_individual_table_t *self, tsk_size_t num_rows) Truncates this table so that only the first num_rows are retained. Parameters • self – A pointer to a tsk_individual_table_t object. • num_rows – The number of rows to retain in the table. Returns Return 0 on success or a negative value on failure. int tsk_individual_table_extend(tsk_individual_table_t *self, const tsk_individual_table_t *other, tsk_size_t num_rows, const tsk_id_t *row_indexes, tsk_flags_t options) Extends this table by appending rows copied from another table. Appends the rows at the specified indexes from the table other to the end of this table. Row indexes can be repeated and in any order. If row_indexes is NULL, append the first num_rows from other to this table. Note that metadata is copied as-is and is not checked for compatibility with any existing schema on this table. Parameters • self – A pointer to a tsk_individual_table_t object where rows are to be added. • other – A pointer to a tsk_individual_table_t object where rows are copied from. • num_rows – The number of rows from other to append to this table. • row_indexes – Array of row indexes in other. If NULL is passed then the first num_rows of other are used. • options – Bitwise option flags. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. bool tsk_individual_table_equals(const tsk_individual_table_t *self, const tsk_individual_table_t *other, tsk_flags_t options) Returns true if the data in the specified table is identical to the data in this table. Options Options to control the comparison can be specified by providing one or more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. TSK_CMP_IGNORE_METADATA Do not include metadata or metadata schemas in the comparison. Parameters Returns Return true if the specified table is equal to this table. int tsk_individual_table_copy(const tsk_individual_table_t *self, tsk_individual_table_t *dest, tsk_flags_t options) Copies the state of this table into the specified destination. By default the method initialises the specified destination table. If the destination is already initialised, the TSK_NO_INIT option should be supplied to avoid leaking memory. Indexes that are present are also copied to the destination table. Parameters • self – A pointer to a tsk_individual_table_t object. • dest – A pointer to a tsk_individual_table_t object. If the TSK_NO_INIT option is specified, this must be an initialised individual table. If not, it must be an uninitialised individual table. • options – Bitwise option flags. Returns Return 0 on success or a negative value on failure. int tsk_individual_table_get_row(const tsk_individual_table_t *self, tsk_id_t index, tsk_individual_t *row) Get the row at the specified index. Updates the specified individual struct to reflect the values in the specified row. Pointers to memory within this struct are handled by the table and should not be freed by client code. These pointers are guaranteed to be valid until the next operation that modifies the table (e.g., by adding a new row), but not afterwards. Parameters • self – A pointer to a tsk_individual_table_t object. • index – The requested table row. • row – A pointer to a tsk_individual_t struct that is updated to reflect the values in the specified row. Returns Return 0 on success or a negative value on failure. int tsk_individual_table_set_metadata_schema(tsk_individual_table_t *self, const char *metadata_schema, tsk_size_t metadata_schema_length) Set the metadata schema. Copies the metadata schema string to this table, replacing any existing. Parameters • self – A pointer to a tsk_individual_table_t object. • metadata_schema – A pointer to a char array • metadata_schema_length – The size of the metadata schema in bytes. Returns Return 0 on success or a negative value on failure. void tsk_individual_table_print_state(const tsk_individual_table_t *self, FILE *out) Print out the state of this table to the specified stream. This method is intended for debugging purposes and should not be used in production code. The format of the output should not be depended on and may change arbitrarily between versions. Parameters ### Nodes¶ struct tsk_node_t A single node defined by a row in the node table. See the data model section for the definition of a node and its properties. Public Members tsk_id_t id Non-negative ID value corresponding to table row. tsk_flags_t flags Bitwise flags. double time Time. tsk_id_t population Population ID. tsk_id_t individual Individual ID. const char *metadata Metadata. tsk_size_t metadata_length Size of the metadata in bytes. struct tsk_node_table_t The node table. See the node table definition for details of the columns in this table. Public Members tsk_size_t num_rows The number of rows in this table. tsk_size_t metadata_length The total length of the metadata column. tsk_flags_t *flags The flags column. double *time The time column. tsk_id_t *population The population column. tsk_id_t *individual The individual column. char *metadata The metadata column. tsk_size_t *metadata_offset The metadata_offset column. char *metadata_schema The metadata schema. int tsk_node_table_init(tsk_node_table_t *self, tsk_flags_t options) Initialises the table by allocating the internal memory. This must be called before any operations are performed on the table. See the API structure for details on how objects are initialised and freed. Parameters • self – A pointer to an uninitialised tsk_node_table_t object. • options – Allocation time options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. int tsk_node_table_free(tsk_node_table_t *self) Free the internal memory for the specified table. Parameters Returns Always returns 0. tsk_id_t tsk_node_table_add_row(tsk_node_table_t *self, tsk_flags_t flags, double time, tsk_id_t population, tsk_id_t individual, const char *metadata, tsk_size_t metadata_length) Adds a row to this node table. Add a new node with the specified flags, time, population, individual and metadata to the table. A copy of the metadata parameter is taken immediately. See the table definition for details of the columns in this table. Parameters • self – A pointer to a tsk_node_table_t object. • flags – The bitwise flags for the new node. • time – The time for the new node. • population – The population for the new node. Set to TSK_NULL if not known. • individual – The individual for the new node. Set to TSK_NULL if not known. • metadata – The metadata to be associated with the new node. This is a pointer to arbitrary memory. Can be NULL if metadata_length is 0. • metadata_length – The size of the metadata array in bytes. Returns Return the ID of the newly added node on success, or a negative value on failure. int tsk_node_table_clear(tsk_node_table_t *self) Clears this table, setting the number of rows to zero. No memory is freed as a result of this operation; please use tsk_node_table_free() to free the table’s internal resources. Note that the metadata schema is not cleared. Parameters Returns Return 0 on success or a negative value on failure. int tsk_node_table_truncate(tsk_node_table_t *self, tsk_size_t num_rows) Truncates this table so that only the first num_rows are retained. Parameters • self – A pointer to a tsk_node_table_t object. • num_rows – The number of rows to retain in the table. Returns Return 0 on success or a negative value on failure. int tsk_node_table_extend(tsk_node_table_t *self, const tsk_node_table_t *other, tsk_size_t num_rows, const tsk_id_t *row_indexes, tsk_flags_t options) Extends this table by appending rows copied from another table. Appends the rows at the specified indexes from the table other to the end of this table. Row indexes can be repeated and in any order. If row_indexes is NULL, append the first num_rows from other to this table. Note that metadata is copied as-is and is not checked for compatibility with any existing schema on this table. Parameters • self – A pointer to a tsk_node_table_t object where rows are to be added. • other – A pointer to a tsk_node_table_t object where rows are copied from. • num_rows – The number of rows from other to append to this table. • row_indexes – Array of row indexes in other. If NULL is passed then the first num_rows of other are used. • options – Bitwise option flags. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. bool tsk_node_table_equals(const tsk_node_table_t *self, const tsk_node_table_t *other, tsk_flags_t options) Returns true if the data in the specified table is identical to the data in this table. Options Options to control the comparison can be specified by providing one or more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. TSK_CMP_IGNORE_METADATA Do not include metadata or metadata schemas in the comparison. Parameters Returns Return true if the specified table is equal to this table. int tsk_node_table_copy(const tsk_node_table_t *self, tsk_node_table_t *dest, tsk_flags_t options) Copies the state of this table into the specified destination. By default the method initialises the specified destination table. If the destination is already initialised, the TSK_NO_INIT option should be supplied to avoid leaking memory. Parameters • self – A pointer to a tsk_node_table_t object. • dest – A pointer to a tsk_node_table_t object. If the TSK_NO_INIT option is specified, this must be an initialised node table. If not, it must be an uninitialised node table. • options – Bitwise option flags. Returns Return 0 on success or a negative value on failure. int tsk_node_table_get_row(const tsk_node_table_t *self, tsk_id_t index, tsk_node_t *row) Get the row at the specified index. Updates the specified node struct to reflect the values in the specified row. Pointers to memory within this struct are handled by the table and should not be freed by client code. These pointers are guaranteed to be valid until the next operation that modifies the table (e.g., by adding a new row), but not afterwards. Parameters • self – A pointer to a tsk_node_table_t object. • index – The requested table row. • row – A pointer to a tsk_node_t struct that is updated to reflect the values in the specified row. Returns Return 0 on success or a negative value on failure. int tsk_node_table_set_metadata_schema(tsk_node_table_t *self, const char *metadata_schema, tsk_size_t metadata_schema_length) Set the metadata schema. Copies the metadata schema string to this table, replacing any existing. Parameters • self – A pointer to a tsk_node_table_t object. • metadata_schema – A pointer to a char array • metadata_schema_length – The size of the metadata schema in bytes. Returns Return 0 on success or a negative value on failure. void tsk_node_table_print_state(const tsk_node_table_t *self, FILE *out) Print out the state of this table to the specified stream. This method is intended for debugging purposes and should not be used in production code. The format of the output should not be depended on and may change arbitrarily between versions. Parameters • self – A pointer to a tsk_node_table_t object. • out – The stream to write the summary to. ### Edges¶ struct tsk_edge_t A single edge defined by a row in the edge table. See the data model section for the definition of an edge and its properties. Public Members tsk_id_t id Non-negative ID value corresponding to table row. tsk_id_t parent Parent node ID. tsk_id_t child Child node ID. double left Left coordinate. double right Right coordinate. const char *metadata Metadata. tsk_size_t metadata_length Size of the metadata in bytes. struct tsk_edge_table_t The edge table. See the edge table definition for details of the columns in this table. Public Members tsk_size_t num_rows The number of rows in this table. tsk_size_t metadata_length The total length of the metadata column. double *left The left column. double *right The right column. tsk_id_t *parent The parent column. tsk_id_t *child The child column. char *metadata The metadata column. tsk_size_t *metadata_offset The metadata_offset column. char *metadata_schema The metadata schema. tsk_flags_t options Flags for this table. int tsk_edge_table_init(tsk_edge_table_t *self, tsk_flags_t options) Initialises the table by allocating the internal memory. This must be called before any operations are performed on the table. See the API structure for details on how objects are initialised and freed. Options Options can be specified by providing one or more of the following bitwise flags: TSK_NO_METADATA Do not allocate space to store metadata in this table. Operations attempting to add non-empty metadata to the table will fail with error TSK_ERR_METADATA_DISABLED. Parameters • self – A pointer to an uninitialised tsk_edge_table_t object. • options – Allocation time options. Returns Return 0 on success or a negative value on failure. int tsk_edge_table_free(tsk_edge_table_t *self) Free the internal memory for the specified table. Parameters Returns Always returns 0. tsk_id_t tsk_edge_table_add_row(tsk_edge_table_t *self, double left, double right, tsk_id_t parent, tsk_id_t child, const char *metadata, tsk_size_t metadata_length) Adds a row to this edge table. Add a new edge with the specified left, right, parent, child and metadata to the table. See the table definition for details of the columns in this table. Parameters • self – A pointer to a tsk_edge_table_t object. • left – The left coordinate for the new edge. • right – The right coordinate for the new edge. • parent – The parent node for the new edge. • child – The child node for the new edge. • metadata – The metadata to be associated with the new edge. This is a pointer to arbitrary memory. Can be NULL if metadata_length is 0. • metadata_length – The size of the metadata array in bytes. Returns Return the ID of the newly added edge on success, or a negative value on failure. int tsk_edge_table_clear(tsk_edge_table_t *self) Clears this table, setting the number of rows to zero. No memory is freed as a result of this operation; please use tsk_edge_table_free() to free the table’s internal resources. Note that the metadata schema is not cleared. Parameters Returns Return 0 on success or a negative value on failure. int tsk_edge_table_truncate(tsk_edge_table_t *self, tsk_size_t num_rows) Truncates this table so that only the first num_rows are retained. Parameters • self – A pointer to a tsk_edge_table_t object. • num_rows – The number of rows to retain in the table. Returns Return 0 on success or a negative value on failure. int tsk_edge_table_extend(tsk_edge_table_t *self, const tsk_edge_table_t *other, tsk_size_t num_rows, const tsk_id_t *row_indexes, tsk_flags_t options) Extends this table by appending rows copied from another table. Appends the rows at the specified indexes from the table other to the end of this table. Row indexes can be repeated and in any order. If row_indexes is NULL, append the first num_rows from other to this table. Note that metadata is copied as-is and is not checked for compatibility with any existing schema on this table. Parameters • self – A pointer to a tsk_edge_table_t object where rows are to be added. • other – A pointer to a tsk_edge_table_t object where rows are copied from. • num_rows – The number of rows from other to append to this table. • row_indexes – Array of row indexes in other. If NULL is passed then the first num_rows of other are used. • options – Bitwise option flags. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. bool tsk_edge_table_equals(const tsk_edge_table_t *self, const tsk_edge_table_t *other, tsk_flags_t options) Returns true if the data in the specified table is identical to the data in this table. Options Options to control the comparison can be specified by providing one or more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. TSK_CMP_IGNORE_METADATA Do not include metadata or metadata schemas in the comparison. Parameters Returns Return true if the specified table is equal to this table. int tsk_edge_table_copy(const tsk_edge_table_t *self, tsk_edge_table_t *dest, tsk_flags_t options) Copies the state of this table into the specified destination. By default the method initialises the specified destination table. If the destination is already initialised, the TSK_NO_INIT option should be supplied to avoid leaking memory. Parameters • self – A pointer to a tsk_edge_table_t object. • dest – A pointer to a tsk_edge_table_t object. If the TSK_NO_INIT option is specified, this must be an initialised edge table. If not, it must be an uninitialised edge table. • options – Bitwise option flags. Returns Return 0 on success or a negative value on failure. int tsk_edge_table_get_row(const tsk_edge_table_t *self, tsk_id_t index, tsk_edge_t *row) Get the row at the specified index. Updates the specified edge struct to reflect the values in the specified row. Pointers to memory within this struct are handled by the table and should not be freed by client code. These pointers are guaranteed to be valid until the next operation that modifies the table (e.g., by adding a new row), but not afterwards. Parameters • self – A pointer to a tsk_edge_table_t object. • index – The requested table row. • row – A pointer to a tsk_edge_t struct that is updated to reflect the values in the specified row. Returns Return 0 on success or a negative value on failure. int tsk_edge_table_set_metadata_schema(tsk_edge_table_t *self, const char *metadata_schema, tsk_size_t metadata_schema_length) Set the metadata schema. Copies the metadata schema string to this table, replacing any existing. Parameters • self – A pointer to a tsk_edge_table_t object. • metadata_schema – A pointer to a char array • metadata_schema_length – The size of the metadata schema in bytes. Returns Return 0 on success or a negative value on failure. void tsk_edge_table_print_state(const tsk_edge_table_t *self, FILE *out) Print out the state of this table to the specified stream. This method is intended for debugging purposes and should not be used in production code. The format of the output should not be depended on and may change arbitrarily between versions. Parameters • self – A pointer to a tsk_edge_table_t object. • out – The stream to write the summary to. ### Migrations¶ struct tsk_migration_t A single migration defined by a row in the migration table. See the data model section for the definition of a migration and its properties. Public Members tsk_id_t id Non-negative ID value corresponding to table row. tsk_id_t source Source population ID. tsk_id_t dest Destination population ID. tsk_id_t node Node ID. double left Left coordinate. double right Right coordinate. double time Time. const char *metadata Metadata. tsk_size_t metadata_length Size of the metadata in bytes. struct tsk_migration_table_t The migration table. See the migration table definition for details of the columns in this table. Public Members tsk_size_t num_rows The number of rows in this table. tsk_size_t metadata_length The total length of the metadata column. tsk_id_t *source The source column. tsk_id_t *dest The dest column. tsk_id_t *node The node column. double *left The left column. double *right The right column. double *time The time column. char *metadata The metadata column. tsk_size_t *metadata_offset The metadata_offset column. char *metadata_schema The metadata schema. int tsk_migration_table_init(tsk_migration_table_t *self, tsk_flags_t options) Initialises the table by allocating the internal memory. This must be called before any operations are performed on the table. See the API structure for details on how objects are initialised and freed. Parameters • self – A pointer to an uninitialised tsk_migration_table_t object. • options – Allocation time options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. int tsk_migration_table_free(tsk_migration_table_t *self) Free the internal memory for the specified table. Parameters Returns Always returns 0. tsk_id_t tsk_migration_table_add_row(tsk_migration_table_t *self, double left, double right, tsk_id_t node, tsk_id_t source, tsk_id_t dest, double time, const char *metadata, tsk_size_t metadata_length) Adds a row to this migration table. Add a new migration with the specified left, right, node, source, dest, time and metadata to the table. See the table definition for details of the columns in this table. Parameters • self – A pointer to a tsk_migration_table_t object. • left – The left coordinate for the new migration. • right – The right coordinate for the new migration. • node – The node ID for the new migration. • source – The source population ID for the new migration. • dest – The destination population ID for the new migration. • time – The time for the new migration. • metadata – The metadata to be associated with the new migration. This is a pointer to arbitrary memory. Can be NULL if metadata_length is 0. • metadata_length – The size of the metadata array in bytes. Returns Return the ID of the newly added migration on success, or a negative value on failure. int tsk_migration_table_clear(tsk_migration_table_t *self) Clears this table, setting the number of rows to zero. No memory is freed as a result of this operation; please use tsk_migration_table_free() to free the table’s internal resources. Note that the metadata schema is not cleared. Parameters Returns Return 0 on success or a negative value on failure. int tsk_migration_table_truncate(tsk_migration_table_t *self, tsk_size_t num_rows) Truncates this table so that only the first num_rows are retained. Parameters • self – A pointer to a tsk_migration_table_t object. • num_rows – The number of rows to retain in the table. Returns Return 0 on success or a negative value on failure. int tsk_migration_table_extend(tsk_migration_table_t *self, const tsk_migration_table_t *other, tsk_size_t num_rows, const tsk_id_t *row_indexes, tsk_flags_t options) Extends this table by appending rows copied from another table. Appends the rows at the specified indexes from the table other to the end of this table. Row indexes can be repeated and in any order. If row_indexes is NULL, append the first num_rows from other to this table. Note that metadata is copied as-is and is not checked for compatibility with any existing schema on this table. Parameters • self – A pointer to a tsk_migration_table_t object where rows are to be added. • other – A pointer to a tsk_migration_table_t object where rows are copied from. • num_rows – The number of rows from other to append to this table. • row_indexes – Array of row indexes in other. If NULL is passed then the first num_rows of other are used. • options – Bitwise option flags. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. bool tsk_migration_table_equals(const tsk_migration_table_t *self, const tsk_migration_table_t *other, tsk_flags_t options) Returns true if the data in the specified table is identical to the data in this table. Options Options to control the comparison can be specified by providing one or more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. TSK_CMP_IGNORE_METADATA Do not include metadata or metadata schemas in the comparison. Parameters Returns Return true if the specified table is equal to this table. int tsk_migration_table_copy(const tsk_migration_table_t *self, tsk_migration_table_t *dest, tsk_flags_t options) Copies the state of this table into the specified destination. By default the method initialises the specified destination table. If the destination is already initialised, the TSK_NO_INIT option should be supplied to avoid leaking memory. Parameters • self – A pointer to a tsk_migration_table_t object. • dest – A pointer to a tsk_migration_table_t object. If the TSK_NO_INIT option is specified, this must be an initialised migration table. If not, it must be an uninitialised migration table. • options – Bitwise option flags. Returns Return 0 on success or a negative value on failure. int tsk_migration_table_get_row(const tsk_migration_table_t *self, tsk_id_t index, tsk_migration_t *row) Get the row at the specified index. Updates the specified migration struct to reflect the values in the specified row. Pointers to memory within this struct are handled by the table and should not be freed by client code. These pointers are guaranteed to be valid until the next operation that modifies the table (e.g., by adding a new row), but not afterwards. Parameters • self – A pointer to a tsk_migration_table_t object. • index – The requested table row. • row – A pointer to a tsk_migration_t struct that is updated to reflect the values in the specified row. Returns Return 0 on success or a negative value on failure. int tsk_migration_table_set_metadata_schema(tsk_migration_table_t *self, const char *metadata_schema, tsk_size_t metadata_schema_length) Set the metadata schema. Copies the metadata schema string to this table, replacing any existing. Parameters • self – A pointer to a tsk_migration_table_t object. • metadata_schema – A pointer to a char array • metadata_schema_length – The size of the metadata schema in bytes. Returns Return 0 on success or a negative value on failure. void tsk_migration_table_print_state(const tsk_migration_table_t *self, FILE *out) Print out the state of this table to the specified stream. This method is intended for debugging purposes and should not be used in production code. The format of the output should not be depended on and may change arbitrarily between versions. Parameters ### Sites¶ struct tsk_site_t A single site defined by a row in the site table. See the data model section for the definition of a site and its properties. Public Members tsk_id_t id Non-negative ID value corresponding to table row. double position Position coordinate. const char *ancestral_state Ancestral state. tsk_size_t ancestral_state_length Ancestral state length in bytes. const char *metadata Metadata. tsk_size_t metadata_length Metadata length in bytes. struct tsk_site_table_t The site table. See the site table definition for details of the columns in this table. Public Members tsk_size_t num_rows The number of rows in this table. tsk_size_t metadata_length The total length of the metadata column. double *position The position column. char *ancestral_state The ancestral_state column. tsk_size_t *ancestral_state_offset The ancestral_state_offset column. char *metadata The metadata column. tsk_size_t *metadata_offset The metadata_offset column. char *metadata_schema The metadata schema. int tsk_site_table_init(tsk_site_table_t *self, tsk_flags_t options) Initialises the table by allocating the internal memory. This must be called before any operations are performed on the table. See the API structure for details on how objects are initialised and freed. Parameters • self – A pointer to an uninitialised tsk_site_table_t object. • options – Allocation time options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. int tsk_site_table_free(tsk_site_table_t *self) Free the internal memory for the specified table. Parameters Returns Always returns 0. tsk_id_t tsk_site_table_add_row(tsk_site_table_t *self, double position, const char *ancestral_state, tsk_size_t ancestral_state_length, const char *metadata, tsk_size_t metadata_length) Adds a row to this site table. Add a new site with the specified position, ancestral_state and metadata to the table. Copies of ancestral_state and metadata are immediately taken. See the table definition for details of the columns in this table. Parameters • self – A pointer to a tsk_site_table_t object. • position – The position coordinate for the new site. • ancestral_state – The ancestral_state for the new site. • ancestral_state_length – The length of the ancestral_state in bytes. • metadata – The metadata to be associated with the new site. This is a pointer to arbitrary memory. Can be NULL if metadata_length is 0. • metadata_length – The size of the metadata array in bytes. Returns Return the ID of the newly added site on success, or a negative value on failure. int tsk_site_table_clear(tsk_site_table_t *self) Clears this table, setting the number of rows to zero. No memory is freed as a result of this operation; please use tsk_site_table_free() to free the table’s internal resources. Note that the metadata schema is not cleared. Parameters Returns Return 0 on success or a negative value on failure. int tsk_site_table_truncate(tsk_site_table_t *self, tsk_size_t num_rows) Truncates this table so that only the first num_rows are retained. Parameters • self – A pointer to a tsk_site_table_t object. • num_rows – The number of rows to retain in the table. Returns Return 0 on success or a negative value on failure. int tsk_site_table_extend(tsk_site_table_t *self, const tsk_site_table_t *other, tsk_size_t num_rows, const tsk_id_t *row_indexes, tsk_flags_t options) Extends this table by appending rows copied from another table. Appends the rows at the specified indexes from the table other to the end of this table. Row indexes can be repeated and in any order. If row_indexes is NULL, append the first num_rows from other to this table. Note that metadata is copied as-is and is not checked for compatibility with any existing schema on this table. Parameters • self – A pointer to a tsk_site_table_t object where rows are to be added. • other – A pointer to a tsk_site_table_t object where rows are copied from. • num_rows – The number of rows from other to append to this table. • row_indexes – Array of row indexes in other. If NULL is passed then the first num_rows of other are used. • options – Bitwise option flags. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. bool tsk_site_table_equals(const tsk_site_table_t *self, const tsk_site_table_t *other, tsk_flags_t options) Returns true if the data in the specified table is identical to the data in this table. Options Options to control the comparison can be specified by providing one or more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. TSK_CMP_IGNORE_METADATA Do not include metadata or metadata schemas in the comparison. Parameters Returns Return true if the specified table is equal to this table. int tsk_site_table_copy(const tsk_site_table_t *self, tsk_site_table_t *dest, tsk_flags_t options) Copies the state of this table into the specified destination. By default the method initialises the specified destination table. If the destination is already initialised, the TSK_NO_INIT option should be supplied to avoid leaking memory. Parameters • self – A pointer to a tsk_site_table_t object. • dest – A pointer to a tsk_site_table_t object. If the TSK_NO_INIT option is specified, this must be an initialised site table. If not, it must be an uninitialised site table. • options – Bitwise option flags. Returns Return 0 on success or a negative value on failure. int tsk_site_table_get_row(const tsk_site_table_t *self, tsk_id_t index, tsk_site_t *row) Get the row at the specified index. Updates the specified site struct to reflect the values in the specified row. Pointers to memory within this struct are handled by the table and should not be freed by client code. These pointers are guaranteed to be valid until the next operation that modifies the table (e.g., by adding a new row), but not afterwards. Parameters • self – A pointer to a tsk_site_table_t object. • index – The requested table row. • row – A pointer to a tsk_site_t struct that is updated to reflect the values in the specified row. Returns Return 0 on success or a negative value on failure. int tsk_site_table_set_metadata_schema(tsk_site_table_t *self, const char *metadata_schema, tsk_size_t metadata_schema_length) Set the metadata schema. Copies the metadata schema string to this table, replacing any existing. Parameters • self – A pointer to a tsk_site_table_t object. • metadata_schema – A pointer to a char array • metadata_schema_length – The size of the metadata schema in bytes. Returns Return 0 on success or a negative value on failure. void tsk_site_table_print_state(const tsk_site_table_t *self, FILE *out) Print out the state of this table to the specified stream. This method is intended for debugging purposes and should not be used in production code. The format of the output should not be depended on and may change arbitrarily between versions. Parameters • self – A pointer to a tsk_site_table_t object. • out – The stream to write the summary to. ### Mutations¶ struct tsk_mutation_t A single mutation defined by a row in the mutation table. See the data model section for the definition of a mutation and its properties. Public Members tsk_id_t id Non-negative ID value corresponding to table row. tsk_id_t site Site ID. tsk_id_t node Node ID. tsk_id_t parent Parent mutation ID. double time Mutation time. const char *derived_state Derived state. tsk_size_t derived_state_length Size of the derived state in bytes. const char *metadata Metadata. tsk_size_t metadata_length Size of the metadata in bytes. struct tsk_mutation_table_t The mutation table. See the mutation table definition for details of the columns in this table. Public Members tsk_size_t num_rows The number of rows in this table. tsk_size_t metadata_length The total length of the metadata column. tsk_id_t *node The node column. tsk_id_t *site The site column. tsk_id_t *parent The parent column. double *time The time column. char *derived_state The derived_state column. tsk_size_t *derived_state_offset The derived_state_offset column. char *metadata The metadata column. tsk_size_t *metadata_offset The metadata_offset column. char *metadata_schema The metadata schema. int tsk_mutation_table_init(tsk_mutation_table_t *self, tsk_flags_t options) Initialises the table by allocating the internal memory. This must be called before any operations are performed on the table. See the API structure for details on how objects are initialised and freed. Parameters • self – A pointer to an uninitialised tsk_mutation_table_t object. • options – Allocation time options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. int tsk_mutation_table_free(tsk_mutation_table_t *self) Free the internal memory for the specified table. Parameters Returns Always returns 0. tsk_id_t tsk_mutation_table_add_row(tsk_mutation_table_t *self, tsk_id_t site, tsk_id_t node, tsk_id_t parent, double time, const char *derived_state, tsk_size_t derived_state_length, const char *metadata, tsk_size_t metadata_length) Adds a row to this mutation table. Add a new mutation with the specified site, parent, derived_state and metadata to the table. Copies of derived_state and metadata are immediately taken. See the table definition for details of the columns in this table. Parameters • self – A pointer to a tsk_mutation_table_t object. • site – The site ID for the new mutation. • node – The ID of the node this mutation occurs over. • parent – The ID of the parent mutation. • time – The time of the mutation. • derived_state – The derived_state for the new mutation. • derived_state_length – The length of the derived_state in bytes. • metadata – The metadata to be associated with the new mutation. This is a pointer to arbitrary memory. Can be NULL if metadata_length is 0. • metadata_length – The size of the metadata array in bytes. Returns Return the ID of the newly added mutation on success, or a negative value on failure. int tsk_mutation_table_clear(tsk_mutation_table_t *self) Clears this table, setting the number of rows to zero. No memory is freed as a result of this operation; please use tsk_mutation_table_free() to free the table’s internal resources. Note that the metadata schema is not cleared. Parameters Returns Return 0 on success or a negative value on failure. int tsk_mutation_table_truncate(tsk_mutation_table_t *self, tsk_size_t num_rows) Truncates this table so that only the first num_rows are retained. Parameters • self – A pointer to a tsk_mutation_table_t object. • num_rows – The number of rows to retain in the table. Returns Return 0 on success or a negative value on failure. int tsk_mutation_table_extend(tsk_mutation_table_t *self, const tsk_mutation_table_t *other, tsk_size_t num_rows, const tsk_id_t *row_indexes, tsk_flags_t options) Extends this table by appending rows copied from another table. Appends the rows at the specified indexes from the table other to the end of this table. Row indexes can be repeated and in any order. If row_indexes is NULL, append the first num_rows from other to this table. Note that metadata is copied as-is and is not checked for compatibility with any existing schema on this table. Parameters • self – A pointer to a tsk_mutation_table_t object where rows are to be added. • other – A pointer to a tsk_mutation_table_t object where rows are copied from. • num_rows – The number of rows from other to append to this table. • row_indexes – Array of row indexes in other. If NULL is passed then the first num_rows of other are used. • options – Bitwise option flags. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. bool tsk_mutation_table_equals(const tsk_mutation_table_t *self, const tsk_mutation_table_t *other, tsk_flags_t options) Returns true if the data in the specified table is identical to the data in this table. Options Options to control the comparison can be specified by providing one or more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. TSK_CMP_IGNORE_METADATA Do not include metadata or metadata schemas in the comparison. Parameters Returns Return true if the specified table is equal to this table. int tsk_mutation_table_copy(const tsk_mutation_table_t *self, tsk_mutation_table_t *dest, tsk_flags_t options) Copies the state of this table into the specified destination. By default the method initialises the specified destination table. If the destination is already initialised, the TSK_NO_INIT option should be supplied to avoid leaking memory. Parameters • self – A pointer to a tsk_mutation_table_t object. • dest – A pointer to a tsk_mutation_table_t object. If the TSK_NO_INIT option is specified, this must be an initialised mutation table. If not, it must be an uninitialised mutation table. • options – Bitwise option flags. Returns Return 0 on success or a negative value on failure. int tsk_mutation_table_get_row(const tsk_mutation_table_t *self, tsk_id_t index, tsk_mutation_t *row) Get the row at the specified index. Updates the specified mutation struct to reflect the values in the specified row. Pointers to memory within this struct are handled by the table and should not be freed by client code. These pointers are guaranteed to be valid until the next operation that modifies the table (e.g., by adding a new row), but not afterwards. Parameters • self – A pointer to a tsk_mutation_table_t object. • index – The requested table row. • row – A pointer to a tsk_mutation_t struct that is updated to reflect the values in the specified row. Returns Return 0 on success or a negative value on failure. int tsk_mutation_table_set_metadata_schema(tsk_mutation_table_t *self, const char *metadata_schema, tsk_size_t metadata_schema_length) Set the metadata schema. Copies the metadata schema string to this table, replacing any existing. Parameters • self – A pointer to a tsk_mutation_table_t object. • metadata_schema – A pointer to a char array • metadata_schema_length – The size of the metadata schema in bytes. Returns Return 0 on success or a negative value on failure. void tsk_mutation_table_print_state(const tsk_mutation_table_t *self, FILE *out) Print out the state of this table to the specified stream. This method is intended for debugging purposes and should not be used in production code. The format of the output should not be depended on and may change arbitrarily between versions. Parameters ### Populations¶ struct tsk_population_t A single population defined by a row in the population table. See the data model section for the definition of a population and its properties. Public Members tsk_id_t id Non-negative ID value corresponding to table row. const char *metadata Metadata. tsk_size_t metadata_length Metadata length in bytes. struct tsk_population_table_t The population table. See the population table definition for details of the columns in this table. Public Members tsk_size_t num_rows The number of rows in this table. tsk_size_t metadata_length The total length of the metadata column. char *metadata The metadata column. tsk_size_t *metadata_offset The metadata_offset column. char *metadata_schema The metadata schema. int tsk_population_table_init(tsk_population_table_t *self, tsk_flags_t options) Initialises the table by allocating the internal memory. This must be called before any operations are performed on the table. See the API structure for details on how objects are initialised and freed. Parameters • self – A pointer to an uninitialised tsk_population_table_t object. • options – Allocation time options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. int tsk_population_table_free(tsk_population_table_t *self) Free the internal memory for the specified table. Parameters Returns Always returns 0. tsk_id_t tsk_population_table_add_row(tsk_population_table_t *self, const char *metadata, tsk_size_t metadata_length) Adds a row to this population table. Add a new population with the specified metadata to the table. A copy of the metadata is immediately taken. See the table definition for details of the columns in this table. Parameters • self – A pointer to a tsk_population_table_t object. • metadata – The metadata to be associated with the new population. This is a pointer to arbitrary memory. Can be NULL if metadata_length is 0. • metadata_length – The size of the metadata array in bytes. Returns Return the ID of the newly added population on success, or a negative value on failure. int tsk_population_table_clear(tsk_population_table_t *self) Clears this table, setting the number of rows to zero. No memory is freed as a result of this operation; please use tsk_population_table_free() to free the table’s internal resources. Note that the metadata schema is not cleared. Parameters Returns Return 0 on success or a negative value on failure. int tsk_population_table_truncate(tsk_population_table_t *self, tsk_size_t num_rows) Truncates this table so that only the first num_rows are retained. Parameters • self – A pointer to a tsk_population_table_t object. • num_rows – The number of rows to retain in the table. Returns Return 0 on success or a negative value on failure. int tsk_population_table_extend(tsk_population_table_t *self, const tsk_population_table_t *other, tsk_size_t num_rows, const tsk_id_t *row_indexes, tsk_flags_t options) Extends this table by appending rows copied from another table. Appends the rows at the specified indexes from the table other to the end of this table. Row indexes can be repeated and in any order. If row_indexes is NULL, append the first num_rows from other to this table. Note that metadata is copied as-is and is not checked for compatibility with any existing schema on this table. Parameters • self – A pointer to a tsk_population_table_t object where rows are to be added. • other – A pointer to a tsk_population_table_t object where rows are copied from. • num_rows – The number of rows from other to append to this table. • row_indexes – Array of row indexes in other. If NULL is passed then the first num_rows of other are used. • options – Bitwise option flags. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. bool tsk_population_table_equals(const tsk_population_table_t *self, const tsk_population_table_t *other, tsk_flags_t options) Returns true if the data in the specified table is identical to the data in this table. Options Options to control the comparison can be specified by providing one or more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. TSK_CMP_IGNORE_METADATA Do not include metadata in the comparison. Note that as metadata is the only column in the population table, two population tables are considered equal if they have the same number of rows if this flag is specified. Parameters Returns Return true if the specified table is equal to this table. int tsk_population_table_copy(const tsk_population_table_t *self, tsk_population_table_t *dest, tsk_flags_t options) Copies the state of this table into the specified destination. By default the method initialises the specified destination table. If the destination is already initialised, the TSK_NO_INIT option should be supplied to avoid leaking memory. Parameters • self – A pointer to a tsk_population_table_t object. • dest – A pointer to a tsk_population_table_t object. If the TSK_NO_INIT option is specified, this must be an initialised population table. If not, it must be an uninitialised population table. • options – Bitwise option flags. Returns Return 0 on success or a negative value on failure. int tsk_population_table_get_row(const tsk_population_table_t *self, tsk_id_t index, tsk_population_t *row) Get the row at the specified index. Updates the specified population struct to reflect the values in the specified row. Pointers to memory within this struct are handled by the table and should not be freed by client code. These pointers are guaranteed to be valid until the next operation that modifies the table (e.g., by adding a new row), but not afterwards. Parameters • self – A pointer to a tsk_population_table_t object. • index – The requested table row. • row – A pointer to a tsk_population_t struct that is updated to reflect the values in the specified row. Returns Return 0 on success or a negative value on failure. int tsk_population_table_set_metadata_schema(tsk_population_table_t *self, const char *metadata_schema, tsk_size_t metadata_schema_length) Set the metadata schema. Copies the metadata schema string to this table, replacing any existing. Parameters • self – A pointer to a tsk_population_table_t object. • metadata_schema – A pointer to a char array • metadata_schema_length – The size of the metadata schema in bytes. Returns Return 0 on success or a negative value on failure. void tsk_population_table_print_state(const tsk_population_table_t *self, FILE *out) Print out the state of this table to the specified stream. This method is intended for debugging purposes and should not be used in production code. The format of the output should not be depended on and may change arbitrarily between versions. Parameters ### Provenances¶ struct tsk_provenance_t A single provenance defined by a row in the provenance table. See the data model section for the definition of a provenance object and its properties. See the Provenance section for more information on how provenance records should be structured. Public Members tsk_id_t id Non-negative ID value corresponding to table row. const char *timestamp The timestamp. tsk_size_t timestamp_length The timestamp length in bytes. const char *record The record. tsk_size_t record_length The record length in bytes. struct tsk_provenance_table_t The provenance table. See the provenance table definition for details of the columns in this table. Public Members tsk_size_t num_rows The number of rows in this table. tsk_size_t timestamp_length The total length of the timestamp column. tsk_size_t record_length The total length of the record column. char *timestamp The timestamp column. tsk_size_t *timestamp_offset The timestamp_offset column. char *record The record column. tsk_size_t *record_offset The record_offset column. int tsk_provenance_table_init(tsk_provenance_table_t *self, tsk_flags_t options) Initialises the table by allocating the internal memory. This must be called before any operations are performed on the table. See the API structure for details on how objects are initialised and freed. Parameters • self – A pointer to an uninitialised tsk_provenance_table_t object. • options – Allocation time options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. int tsk_provenance_table_free(tsk_provenance_table_t *self) Free the internal memory for the specified table. Parameters Returns Always returns 0. tsk_id_t tsk_provenance_table_add_row(tsk_provenance_table_t *self, const char *timestamp, tsk_size_t timestamp_length, const char *record, tsk_size_t record_length) Adds a row to this provenance table. Add a new provenance with the specified timestamp and record to the table. Copies of the timestamp and record are immediately taken. See the table definition for details of the columns in this table. Parameters • self – A pointer to a tsk_provenance_table_t object. • timestamp – The timestamp to be associated with the new provenance. This is a pointer to arbitrary memory. Can be NULL if timestamp_length is 0. • timestamp_length – The size of the timestamp array in bytes. • record – The record to be associated with the new provenance. This is a pointer to arbitrary memory. Can be NULL if record_length is 0. • record_length – The size of the record array in bytes. Returns Return the ID of the newly added provenance on success, or a negative value on failure. int tsk_provenance_table_clear(tsk_provenance_table_t *self) Clears this table, setting the number of rows to zero. No memory is freed as a result of this operation; please use tsk_provenance_table_free() to free the table’s internal resources. Parameters Returns Return 0 on success or a negative value on failure. int tsk_provenance_table_truncate(tsk_provenance_table_t *self, tsk_size_t num_rows) Truncates this table so that only the first num_rows are retained. Parameters • self – A pointer to a tsk_provenance_table_t object. • num_rows – The number of rows to retain in the table. Returns Return 0 on success or a negative value on failure. int tsk_provenance_table_extend(tsk_provenance_table_t *self, const tsk_provenance_table_t *other, tsk_size_t num_rows, const tsk_id_t *row_indexes, tsk_flags_t options) Extends this table by appending rows copied from another table. Appends the rows at the specified indexes from the table other to the end of this table. Row indexes can be repeated and in any order. If row_indexes is NULL, append the first num_rows from other to this table. Parameters • self – A pointer to a tsk_provenance_table_t object where rows are to be added. • other – A pointer to a tsk_provenance_table_t object where rows are copied from. • num_rows – The number of rows from other to append to this table. • row_indexes – Array of row indexes in other. If NULL is passed then the first num_rows of other are used. • options – Bitwise option flags. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. Returns Return 0 on success or a negative value on failure. bool tsk_provenance_table_equals(const tsk_provenance_table_t *self, const tsk_provenance_table_t *other, tsk_flags_t options) Returns true if the data in the specified table is identical to the data in this table. Options Options to control the comparison can be specified by providing one or more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns. TSK_CMP_IGNORE_TIMESTAMPS Do not include the timestamp column when comparing provenance tables. Parameters Returns Return true if the specified table is equal to this table. int tsk_provenance_table_copy(const tsk_provenance_table_t *self, tsk_provenance_table_t *dest, tsk_flags_t options) Copies the state of this table into the specified destination. By default the method initialises the specified destination table. If the destination is already initialised, the TSK_NO_INIT option should be supplied to avoid leaking memory. Parameters • self – A pointer to a tsk_provenance_table_t object. • dest – A pointer to a tsk_provenance_table_t object. If the TSK_NO_INIT option is specified, this must be an initialised provenance table. If not, it must be an uninitialised provenance table. • options – Bitwise option flags. Returns Return 0 on success or a negative value on failure. int tsk_provenance_table_get_row(const tsk_provenance_table_t *self, tsk_id_t index, tsk_provenance_t *row) Get the row at the specified index. Updates the specified provenance struct to reflect the values in the specified row. Pointers to memory within this struct are handled by the table and should not be freed by client code. These pointers are guaranteed to be valid until the next operation that modifies the table (e.g., by adding a new row), but not afterwards. Parameters • self – A pointer to a tsk_provenance_table_t object. • index – The requested table row. • row – A pointer to a tsk_provenance_t struct that is updated to reflect the values in the specified row. Returns Return 0 on success or a negative value on failure. void tsk_provenance_table_print_state(const tsk_provenance_table_t *self, FILE *out) Print out the state of this table to the specified stream. This method is intended for debugging purposes and should not be used in production code. The format of the output should not be depended on and may change arbitrarily between versions. Parameters ## Table indexes¶ Along with the tree sequence ordering requirements, the Table indexes allow us to take a table collection and efficiently operate on the trees defined within it. This section defines the rules for safely operating on table indexes and their life-cycle. The edge index used for tree generation consists of two arrays, each holding N edge IDs (where N is the size of the edge table). When the index is computed using tsk_table_collection_build_index(), we store the current size of the edge table along with the two arrays of edge IDs. The function tsk_table_collection_has_index() then returns true iff (a) both of these arrays are not NULL and (b) the stored number of edges is the same as the current size of the edge table. Updating the edge table does not automatically invalidate the indexes. Thus, if we call tsk_edge_table_clear() on an edge table which has an index, this index will still exist. However, it will not be considered a valid index by tsk_table_collection_has_index() because of the size mismatch. Similarly for functions that increase the size of the table. Note that it is possible then to have tsk_table_collection_has_index() return true, but the index is not actually valid, if, for example, the user has manipulated the node and edge tables to describe a different topology, which happens to have the same number of edges. The behaviour of methods that use the indexes will be undefined in this case. Thus, if you are manipulating an existing table collection that may be indexed, it is always recommended to call tsk_table_collection_drop_index() first. ## Tree sequences¶ Warning This part of the API is more preliminary and may be subject to change. struct tsk_treeseq_t The tree sequence object. int tsk_treeseq_init(tsk_treeseq_t *self, const tsk_table_collection_t *tables, tsk_flags_t options) int tsk_treeseq_load(tsk_treeseq_t *self, const char *filename, tsk_flags_t options) int tsk_treeseq_loadf(tsk_treeseq_t *self, FILE *file, tsk_flags_t options) int tsk_treeseq_dump(const tsk_treeseq_t *self, const char *filename, tsk_flags_t options) int tsk_treeseq_dumpf(const tsk_treeseq_t *self, FILE *file, tsk_flags_t options) int tsk_treeseq_copy_tables(const tsk_treeseq_t *self, tsk_table_collection_t *tables, tsk_flags_t options) int tsk_treeseq_free(tsk_treeseq_t *self) void tsk_treeseq_print_state(const tsk_treeseq_t *self, FILE *out) ## Trees¶ Warning This part of the API is more preliminary and may be subject to change. struct tsk_tree_t A single tree in a tree sequence. A tsk_tree_t object has two basic functions: 1. Represent the state of a single tree in a tree sequence; 2. Provide methods to transform this state into different trees in the sequence. The state of a single tree in the tree sequence is represented using the quintuply linked encoding: please see the data model section for details on how this works. The left-to-right ordering of nodes in this encoding is arbitrary, and may change depending on the order in which trees are accessed within the sequence. Please see the Tree traversals examples for recommended usage. On initialisation, a tree is in a “null” state: each sample is a root and there are no edges. We must call one of the ‘seeking’ methods to make the state of the tree object correspond to a particular tree in the sequence. Please see the Tree iteration examples for recommended usage. Public Members const tsk_treeseq_t *tree_sequence The parent tree sequence. tsk_id_t left_root The leftmost root in the tree. Roots are siblings, and other roots can be found using right_sib. tsk_id_t *parent The parent of node u is parent[u]. Equal to TSK_NULL if node u is a root or is not a node in the current tree. tsk_id_t *left_child The leftmost child of node u is left_child[u]. Equal to TSK_NULL if node u is a leaf or is not a node in the current tree. tsk_id_t *right_child The rightmost child of node u is right_child[u]. Equal to TSK_NULL if node u is a leaf or is not a node in the current tree. tsk_id_t *left_sib The sibling to the left of node u is left_sib[u]. Equal to TSK_NULL if node u has no siblings to its left. tsk_id_t *right_sib The sibling to the right of node u is right_sib[u]. Equal to TSK_NULL if node u has no siblings to its right. int tsk_tree_init(tsk_tree_t *self, const tsk_treeseq_t *tree_sequence, tsk_flags_t options) int tsk_tree_free(tsk_tree_t *self) tsk_id_t tsk_tree_get_index(const tsk_tree_t *self) tsk_size_t tsk_tree_get_num_roots(const tsk_tree_t *self) int tsk_tree_first(tsk_tree_t *self) int tsk_tree_last(tsk_tree_t *self) int tsk_tree_next(tsk_tree_t *self) int tsk_tree_prev(tsk_tree_t *self) int tsk_tree_clear(tsk_tree_t *self) void tsk_tree_print_state(const tsk_tree_t *self, FILE *out) ## Low-level sorting¶ In some highly performance sensitive cases it can be useful to have more control over the process of sorting tables. This low-level API allows a user to provide their own edge sorting function. This can be useful, for example, to use parallel sorting algorithms, or to take advantage of the more efficient sorting procedures available in C++. It is the user’s responsibility to ensure that the edge sorting requirements are fulfilled by this function. Todo Create an idiomatic C++11 example where we load a table collection file from argv[1], and sort the edges using std::sort, based on the example in tests/test_minimal_cpp.cpp. We can include this in the examples below, and link to it here. struct _tsk_table_sorter_t Low-level table sorting method. Public Members tsk_table_collection_t *tables The input tables that are being sorted. int (*sort_edges)(struct _tsk_table_sorter_t *self, tsk_size_t start) The edge sorting function. If set to NULL, edges are not sorted. int (*sort_mutations)(struct _tsk_table_sorter_t *self) The mutation sorting function. int (*sort_individuals)(struct _tsk_table_sorter_t *self) The individual sorting function. void *user_data An opaque pointer for use by client code. tsk_id_t *site_id_map Mapping from input site IDs to output site IDs. int tsk_table_sorter_init(struct _tsk_table_sorter_t *self, tsk_table_collection_t *tables, tsk_flags_t options) Initialises the memory for the sorter object. This must be called before any operations are performed on the table sorter and initialises all fields. The edge_sort function is set to the default method using qsort. The user_data field is set to NULL. This method supports the same options as tsk_table_collection_sort(). Parameters • self – A pointer to an uninitialised tsk_table_sorter_t object. • tables – The table collection to sort. • options – Sorting options. Returns Return 0 on success or a negative value on failure. int tsk_table_sorter_run(struct _tsk_table_sorter_t *self, const tsk_bookmark_t *start) Runs the sort using the configured functions. Runs the sorting process: 1. Drop the table indexes. 2. If the sort_edges function pointer is not NULL, run it. The first parameter to the called function will be a pointer to this table_sorter_t object. The second parameter will be the value start.edges. This specifies the offset at which sorting should start in the edge table. This offset is guaranteed to be within the bounds of the edge table. 3. Sort the site table, building the mapping between site IDs in the current and sorted tables. 4. Sort the mutation table, using the sort_mutations pointer. If an error occurs during the execution of a user-supplied sorting function a non-zero value must be returned. This value will then be returned by tsk_table_sorter_run. The error return value should be chosen to avoid conflicts with tskit error codes. See tsk_table_collection_sort() for details on the start parameter. Parameters • self – A pointer to a tsk_table_sorter_t object. • start – The position in the tables at which sorting starts. Returns Return 0 on success or a negative value on failure. int tsk_table_sorter_free(struct _tsk_table_sorter_t *self) Free the internal memory for the specified table sorter. Parameters • self – A pointer to an initialised tsk_table_sorter_t object. Returns Always returns 0. ## Miscellaneous functions¶ const char *tsk_strerror(int err) Return a description of the specified error. The memory for the returned string is handled by the library and should not be freed by client code. Parameters • err – A tskit error code. Returns A description of the error. ## Constants¶ ### API Version¶ TSK_VERSION_MAJOR 0 The library major version. Incremented when breaking changes to the API or ABI are introduced. This includes any changes to the signatures of functions and the sizes and types of externally visible structs. TSK_VERSION_MINOR 99 The library major version. Incremented when non-breaking backward-compatible changes to the API or ABI are introduced, i.e., the addition of a new function. TSK_VERSION_PATCH 13 The library patch version. Incremented when any changes not relevant to the to the API or ABI are introduced, i.e., internal refactors of bugfixes. ### Generic Errors¶ TSK_ERR_GENERIC -1 Generic error thrown when no other message can be generated. TSK_ERR_NO_MEMORY -2 Memory could not be allocated. TSK_ERR_IO -3 An IO error occured. TSK_ERR_BAD_PARAM_VALUE -4 TSK_ERR_BUFFER_OVERFLOW -5 TSK_ERR_UNSUPPORTED_OPERATION -6 TSK_ERR_GENERATE_UUID -7 TSK_ERR_EOF -8 The file stream ended after reading zero bytes. ### File format errors¶ TSK_ERR_FILE_FORMAT -100 A file could not be read because it is in the wrong format TSK_ERR_FILE_VERSION_TOO_OLD -101 The file is in tskit format, but the version is too old for the library to read. The file should be upgraded to the latest version using the tskit upgrade command line utility. TSK_ERR_FILE_VERSION_TOO_NEW -102 The file is in tskit format, but the version is too new for the library to read. To read the file you must upgrade the version of tskit. Todo Add in groups for rest of the error types and document. ## Examples¶ ### Basic forwards simulator¶ This is an example of using the tables API to define a simple haploid Wright-Fisher simulator. Because this simple example repeatedly sorts the edge data, it is quite inefficient and should not be used as the basis of a large-scale simulator. Note This example uses the C function rand and constant RAND_MAX for random number generation. These methods are used for example purposes only and a high-quality random number library should be preferred for code used for research. Examples include, but are not limited to: 1. The GNU Scientific Library, which is licensed under the GNU General Public License, version 3 (GPL3+. 2. For C++ projects using C++11 or later, the built-in random number library. 3. The numpy C API may be useful for those writing Python extension modules in C/C++. Todo Give a pointer to an example that caches and flushes edge data efficiently. Probably using the C++ API? #include <stdio.h> #include <stdlib.h> #include <assert.h> #include <err.h> #include <tskit/tables.h> #define check_tsk_error(val) \ if (val < 0) { \ errx(EXIT_FAILURE, "line %d: %s", __LINE__, tsk_strerror(val)); \ } void simulate( tsk_table_collection_t *tables, int N, int T, int simplify_interval) { tsk_id_t *buffer, *parents, *children, child, left_parent, right_parent; double breakpoint; int ret, j, t, b; assert(simplify_interval != 0); // leads to division by zero buffer = malloc(2 * N * sizeof(tsk_id_t)); if (buffer == NULL) { errx(EXIT_FAILURE, "Out of memory"); } tables->sequence_length = 1.0; parents = buffer; for (j = 0; j < N; j++) { parents[j] = tsk_node_table_add_row(&tables->nodes, 0, T, TSK_NULL, TSK_NULL, NULL, 0); check_tsk_error(parents[j]); } b = 0; for (t = T - 1; t >= 0; t--) { /* Alternate between using the first and last N values in the buffer */ parents = buffer + (b * N); b = (b + 1) % 2; children = buffer + (b * N); for (j = 0; j < N; j++) { child = tsk_node_table_add_row( &tables->nodes, 0, t, TSK_NULL, TSK_NULL, NULL, 0); check_tsk_error(child); /* NOTE: the use of rand() is discouraged for * research code and proper random number generator * libraries should be preferred. */ left_parent = parents[(size_t)((rand()/(1.+RAND_MAX))*N)]; right_parent = parents[(size_t)((rand()/(1.+RAND_MAX))*N)]; do { breakpoint = rand()/(1.+RAND_MAX); } while (breakpoint == 0); /* tiny proba of breakpoint being 0 */ ret = tsk_edge_table_add_row( &tables->edges, 0, breakpoint, left_parent, child, NULL, 0); check_tsk_error(ret); ret = tsk_edge_table_add_row( &tables->edges, breakpoint, 1, right_parent, child, NULL, 0); check_tsk_error(ret); children[j] = child; } if (t % simplify_interval == 0) { printf("Simplify at generation %lld: (%lld nodes %lld edges)", (long long) t, (long long) tables->nodes.num_rows, (long long) tables->edges.num_rows); /* Note: Edges must be sorted for simplify to work, and we use a brute force * approach of sorting each time here for simplicity. This is inefficient. */ ret = tsk_table_collection_sort(tables, NULL, 0); check_tsk_error(ret); ret = tsk_table_collection_simplify(tables, children, N, 0, NULL); check_tsk_error(ret); printf(" -> (%lld nodes %lld edges)\n", (long long) tables->nodes.num_rows, (long long) tables->edges.num_rows); for (j = 0; j < N; j++) { children[j] = j; } } } free(buffer); } int main(int argc, char **argv) { int ret; tsk_table_collection_t tables; if (argc != 6) { errx(EXIT_FAILURE, "usage: N T simplify-interval output-file seed"); } ret = tsk_table_collection_init(&tables, 0); check_tsk_error(ret); srand((unsigned)atoi(argv[5])); simulate(&tables, atoi(argv[1]), atoi(argv[2]), atoi(argv[3])); ret = tsk_table_collection_dump(&tables, argv[4], 0); check_tsk_error(ret); tsk_table_collection_free(&tables); return 0; }  ### Tree iteration¶ #include <stdio.h> #include <stdlib.h> #include <err.h> #include <tskit.h> #define check_tsk_error(val) \ if (val < 0) { \ errx(EXIT_FAILURE, "line %d: %s", __LINE__, tsk_strerror(val)); \ } int main(int argc, char **argv) { int ret, iter; tsk_treeseq_t ts; tsk_tree_t tree; if (argc != 2) { errx(EXIT_FAILURE, "usage: <tree sequence file>"); } ret = tsk_treeseq_load(&ts, argv[1], 0); check_tsk_error(ret); ret = tsk_tree_init(&tree, &ts, 0); check_tsk_error(ret); printf("Iterate forwards\n"); for (iter = tsk_tree_first(&tree); iter == 1; iter = tsk_tree_next(&tree)) { printf("\ttree %lld has %lld roots\n", (long long) tsk_tree_get_index(&tree), (long long) tsk_tree_get_num_roots(&tree)); } check_tsk_error(iter); printf("Iterate backwards\n"); for (iter = tsk_tree_last(&tree); iter == 1; iter = tsk_tree_prev(&tree)) { printf("\ttree %lld has %lld roots\n", (long long) tsk_tree_get_index(&tree), (long long) tsk_tree_get_num_roots(&tree)); } check_tsk_error(iter); tsk_tree_free(&tree); tsk_treeseq_free(&ts); return 0; }  ### Tree traversals¶ In this example we load a tree sequence file, and then traverse the first tree in three different ways: 1. We first traverse the tree in preorder using recursion. This is a very common way of navigating around trees and can be very convenient for some applications. For example, here we compute the depth of each node (i.e., it’s distance from the root) and use this when printing out the nodes as we visit them. 2. Then we traverse the tree in preorder using an iterative approach. This is a little more efficient than using recursion, and is sometimes more convenient than structuring the calculation recursively. Note that we allocate a stack here with space to hold the total number of nodes in the tree sequence. This is safe, but it likely to be a massive over estimate. However, this makes very little difference in practise even for tree sequences with millions of nodes since it’s likely only the first page (usually 4K) will be written to and the rest of the stack will never therefore be mapped to physical memory. 3. In the third example we iterate upwards from the samples rather than downwards from the root. #include <stdio.h> #include <stdlib.h> #include <err.h> #include <tskit.h> #define check_tsk_error(val) \ if (val < 0) { \ errx(EXIT_FAILURE, "line %d: %s", __LINE__, tsk_strerror(val)); \ } static void _traverse(tsk_tree_t *tree, tsk_id_t u, int depth) { tsk_id_t v; int j; for (j = 0; j < depth; j++) { printf(" "); } printf("Visit recursive %lld\n", (long long) u); for (v = tree->left_child[u]; v != TSK_NULL; v = tree->right_sib[v]) { _traverse(tree, v, depth + 1); } } static void traverse_recursive(tsk_tree_t *tree) { tsk_id_t root; for (root = tree->left_root; root != TSK_NULL; root = tree->right_sib[root]) { _traverse(tree, root, 0); } } static void traverse_stack(tsk_tree_t *tree) { int stack_top; tsk_id_t u, v, root; tsk_id_t *stack = malloc(tsk_treeseq_get_num_nodes(tree->tree_sequence) * sizeof(*stack)); if (stack == NULL) { errx(EXIT_FAILURE, "Out of memory"); } for (root = tree->left_root; root != TSK_NULL; root = tree->right_sib[root]) { stack_top = 0; stack[stack_top] = root; while (stack_top >= 0) { u = stack[stack_top]; stack_top--; printf("Visit stack %lld\n", (long long) u); /* Put nodes on the stack right-to-left, so we visit in left-to-right */ for (v = tree->right_child[u]; v != TSK_NULL; v = tree->left_sib[v]) { stack_top++; stack[stack_top] = v; } } } free(stack); } static void traverse_upwards(tsk_tree_t *tree) { const tsk_id_t *samples = tsk_treeseq_get_samples(tree->tree_sequence); tsk_size_t num_samples = tsk_treeseq_get_num_samples(tree->tree_sequence); tsk_size_t j; tsk_id_t u; for (j = 0; j < num_samples; j++) { u = samples[j]; while (u != TSK_NULL) { printf("Visit upwards: %lld\n", (long long) u); u = tree->parent[u]; } } } int main(int argc, char **argv) { int ret; tsk_treeseq_t ts; tsk_tree_t tree; if (argc != 2) { errx(EXIT_FAILURE, "usage: <tree sequence file>"); } ret = tsk_treeseq_load(&ts, argv[1], 0); check_tsk_error(ret); ret = tsk_tree_init(&tree, &ts, 0); check_tsk_error(ret); ret = tsk_tree_first(&tree); check_tsk_error(ret); traverse_recursive(&tree); traverse_stack(&tree); traverse_upwards(&tree); tsk_tree_free(&tree); tsk_treeseq_free(&ts); return 0; }  ### File streaming¶ It is often useful to read tree sequence files from a stream rather than from a fixed filename. This example shows how to do this using the tsk_table_collection_loadf() and tsk_table_collection_dumpf() functions. Here, we sequentially load table collections from the stdin stream and write them back out to stdout with their mutations removed. #include <stdio.h> #include <stdlib.h> #include <tskit/tables.h> #define check_tsk_error(val) \ if (val < 0) { \ fprintf(stderr, "Error: line %d: %s\n", __LINE__, tsk_strerror(val)); \ exit(EXIT_FAILURE); \ } int main(int argc, char **argv) { int ret; int j = 0; tsk_table_collection_t tables; ret = tsk_table_collection_init(&tables, 0); check_tsk_error(ret); while (true) { ret = tsk_table_collection_loadf(&tables, stdin, TSK_NO_INIT); if (ret == TSK_ERR_EOF) { break; } check_tsk_error(ret); fprintf(stderr, "Tree sequence %d had %lld mutations\n", j, (long long) tables.mutations.num_rows); ret = tsk_mutation_table_truncate(&tables.mutations, 0); check_tsk_error(ret); ret = tsk_table_collection_dumpf(&tables, stdout, 0); check_tsk_error(ret); j++; } tsk_table_collection_free(&tables); return EXIT_SUCCESS; }  Note that we use the value TSK_ERR_EOF to detect when the stream ends, as we don’t know how many tree sequences to expect on the input. In this case, TSK_ERR_EOF is not considered an error and we exit normally. Running this program on some tree sequence files we might get: $ cat tmp1.trees tmp2.trees | ./build/streaming > no_mutations.trees
Tree sequence 0 had 38 mutations
Tree sequence 1 had 132 mutations


Then, running this program again on the output of the previous command, we see that we now have two tree sequences with their mutations removed stored in the file no_mutations.trees:

\$ ./build/streaming < no_mutations.trees > /dev/null
Tree sequence 0 had 0 mutations
Tree sequence 1 had 0 mutations