Crate tskit 

A rust interface to tskit.

This crate provides a mapping of the tskit C API to rust. The result is an interface similar to the tskit Python interface, but with all operations implemented using compiled code.

Features

Interface to the C library

• TableCollection wraps tsk_table_collection_t.
• TreeSequence wraps tsk_treeseq_t.
• Tree wraps tsk_tree_t.
• Tree iteration occurs via traits from streaming_iterator.
• Errors returned from C map to TskitError::ErrorCode. Their string messages can be obtained by printing the error type.

Safety

• The types listed above handle all the memory management!
• All array accesses are range-checked.
• Object lifetimes are clear:
  • Creating a tree sequence moves/consumes a table collection.
  • Tree lifetimes are tied to that of the parent tree sequence.
  • Table objects (NodeTable, etc..) are only represented by non-owning, immutable types.

Prelude

The prelude module contains definitions that are difficult/annoying to live without. In particuar, this module exports various traits that make it so that client code does not have to use them a la carte.

We recomment that client code import all symbols from this module:

use tskit::prelude::*;

The various documentation examples manually use each trait both in order to illustrate which traits are needed and to serve as doc tests.

Optional features

Some features are optional, and are activated by requesting them in your Cargo.toml file.

• provenance

  • Enables provenance

• derive enables the following derive macros:

  • crate::metadata::MutationMetadata
  • crate::metadata::IndividualMetadata
  • crate::metadata::SiteMetadata
  • crate::metadata::EdgeMetadata
  • crate::metadata::NodeMetadata
  • crate::metadata::MigrationMetadata
  • crate::metadata::PopulationMetadata

  To see these derive macros in action, take a look here.

• unsafe_init enables crate::TableCollection::new_from_raw

To add features to your Cargo.toml file:

[dependencies]
tskit = {version = "0.2.0", features=["feature0", "feature1"]}

Table rows and iterators over rows

Background: what is going on at the C level

The C API represents a row as a struct containing various fields. For example, a “mutation” (row of a mutation table) is represented by crate::bindings::tsk_mutation_t.

These low-level types contain pointers into ragged arrays such as metadata. These pointers do not point to new allocations. Rather, they point to subsets of the ragged arrays found in the parent objects (tables).

The API to populate the row types is to first allocate one (either on the stack or on the heap) and then call a function. For example, crate::bindings::tsk_mutation_table_get_row will fill in the fields of a crate::bindings::tsk_mutation_t.

The challenge on the rust side is how to specify the lifetime relationship between a row object and its parent object.

Differences between table collections and tree sequences

The row types mentioned above can be accessed from table collections and from tree sequences.

However, tree sequence initialization pre-computes site and mutation objects as well as the nodes associated with individuals. Therefore, we can obtain constant-time access to references to site and mutation objects from a tree sequence.

The situation for objects directly from table collections poses a challenge. We could re-use an instance of a row object for, say, a “mutation table row iterator” type, but doing so would result in incorrect data if the output values were stored. (Re-use would mean that the pointers to metadata, etc., would get re-written at each “turn” of the iterator.) Therefore, when accessing from tables, we return new instances of the low level types.

The relevant rust types

For tables:

• Node is returned by NodeTable::row and is the iterator value of NodeTable::iter and TableCollection::node_iter.
• Edge is returned by EdgeTable::row and is the iterator value of EdgeTable::iter and TableCollection::edge_iter.
• Individual is returned by IndividualTable::row and is the iterator value of IndividualTable::iter and TableCollection::individual_iter.
• Site is returned by SiteTable::row and is the iterator value of SiteTable::iter and TableCollection::site_iter.
• Mutation is returned by MutationTable::row and is the iterator value of MutationTable::iter and TableCollection::mutation_iter.
• Population is returned by PopulationTable::row and is the iterator value of PopulationTable::iter and TableCollection::population_iter.
• Migration is returned by MigrationTable::row and is the iterator value of MigrationTable::iter and TableCollection::migration_iter.
• Provenance is returned by provenance::ProvenanceTable::row and is the iterator value of provenance::ProvenanceTable::iter and TableCollection::provenance_iter.

These types are thin wrappers around the C types and have the same sizeof and alignment.

For table collections and trees:

• SiteRef and MutationRef replace Site and Mutation, respectively.
• SiteRef is the output of TreeSequence::site_iter and Tree::site_iter.
• MutationRef is the output of SiteRef::mutation_iter.

These “Ref” types are thin wrappers around shared references to the underlying C types.

Further,

• TreeSequence::individual_iter outputs Individual objects whose nodes field is populated (if the individual is associated w/any nodes).

What is missing?

• A lot of wrappers to the C functions.
• Tree sequence statistics!

Manual

A manual is here.

Re-exports

pub use error::TskitError;

Modules

bindingsbindings

Low-level (“unsafe”) bindings to the C API.

error

Error handling

metadata

Support for table row metadata

prelude

Export commonly-use types and traits

provenanceprovenance

Optional module for table and tree sequence provenance tables.

types

“Other” tskit types live here.

Macros

handle_metadata_return

Convenience macro to handle implementing crate::metadata::MetadataRoundtrip

Structs

CurrentTreeEdgeDifferences

Edge

A lifetime-bound Edge.

EdgeDifference

An edge difference. Edge insertions and removals are differentiated by marker types Insertion and Removal, respectively.

EdgeDifferencesIterator

Manages iteration over trees to obtain edge differences.

EdgeId

An edge ID

EdgeInsertionsIterator

EdgeRemovalsIterator

EdgeTable

An edge table.

Individual

A lifetime-bound Individual.

IndividualFlags

Individual flags

IndividualId

An individual ID

IndividualTable

An individual table.

IndividualTableSortOptions

Modify behavior of crate::TableCollection::topological_sort_individuals.

Insertion

Marker type for edge insertion.

Location

A newtype for the concept of location. A Location may represent a location or the output of arithmetic involving locations.

Migration

A lifetime-bound Migration.

MigrationId

A migration ID

MigrationTable

A migration table.

Mutation

A lifetime-bound Mutation.

MutationId

A mutation ID

MutationParentsFlags

MutationRef

Reference to a mutation stored in a tree sequence.

MutationTable

An immutable view of site table.

Node

A lifetime-bound Node.

NodeDefaults

Defaults for node table rows without metadata

NodeDefaultsWithMetadata

Notes

NodeFlags

NodeId

A node ID

NodeTable

A node table

Population

A lifetime-bound Population.

PopulationId

A population ID

PopulationTable

A population table

Position

A newtype for the concept of “genomic position”. A Position can represent either a locus or a distance between loci.

Provenanceprovenance

ProvenanceIdprovenance

A provenance ID

Removal

Marker type for edge removal.

SimplificationOptions

Control the behavior of table simplification.

Site

A lifetime-bound site.

SiteId

A site ID

SiteRef

Reference to a site stored in a tree sequence.

SiteTable

A site table.

SizeType

Wraps tsk_size_t

TableClearOptions

Modify behavior of crate::TableCollection::clear.

TableCollection

A table collection.

TableEqualityOptions

Modify behavior of crate::TableCollection::equals.

TableIntegrityCheckFlags

Flags to affect the behavior of TableCollection::check_integrity.

TableOutputOptions

Modify behavior of crate::TableCollection::dump.

TableSortOptions

Modify behavior of crate::TableCollection::sort.

Time

A newtype for the concept of time. A Time value can represent either a point in time or the output of arithmetic involving time.

Tree

A Tree.

TreeFlags

Specify the behavior of iterating over crate::Tree objects. See crate::TreeSequence::tree_iterator.

TreeSequence

A tree sequence.

TreeSequenceFlags

Modify behavior of crate::TableCollection::tree_sequence and crate::TreeSequence::new.

Enums

NodeTraversalOrder

Traits

DoubleEndedStreamingIterator

A streaming iterator able to yield elements from both ends.

IndividualLocation

Abstraction of individual location.

IndividualParents

Abstraction of individual parents.

StreamingIterator

An interface for dealing with streaming iterators.

TableColumn

Interface of a non-ragged table column.

Functions

c_api_major_version

C API major version

c_api_minor_version

C API minor version

c_api_patch_version

C API patch version

c_api_version

The C API version in MAJOR.MINOR.PATCH format

version

Version of the rust crate.

Type Aliases

EdgeInsertion

Type alias for EdgeDifference<Insertion>

EdgeRemoval

Type alias for EdgeDifference<Removal>

RawFlags

Alias for tsk_flags_t

TskReturnValue

Handles return codes from low-level tskit functions.