Trait tskit::provenance::Provenance[−][src]

pub trait Provenance: TableAccess {
    fn add_provenance(
        &mut self, 
        record: &str
    ) -> Result<ProvenanceId, TskitError>;
    fn provenances(&self) -> ProvenanceTable<'_>;

    fn provenances_iter(&self) -> TableIterator<ProvenanceTable<'_>> { ... }
}

Expand description

Enable provenance table access.

tskit provides implementations of this trait for crate::TableCollection and crate::TreeSequence.

Examples

For table collections

use tskit::provenance::Provenance;
let mut tables = tskit::TableCollection::new(1000.).unwrap();
tables.add_provenance(&String::from("Some provenance")).unwrap();

// Get reference to the table
let prov_ref = tables.provenances();

// Get the first row
let row_0 = prov_ref.row(0).unwrap();

assert_eq!(row_0.record, "Some provenance");

// Get the first record
let record_0 = prov_ref.record(0).unwrap();
assert_eq!(record_0, row_0.record);

// Get the first time stamp
let timestamp = prov_ref.timestamp(0).unwrap();
assert_eq!(timestamp, row_0.timestamp);

// You can get the `chrono::DateTime` object back from the `String`:

let dt = chrono::DateTime::parse_from_rfc3339(&timestamp).unwrap();

// You can get specific time types back, too:
use core::str::FromStr;
let dt_utc = chrono::DateTime::<chrono::Utc>::from_str(&timestamp).unwrap();
let dt_local = chrono::DateTime::<chrono::Local>::from_str(&timestamp).unwrap();
println!("local = {}", dt_local);

// Provenance transfers to the tree sequences
let treeseq = tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
assert_eq!(treeseq.provenances().record(0).unwrap(), "Some provenance");
// We can still compare to row_0 because it is a copy of the row data:
assert_eq!(treeseq.provenances().record(0).unwrap(), row_0.record);

For tree sequences

use tskit::provenance::Provenance;
let mut tables = tskit::TableCollection::new(1000.).unwrap();
let mut treeseq = tables.tree_sequence(tskit::TreeSequenceFlags::BUILD_INDEXES).unwrap();
treeseq.add_provenance(&String::from("All your provenance r belong 2 us.")).unwrap();

let prov_ref = treeseq.provenances();
let row_0 = prov_ref.row(0).unwrap();
assert_eq!(row_0.record, "All your provenance r belong 2 us.");
let record_0 = prov_ref.record(0).unwrap();
assert_eq!(record_0, row_0.record);
let timestamp = prov_ref.timestamp(0).unwrap();
assert_eq!(timestamp, row_0.timestamp);
let dt = chrono::DateTime::parse_from_rfc3339(&timestamp).unwrap();
use core::str::FromStr;
let dt_utc = chrono::DateTime::<chrono::Utc>::from_str(&timestamp).unwrap();
let dt_local = chrono::DateTime::<chrono::Local>::from_str(&timestamp).unwrap();
println!("local = {}", dt_local);

Required methods

[src]

fn add_provenance(&mut self, record: &str) -> Result<ProvenanceId, TskitError>

Add provenance record with a time stamp.

All implementation of this trait provided by tskit use an ISO 8601 format time stamp written using the RFC 3339 specification. This formatting approach has been the most straightforward method for supporting round trips to/from a ProvenanceTable. The implementations used here use the chrono crate.