Struct TreeInterface

pub struct TreeInterface { /* private fields */ }

Implementations

impl TreeInterface

pub fn as_ptr(&self) -> *const tsk_tree_t

Pointer to the low-level C type.

pub fn as_mut_ptr(&mut self) -> *mut tsk_tree_t

Mutable pointer to the low-level C type.

pub fn flags(&self) -> TreeFlags

pub fn parent_array(&self) -> &[NodeId]

Failing examples

The lifetime of the slice is tied to the parent object:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::default()).unwrap();
while let Some(tree) = tree_iter.next() {
    let p = tree.parent_array();
    drop(tree_iter);
    for _ in p {} // ERROR
}

pub fn samples_array(&self) -> Result<&[NodeId], TskitError>

Failing examples

An error will be returned if [’crate::TreeFlags::SAMPLE_LISTS`] is not used:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::default()).unwrap(); // ERROR
while let Some(tree) = tree_iter.next() {
    let s = tree.samples_array().unwrap();
    for _ in s {}
}

The lifetime of the slice is tied to the parent object:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::SAMPLE_LISTS).unwrap();
while let Some(tree) = tree_iter.next() {
    let s = tree.samples_array().unwrap();
    drop(tree_iter);
    for _ in s {} // ERROR
}

pub fn next_sample_array(&self) -> Result<&[NodeId], TskitError>

Failing examples

An error will be returned if [’crate::TreeFlags::SAMPLE_LISTS`] is not used:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::default()).unwrap(); // ERROR
while let Some(tree) = tree_iter.next() {
    let n = tree.next_sample_array().unwrap();
    for _ in n {}
}

The lifetime of the slice is tied to the parent object:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::SAMPLE_LISTS).unwrap();
while let Some(tree) = tree_iter.next() {
    let n = tree.next_sample_array().unwrap();
    drop(tree_iter);
    for _ in n {} // ERROR
}

pub fn left_sample_array(&self) -> Result<&[NodeId], TskitError>

Failing examples

An error will be returned if [’crate::TreeFlags::SAMPLE_LISTS`] is not used:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::default()).unwrap(); // Error
while let Some(tree) = tree_iter.next() {
    let l = tree.left_sample_array().unwrap();
    for _ in l {}
}

The lifetime of the slice is tied to the parent object:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::SAMPLE_LISTS).unwrap();
while let Some(tree) = tree_iter.next() {
    let l = tree.left_sample_array().unwrap();
    drop(tree_iter);
    for _ in l {} // Error
}

pub fn right_sample_array(&self) -> Result<&[NodeId], TskitError>

Failing examples

An error will be returned if [’crate::TreeFlags::SAMPLE_LISTS`] is not used:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::default()).unwrap(); // ERROR
while let Some(tree) = tree_iter.next() {
    let r = tree.right_sample_array().unwrap();
    for _ in r {}
}

The lifetime of the slice is tied to the parent object:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::SAMPLE_LISTS).unwrap();
while let Some(tree) = tree_iter.next() {
    let r = tree.right_sample_array().unwrap();
    drop(tree_iter);
    for _ in r {} // ERROR
}

pub fn left_sib_array(&self) -> &[NodeId]

Failing examples

The lifetime of the slice is tied to the parent object:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::default()).unwrap();
while let Some(tree) = tree_iter.next() {
    let r = tree.left_sib_array();
    drop(tree_iter);
    for _ in r {} // ERROR
}

pub fn right_sib_array(&self) -> &[NodeId]

Failing examples

The lifetime of the slice is tied to the parent object:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::default()).unwrap();
while let Some(tree) = tree_iter.next() {
    let r = tree.right_sib_array();
    drop(tree_iter);
    for _ in r {} // ERROR
}

pub fn left_child_array(&self) -> &[NodeId]

Failing examples

The lifetime of the slice is tied to the parent object:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::default()).unwrap();
while let Some(tree) = tree_iter.next() {
    let l = tree.left_child_array();
    drop(tree_iter);
    for _ in l {} // ERROR
}

pub fn right_child_array(&self) -> &[NodeId]

Failing examples

The lifetime of the slice is tied to the parent object:

use streaming_iterator::StreamingIterator;
let tables = tskit::TableCollection::new(1.).unwrap();
let treeseq =
tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
let mut tree_iter = treeseq.tree_iterator(tskit::TreeFlags::default()).unwrap();
while let Some(tree) = tree_iter.next() {
    let r = tree.right_child_array();
    drop(tree_iter);
    for _ in r {} // ERROR
}

pub fn interval(&self) -> (Position, Position)

Return the [left, right) coordinates of the tree.

pub fn span(&self) -> Position

Return the length of the genome for which this tree is the ancestry.

pub fn parent<N: Into<NodeId> + Copy + Debug>(&self, u: N) -> Option<NodeId>

Get the parent of node u.

Returns None if u is out of range.

pub fn left_child<N: Into<NodeId> + Copy>(&self, u: N) -> Option<NodeId>

Get the left child of node u.

Returns None if u is out of range.

pub fn right_child<N: Into<NodeId> + Copy>(&self, u: N) -> Option<NodeId>

Get the right child of node u.

Returns None if u is out of range.

pub fn left_sib<N: Into<NodeId> + Copy>(&self, u: N) -> Option<NodeId>

Get the left sib of node u.

Returns None if u is out of range.

pub fn right_sib<N: Into<NodeId> + Copy>(&self, u: N) -> Option<NodeId>

Get the right sib of node u.

Returns None if u is out of range.

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

👎Deprecated since 0.2.3: Please use Tree::sample_nodes instead

Obtain the list of samples for the current tree/tree sequence as a vector.

Panics

Will panic if the number of samples is too large to cast to a valid id.

pub fn sample_nodes(&self) -> &[NodeId]

Get the list of sample nodes as a slice.

pub fn parents<N: Into<NodeId> + Copy>( &self, u: N, ) -> impl Iterator<Item = NodeId> + '_

Return an Iterator from the node u to the root of the tree, travering all parent nodes.

Returns

• Some(iterator) if u is valid
• None otherwise

pub fn children<N: Into<NodeId> + Copy>( &self, u: N, ) -> impl Iterator<Item = NodeId> + '_

Return an Iterator over the children of node u.

Returns

• Some(iterator) if u is valid
• None otherwise

pub fn samples<N: Into<NodeId> + Copy>( &self, u: N, ) -> Result<impl Iterator<Item = NodeId> + '_, TskitError>

Return an Iterator over the sample nodes descending from node u.

Note

If u is itself a sample, then it is included in the values returned.

Returns

• Some(Ok(iterator)) if TreeFlags::SAMPLE_LISTS is in TreeInterface::flags
• Some(Err(_)) if TreeFlags::SAMPLE_LISTS is not in TreeInterface::flags
• None if u is not valid.

pub fn roots(&self) -> impl Iterator<Item = NodeId> + '_

Return an Iterator over the roots of the tree.

Note

For a tree with multiple roots, the iteration starts at the left root.

pub fn roots_to_vec(&self) -> Vec<NodeId>

Return all roots as a vector.

pub fn traverse_nodes( &self, order: NodeTraversalOrder, ) -> Box<dyn Iterator<Item = NodeId> + '_>

Return an Iterator over all nodes in the tree.

Parameters

• order: A value from NodeTraversalOrder specifying the iteration order.

pub fn total_branch_length(&self, by_span: bool) -> Result<Time, TskitError>

Return the crate::NodeTable for this current tree (and the tree sequence from which it came).

This is a convenience function for accessing node times, etc.. Calculate the total length of the tree via a preorder traversal.

Parameters

• by_span: if true, multiply the return value by TreeInterface::span.

Errors

TskitError may be returned if a node index is out of range.

pub fn num_tracked_samples<N: Into<NodeId> + Copy>( &self, u: N, ) -> Result<SizeType, TskitError>

Get the number of samples below node u.

Errors

• TskitError if TreeFlags::NO_SAMPLE_COUNTS.

pub fn kc_distance( &self, other: &TreeInterface, 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. If lambda is 0, we only consider topology. If lambda is 1, we only consider branch lengths.

pub fn virtual_root(&self) -> NodeId

Return the virtual root of the tree.