moved README.md to sphinx docs

man/contents.rst

@@ -2,10 +2,9 @@ plot_phylo
 ==========
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 4
 
    index.md
-   pages/introduction.md
    pages/installation.md
    pages/quickstart.md
    pages/parameters.md

man/index.md

@@ -1,7 +1,18 @@
 # plot_phylo
+![Illustration](pages/examples/layered.png "Illustration")
+
+This module allows the user to plot a phylogenetic tree on an existing matplotlib axis.
+
+This means that:
+* Phylogenies can be incorporated into existing plots.
+* Annotations can be added using standard matplotlib functionality.
+* Plots can be output in png, pdf, svg or tiff formats.
+* Automatically generated and updated figures can include phylogenies
+
 1. [Installation](pages/installation.md)
 2. [Quick Start](pages/quickstart.md)
-3. [Incorporating Matplotlib Parameters](pages/matplotlib.md)
-4. [Parameters](pages/parameters.md)
+3. [Parameters](pages/parameters.md)
+4. [Incorporating Matplotlib Elements](pages/matplotlib.md)
 5. [Functions](pages/functions.md)
 6. [Detailed Example](pages/detailed.md)
+

man/pages/detailed.md

@@ -1 +1,95 @@
-# Detailed Example
+# Detailed Example
+This detailed example shows how `plot_phylo` can be combined with matplotlib and basic Python to draw complex plots.
+
+```
+# Build the blank figure
+f = plt.figure(figsize=(15, 10))
+ax = plt.subplot(1, 1, 1)
+
+# Set the x and y axis limits
+ax.set_xlim(2, 122)
+ax.set_ylim(9, 21)
+ypos_val = 10
+
+# Define colours for specific nodes
+colours = {'Gorilla gorilla': '#e21c0c', 'Pan troglodytes': '#0c57e2', 'Saimiri boliviensis': '#338c3e',
+           'Chiropotes satanas': '#dc9d0c'}
+
+# Draw the left tree
+results_left = plot_phylo.plot_phylo("primates.nw",
+                                      ax, xpos=5, ypos=ypos_val, width=15,
+                                      show_axis=False, show_support=False,
+                                      font_size=16, col_dict=colours,
+                                      rev_align_tips=True)
+
+# Draw the right tree
+results_right = plot_phylo.plot_phylo("primates_mixed.nw",
+                                       ax, xpos=105, ypos=10, width=15,
+                                       show_axis=False, show_support=False,
+                                       reverse=True,
+                                       font_size=16, col_dict=colours,
+                                       rev_align_tips=True)
+
+# Using matplotlib and basic Python functionality on the returned dictionaries from hereforward
+
+# Connection between trees
+
+# Find the labels which differ between trees
+links = []
+for r1 in results_left:
+    # Find the index of each label in the tree
+    ind1 = results_left[r1]['index']
+    ind2 = results_right[r1]['index']
+    
+    # If they differ, store them
+    if ind1 != ind2:
+        links.append(r1)
+
+for link in links:
+    # Retrieve the positions of the non-matched labels
+    left_box = results_left[link]
+    right_box = results_right[link]
+    
+    # Get the position of the labels in each tree
+    left_x = left_box['xmax'] + 1
+    left_y = left_box['ymid']
+    
+    right_x = right_box['xmin'] - 1
+    right_y = right_box['ymid']
+
+    # Plot the points on the left tree
+    ax.scatter(left_x, left_y, color=colours[link])
+    
+    # Plot the points on the right tree
+    ax.scatter(right_x, right_y, color=colours[link])
+    
+    # Connect the two points
+    ax.plot([left_x, right_x], [left_y, right_y], color=colours[link])
+
+# Box highlighting great apes
+# Define which species are great apes
+great_apes = ['Gorilla gorilla', 'Pan troglodytes', 'Homo sapiens', 'Pongo abelii']
+ga_pos = []
+
+# Store the positions of the great ape labels
+for nam, box in results_left.items():
+    if nam in great_apes:
+        ga_pos.append(box['ymin'])
+        ga_pos.append(box['ymax'])
+
+# Draw the grey box. 15.5 is based on visually inspecting the axis.
+ax.fill_between([15.5, box['xmax']], min(ga_pos), max(ga_pos), color='lightgrey')
+
+# Additional labels
+# Add the Tree 1 and Tree 2 labels, using figure co-ordinates
+f.text(0.2, 0.85, 'Tree 1', ha='center', fontsize=16, fontweight='bold')
+f.text(0.8, 0.85, 'Tree 2', ha='center', fontsize=16, fontweight='bold')
+
+# Add the overall title
+f.suptitle("Primate Phylogeny", fontsize=24, y=0.92)
+
+# Save
+f.savefig("examples/layered.png", bbox_inches='tight')
+```
+
+![Detailed Example](./examples/layered.png "Detailed Example")

man/pages/installation.md

@@ -1,12 +1,11 @@
-## Installation
+# Installation
 
 **Requirements**
 
 * python >= 3.6
 * matplotlib >= 2.1.1
 * ete3 >= 3.1.0
 
-## Installation
 The module can be installed using pip
 
 `pip install plot_phylo`

man/pages/matplotlib.md

@@ -1 +1,78 @@
-# Incorporating Matplotlib Parameters
+# Adding Matplotlib Elements to your Tree
+One of the main advantages of this module is that, as plots are generated using matplotlib and added to an active axis, other elements of matplotlib plots can be incorporated - the plot remains activate and can be edited.
+
+The plot_phylo function returns a dictionary where the keys are the tip labels and the values are the boundaries of the text boxes containing the tip labels, in axis units. 
+
+For example, the first few items in the list returned from the function call above are as follows:
+
+
+```
+{'Cercopithecus neglectus': {'index': 0,
+  'xmin': 9.656,
+  'xmax': 16.336,
+  'ymin': 9.882,
+  'ymax': 10.118,
+  'ymid': 10.0,
+  'xmid': 12.883},
+ 'Macaca mulatta': {'index': 1,
+  'xmin': 9.609,
+  'xmax': 14.2,
+  'ymin': 9.215,
+  'ymax': 9.452,
+  'ymid': 9.333,
+  'xmid': 12.101},
+ 'Colobus angolensis': {'index': 2,
+  'xmin': 9.649,
+  'xmax': 15.016,
+  'ymin': 8.548,
+  'ymax': 8.785,
+  'ymid': 8.667,
+  'xmid': 12.883},
+...
+```
+
+`xmin`, `xmid` and `xmax` are the positions of the left, centre and right of the tip label text on the x-axis.
+
+`ymin`, `ymid` and `ymax` are the positions of the bottom, centre and top of the tip label text on the y-axis.
+
+`ind` is the position of this label on the tree, reading from top to bottom, starting at 0.
+
+For example, for the first list item, Cercopithecus neglectus is the tip label. On the plot, this label spans positions 9.656 to 16.336 on the x-axis and 9.882 to 10.118 on the y axis. It is at position 0 in the tree.
+
+
+Providing these positions allows the user to add annotations etc. to the tip labels using matplotlib after drawing the plot.
+
+For example, here, the boundary box is of the first tip label is marked on the tree.
+
+```
+f = plt.figure(figsize=(8, 10))
+a = plt.subplot()
+
+# To use the text positions, the axis limits should be explicitly
+# specified before the plot is drawn
+
+plt.xlim(-2, 20)
+plt.ylim(-2, 11)
+
+# Draw the tree
+results = plot_phylo.plot_phylo("examples/primates.nw", a)
+
+# Retrieve the first result - for C. neglectus
+c_neg_results = results['Cercopithecus neglectus']
+
+# Plot these points on the axis
+# Bottom left
+plt.scatter(c_neg_results['xmin'], c_neg_results['ymin'], color='green', s=15)
+# Top left
+plt.scatter(c_neg_results['xmin'], c_neg_results['ymax'], color='red', s=15)
+# Bottom right
+plt.scatter(c_neg_results['xmax'], c_neg_results['ymin'], color='blue', s=15)
+# Top right
+plt.scatter(c_neg_results['xmax'], c_neg_results['ymax'], color='orange', s=15)
+
+# Save
+f.savefig("examples/basic_plot_box.png", bbox_inches='tight')
+
+```
+![Basic tree with box](./examples/basic_plot_box.png "Basic tree with box")
+