v1: remove gadfly plots (#19)

* removed gadfly and related dependencies; small-case names
* bug fix: placement of minor edge labels in :fulltree style
* more options for edge widths, colors and label sizes

Project.toml

@@ -1,23 +1,17 @@
 name = "PhyloPlots"
 uuid = "c0d5b6db-e3fc-52bc-a87d-1d050989ed3b"
 license = "MIT"
-version = "0.3.2"
+version = "1.0.0"
 
 [deps]
-ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
-Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
-Gadfly = "c91e804a-d5a3-530f-b6f0-dfbca275c004"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 PhyloNetworks = "33ad39ac-ed31-50eb-9b15-43d0656eaa72"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 RCall = "6f49c342-dc21-5d91-9882-a32aef131414"
 
 [compat]
-ColorTypes = "0.7, 0.8, 0.9, 0.10, 0.11"
-Colors = "0.9, 0.10, 0.11, 0.12"
 DataFrames = "0.13, 0.14, 0.15, 0.16, 0.17, 0.18, 0.19, 0.20, 0.21, 0.22, 1.0"
-Gadfly = "1.0, 1.1, 1.2, 1.3"
 PhyloNetworks = "0.9, 0.10, 0.11, 0.12, 0.13, 0.14, 0.15, 0.16, 1" # extras to let PN build its documentation of new releases
 RCall = "0.11, 0.12, 0.13"
 julia = "0.7, 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7"

docs/Project.toml

@@ -2,10 +2,8 @@
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterMarkdown = "997ab1e6-3595-5248-9280-8efb232c3433"
-# will be added by the CI platform as being developed:
-# PhyloPlots = "c0d5b6db-e3fc-52bc-a87d-1d050989ed3b"
-# will be added to track master version in make.jl:
-# PhyloNetworks = "33ad39ac-ed31-50eb-9b15-43d0656eaa72"
+PhyloNetworks = "33ad39ac-ed31-50eb-9b15-43d0656eaa72"
+PhyloPlots = "c0d5b6db-e3fc-52bc-a87d-1d050989ed3b"
 RCall = "6f49c342-dc21-5d91-9882-a32aef131414"
 
 [compat]

docs/readme.md

@@ -1,13 +1,36 @@
 # notes to maintain documentation
 
-- built with [Documenter](https://juliadocs.github.io/Documenter.jl)
+## to make a local version of the website
+
+```shell
+julia --project=docs/ -e 'using Pkg; Pkg.instantiate(); Pkg.develop(PackageSpec(path=pwd()))'
+julia --project=docs/ --color=yes docs/make.jl
+```
+
+or interactively in `docs/`:
+```shell
+pkg> activate .
+pkg> instantiate
+pkg> dev ~/.julia/dev/PhyloPlots
+pkg> add PhyloNetworks#master
+julia> include("make.jl")
+```
+
+it will:
+- tests the `jldoctest` blocks of examples in the docstrings
+- creates or updates a `build/` directory with html files
+
+## how it works: overview
+
+- built with [Documenter](https://juliadocs.github.io/Documenter.jl), see
+  its [doc](https://juliadocs.github.io/Documenter.jl/stable/man/syntax/)
+  for more details on its md syntax.
 - deployed [here](https://cecileane.github.io/PhyloPlots.jl/)
   (go to `dev/` or `stable/`)
   using github and files committed to the `gh-pages` branch.
 
-## how it works: overview
-
 - `.github/workflows/ci.yml` asks to run `docs/make.jl` after a successful test & build.
+  it installs `R`, since PhyloPlots depends on RCall which depends on R.
 - the julia script `docs/make.jl` has these steps:
   1. install the master version of PhyloNetworks
   1. run `makedocs()` from `Documenter`: make the documentation;
@@ -21,28 +44,9 @@
 - update the Documenter version in `docs/Project.toml`: check to see if a new
   version of Documenter was released. If so, up the dependency, check locally
   that it works, make any updates as needed.
-- update Julia version in `.github/workflows/ci.yml`, `matrix.version`
-## The "Documenter md" format
-
-### Note on the format
-
-The documentation pages are all written in this format. It is a regular md, but
-with extra blocks of codes (as `@example` and `@setup`) that contain Julia
-commands. These lines will be executed during the `makedoc()` process. See the
-`Documenter` [doc](https://juliadocs.github.io/Documenter.jl/stable/man/syntax/)
-for more details on the syntax. For instance, @example blocks with the same "name"
-are run in the same session. Otherwise, an @example blocks with no name
-is run in its own anonymous Modules.
-
-### Setting up the plot environment
-
-Some of these blocs may contain plots, which are going to be drawn during the
-process, requiring the use of `PhyloPlots` along with `RCall`. Hence,
-before the doc is built, `.github/workflows/ci.yml` installs `R` on the server,
-sets up the julia environment with dependencies like `PhyloPlots` before
-starting the build in itself.
+- update Julia version in `.github/workflows/ci.yml`, `docs:` section.
 
-### Directory of the plots
+## plots for the documentation
 
 We chose to group all the output plots in the directory `assets/figures`.
 Hence, the typical setup in a documentation page containing plots is:
@@ -58,58 +62,10 @@ exist. In theory, it only needs to be called once (by the first documentation
 page being built). However, as this order might be subject to change over time,
 it could be safer to include it on every such page.
 
-### Format of the plots
-
-After trial and error and discussions, we chose to use only the *SVG* format
-for the plot. This format should ensure that when a plot is drawn again,
-identical, in a new build, then Git will recognize that it has not change, and
-hence not save a new version of it. This should ensure that the repository does
-not grow unreasonably at each build of the doc, i.e. after each push to
-master. The typical commands to save and display a plot should hence be:
-
-    ```@example name
-    R"svg"(figname("my_useful_name.svg"), width=4, height=3); # hide
-    plot(net, :R);
-    R"dev.off()" # hide
-    nothing # hide
-    ```
-    ![my_useful_name](../assets/figures/my_useful_name.svg)
-
-I like to add `R"par"(mar=[.1,.1,.1,.1]) # hide` since the default margins are too wide for my preference.
-
-**Warning**: this is not like an interactive session. If the same file name
-is re-used by some other documentation page for some other plot, only the
-final version of the plot will be committed by git, with possible unintended
-consequences. Make sure to use different file names for plots that are supposed
-to look different (across the whole site).
-
-## to make a local version of the website
-
-```shell
-julia --project=docs/ -e 'using Pkg; Pkg.instantiate(); Pkg.develop(PackageSpec(path=pwd()))'
-julia --project=docs/ --color=yes docs/make.jl
-```
-
-or interactively in `docs/`:
-```shell
-pkg> activate .
-pkg> instantiate
-pkg> dev ~/.julia/dev/PhyloPlots
-pkg> add PhyloNetworks#master
-julia> include("make.jl")
-```
-
-it will:
-- tests the `jldoctest` blocks of examples in the docstrings
-- creates or updates a `build/` directory with html files
-
-## references
-
-big difference:
-
-    [blabla](@ref)
-    [`blabla`](@ref)
+After trial and error and discussions, we chose to use only the *SVG* format.
+This format should ensure that when a plot is drawn again, it is identical,
+making it more efficient for git to track changes.
 
-The first version will look for a *section* header "blabla", to link to that section.
-The secon version will look for a *function* named "blabla",
-to link to the documentation for that function.
+**Warning**: If the same file name is re-used across documentation pages, only the
+final version will be committed by git. Make sure to use different file names for
+plots that are supposed to look different (across the whole site).

docs/src/man/adding_data.md

@@ -6,72 +6,82 @@ figname(x) = joinpath("..", "assets", "figures", x)
 
 # Adding data
 
-In this section, we will look over ways of adding extra information or data to a plot.
+In this section, we look over ways of adding extra information or data to a plot.
 
 ## Adding labels
 
 !!! note
-    For demonstration purposes, I will walk through the process of adding labels to edges,
+    For demonstration purposes, we walk through the process of adding labels to edges,
     with notes on how to do the same for nodes in parentheses.
 
 To add labels on edges (or nodes), we need to know their numbers. We can use the
-`showEdgeNumbers = true` option for this. (Use `showNodeNumbers = true` to see node numbers).
+`showedgenumbers = true` option for this. (Use `shownodenumbers = true` to see node numbers).
 
 ```@example adding_data
-R"svg"(figname("adding_data1.svg"), width=3, height=3) # hide
-R"par"(mar=[.1,.1,.1,.1]) # hide
+R"svg"(figname("adding_data1.svg"), width=6, height=3) # hide
+R"par"(mar=[.1,.1,.1,.1]); R"layout"([1 2]); # hide
 net = readTopology("(A,((B,#H1),((C)#H1, D)));") # hide
-plot(net, :R, showEdgeNumber=true);
+plot(net, showedgenumber=true);
+plot(net, showedgenumber=true, edgenumbercolor="red4");
 R"dev.off()" # hide
 nothing # hide
 ```
 ![example1](../assets/figures/adding_data1.svg)
 
-We will need to define a DataFrame with two columns of information: the number of the edge (or
+Edge numbers are shown in grey by default (to avoid mistaking them
+for edge lengths), but their color can be adjusted as shown above.
+
+We then need to define a DataFrame with two columns of information: the number of the edge (or
 node), and the label that goes on it, like this:
 
-| Number | Label            |
+| number | label            |
 |--------|------------------|
-| 1      | "My first edge"  |
-| 2      | "My second edge" |
+| 1      | "edge number 1"  |
+| 2      | "edge # 2" |
 
 After including the DataFrames package, we can define it as so:
 ```@repl
 using DataFrames
-DataFrame(Number=[1, 2], Label=["My first edge", "My second edge"])
+DataFrame(number=[1,2], label=["edge number 1","edge # 2"])
 ```
-Using this dataframe as input to the `edgeLabel` (`nodeLabel` for nodes) option puts the text on the correct edges:
+Using this data frame as input to the `edgelabel` option (`nodelabel` for nodes)
+puts the text on the correct edges:
 ```@example adding_data
 R"svg"(figname("edge_labels_example.svg"), width=4, height=3) # hide
 R"par"(mar=[.1,.1,.1,.1]) # hide
 net = readTopology("(A,((B,#H1),(C,(D)#H1)));") # hide
-plot(net, :R, edgeLabel=DataFrame(Number=[1, 2], Label=["My first edge", "My second edge"]));
+plot(net, edgelabel=DataFrame(number = [1,2],
+                              label = ["edge number 1", "edge # 2"]),
+          edgelabelcolor="orangered", edgecex=[0.9,1.1]);
 R"dev.off()" # hide
 nothing # hide
 ```
 ![example2](../assets/figures/edge_labels_example.svg)
 
-## Adding other data using R
+## Adding other annotations using R
 
-We can use the return values of [`plot`](@ref) to get some information on the coordinates of 
+We can use the return values of [`plot`](@ref) to get information on the coordinates of
 different elements of the plot. Using this, we can add any other information we want.
 
 The [`plot`](@ref) function returns the following tuple:
 ```
-(xmin, xmax, ymin, ymax, node_x, node_y, node_yB, node_yE,
-edge_xB, edge_xE, edge_yB, edge_yE, ndf, edf)
+(xmin, xmax, ymin, ymax,
+ node_x, node_y, node_yB, node_yE,
+ edge_xB, edge_xE, edge_yB, edge_yE,
+ nodedataframe, edgedataframe)
 ```
-See the documentation for descriptions on every element: [`plot`](@ref)
+See the documentation for descriptions of these elements: [`plot`](@ref)
 
 ## Side clade bars example
 
-Here's some example code that adds bars to denote clades in the margin:
+Here's example code that adds bars to denote clades in the margin:
 
 ```@example adding_data
 R"svg"(figname("side_bars.svg"), width=4, height=4) # hide
 R"par"(mar=[.1,.1,.1,.1]) # hide
 net = readTopology("(((((((1,2),3),4),5),(6,7)),(8,9)),10);");
-plot(net, :R, xlim=(1, 10))
+plot(net, xlim=(1,10))
+using RCall # to send any R command, to make further plot modifications
 R"segments"([9, 9, 9], [0.8, 7.8, 9.8], [9, 9, 9], [7.2, 9.2, 10.2])
 R"text"([9.5, 9.5, 9.5], [4, 8.5, 10], ["C", "B", "A"])
 R"dev.off()" # hide
@@ -86,7 +96,7 @@ Below, we store the plot output in `res`, then check its first two values
 because they contain the default range of the x axis; `xmin` and `xmax`.
 
 ```@example adding_data
-res = plot(net, :R);
+res = plot(net);
 res[1:2]
 ```
 
@@ -95,14 +105,15 @@ range is about `(0.3, 9)`. To give us extra space to work with, we can
 set `xlim` to `(1,10)`, forcing the range to be wider.
 
 ```julia
-plot(net, :R, xlim=(1, 10));
+plot(net, xlim=(1, 10));
 ```
 
 Knowing the coordinates, we can now add more information to the plot through
-`RCall`. For this, I use the `segments` and `text` functions to add side bars with
+`RCall`. For this, I use the R functions `segments` and `text` to add side bars with
 text on them.
 
-```
+```julia
+using RCall # add (install) the RCall package prior to 'using' it
 R"segments"([9, 9, 9], [0.8, 7.8, 9.8], [9, 9, 9], [7.2, 9.2, 10.2])
 R"text"([9.5, 9.5, 9.5], [4, 8.5, 10], ["C", "B", "A"])
 ```