From 4e1ae1ee90854296fd062a7ad7098e785cdde836 Mon Sep 17 00:00:00 2001 From: molpopgen Date: Sun, 27 Dec 2020 12:04:52 -0800 Subject: [PATCH] Describe edge buffering. Closes #54 --- src/edge_buffer.rs | 41 +++++++++++++++++++++++++++++++- src/simplify_from_edge_buffer.rs | 5 ++++ 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/src/edge_buffer.rs b/src/edge_buffer.rs index 226a36f5..a8090fc4 100644 --- a/src/edge_buffer.rs +++ b/src/edge_buffer.rs @@ -5,9 +5,48 @@ use crate::segment::Segment; /// Simplification of simulated data happens /// via [``crate::simplify_from_edge_buffer()``]. /// +/// # Overview +/// +/// The typical tree sequence recording workflow +/// goes like this. When a new node is "born", +/// we: +/// +/// 1. Add a new node to the node table. This +/// new node is a "child". +/// 2. Add edges to the edge table representing +/// the genomic intervals passed on from +/// various parents to this child node. +/// +/// We repeat `1` and `2` for a while, then +/// we [``sort the tables``](crate::TableCollection::sort_tables_for_simplification). +/// After sorting, we [``simplify``](crate::simplify_tables()) the tables. +/// +/// We can avoid the sorting step using this type. +/// To start, we record the list of currently-alive nodes +/// [``here``](crate::SamplesInfo::edge_buffer_founder_nodes). +/// +/// Then, we use `parent` ID values as the +/// `head` values for linked lists stored in a +/// [``NestedForwardList``](crate::nested_forward_list::NestedForwardList). +/// +/// By its very nature, offspring are generated by birth order. +/// Further, a well-behaved forward simulation is capable of calculating +/// edges from left-to-right along a genome. Thus, we can +/// [``extend``](crate::nested_forward_list::NestedForwardList::extend) +/// the data for each chain with [``Segment``] instances representing +/// transmission events. The segment's [``node``](Segment::node) field represents +/// the child. +/// +/// After recording for a while, we call +/// [``simplify_from_edge_buffer``](crate::simplify_from_edge_buffer()) to simplify +/// the tables. After simplification, the client code must re-populate +/// [``the list``](crate::SamplesInfo::edge_buffer_founder_nodes) of alive nodes. +/// Once that is done, we can keep recording, etc.. +/// /// # Example /// /// For a full example of use in simulation, /// see the source code for -/// [``crate::wright_fisher::neutral_wf()``]. +/// [``wright_fisher::neutral_wf``](crate::wright_fisher::neutral_wf) +/// pub type EdgeBuffer = NestedForwardList; diff --git a/src/simplify_from_edge_buffer.rs b/src/simplify_from_edge_buffer.rs index 97926c34..6cdf4e0c 100644 --- a/src/simplify_from_edge_buffer.rs +++ b/src/simplify_from_edge_buffer.rs @@ -147,6 +147,11 @@ fn process_births_from_buffer( /// /// The input tables must be sorted. /// See [``TableCollection::sort_tables_for_simplification``]. +/// +/// # Limitations +/// +/// The simplification code does not currently validate +/// that "buffered" edges do indeed represent a valid sort order. pub fn simplify_from_edge_buffer( samples: &SamplesInfo, flags: SimplificationFlags,