Struct tskit::IndividualTable

source ·

#[repr(transparent)]
pub struct IndividualTable { /* private fields */ }

Expand description

An immutable view of a individual table.

Implementations§

source §

impl 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