From 59c3ef01e81ccbf992a7048e46a07eabf57a92e9 Mon Sep 17 00:00:00 2001
From: Will Dumm <wrhdumm@gmail.com>
Date: Mon, 23 May 2022 16:28:43 -0700
Subject: [PATCH] add new syntax and remove identical leaf labels requirement

---
 README.md           | 14 +++++++++++++-
 docs/quickstart.rst | 19 +++++++++++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0f5835c..2305921 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,19 @@ dag.trim_optimal_weight(**node_count_funcs, optimal_func=min)
 
 # Sample a tree from the dag and make it an ete tree
 t = dag.sample().to_ete()
+
+# the history DAG also supports indexing and iterating:
+t = dag[0].to_ete()
+trees = [tree for tree in dag]
+
+# Another method for fetching all trees in the dag is provided, but the order
+# will not match index order:
+scrambled_trees = list(dag.get_trees())
+
+
+# Union is implemented as dag merging, including with sequences of dags
+newdag = dag[0] | dag[1]
+newdag = dag[0] | (dag[i] for i in range(3,5))
 ```
 
 ### Highlights
@@ -87,7 +100,6 @@ meet the following criteria:
 * The label attributes used to construct history DAG labels must be unique,
     because history DAG nodes which represent leaves must be labeled uniquely.
 
-In addition, all the trees in the collection must have identical sets of leaf labels.
 
 ## Documentation
 
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index b170f05..30058ac 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -198,3 +198,22 @@ ete tree for further rendering/processing:
 
 The :meth:`historydag.HistoryDag.to_ete` method allows full control over
 mapping of history DAG node attributes to :class:`ete3.Tree` node attributes.
+
+We can also retrieve trees in the history DAG by index, and iterate in
+index-order:
+
+>>> t = dag[0].to_ete()
+>>> trees = [tree for tree in dag]
+
+Another method for fetching all trees in the dag is provided, but the order
+will not match index order:
+
+>>> scrambled_trees = list(dag.get_trees())
+
+
+History DAGs can be merged using the :meth:`historydag.HistoryDag.merge`
+method, or equivalently using the ``or`` operator. This supports merging with
+sequences of history DAGs.
+
+>>> newdag = dag[0] | dag[1]
+>>> newdag = dag[0] | (dag[i] for i in range(3,5))