Struct tskit::Tree

pub struct Tree { /* fields omitted */ }

A Tree.

Wrapper around tsk_tree_t.

Implementations

impl Tree

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) -> (f64, f64)

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

pub fn span(&self) -> f64

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

pub fn parent(&self, u: NodeId) -> Result<NodeId, TskitError>

Get the parent of node u.

Errors

TskitError if u is out of range.

pub fn left_child(&self, u: NodeId) -> Result<NodeId, TskitError>

Get the left child of node u.

Errors

TskitError if u is out of range.

pub fn right_child(&self, u: NodeId) -> Result<NodeId, TskitError>

Get the right child of node u.

Errors

TskitError if u is out of range.

pub fn left_sib(&self, u: NodeId) -> Result<NodeId, TskitError>

Get the left sib of node u.

Errors

TskitError if u is out of range.

pub fn right_sib(&self, u: NodeId) -> Result<NodeId, TskitError>

Get the right sib of node u.

Errors

TskitError::IndexError 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.

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

Get the list of sample nodes as a slice.

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

👎 Deprecated since 0.2.3:

Please use Tree::parents instead

Return an Iterator from the node u to the root of the tree.

Errors

TskitError::IndexError if u is out of range.

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

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

Errors

TskitError::IndexError if u is out of range.

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

Return an Iterator over the children of node u.

Errors

TskitError::IndexError if u is out of range.

pub fn samples(
    &self,
    u: NodeId
) -> 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.

Errors

TskitError::IndexError if u is out of range.

TskitError::NotTrackingSamples if TreeFlags::SAMPLE_LISTS was not used to initialize self.

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 node_table<'a>(&'a self) -> NodeTable<'a>

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

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

Calculate the total length of the tree via a preorder traversal.

Parameters

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

Errors

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

pub fn num_tracked_samples(&self, u: NodeId) -> Result<u64, TskitError>

Get the number of samples below node u.

Errors

• TskitError if TreeFlags::NO_SAMPLE_COUNTS.

pub fn kc_distance(&self, other: &Tree, 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.

Trait Implementations

impl DoubleEndedStreamingIterator for Tree

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) -> B where
    F: FnMut(B, &Self::Item) -> B, 

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

impl Drop for Tree

fn drop(&mut self)

Executes the destructor for this type.

impl StreamingIterator for Tree

type Item = Tree

The type of the elements being iterated over.

fn advance(&mut self)

Advances the iterator to the next element.

fn get(&self) -> Option<&Tree>

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 all<F>(&mut self, f: F) -> bool where
    F: FnMut(&Self::Item) -> bool, 

Determines if all elements of the iterator satisfy a predicate.

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

Determines if any elements of the iterator satisfy a predicate.

fn by_ref(&mut self) -> &mut Self

Borrows an iterator, rather than consuming it.

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

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

fn cloned(self) -> Cloned<Self> where
    Self::Item: Clone, 

Produces a normal, non-streaming, iterator by cloning the elements of this iterator.

fn count(self) -> usize

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

fn filter<F>(self, f: F) -> Filter<Self, F> where
    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
    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
    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
    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
    F: FnMut(&Self::Item) -> bool, 

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

fn fuse(self) -> Fuse<Self>

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), 

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

Creates an iterator which skips the first n elements.

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

Creates an iterator that skips initial elements matching a predicate.

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

Creates an iterator which only returns the first n elements.

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

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

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

Creates an iterator which returns elemens in the opposite order.

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

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

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

Calls a closure on each element of an iterator.

impl TskitTypeAccess<tsk_tree_t> for Tree

fn as_ptr(&self) -> *const tsk_tree_t

Return const pointer

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

Return mutable pointer