Struct OwningIndividualTable

Source

pub struct OwningIndividualTable { /* private fields */ }

Expand description

A standalone individual table that owns its data.

§Examples

use tskit::OwningIndividualTable;

let mut individuals = OwningIndividualTable::default();
let rowid = individuals.add_row(0, None, None).unwrap();
assert_eq!(rowid, 0);
assert_eq!(individuals.num_rows(), 1);

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

use tskit::OwningIndividualTable;

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

let metadata = IndividualMetadata{value: 42};

let mut individuals = OwningIndividualTable::default();

let rowid = individuals.add_row_with_metadata(0, None, None, &metadata).unwrap();
assert_eq!(rowid, 0);

match individuals.metadata::<IndividualMetadata>(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§

Source §

Methods from Deref<Target = IndividualTable>§

Source

pub fn num_rows(&self) -> SizeType

Return the number of rows

Source

pub fn flags<I: Into<IndividualId> + Copy>( &self, row: I, ) -> Option<IndividualFlags>

Return the flags for a given row.

§Returns

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

Source

pub fn location<I: Into<IndividualId> + Copy>( &self, row: I, ) -> Option<&[Location]>

Return the locations for a given row.

§Returns

Some(location) if row is valid.
None otherwise.

Source

pub fn parents<I: Into<IndividualId> + Copy>( &self, row: I, ) -> Option<&[IndividualId]>

Return the parents for a given row.

§Returns

Some(parents) if row is valid.
None otherwise.

Source

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

Return the metadata for a given 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

For all examples, this is our metadata type. We will add all instances with a value of x = 1.

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

§Without matches

// We know the metadata are here, so we unwrap the Option and the Result:
let decoded = tables.individuals().metadata::<IndividualMetadata>(0.into()).unwrap().unwrap();
assert_eq!(decoded.x, 1);

§Checking for errors and absence of metadata

The Option<Result<_>> return value allows all three return possibilities to be easily covered:

match tables.individuals().metadata::<IndividualMetadata>(0.into())
{
    Some(Ok(metadata)) => assert_eq!(metadata.x, 1),
    Some(Err(_)) => panic!("got an error??"),
    None => panic!("Got None??"),
};

§Attempting to use the wrong type.

Let’s define a mutation metadata type with the exact same fields as our individual metadata defined above:

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

This type has the wrong trait bound and will cause compilation to fail:

match tables.individuals().metadata::<MutationMetadata>(0.into())
{
    Some(Ok(metadata)) => assert_eq!(metadata.x, 1),
    Some(Err(_)) => panic!("got an error??"),
    None => panic!("Got None??"),
};

§Limitations: different type, same trait bound

Finally, let us consider a different struct that has identical fields to IndividualMetadata defined above and also implements the correct trait:

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

Let’s walk through a detailed example:

// create a mutable table collection
let mut tables = tskit::TableCollection::new(100.).unwrap();
// Create some metadata based on our FIRST type
let metadata = IndividualMetadata { x: 1 };
// Add a row with our metadata
assert!(tables.add_individual_with_metadata(0, None, None, &metadata).is_ok());
// Trying to fetch using our SECOND type as the generic type works!
match tables.individuals().metadata::<IndividualMetadataToo>(0.into())
{
    Some(Ok(metadata)) => assert_eq!(metadata.x, 1),
    Some(Err(_)) => panic!("got an error??"),
    None => panic!("Got None??"),
};

What is going on here? Both types satisfy the same trait bound (metadata::IndividualMetadata) and their data fields look identical to serde_json. Thus, one is exchangeable for the other because they have the exact same behavior.

However, it is also true that this is (often/usually/always) not exactly what we want. We are experimenting with encapsulation APIs involving traits with associated types to enforce at compile time that exactly one type (struct/enum, etc.) is a valid metadata type for a table.

Source