Merge pull request #57 from molpopgen/describe_edge_buffering

Describe edge buffering. Closes #54

Author: molpopgen

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<Segment>;

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,