Merge pull request #67 from EcoJulia/mkb/patch_docs

small doc fixes
EcoJulia · Oct 14, 2021 · c3b9b92 · c3b9b92
2 parents c958d11 + 84d75b3
commit c3b9b92
Show file tree

Hide file tree

Showing 9 changed files with 50 additions and 25 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -15,6 +15,7 @@ makedocs(modules = [Phylo, Phylo.API],
                  "Modelling traits" => "man/modelling.md",
                  "Plotting" => "man/plotting.md"
              ],
+             "List of functions" => "functionlist.md",
              "API" => "api.md"
          ])
 

diff --git a/docs/src/api.md b/docs/src/api.md
@@ -29,9 +29,6 @@ extends `Phylo.API._addnode!()` (and therefore the directly accessible
 to be extended for any new subtype, and which have default
 implementations.
 
-```@contents
-```
-
 ```@autodocs
 Modules = [Phylo.API]
 Private = false

diff --git a/docs/src/functionlist.md b/docs/src/functionlist.md
@@ -0,0 +1,3 @@
+
+```@index
+```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -15,6 +15,3 @@ are very welcome!
 
 ```@contents
 ```
-
-```@index
-```
diff --git a/docs/src/man/attributes.md b/docs/src/man/attributes.md
@@ -7,7 +7,6 @@ gettrees
 nroots
 getroots
 gettreenames
-getonetree
 ```
 
 ### Methods on Trees
@@ -46,10 +45,8 @@ setnodedata!
 hasheight
 getheight
 setheight!
-hasparent
 getparent
 getancestors
-haschildren
 getchildren
 getdescendants
 ```
@@ -62,10 +59,8 @@ getlength
 hasrootheight
 getrootheight
 setrootheight!
-clearrootheight!
 getbranchdata
 setbranchdata!
-getrootdistance
 ```
 
 
@@ -92,9 +87,6 @@ getbranchname
 hasbranch
 getbranch
 getbranches
-hasrootheight
-getrootheight
-setrootheight!
 validate!
 branchdims
 ```

diff --git a/docs/src/man/manipulating.md b/docs/src/man/manipulating.md
@@ -5,7 +5,6 @@ TODO: examples here are needed
 ```@docs
 createbranch!
 deletebranch!
-branch!
 createnode!
 createnodes!
 deletenode!

diff --git a/docs/src/man/plotting.md b/docs/src/man/plotting.md
@@ -22,7 +22,7 @@ default is `:dendrogram`
 ```@example plotting
 using Phylo, Plots
 ENV["GKSwstype"]="nul" # hide
-default(linecolor = :black, size = (600, 600)) # looks nicer with black lines
+default(linecolor = :black, size = (400, 400)) # looks nicer with black lines
 hummers = open(parsenewick, Phylo.path("hummingbirds.tree"))
 plot(hummers, size = (400, 600), showtips = false)
 ```
@@ -89,7 +89,8 @@ plot(hummers,
     size = (400, 800), 
     linecolor = :orange, linewidth = 5, 
     markersize = 10, markercolor = :steelblue, markerstrokecolor = :white,
-    series_annotations = text.(1:nnodes(hummers), 6, :center, :center, :white)
+    series_annotations = text.(1:nnodes(hummers), 5, :center, :center, :white,
+    tipfont = (4,))
 )
 ```
 
@@ -111,7 +112,7 @@ rand!(tempsampler, hummers)
 plot(hummers, showtips = false,   
    marker_group = "TemperatureTrait",  
     legend = :topleft, msc = :white, treetype = :fan, 
-    c = [:red :blue :green], size = (600, 600)) 
+    c = [:red :blue :green]) 
 ```
 ```@docs
 map_depthfirst

diff --git a/src/Phylo.jl b/src/Phylo.jl
@@ -89,16 +89,16 @@ end
 include("Interface.jl")
 # AbstractTree methods
 export ntrees, gettrees, nroots, getroots, getroot
-export treenametype, gettreenames, getonetree, gettreename
+export treenametype, gettreenames, gettreename #, getonetree #unimplemented
 export roottype, nodetype, nodedatatype, nodenametype
 export branchtype, branchdatatype, branchnametype
-export createbranch!, deletebranch!, branch!
+export createbranch!, deletebranch!
 export createnode!, createnodes!, deletenode!
 export getnodenames, getnodename, hasnode, getnode, getnodes
 export getbranchnames, getbranchname, hasbranch, getbranch, getbranches
 export hasrootheight, getrootheight, setrootheight!
-export hasparent, getparent, getancestors
-export haschildren, getchildren, getdescendants
+export getparent, getancestors #, hasparent # unimplemented
+export getchildren, getdescendants #, haschildren # unimplemented
 export validate!, traversal, branchdims
 
 @deprecate addnode! createnode!
@@ -121,9 +121,9 @@ export hasheight, getheight, setheight!
 
 # AbstractTree / AbstractBranch methods
 export src, dst, getlength
-export hasrootheight, getrootheight, setrootheight!, clearrootheight!
+export hasrootheight, getrootheight, setrootheight! #, clearrootheight! #unimplemented
 export getbranchdata, setbranchdata!
-export getrootdistance
+# export getrootdistance # unimplemented
 
 @deprecate getnoderecord getnodedata
 @deprecate setnoderecord! setnodedata!

diff --git a/src/metrics.jl b/src/metrics.jl
@@ -1,4 +1,32 @@
-function mrca(tree, target)
+"""
+    mrca(tree::AbstractTree, target)
+
+Returns the node within `tree` that is the Most Recent Common Ancestor of the 
+leaves (or internal nodes) defined by `target`. `target` can be an iterator
+over nodes or an AbstractArray of nodes. The return value has the same node
+type as the elements of `target`.
+
+### Examples
+≡≡≡≡≡≡≡≡≡≡≡
+
+julia> tree = open(parsenewick, Phylo.path("H1N1.newick"))
+RootedTree with 507 tips, 1013 nodes and 1012 branches.
+Leaf names are 227, 294, 295, 110, 390, ... [501 omitted] ... and 418
+
+
+julia> tips = rand(collect(nodefilter(isleaf, tree)), 3)
+3-element Vector{LinkNode{OneRoot, String, Dict{String, Any}, LinkBranch{OneRoot, String, Dict{String, Any}, Float64}}}:
+ LinkNode 153, a tip of the tree with an incoming connection (branch 888).
+
+ LinkNode 120, a tip of the tree with an incoming connection (branch 195).
+
+ LinkNode 504, a tip of the tree with an incoming connection (branch 44).
+
+
+julia> mrca(tree, tips)
+LinkNode Node 1003, an internal node with 1 inbound and 2 outbound connections (branches 1001 and 999, 1000)
+"""
+function mrca(tree::AbstractTree, target)
     ancestors = getancestors(tree, first(target))
     ranks = Dict(j => i for (i,j) in enumerate(ancestors))
     checked = Set(ancestors)
@@ -13,6 +41,13 @@ function mrca(tree, target)
     ancestors[oldest]
 end
 
+"""
+    nodeheights(tree::Phylo.AbstractTree; onlyleaves = false, noleaves = false)
+
+Returns an AxisArray of the height of all nodes in `tree` over the root node.
+`onlyleaves` and `noleaves` filter the nodes for leaves and internal nodes,
+respectively
+"""
 function nodeheights(tree::Phylo.AbstractTree; onlyleaves = false, noleaves = false)
     function findheights!(clade::String, parentheight::Float64 = 0.0)
         myheight = parentheight