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

• EdgeDifference
  An edge difference. Edge insertions and removals are differentiated by marker types Insertion and Removal, respectively.
• EdgeDifferences
  Concrete type implementing Iterator over EdgeInsertion or EdgeRemoval. Created by EdgeDifferencesIterator::edge_insertions or EdgeDifferencesIterator::edge_removals, respectively.
• EdgeDifferencesIterator
  Manages iteration over trees to obtain edge differences.
• 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].
• 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.
• 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
• NodeDefaults
  Defaults for node table rows without metadata
• NodeDefaultsWithMetadata
  Notes
• NodeFlags
  Node flags
• NodeId
  A node ID
• NodeTable
  An immtable view of a node table.
• NodeTableRow
  Row of a NodeTable
• OwningEdgeTable
  A standalone edge table that owns its data.
• OwningIndividualTable
  A standalone individual table that owns its data.
• OwningMigrationTable
  A standalone migration table that owns its data.
• OwningMutationTable
  A standalone mutation table that owns its data.
• OwningNodeTable
  A standalone node table that owns its data.
• OwningPopulationTable
  A standalone population table that owns its data.
• OwningSiteTable
  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
• Removal
  Marker type for edge removal.
• 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
  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 [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.

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

• 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.