- We assume familiarity with
tskit. See tskit.dev.
- Comfort with rust is required.
tskit means the rust API.
tskit-python refer to the C and Python APIs, respectively.
The phrase "data model" refers to this. This document will make little sense without an understanding of the data model.
Where necessary, we will note differences from the behavior of
Much of the rust API works by calling the C API. We do not change the semantics of the C API. However, we do make stricter statements about the ownership relationships between types. For example, the C API can result in the following situation:
- A heap-allocated table collection is used to record data about the ancestry of a sample.
- That table collection is used to initialize a tree sequence. The tree sequence is told to take ownership of the tables.
This is a case where the C API requires that you respectfully no longer work with the heap-allocated table collection. To do so is undefined behavior.
The rust API forbids such situations. The creation of a tree sequence from tables consumes the tables via a move operation. Thus, any further actions on the tables is a compiler error.
This example is the kinds of differences between
Undefined behavior is (close to) impossible with
The use-cases for
tskit-rust are the same as for
- Developing a new performance-oriented application.
- The input/output of this application will be a
Briefly, you get the performance of
C and the strong safety guarantees of
The crate does not cover the entire
However, client code can make direct calls to that API via the module
[dependencies] tskit = "~X.Y.Z"