Struct tskit::TableCollection

pub struct TableCollection { /* fields omitted */ }

A table collection.

This is a thin wrapper around the C type tsk_table_collection_t.

Current limitations

Examples

let mut tables = tskit::TableCollection::new(100.).unwrap();
assert_eq!(tables.sequence_length(), 100.);

// Adding edges:

let rv = tables.add_edge(0., 53., 1, 11).unwrap();

// Add node:

let rv = tables.add_node(0, 3.2, tskit::TSK_NULL, tskit::TSK_NULL).unwrap();

// Get immutable reference to edge table
let edges = tables.edges();
assert_eq!(edges.num_rows(), 1);

// Get immutable reference to node table
let nodes = tables.nodes();
assert_eq!(nodes.num_rows(), 1);

See the examples/ directory of the repository for examples of metadata encoding and decoding.

Future road map

1. Support all table types. Currently, we only support those needed for current goals in ongoing projects.
2. Strengthen some of the error handling.

Addressing point 3 may require API breakage.

Implementations

impl TableCollection

pub fn new(sequence_length: f64) -> Result<Self, TskitError>

Create a new table collection with a sequence length.

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

Load a table collection from a file.

pub fn sequence_length(&self) -> f64

Length of the sequence/“genome”.

pub fn edges<'a>(&'a self) -> EdgeTable<'a>

Get reference to the EdgeTable. Lifetime of return value is tied to (this) parent object.

pub fn nodes<'a>(&'a self) -> NodeTable<'a>

Get reference to the NodeTable. Lifetime of return value is tied to (this) parent object.

pub fn sites<'a>(&'a self) -> SiteTable<'a>

Get reference to the SiteTable. Lifetime of return value is tied to (this) parent object.

pub fn mutations<'a>(&'a self) -> MutationTable<'a>

Get reference to the MutationTable. Lifetime of return value is tied to (this) parent object.

pub fn populations<'a>(&'a self) -> PopulationTable<'a>

Get reference to the PopulationTable. Lifetime of return value is tied to (this) parent object.

pub fn add_edge(
    &mut self,
    left: f64,
    right: f64,
    parent: tsk_id_t,
    child: tsk_id_t
) -> TskReturnValue

Add a row to the edge table

pub fn add_edge_with_metadata(
    &mut self,
    left: f64,
    right: f64,
    parent: tsk_id_t,
    child: tsk_id_t,
    metadata: Option<&dyn MetadataRoundtrip>
) -> TskReturnValue

Add a row with metadata to the edge table

pub fn add_node(
    &mut self,
    flags: tsk_flags_t,
    time: f64,
    population: tsk_id_t,
    individual: tsk_id_t
) -> TskReturnValue

Add a row to the node table

pub fn add_node_with_metadata(
    &mut self,
    flags: tsk_flags_t,
    time: f64,
    population: tsk_id_t,
    individual: tsk_id_t,
    metadata: Option<&dyn MetadataRoundtrip>
) -> TskReturnValue

Add a row with metadata to the node table

pub fn add_site(
    &mut self,
    position: f64,
    ancestral_state: Option<&[u8]>
) -> TskReturnValue

Add a row to the site table

pub fn add_site_with_metadata(
    &mut self,
    position: f64,
    ancestral_state: Option<&[u8]>,
    metadata: Option<&dyn MetadataRoundtrip>
) -> TskReturnValue

Add a row with metadata to the site table

pub fn add_mutation(
    &mut self,
    site: tsk_id_t,
    node: tsk_id_t,
    parent: tsk_id_t,
    time: f64,
    derived_state: Option<&[u8]>
) -> TskReturnValue

Add a row to the mutation table.

pub fn add_mutation_with_metadata(
    &mut self,
    site: tsk_id_t,
    node: tsk_id_t,
    parent: tsk_id_t,
    time: f64,
    derived_state: Option<&[u8]>,
    metadata: Option<&dyn MetadataRoundtrip>
) -> TskReturnValue

Add a row with metadata to the mutation table.

pub fn add_population(&mut self) -> TskReturnValue

Add a row to the population_table

pub fn add_population_with_metadata(
    &mut self,
    metadata: Option<&dyn MetadataRoundtrip>
) -> TskReturnValue

Add a row with metadata to the population_table

pub fn build_index(&mut self, flags: tsk_flags_t) -> TskReturnValue

Build the “input” and “output” indexes for the edge table.

flags is currently unused, so pass in 0.

pub fn sort(&mut self, start: &Bookmark, options: tsk_flags_t) -> TskReturnValue

Sort the tables.
The bookmark can be used to affect where sorting starts from for each table.

pub fn full_sort(&mut self) -> TskReturnValue

Fully sort all functions. Implemented via a call to sort.

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

Dump the table collection to file. If tables are not sorted and indexes, this function will raise and error. In order to output such data, include TSK_NO_BUILD_INDEXES in options. Otherwisze, use 0 for options.

pub fn clear(&mut self, options: tsk_flags_t) -> TskReturnValue

Clear the contents of all tables. Does not release memory. Memory will be released when the object goes out of scope.

pub fn equals(&self, other: &TableCollection, options: tsk_flags_t) -> bool

Return true if self contains the same data as other, and false otherwise.

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

Return a “deep” copy of the tables.

pub fn tree_sequence(self) -> Result<TreeSequence, TskitError>

Return a crate::TreeSequence based on the tables. This function will raise errors if tables are not sorted, not indexed, or invalid in any way.

Trait Implementations

impl Drop for TableCollection

fn drop(&mut self)

Executes the destructor for this type.

impl TskitTypeAccess<tsk_table_collection_t> for TableCollection

fn as_ptr(&self) -> *const tsk_table_collection_t

Return const pointer

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

Return mutable pointer