1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
//! Traits related to user-facing types
use crate::edge_table::EdgeTableIterator;
use crate::individual_table::IndividualTableIterator;
use crate::migration_table::MigrationTableIterator;
use crate::mutation_table::MutationTableIterator;
use crate::node_table::NodeTableIterator;
use crate::population_table::PopulationTableIterator;
use crate::site_table::SiteTableIterator;
use crate::table_iterator::make_table_iterator;
use crate::EdgeTable;
use crate::IndividualTable;
use crate::MigrationTable;
use crate::MutationTable;
use crate::NodeTable;
use crate::PopulationTable;
use crate::SiteTable;
/// Provide pointer access to underlying C types
pub trait TskitTypeAccess<T> {
/// Return const pointer
fn as_ptr(&self) -> *const T;
/// Return mutable pointer
fn as_mut_ptr(&mut self) -> *mut T;
}
/// Immutable access to tables.
///
/// For objects that contain the full suite of tables,
/// implementing this trait provides immutable access
/// to their data.
///
/// For most types, the provided implementations of `_iter`
/// methods should do.
///
/// # Examples
///
/// ```
/// use tskit::TableAccess;
///
/// let mut tables = tskit::TableCollection::new(1.).unwrap();
/// // The borrows are immuatble, so we can
/// // take multiple table references from the same object.
/// let e = tables.edges();
/// let n = tables.nodes();
/// ```
///
/// The borrow checker will keep you from getting in trouble:
///
/// ```compile_fail
/// use tskit::TableAccess;
///
/// let mut tables = tskit::TableCollection::new(1.).unwrap();
/// let e = tables.edges();
/// tables.add_edge(0.0, 1.0, 0, 1).unwrap();
/// let p = e.parent(0).unwrap(); // FAIL!
/// ```
pub trait TableAccess {
/// Get reference to the [``EdgeTable``](crate::EdgeTable).
fn edges(&self) -> EdgeTable;
/// Return an iterator over the edges.
/// See [`EdgeTable::iter`] for details.
fn edges_iter(&self) -> EdgeTableIterator {
make_table_iterator::<EdgeTable>(self.edges())
}
/// Get reference to the [``NodeTable``](crate::NodeTable).
fn nodes(&self) -> NodeTable;
/// Return an iterator over the nodes.
/// See [`NodeTable::iter`] for details.
fn nodes_iter(&self) -> NodeTableIterator {
make_table_iterator::<NodeTable>(self.nodes())
}
/// Get reference to the [``MutationTable``](crate::MutationTable).
fn mutations(&self) -> MutationTable;
/// Return an iterator over the mutations.
/// See [`MutationTable::iter`] for details.
fn mutations_iter(&self) -> MutationTableIterator {
make_table_iterator::<MutationTable>(self.mutations())
}
/// Get reference to the [``SiteTable``](crate::SiteTable).
fn sites(&self) -> SiteTable;
/// Return an iterator over the sites.
/// See [`SiteTable::iter`] for details.
fn sites_iter(&self) -> SiteTableIterator {
make_table_iterator::<SiteTable>(self.sites())
}
/// Get reference to the [``PopulationTable``](crate::PopulationTable).
fn populations(&self) -> PopulationTable;
/// Return an iterator over the populations.
/// See [`PopulationTable::iter`] for details.
fn populations_iter(&self) -> PopulationTableIterator {
make_table_iterator::<PopulationTable>(self.populations())
}
/// Get reference to the [``MigrationTable``](crate::MigrationTable).
fn migrations(&self) -> MigrationTable;
/// Return an iterator over the migration events.
/// See [`MigrationTable::iter`] for details.
fn migrations_iter(&self) -> MigrationTableIterator {
make_table_iterator::<MigrationTable>(self.migrations())
}
/// Get reference to the [``IndividualTable``](crate::IndividualTable).
fn individuals(&self) -> IndividualTable;
/// Return an iterator over the individuals.
/// See [`IndividualTable::iter`] for details.
fn individuals_iter(&self) -> IndividualTableIterator {
make_table_iterator::<IndividualTable>(self.individuals())
}
}
/// Interface for returning lists of node ids from
/// types implementing [`TableAccess`].
pub trait NodeListGenerator: TableAccess {
/// Obtain a vector containing the indexes ("ids")
/// of all nodes for which [`crate::TSK_NODE_IS_SAMPLE`]
/// is `true`.
///
/// The provided implementation dispatches to
/// [`crate::NodeTable::samples_as_vector`].
fn samples_as_vector(&self) -> Vec<crate::NodeId> {
self.nodes().samples_as_vector()
}
/// Obtain a vector containing the indexes ("ids") of all nodes
/// satisfying a certain criterion.
///
/// The provided implementation dispatches to
/// [`crate::NodeTable::create_node_id_vector`].
///
/// # Parameters
///
/// * `f`: a function. The function is passed the current table
/// collection and each [`crate::node_table::NodeTableRow`].
/// If `f` returns `true`, the index of that row is included
/// in the return value.
///
/// # Examples
///
/// Get all nodes with time > 0.0:
///
/// ```
/// use tskit::tsk_id_t;
/// use tskit::TableAccess;
/// use tskit::NodeListGenerator;
///
/// let mut tables = tskit::TableCollection::new(100.).unwrap();
/// tables
/// .add_node(tskit::TSK_NODE_IS_SAMPLE, 0.0, tskit::PopulationId::NULL,
/// tskit::IndividualId::NULL)
/// .unwrap();
/// tables
/// .add_node(tskit::TSK_NODE_IS_SAMPLE, 1.0, tskit::PopulationId::NULL,
/// tskit::IndividualId::NULL)
/// .unwrap();
/// let samples = tables.create_node_id_vector(
/// |row: &tskit::NodeTableRow| row.time > 0.,
/// );
/// assert_eq!(samples[0], 1);
///
/// // Get all nodes that have a mutation:
///
/// fn node_has_mutation(
/// // dyn trait here means this
/// // will work with TreeSequence, too.
/// tables_type: &dyn tskit::TableAccess,
/// row: &tskit::NodeTableRow,
/// ) -> bool {
/// for mrow in tables_type.mutations_iter() {
/// if mrow.node == row.id {
/// return true;
/// }
/// }
/// false
/// }
///
/// // Get all nodes that have a mutation:
///
/// tables.add_mutation(0, 0, tskit::MutationId::NULL, 0.0, None).unwrap();
/// let samples_with_mut = tables.create_node_id_vector(
/// |row: &tskit::NodeTableRow| node_has_mutation(&tables, row));
/// assert_eq!(samples_with_mut[0], 0);
/// ```
fn create_node_id_vector(
&self,
f: impl FnMut(&crate::NodeTableRow) -> bool,
) -> Vec<crate::NodeId> {
self.nodes().create_node_id_vector(f)
}
}