Struct tskit::Tree

pub struct Tree<'treeseq> { /* private fields */ }

A Tree.

Wrapper around tsk_tree_t.

Methods from Deref<Target = 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.

Trait Implementations

impl<'treeseq> Deref for Tree<'treeseq>

type Target = TreeInterface

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'treeseq> DerefMut for Tree<'treeseq>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'ts> DoubleEndedStreamingIterator for Tree<'ts>

fn advance_back(&mut self)

Advances the iterator to the next element from the back of the iterator.

fn next_back(&mut self) -> Option<&Self::Item>

Advances the iterator and returns the next value from the back.

fn rfold<B, F>(self, init: B, f: F) -> Bwhere Self: Sized, F: FnMut(B, &Self::Item) -> B,

Reduces the iterator’s elements to a single, final value, starting from the back.

impl<'treeseq> Drop for Tree<'treeseq>

fn drop(&mut self)

Executes the destructor for this type.

impl<'ts> StreamingIterator for Tree<'ts>

type Item = Tree<'ts>

The type of the elements being iterated over.

fn advance(&mut self)

Advances the iterator to the next element.

fn get(&self) -> Option<&Self::Item>

Returns a reference to the current element of the iterator.

fn next(&mut self) -> Option<&Self::Item>

Advances the iterator and returns the next value.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the iterator.

fn is_done(&self) -> bool

Checks if get() will return None.

fn all<F>(&mut self, f: F) -> boolwhere Self: Sized, F: FnMut(&Self::Item) -> bool,

Determines if all elements of the iterator satisfy a predicate.

fn any<F>(&mut self, f: F) -> boolwhere Self: Sized, F: FnMut(&Self::Item) -> bool,

Determines if any elements of the iterator satisfy a predicate.

fn by_ref(&mut self) -> &mut Selfwhere Self: Sized,

Borrows an iterator, rather than consuming it.

fn chain<I>(self, other: I) -> Chain<Self, I>where Self: Sized, I: StreamingIterator<Item = Self::Item>,

Consumes two iterators and returns a new iterator that iterates over both in sequence.

fn count(self) -> usizewhere Self: Sized,

Consumes the iterator, counting the number of remaining elements and returning it.

fn filter<F>(self, f: F) -> Filter<Self, F>where Self: Sized, F: FnMut(&Self::Item) -> bool,

Creates an iterator which uses a closure to determine if an element should be yielded.

fn filter_map<B, F>(self, f: F) -> FilterMap<Self, B, F>where Self: Sized, F: FnMut(&Self::Item) -> Option<B>,

Creates an iterator which both filters and maps by applying a closure to elements.

fn flat_map<J, F>(self, f: F) -> FlatMap<Self, J, F>where Self: Sized, J: StreamingIterator, F: FnMut(&Self::Item) -> J,

Creates an iterator which flattens iterators obtained by applying a closure to elements. Note that the returned iterators must be streaming iterators.

fn filter_map_deref<B, F>(self, f: F) -> FilterMapDeref<Self, F>where Self: Sized, F: FnMut(&Self::Item) -> Option<B>,

Creates a regular, non-streaming iterator which both filters and maps by applying a closure to elements.

fn find<F>(&mut self, f: F) -> Option<&Self::Item>where Self: Sized, F: FnMut(&Self::Item) -> bool,

Returns the first element of the iterator that satisfies the predicate.

fn fuse(self) -> Fuse<Self>where Self: Sized,

Creates an iterator which is “well behaved” at the beginning and end of iteration.

fn inspect<F>(self, f: F) -> Inspect<Self, F>where F: FnMut(&Self::Item), Self: Sized,

Call a closure on each element, passing the element on. The closure is called upon calls to advance or advance_back, and exactly once per element regardless of how many times (if any) get is called.

fn map<B, F>(self, f: F) -> Map<Self, B, F>where Self: Sized, F: FnMut(&Self::Item) -> B,

Creates an iterator which transforms elements of this iterator by passing them to a closure.

fn map_deref<B, F>(self, f: F) -> MapDeref<Self, F>where Self: Sized, F: FnMut(&Self::Item) -> B,

Creates a regular, non-streaming iterator which transforms elements of this iterator by passing them to a closure.

fn map_ref<B, F>(self, f: F) -> MapRef<Self, F>where Self: Sized, F: Fn(&Self::Item) -> &B, B: ?Sized,

Creates an iterator which transforms elements of this iterator by passing them to a closure.

fn nth(&mut self, n: usize) -> Option<&Self::Item>

Consumes the first n elements of the iterator, returning the next one.

fn position<F>(&mut self, f: F) -> Option<usize>where Self: Sized, F: FnMut(&Self::Item) -> bool,

Returns the index of the first element of the iterator matching a predicate.

fn skip(self, n: usize) -> Skip<Self>where Self: Sized,

Creates an iterator which skips the first n elements.

fn skip_while<F>(self, f: F) -> SkipWhile<Self, F>where Self: Sized, F: FnMut(&Self::Item) -> bool,

Creates an iterator that skips initial elements matching a predicate.

fn take(self, n: usize) -> Take<Self>where Self: Sized,

Creates an iterator which only returns the first n elements.

fn take_while<F>(self, f: F) -> TakeWhile<Self, F>where Self: Sized, F: FnMut(&Self::Item) -> bool,

Creates an iterator which only returns initial elements matching a predicate.

fn rev(self) -> Rev<Self>where Self: Sized + DoubleEndedStreamingIterator,

Creates an iterator which returns elemens in the opposite order.

fn fold<B, F>(self, init: B, f: F) -> Bwhere Self: Sized, F: FnMut(B, &Self::Item) -> B,

Reduces the iterator’s elements to a single, final value.

fn for_each<F>(self, f: F)where Self: Sized, F: FnMut(&Self::Item),

Calls a closure on each element of an iterator.