Merge pull request #68 from stephenshank/master

Updates for revision

.gitignore

@@ -43,4 +43,7 @@ jspm_packages
 # Output of 'npm pack'
 *.tgz
 .idea
-bower_components
+bower_components
+
+# OS specific files
+.DS_Store

README.md

@@ -1,16 +1,45 @@
 # phylotree.js
 
-A JavaScript interactive viewer of [phylogenetic trees](https://en.wikipedia.org/wiki/Phylogenetic_tree), written as an extension of the [D3](http://d3js.org) [hierarchy layout](https://github.com/mbostock/d3/wiki/Hierarchy-Layout). It generates high quality SVG vector graphics, allows a great degree of customizability (CSS or JavaScript callbacks), and comes with a lot of *built-in* convenicence features. 
+A JavaScript library for developing applications and interactive visualizations involving [phylogenetic trees](https://en.wikipedia.org/wiki/Phylogenetic_tree), written as an extension of the [D3](http://d3js.org) [hierarchy layout](https://github.com/d3/d3-3.x-api-reference/blob/master/Hierarchy-Layout.md). It generates high quality SVG vector graphics, allows a great degree of customizability (CSS or JavaScript callbacks), and comes with a lot of *built-in* convenience features. 
 
-Key features
+## Documentation
+
+Documentation for phylotree.js can be [found here](http://phylotree.hyphy.org/documentation).
+
+## Examples
+
+With `phylotree.js`, it is possible to interface phylogenetic trees with a variety of other software to produce custom, interactive visualizations of phylogenetic data. A simple example entails a [small tree that interacts with a D3.js bar chart](http://phylotree.hyphy.org/examples/phylo-bar/):
+
+![Alt Text](images/bar.gif)
+
+while a complex example involves a [large tree that interacts with a structural viewer](http://phylotree.hyphy.org/examples/large-ancestral-structural-viewer/):
+
+![Alt Text](images/structure.gif)
+
+### Gallery
+
+A [gallery of examples](http://phylotree.hyphy.org/documentation/examples.html) is a good place to learn different ways that phylotree.js can be used to display and annotate trees. 
+
+### Standalone web application
+
+A [full-featured web application](http://veg.github.io/phylotree.js/index.html) based on phylotree.js, implemented in [index.html](index.html).
 
-* Runs entirely in the browser, including Newick parsing. 
-* Can easily handle trees with thousands of tips.
+### Molecular evolution platforms
+
+phylotree.js is also used by the 2017 revision of the [datamonkey.org server](http://datamonkey.org) for molecular sequence analysis. 
+
+## Features
+
+* Capable of handling multiple selection categories for comparative analysis.
+* Several mechanisms for selecting branches, including by clade, path to root, individual branches, internal branches, leaves, and branches that are nearby after layout.
+* Runs entirely in the browser, including Newick/PhyloXML/NexML parsing. 
+* Can handle trees with thousands of tips.
 * Supports linear, radial, scaled branch, tip-aligned, and scaled tip size views.
 * The viewer can be constrained to fit in a given SVG box, or scale based on the size of the tree.
 * Numerous interactive features, including
  * Scaling 
  * Animated rerooting
+ * Ladderization
  * Clade collapse and hiding to explore large trees
  * Node, clade, and subtree selection
  * Tools to automatically select subsets of tree branches based on conditions.
@@ -19,24 +48,15 @@ Key features
  * Customize the way tip names are displayed
  * Transform branch lengths based on branch attributes (e.g. a non-linear scale).
  * Redefine the way a tree is displayed by writing custom CSS
-
-
-## Examples
-
-1. A [gallery of examples](http://bl.ocks.org/spond) is a good place to learn different ways that phylotree.js can be used to display and annotate the trees. 
-2. A [full-featured web application](http://veg.github.io/phylotree.js/index.html) based on phylotree.js, implemented in [index.html](index.html).
-3. phylotree.js is also used by the 2017 revision of the [datamonkey.org server](http://datamonkey.org) for molecular sequence analysis. 
+* Available on [npm](https://www.npmjs.com/package/phylotree) to facilitate modern JavaScript development.
 
 ## Dependencies 
 
 See [package.json](package.json) for dependencies. 
 
-## Tests
+## Development
 
-Run tests using `mocha`.
-
-## Documentation
-Documentation for phylotree.js can be [found here](http://phylotree.hyphy.org/documentation).
+### Documentation
 
 Documentation was created using [sphinx-js](https://github.com/erikrose/sphinx-js). Install with
 
@@ -48,4 +68,8 @@ and build with
 
 ```
 npm run docs
-```
+```
+
+### Tests
+
+Run tests using `mocha`.

dist/.gitignore

@@ -0,0 +1 @@
+phylotree.js

docs/examples.rst

@@ -9,6 +9,12 @@ Hello-world
  * `View Hello-world example </examples/hello-world>`_
  * `View Hello-world source <https://github.com/veg/phylotree.js/blob/master/examples/hello-world/index.html>`_
 
+Phylo-bar
+ A phylogenetic tree that interfaces with a D3.js bar chart to count classes of substitutions along portions of a phylogeny.
+
+ * `View Phylo-bar example </examples/phylo-bar>`_
+ * `View Phylo-bar source <https://github.com/veg/phylotree.js/blob/master/examples/phylo-bar/index.html>`_
+
 Vanilla
  The simplest tree possible, with all default features disabled.
 
@@ -39,6 +45,26 @@ Variable size and shape for leaf nodes
  * `View Variable leaves example </examples/clone-compartment>`_
  * `View Variable leaves source <https://github.com/veg/phylotree.js/blob/master/examples/clone-compartment/index.html>`_
 
+Zoom
+ Example of zooming and panning.
+
+ * `View Zooming example </examples/zoom>`_
+ * `View Zooming source <https://github.com/veg/phylotree.js/blob/master/examples/zoom/index.html>`_
+
+Leaf metadata
+ Visualize some artificial data associated with leaves of a tree.
+
+ * `View Leaf metadata example </examples/leafdata>`_
+ * `View Leaf metadata source <https://github.com/veg/phylotree.js/blob/master/examples/leafdata/index.html>`_
+
+XML parsing
+ Parse PhyloXML or NexML formats.
+
+ * `View PhyloXML example </examples/phyloxml>`_
+ * `View PhyloXML source <https://github.com/veg/phylotree.js/blob/master/examples/phyloxml/index.html>`_
+ * `View NexML example </examples/nexml>`_
+ * `View NexML source <https://github.com/veg/phylotree.js/blob/master/examples/nexml/index.html>`_
+
 Large tree
  Viewing a large tree with a Starcraft-style guide.
 
@@ -61,4 +87,11 @@ Ancestral sequence structural viewer
  * `View Ancestral sequence structural viewer example </examples/large-ancestral-structural-viewer>`_
  * `View Ancestral sequence structural viewer source <https://github.com/veg/phylotree.js/blob/master/examples/large-ancestral-structural-viewer/index.html>`_
 
+Interactive tanglegram
+ A tanglegram to compare phylogenies inferred from muliple vs. single tissue samples. Crossings are minimized using a 
+ dynamic programming algorithm, and the single-tissue tree enables selections to highlight inter-tree crossings.
+
+ * `View Interactive tanglegram example </examples/siv>`_
+ * `View Interactive tanglegram source <https://github.com/veg/phylotree.js/blob/master/examples/siv/index.html>`_
+
 .. _HyPhy: http://hyphy.org/

docs/fundamentals.rst

@@ -17,12 +17,16 @@ attached to the ``d3.layout`` namespace.
 .. autofunction:: d3.layout.phylotree([container])
 
 Phylotrees are themselves functions, with many methods attached and variables
-that have been closed over to provide an internal state.
+that have been closed over to provide an internal state. Newick, PhyloXML, and
+NeXML formats are supported.
 
 .. autofunction:: phylotree~phylotree(nwk[, bootstrap_values])
 
+.. autofunction:: d3.layout.phylotree.nexml_parser
+
 Internally, Phylotree.js uses the `D3 hierarchy layout`_. The following function
-parses Newick strings into a hierarchical JSON format.
+parses Newick strings into a hierarchical JSON format. Certain ad-hoc extensions,
+such as those used by HyPhy or Beast, are (partially) supported.
 
 .. autofunction:: d3.layout.newick_parser(nwk_str[, bootstrap_values])
 

docs/index.rst

@@ -8,7 +8,7 @@ Welcome to Phylotree.js's documentation!
 
 Phylotree.js is a Javascript library for working with phylogenetic trees. Uses include web application development and interactive data visualization for phylogenetics.
 
-It is written as a `D3`_ layout, and aspires to be a general purpose tool. Example uses include `a standalone web application`_ for viewing and labeling phylogenetic trees, the `Datamonkey`_ webserver for comparative sequence analysis, and an `ancestral sequence structural viewer`_.
+It is written as a `D3`_ layout, and aspires to be a general purpose tool for visualizing and selecting branches in phylogenetic trees. Example uses include `a standalone web application`_ for viewing and labeling phylogenetic trees, the `Datamonkey`_ webserver for comparative sequence analysis, an `ancestral sequence structural viewer`_, and an `interactive tanglegram`_.
 
 The code is `available on Github`_.
 
@@ -30,6 +30,7 @@ Contents
 .. _a standalone web application: /
 .. _Datamonkey: http://datamonkey.org
 .. _ancestral sequence structural viewer: /examples/large-ancestral-structural-viewer
+.. _interactive tanglegram: /examples/siv
 .. _available on Github: http://github.com/veg/phylotree.js
 
 Indices and tables

docs/options.rst

@@ -51,6 +51,9 @@ collapsible
 selectable
  `(Boolean)` Determines whether or not individual branches are selectable. Defaults to ``true``.
 
+zoom
+ `(Boolean)` Determines whether or not zooming is enabled. Defaults to ``false``.
+
 restricted-selectable
  `(Array)` Determines what types of global selection actions are possible. Defaults to ``false``.
 

documentation/_sources/examples.rst.txt

@@ -9,6 +9,12 @@ Hello-world
  * `View Hello-world example </examples/hello-world>`_
  * `View Hello-world source <https://github.com/veg/phylotree.js/blob/master/examples/hello-world/index.html>`_
 
+Phylo-bar
+ A phylogenetic tree that interfaces with a D3.js bar chart to count classes of substitutions along portions of a phylogeny.
+
+ * `View Phylo-bar example </examples/phylo-bar>`_
+ * `View Phylo-bar source <https://github.com/veg/phylotree.js/blob/master/examples/phylo-bar/index.html>`_
+
 Vanilla
  The simplest tree possible, with all default features disabled.
 
@@ -39,6 +45,26 @@ Variable size and shape for leaf nodes
  * `View Variable leaves example </examples/clone-compartment>`_
  * `View Variable leaves source <https://github.com/veg/phylotree.js/blob/master/examples/clone-compartment/index.html>`_
 
+Zoom
+ Example of zooming and panning.
+
+ * `View Zooming example </examples/zoom>`_
+ * `View Zooming source <https://github.com/veg/phylotree.js/blob/master/examples/zoom/index.html>`_
+
+Leaf metadata
+ Visualize some artificial data associated with leaves of a tree.
+
+ * `View Leaf metadata example </examples/leafdata>`_
+ * `View Leaf metadata source <https://github.com/veg/phylotree.js/blob/master/examples/leafdata/index.html>`_
+
+XML parsing
+ Parse PhyloXML or NexML formats.
+
+ * `View PhyloXML example </examples/phyloxml>`_
+ * `View PhyloXML source <https://github.com/veg/phylotree.js/blob/master/examples/phyloxml/index.html>`_
+ * `View NexML example </examples/nexml>`_
+ * `View NexML source <https://github.com/veg/phylotree.js/blob/master/examples/nexml/index.html>`_
+
 Large tree
  Viewing a large tree with a Starcraft-style guide.
 
@@ -61,4 +87,11 @@ Ancestral sequence structural viewer
  * `View Ancestral sequence structural viewer example </examples/large-ancestral-structural-viewer>`_
  * `View Ancestral sequence structural viewer source <https://github.com/veg/phylotree.js/blob/master/examples/large-ancestral-structural-viewer/index.html>`_
 
+Interactive tanglegram
+ A tanglegram to compare phylogenies inferred from muliple vs. single tissue samples. Crossings are minimized using a 
+ dynamic programming algorithm, and the single-tissue tree enables selections to highlight inter-tree crossings.
+
+ * `View Interactive tanglegram example </examples/siv>`_
+ * `View Interactive tanglegram source <https://github.com/veg/phylotree.js/blob/master/examples/siv/index.html>`_
+
 .. _HyPhy: http://hyphy.org/

documentation/_sources/fundamentals.rst.txt

@@ -17,12 +17,16 @@ attached to the ``d3.layout`` namespace.
 .. autofunction:: d3.layout.phylotree([container])
 
 Phylotrees are themselves functions, with many methods attached and variables
-that have been closed over to provide an internal state.
+that have been closed over to provide an internal state. Newick, PhyloXML, and
+NeXML formats are supported.
 
 .. autofunction:: phylotree~phylotree(nwk[, bootstrap_values])
 
+.. autofunction:: d3.layout.phylotree.nexml_parser
+
 Internally, Phylotree.js uses the `D3 hierarchy layout`_. The following function
-parses Newick strings into a hierarchical JSON format.
+parses Newick strings into a hierarchical JSON format. Certain ad-hoc extensions,
+such as those used by HyPhy or Beast, are (partially) supported.
 
 .. autofunction:: d3.layout.newick_parser(nwk_str[, bootstrap_values])
 

documentation/_sources/index.rst.txt

@@ -8,7 +8,7 @@ Welcome to Phylotree.js's documentation!
 
 Phylotree.js is a Javascript library for working with phylogenetic trees. Uses include web application development and interactive data visualization for phylogenetics.
 
-It is written as a `D3`_ layout, and aspires to be a general purpose tool. Example uses include `a standalone web application`_ for viewing and labeling phylogenetic trees, the `Datamonkey`_ webserver for comparative sequence analysis, and an `ancestral sequence structural viewer`_.
+It is written as a `D3`_ layout, and aspires to be a general purpose tool for visualizing and selecting branches in phylogenetic trees. Example uses include `a standalone web application`_ for viewing and labeling phylogenetic trees, the `Datamonkey`_ webserver for comparative sequence analysis, an `ancestral sequence structural viewer`_, and an `interactive tanglegram`_.
 
 The code is `available on Github`_.
 
@@ -30,6 +30,7 @@ Contents
 .. _a standalone web application: /
 .. _Datamonkey: http://datamonkey.org
 .. _ancestral sequence structural viewer: /examples/large-ancestral-structural-viewer
+.. _interactive tanglegram: /examples/siv
 .. _available on Github: http://github.com/veg/phylotree.js
 
 Indices and tables

documentation/_sources/options.rst.txt

@@ -51,6 +51,9 @@ collapsible
 selectable
  `(Boolean)` Determines whether or not individual branches are selectable. Defaults to ``true``.
 
+zoom
+ `(Boolean)` Determines whether or not zooming is enabled. Defaults to ``false``.
+
 restricted-selectable
  `(Array)` Determines what types of global selection actions are possible. Defaults to ``false``.
 

documentation/examples.html

@@ -185,6 +185,13 @@ <h1>Examples<a class="headerlink" href="#examples" title="Permalink to this head
 <li><a class="reference external" href="https://github.com/veg/phylotree.js/blob/master/examples/hello-world/index.html">View Hello-world source</a></li>
 </ul>
 </dd>
+<dt>Phylo-bar</dt>
+<dd><p class="first">A phylogenetic tree that interfaces with a D3.js bar chart to count classes of substitutions along portions of a phylogeny.</p>
+<ul class="last simple">
+<li><a class="reference external" href="/examples/phylo-bar">View Phylo-bar example</a></li>
+<li><a class="reference external" href="https://github.com/veg/phylotree.js/blob/master/examples/phylo-bar/index.html">View Phylo-bar source</a></li>
+</ul>
+</dd>
 <dt>Vanilla</dt>
 <dd><p class="first">The simplest tree possible, with all default features disabled.</p>
 <ul class="last simple">
@@ -220,6 +227,29 @@ <h1>Examples<a class="headerlink" href="#examples" title="Permalink to this head
 <li><a class="reference external" href="https://github.com/veg/phylotree.js/blob/master/examples/clone-compartment/index.html">View Variable leaves source</a></li>
 </ul>
 </dd>
+<dt>Zoom</dt>
+<dd><p class="first">Example of zooming and panning.</p>
+<ul class="last simple">
+<li><a class="reference external" href="/examples/zoom">View Zooming example</a></li>
+<li><a class="reference external" href="https://github.com/veg/phylotree.js/blob/master/examples/zoom/index.html">View Zooming source</a></li>
+</ul>
+</dd>
+<dt>Leaf metadata</dt>
+<dd><p class="first">Visualize some artificial data associated with leaves of a tree.</p>
+<ul class="last simple">
+<li><a class="reference external" href="/examples/leafdata">View Leaf metadata example</a></li>
+<li><a class="reference external" href="https://github.com/veg/phylotree.js/blob/master/examples/leafdata/index.html">View Leaf metadata source</a></li>
+</ul>
+</dd>
+<dt>XML parsing</dt>
+<dd><p class="first">Parse PhyloXML or NexML formats.</p>
+<ul class="last simple">
+<li><a class="reference external" href="/examples/phyloxml">View PhyloXML example</a></li>
+<li><a class="reference external" href="https://github.com/veg/phylotree.js/blob/master/examples/phyloxml/index.html">View PhyloXML source</a></li>
+<li><a class="reference external" href="/examples/nexml">View NexML example</a></li>
+<li><a class="reference external" href="https://github.com/veg/phylotree.js/blob/master/examples/nexml/index.html">View NexML source</a></li>
+</ul>
+</dd>
 <dt>Large tree</dt>
 <dd><p class="first">Viewing a large tree with a Starcraft-style guide.</p>
 <ul class="last simple">
@@ -245,6 +275,14 @@ <h1>Examples<a class="headerlink" href="#examples" title="Permalink to this head
 <li><a class="reference external" href="https://github.com/veg/phylotree.js/blob/master/examples/large-ancestral-structural-viewer/index.html">View Ancestral sequence structural viewer source</a></li>
 </ul>
 </dd>
+<dt>Interactive tanglegram</dt>
+<dd><p class="first">A tanglegram to compare phylogenies inferred from muliple vs. single tissue samples. Crossings are minimized using a
+dynamic programming algorithm, and the single-tissue tree enables selections to highlight inter-tree crossings.</p>
+<ul class="last simple">
+<li><a class="reference external" href="/examples/siv">View Interactive tanglegram example</a></li>
+<li><a class="reference external" href="https://github.com/veg/phylotree.js/blob/master/examples/siv/index.html">View Interactive tanglegram source</a></li>
+</ul>
+</dd>
 </dl>
 </div>