Struct tskit::OwningNodeTable

pub struct OwningNodeTable { /* private fields */ }

A standalone node table that owns its data.

Examples

use tskit::OwningNodeTable;

let mut nodes = OwningNodeTable::default();
let rowid = nodes.add_row(0, 1.1, -1, -1).unwrap();
assert_eq!(rowid, 0);
assert_eq!(nodes.num_rows(), 1);

An example with metadata. This requires the cargo feature "derive" for tskit.

use tskit::OwningNodeTable;

#[derive(serde::Serialize,
         serde::Deserialize,
         tskit::metadata::NodeMetadata)]
#[serializer("serde_json")]
struct NodeMetadata {
    value: i32,
}

let metadata = NodeMetadata{value: 42};

let mut nodes = OwningNodeTable::default();

let rowid = nodes.add_row_with_metadata(0, 1., -1, -1, &metadata).unwrap();
assert_eq!(rowid, 0);

match nodes.metadata::<NodeMetadata>(rowid) {
    // rowid is in range, decoding succeeded
    Some(Ok(decoded)) => assert_eq!(decoded.value, 42),
    // rowid is in range, decoding failed
    Some(Err(e)) => panic!("error decoding metadata: {:?}", e),
    None => panic!("row id out of range")
}

Implementations

impl OwningNodeTable

pub fn clear(&mut self) -> TskReturnValue

Clear the table.

impl OwningNodeTable

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

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

impl OwningNodeTable

pub fn add_row<F, T, P, I>( &mut self, flags: F, time: T, population: P, individual: I ) -> Result<NodeId, TskitError>where F: Into<NodeFlags>, T: Into<Time>, P: Into<PopulationId>, I: Into<IndividualId>,

pub fn add_row_with_metadata<F, T, P, I, N>( &mut self, flags: F, time: T, population: P, individual: I, metadata: &N ) -> Result<NodeId, TskitError>where F: Into<NodeFlags>, T: Into<Time>, P: Into<PopulationId>, I: Into<IndividualId>, N: NodeMetadata,

pub fn add_row_with_defaults<T: Into<Time> + Copy, D: DefaultNodeData>( &mut self, time: T, defaults: &D ) -> Result<NodeId, TskitError>

Add row with defaults

Examples

let node_defaults = tskit::NodeDefaults::default();
let rv = nodes.add_row_with_defaults(1.0, &node_defaults).unwrap();
assert_eq!(rv, 0);
let rv = nodes.add_row_with_defaults(1.0, &node_defaults).unwrap();
assert_eq!(rv, 1);

Methods from Deref<Target = NodeTable>

pub fn num_rows(&self) -> SizeType

Return the number of rows

pub fn time<N: Into<NodeId> + Copy>(&self, row: N) -> Option<Time>

Return the time value from row row of the table.

Returns

• Some(time) if row is valid.
• None otherwise.

Examples

if let Some(time) = tables.nodes().time(0) {
// then node id 0 is a valid row id
}

pub fn flags<N: Into<NodeId> + Copy>(&self, row: N) -> Option<NodeFlags>

Return the flags value from row row of the table.

Returns

• Some(flags) if row is valid.
• None otherwise.

Examples

if let Some(flags) = tables.nodes().flags(0) {
// then node id 0 is a valid row id
}

pub fn flags_array_mut(&mut self) -> &mut [NodeFlags]

👎Deprecated since 0.12.0: use flags_slice_mut instead

pub fn time_array_mut(&mut self) -> &mut [Time]

👎Deprecated since 0.12.0: use time_slice_mut instead

pub fn population<N: Into<NodeId> + Copy>(&self, row: N) -> Option<PopulationId>

Return the population value from row row of the table.

Examples

if let Some(pop) = tables.nodes().population(0) {
// then node id 0 is a valid row id
}

Returns

• Some(population) if row is valid.
• None otherwise.

pub fn deme<N: Into<NodeId> + Copy>(&self, row: N) -> Option<PopulationId>

Return the population value from row row of the table.

Examples

See NodeTable::population for examples.

Returns

• Some(population) if row is valid.
• None otherwise.

pub fn individual<N: Into<NodeId> + Copy>(&self, row: N) -> Option<IndividualId>

Return the individual value from row row of the table.

Examples

if let Some(individual) = tables.nodes().individual(0) {
// then node id 0 is a valid row id
}

Returns

• Some(individual) if row is valid.
• None otherwise.

pub fn metadata<T: NodeMetadata>( &self, row: NodeId ) -> Option<Result<T, TskitError>>

Retrieve decoded metadata for a row.

Returns

• Some(Ok(T)) if row is valid and decoding succeeded.
• Some(Err(_)) if row is not valid and decoding failed.
• None if row is not valid.

Errors

• TskitError::MetadataError if decoding fails.

Examples.

The big-picture semantics are the same for all table types. See crate::IndividualTable::metadata for examples.

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

Return an iterator over rows of the table. The value of the iterator is NodeTableRow.

pub fn lending_iter(&self) -> NodeTableRowView<'_>

pub fn row<N: Into<NodeId> + Copy>(&self, r: N) -> Option<NodeTableRow>

Return row r of the table.

Parameters

• r: the row id.

Returns

• Some(row) if r is valid
• None otherwise

pub fn row_view<N: Into<NodeId> + Copy>( &self, r: N ) -> Option<NodeTableRowView<'_>>

Return a view of row r of the table.

Parameters

• r: the row id.

Returns

• Some(row view) if r is valid
• None otherwise

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

Obtain a vector containing the indexes (“ids”) of all nodes for which crate::TSK_NODE_IS_SAMPLE is true.

pub fn create_node_id_vector( &self, f: impl FnMut(&NodeTableRow) -> bool ) -> Vec<NodeId>

Obtain a vector containing the indexes (“ids”) of all nodes satisfying a certain criterion.

pub fn time_slice(&self) -> &[Time]

Get the time column as a slice

pub fn time_slice_raw(&self) -> &[f64]

Get the time column as a slice

pub fn time_slice_mut(&mut self) -> &mut [Time]

Get the time column as a mutable slice

Examples

For a crate::TableCollection, accessing the table creates a temporary that will be dropped, causing this code to not compile:

let time = tables.nodes().time_slice_mut();
println!("{}", time.len()); // ERROR: the temporary node table is dropped by now

Treating the returned slice as an iterable succeeds:

for time in tables.nodes_mut().time_slice_mut() {
    *time = 55.0.into(); // change each node's time value
}
assert!(tables.nodes_mut().time_slice_mut().iter().all(|t| t == &55.0));

Panics

Internally, we rely on a conversion of u64 to usize. This conversion is fallible on some platforms. If the conversion fails, this function will panic.

pub fn time_slice_raw_mut(&mut self) -> &mut [f64]

Get the time column as a mutable slice

pub fn flags_slice(&self) -> &[NodeFlags]

Get the flags column as a slice

pub fn flags_slice_raw(&self) -> &[tsk_flags_t]

Get the flags column as a slice

pub fn flags_slice_mut(&mut self) -> &mut [NodeFlags]

Get the flags column as a mutable slice

Examples

let flags = tables.nodes_mut().flags_slice_mut();
for flag in flags {
// Can do something...
}

for flag in  tables.nodes_mut().flags_slice_mut() {
}

The returned slice is mutable, allowing one to do things like clear the sample status of all nodes:

A copy of the flags can be obtained by collecting results into Vec:

for flag in tables.nodes_mut().flags_slice_mut() {
    flag.remove(tskit::NodeFlags::IS_SAMPLE);
}
assert!(!tables.nodes_mut().flags_slice_mut().iter().any(|f| f.is_sample()));
assert!(tables.nodes().samples_as_vector().is_empty());

let flags = tables.nodes_mut().flags_slice_mut().to_vec();

Owning tables

The ownership semantics differ when tables are not part of a table collection:

let mut nodes = tskit::OwningNodeTable::default();
assert!(nodes.add_row(tskit::NodeFlags::IS_SAMPLE, 10., -1, -1).is_ok());
let flags = nodes.flags_slice_mut();
assert!(flags.iter().all(|f| f.is_sample()));

// while we are at it, let's use our node
// table to populate a table collection.
let mut tables = tskit::TableCollection::new(10.0).unwrap();
tables.set_nodes(&nodes);
assert_eq!(tables.nodes().num_rows(), 1);
assert_eq!(tables.nodes_mut().flags_slice_mut().iter().filter(|f| f.is_sample()).count(), 1);

Panics

Internally, we rely on a conversion of u64 to usize. This conversion is fallible on some platforms. If the conversion fails, this function will panic.

pub fn flags_slice_raw_mut(&mut self) -> &mut [tsk_flags_t]

Get the flags column as a mutable slice

pub fn individual_slice(&self) -> &[IndividualId]

Get the individual column as a slice

pub fn individual_slice_raw(&self) -> &[tsk_id_t]

Get the individual column as a slice

pub fn population_slice(&self) -> &[PopulationId]

Get the population column as a slice

pub fn population_slice_raw(&self) -> &[tsk_id_t]

Get the population column as a slice

Trait Implementations

impl Default for OwningNodeTable

fn default() -> Self

Returns the “default value” for a type.

impl Deref for OwningNodeTable

type Target = NodeTable

The resulting type after dereferencing.

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

Dereferences the value.

impl DerefMut for OwningNodeTable

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

Mutably dereferences the value.