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.

To add features to your Cargo.toml file:

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

What is missing?

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

Re-exports

pub use bindings::TSK_NODE_IS_SAMPLE;

pub use bindings::tsk_flags_t;

pub use error::TskitError;

Modules

bindings

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

EdgeId

An edge ID

EdgeTable

An immutable view of an edge table.

EdgeTableRow

Row of an EdgeTable

IndividualFlags

Individual flags

IndividualId

An individual ID

IndividualTable

An immutable view of a individual table.

IndividualTableRow

Row of a IndividualTable

IndividualTableSortOptions

Modify behavior of [crate::TableCollection::sort_individuals].

Location

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

MigrationId

A migration ID

MigrationTable

An immutable view of a migration table.

MigrationTableRow

Row of a MigrationTable

MutationId

A mutation ID

MutationTable

An immutable view of site table.

MutationTableRow

Row of a MutationTable

NodeFlags

Node flags

NodeId

A node ID

NodeTable

An immtable view of a node table.

NodeTableRow

Row of a NodeTable

OwnedEdgeTable

A standalone edge table that owns its data.

OwnedIndividualTable

A standalone individual table that owns its data.

OwnedMigrationTable

A standalone migration table that owns its data.

OwnedMutationTable

A standalone mutation table that owns its data.

OwnedNodeTable

A standalone node table that owns its data.

OwnedPopulationTable

A standalone population table that owns its data.

OwnedSiteTable

A standalone site table that owns its data.

PopulationId

A population ID

PopulationTable

An immutable view of site table.

PopulationTableRow

Row of a PopulationTable

Position

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

ProvenanceIdprovenance

A provenance ID

SimplificationOptions

Control the behavior of crate::TableCollection::simplify and crate::TreeSequence::simplify

SiteId

A site ID

SiteTable

An immutable view of site table.

SiteTableRow

Row of a SiteTable

SizeType

Wraps tsk_size_t

TableClearOptions

Modify behavior of crate::TableCollection::clear.

TableCollection

A table collection.

TableEqualityOptions

Modify behavior of crate::TableCollection::equals.

TableIntegrityCheckFlags

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 [Tree] objects. See [TreeSequence::tree_iterator].

TreeInterface

TreeSequence

A tree sequence.

TreeSequenceFlags

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

Enums

NodeTraversalOrder

Specify the traversal order used by TreeInterface::traverse_nodes.

Traits

IndividualLocation

Abstraction of individual location.

IndividualParents

Abstraction of individual parents.

NodeListGenerator

Interface for returning lists of node ids from types implementing TableAccess.

TableAccess

Immutable access to tables.

TskitTypeAccess

Provide pointer access to underlying C types

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 Definitions

RawFlags

Alias for tsk_flags_t

TskReturnValue

Handles return codes from low-level tskit functions.