Struct forrustts::TableCollection

pub struct TableCollection { /* fields omitted */ }

A collection of node, edge, site, and mutation tables.

Implementations

impl TableCollection

pub const fn new(genome_length: Position) -> TablesResult<TableCollection>

Create a new instance.

Parameters

• genome_length: the total genome length for the tables.

Errors

Will return TablesError if genome_length < 1.

pub fn add_node(&mut self, time: Time, deme: IdType) -> TablesResult<IdType>

Add a Node to the NodeTable

Parameters

• time, a Time representing the birth time.
• deme a valid IdType representing deme where the node is found.

Returns

An IdType that is the new node’s ID. This value is the index of the node in the node table.

Errors

Will return TablesError if deme < 0.

Example

let mut tables = forrustts::TableCollection::new(100).unwrap();
let id = tables.add_node(1, 0).unwrap();
assert_eq!(id, 0);

pub fn add_edge(
    &mut self,
    left: Position,
    right: Position,
    parent: IdType,
    child: IdType
) -> TablesResult<IdType>

Add an Edge to the EdgeTable.

Parameters

• left, the left end of the edge
• right, the right end of the edge
• parent, the parent of the edge
• child, the child of the edge

Returns

An IdType that is the new edge’s ID. This value is the index of the edge in the edge table.

Errors

Will return TablesError if any of the input are invalid.

Example

let mut tables = forrustts::TableCollection::new(100).unwrap();
let id = tables.add_edge(0, 3, 5, 9).unwrap();
assert_eq!(id, 0);

pub fn add_site(
    &mut self,
    position: Position,
    ancestral_state: Option<Vec<u8>>
) -> TablesResult<IdType>

Add a Site to the SiteTable;

Parameters

• position, the mutation position.
• ancestral_state, the ancestral state at this site.

Notes

If no ancestral_state is provided (None), then client code is assumed to have some default in mind.

The u8 type can be used to encode more complex state information. Take a look at the unit tests for examples. The bitfield crate may also be useful.

Returns

An IdType that is the new site’s ID. This value is the index of the site in the site table.

Errors

Will return TablesError if any of the input are invalid.

Example

let mut tables = forrustts::TableCollection::new(100).unwrap();
// ancestral state is a u9 equal to 3
let id = tables.add_site(3, Some(vec![3])).unwrap();
assert_eq!(id, 0);
// Recovering state can be a bit messy!
assert_eq!(tables.site(id).ancestral_state.as_ref().unwrap(), &vec![3]);

pub fn add_mutation(
    &mut self,
    node: IdType,
    key: usize,
    site: usize,
    derived_state: Option<Vec<u8>>,
    neutral: bool
) -> TablesResult<IdType>

Add a MutationRecord to the MutationTable.

Parameters

• node, the node where the mutation maps.
• key, index of the mutation’s metadata.
• site, the IdType of the mutation’s Site.
• derived_state, the derived state of the variant.
• neutral, true if the mutation affects fitness, false otherwise.

Notes

If no derived_state is provided (None), then client code is assumed to have some default in mind.

The u8 type can be used to encode more complex state information. Take a look at the unit tests for examples. The bitfield crate may also be useful.

Returns

An IdType that is the new mutation’s ID. This value is the index of the mutation in the mutation table.

Errors

Will return TablesError if any of the input are invalid.

Example

let mut tables = forrustts::TableCollection::new(100).unwrap();
// derived state is a u9 equal to 3
let id = tables.add_mutation(0, 0, 0, Some(vec![3]), false).unwrap();
assert_eq!(id, 0);
// Recovering state can be a bit messy!
assert_eq!(tables.mutation(id).derived_state.as_ref().unwrap(), &vec![3]);

pub fn genome_length(&self) -> Position

Get genome length

pub fn mutations(&self) -> &MutationTable

Return immutable reference to the mutation table

pub fn edges(&self) -> &EdgeTable

Return immutable reference to the edge table

pub fn num_edges(&self) -> usize

Return number of edges

pub fn num_nodes(&self) -> usize

Return number of nodes

pub fn nodes(&self) -> &NodeTable

Return immutable reference to node table

pub fn node(&self, i: IdType) -> &Node

Return the i-th Node.

pub fn edge(&self, i: IdType) -> &Edge

Return the i-th Edge.

pub fn site(&self, i: IdType) -> &Site

Return the i-th Site.

pub fn mutation(&self, i: IdType) -> &MutationRecord

Return the i-th MutationRecord.

pub fn sites(&self) -> &SiteTable

Return immutable reference to site table

pub fn enumerate_nodes(&self) -> Enumerate<Iter<'_, Node>>

Provide an enumeration over the node table

pub fn enumerate_edges(&self) -> Enumerate<Iter<'_, Edge>>

Provide an enumeration over the edge table

pub fn enumerate_mutations(&self) -> Enumerate<Iter<'_, MutationRecord>>

Provide an enumeration over the mutation table

pub fn enumerate_sites(&self) -> Enumerate<Iter<'_, Site>>

Provide an enumeration over the site table

pub fn sort_tables_for_simplification(&mut self)

👎 Deprecated since 0.1.0:

use sort_tables instead

Sort all tables for simplification.

pub fn sort_tables(&mut self, flags: TableSortingFlags)

Sort all tables for simplification.

pub fn validate(&self, flags: TableValidationFlags) -> TablesResult<bool>

Run a validation check on the tables.