Expand description
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
wrapstsk_table_collection_t
.TreeSequence
wrapstsk_treeseq_t
.Tree
wrapstsk_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
- Enables
-
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
- Low-level (“unsafe”) bindings to the C API.
- Error handling
- Support for table row metadata
- Export commonly-use types and traits
- provenance
provenance
Optional module for table and tree sequence provenance tables. - “Other” tskit types live here.
Macros
- Convenience macro to handle implementing
crate::metadata::MetadataRoundtrip
Structs
- Concrete type implementing
Iterator
overEdgeInsertion
orEdgeRemoval
. Created byEdgeDifferencesIterator::edge_insertions
orEdgeDifferencesIterator::edge_removals
, respectively. - Manages iteration over trees to obtain edge differences.
- An edge ID
- An immutable view of an edge table.
- Row of an
EdgeTable
- Individual flags
- An individual ID
- An immutable view of a individual table.
- Row of a
IndividualTable
- Modify behavior of [
crate::TableCollection::sort_individuals
]. - Marker type for edge insertion.
- A newtype for the concept of location. A
Location
may represent a location or the output of arithmetic involving locations. - A migration ID
- An immutable view of a migration table.
- Row of a
MigrationTable
- A mutation ID
- An immutable view of site table.
- Row of a
MutationTable
- Defaults for node table rows without metadata
- Notes
- Node flags
- A node ID
- An immtable view of a node table.
- Row of a
NodeTable
- A standalone edge table that owns its data.
- A standalone individual table that owns its data.
- A standalone migration table that owns its data.
- A standalone mutation table that owns its data.
- A standalone node table that owns its data.
- A standalone population table that owns its data.
- A standalone site table that owns its data.
- A population ID
- An immutable view of site table.
- Row of a
PopulationTable
- A newtype for the concept of “genomic position”. A
Position
can represent either a locus or a distance between loci. - ProvenanceId
provenance
A provenance ID - Marker type for edge removal.
- Control the behavior of
crate::TableCollection::simplify
andcrate::TreeSequence::simplify
- A site ID
- An immutable view of site table.
- Row of a
SiteTable
- Wraps
tsk_size_t
- Modify behavior of
crate::TableCollection::clear
. - A table collection.
- Modify behavior of
crate::TableCollection::equals
. - Flags to affect the behavior of
TableCollection::check_integrity
. - Modify behavior of
crate::TableCollection::dump
. - Modify behavior of
crate::TableCollection::sort
. - A newtype for the concept of time. A
Time
value can represent either a point in time or the output of arithmetic involving time. - A Tree.
- Specify the behavior of iterating over [
Tree
] objects. See [TreeSequence::tree_iterator
]. - A tree sequence.
- Modify behavior of
crate::TableCollection::tree_sequence
andcrate::TreeSequence::new
.
Enums
- Specify the traversal order used by
TreeInterface::traverse_nodes
.
Traits
- Abstraction of individual location.
- Abstraction of individual parents.
Functions
- C API major version
- C API minor version
- C API patch version
- The C API version in MAJOR.MINOR.PATCH format
- Version of the rust crate.
Type Definitions
- Type alias for
EdgeDifference<Insertion>
- Type alias for
EdgeDifference<Removal>
- Alias for tsk_flags_t
- Handles return codes from low-level tskit functions.