Struct tskit::TreeSequence

pub struct TreeSequence { /* fields omitted */ }

A tree sequence.

This is a thin wrapper around the C type tsk_treeseq_t.

When created from a TableCollection, the input tables are moved into the TreeSequence object.

Examples

let mut tables = tskit::TableCollection::new(1000.).unwrap();
tables.add_node(0, 1.0, tskit::TSK_NULL, tskit::TSK_NULL).unwrap();
tables.add_node(0, 0.0, tskit::TSK_NULL, tskit::TSK_NULL).unwrap();
tables.add_node(0, 0.0, tskit::TSK_NULL, tskit::TSK_NULL).unwrap();
tables.add_edge(0., 1000., 0, 1).unwrap();
tables.add_edge(0., 1000., 0, 2).unwrap();

// index
tables.build_index();

// tables gets moved into our treeseq variable:
let treeseq = tables.tree_sequence(tskit::TreeSequenceFlags::default()).unwrap();

Implementations

impl TreeSequence

pub fn new(
    tables: TableCollection,
    flags: TreeSequenceFlags
) -> Result<Self, TskitError>

Create a tree sequence from a TableCollection. In general, TableCollection::tree_sequence may be preferred. The table collection is moved/consumed.

Parameters

• tables, a TableCollection

Errors

• TskitError if the tables are not indexed.

Examples

let mut tables = tskit::TableCollection::new(1000.).unwrap();
tables.build_index();
let tree_sequence = tskit::TreeSequence::new(tables, tskit::TreeSequenceFlags::default()).unwrap();

The following may be preferred to the previous example, and more closely mimics the Python tskit interface:

let mut tables = tskit::TableCollection::new(1000.).unwrap();
tables.build_index();
let tree_sequence = tables.tree_sequence(tskit::TreeSequenceFlags::default()).unwrap();

The following raises an error because the tables are not indexed:

let mut tables = tskit::TableCollection::new(1000.).unwrap();
let tree_sequence = tskit::TreeSequence::new(tables,
tskit::TreeSequenceFlags::default()).unwrap();

pub fn dump(
    &self,
    filename: &str,
    options: TableOutputOptions
) -> TskReturnValue

Dump the tree sequence to file.

Note

• options is currently not used. Set to default value. This behavior may change in a future release, which could break API.

Note

This function always sets the flag TSK_NO_BUILD_INDEXES.

pub fn load(filename: &str) -> Result<Self, TskitError>

Load from a file.

pub fn dump_tables(&self) -> Result<TableCollection, TskitError>

Obtain a copy of the TableCollection. The result is a “deep” copy of the tables.

Errors

TskitError will be raised if the underlying C library returns an error code.

pub fn tree_iterator(&self, flags: TreeFlags) -> Result<Tree, TskitError>

Create an iterator over trees.

Parameters

• flags A TreeFlags bit field.

Errors

Examples

// You must include streaming_iterator as a dependency
// and import this type.
use streaming_iterator::StreamingIterator;
// Import this to allow .next_back() for reverse
// iteration over trees.
use streaming_iterator::DoubleEndedStreamingIterator;

let mut tables = tskit::TableCollection::new(1000.).unwrap();
tables.build_index();
let tree_sequence = tables.tree_sequence(tskit::TreeSequenceFlags::default()).unwrap();
let mut tree_iterator = tree_sequence.tree_iterator(tskit::TreeFlags::default()).unwrap();
while let Some(tree) = tree_iterator.next() {
}

Warning

The following code results in an infinite loop. Be sure to note the difference from the previous example.

use streaming_iterator::StreamingIterator;

let mut tables = tskit::TableCollection::new(1000.).unwrap();
tables.build_index();
let tree_sequence = tables.tree_sequence(tskit::TreeSequenceFlags::default()).unwrap();
while let Some(tree) = tree_sequence.tree_iterator(tskit::TreeFlags::default()).unwrap().next() {
}

pub fn samples_to_vec(&self) -> Vec<tsk_id_t>

Get the list of samples as a vector.

pub fn num_trees(&self) -> tsk_size_t

Get the number of trees.

pub fn kc_distance(
    &self,
    other: &TreeSequence,
    lambda: f64
) -> Result<f64, TskitError>

Calculate the average Kendall-Colijn (K-C) distance between pairs of trees whose intervals overlap.

Note

• Citation

Parameters

• lambda specifies the relative weight of topology and branch length. See Tree::kc_distance for more details.

pub fn num_samples(&self) -> tsk_size_t

pub fn simplify(
    &self,
    samples: &[tsk_id_t],
    options: SimplificationOptions,
    idmap: bool
) -> Result<(Self, Option<Vec<tsk_id_t>>), TskitError>

Simplify tables and return a new tree sequence.

Parameters

• samples: a slice containing non-null node ids. The tables are simplified with respect to the ancestry of these nodes.
• options: A SimplificationOptions bit field controlling the behavior of simplification.
• idmap: if true, the return value contains a vector equal in length to the input node table. For each input node, this vector either contains the node’s new index or TSK_NULL if the input node is not part of the simplified history.

Trait Implementations

impl Drop for TreeSequence

fn drop(&mut self)

Executes the destructor for this type.

impl NodeListGenerator for TreeSequence

fn samples_as_vector(&self) -> Vec<tsk_id_t>

Obtain a vector containing the indexes (“ids”) of all nodes for which crate::TSK_NODE_IS_SAMPLE is true.

fn create_node_id_vector(
    &self,
    f: impl FnMut(&NodeTableRow) -> bool
) -> Vec<tsk_id_t>

Obtain a vector containing the indexes (“ids”) of all nodes satisfying a certain criterion.

impl Provenance for TreeSequence

fn add_provenance(&mut self, record: &str) -> TskReturnValue

Add provenance record with a time stamp.

fn provenances(&self) -> ProvenanceTable<'_>

Return an immutable reference to the table, type ProvenanceTable

fn provenances_iter(&self) -> TableIterator<ProvenanceTable<'_>>

Return an iterator over the rows of the ProvenanceTable. See ProvenanceTable::iter for details.

impl TableAccess for TreeSequence

fn edges(&self) -> EdgeTable<'_>

Get reference to the EdgeTable.

fn individuals(&self) -> IndividualTable<'_>

Get reference to the IndividualTable.

fn migrations(&self) -> MigrationTable<'_>

Get reference to the MigrationTable.

fn nodes(&self) -> NodeTable<'_>

Get reference to the NodeTable.

fn sites(&self) -> SiteTable<'_>

Get reference to the SiteTable.

fn mutations(&self) -> MutationTable<'_>

Get reference to the MutationTable.

fn populations(&self) -> PopulationTable<'_>

Get reference to the PopulationTable.

fn edges_iter(&self, decode_metadata: bool) -> TableIterator<EdgeTable<'_>>

Return an iterator over the edges. See EdgeTable::iter for details.

fn nodes_iter(&self, decode_metadata: bool) -> TableIterator<NodeTable<'_>>

Return an iterator over the nodes. See NodeTable::iter for details.

fn mutations_iter(
    &self,
    decode_metadata: bool
) -> TableIterator<MutationTable<'_>>

Return an iterator over the mutations. See MutationTable::iter for details.

fn sites_iter(&self, decode_metadata: bool) -> TableIterator<SiteTable<'_>>

Return an iterator over the sites. See SiteTable::iter for details.

fn populations_iter(
    &self,
    decode_metadata: bool
) -> TableIterator<PopulationTable<'_>>

Return an iterator over the populations. See PopulationTable::iter for details.

fn migrations_iter(
    &self,
    decode_metadata: bool
) -> TableIterator<MigrationTable<'_>>

Return an iterator over the migration events. See MigrationTable::iter for details.

fn individuals_iter(
    &self,
    decode_metadata: bool
) -> TableIterator<IndividualTable<'_>>

Return an iterator over the individuals. See IndividualTable::iter for details.

impl TskitTypeAccess<tsk_treeseq_t> for TreeSequence

fn as_ptr(&self) -> *const tsk_treeseq_t

Return const pointer

fn as_mut_ptr(&mut self) -> *mut tsk_treeseq_t

Return mutable pointer